The Hitchhikers Guide to XML Authoring

8/10/2019 The Hitchhikers Guide to XML Authoring

1/39

Te Hitchhikers Guide to

XML Authoring


2/392


XML AuthoringConens

Does My Organizaion Need XML? 3

Srucure and XMLTe Business Case 3

Preparing For he JourneyUndersanding Srucure and XML 5

Inroducing Srucured FrameMaker Inroducing XML

Why Use XML? 7

XML is Open, No Proprieary XML Suppors Sandards Like DIA, DocBook, or SD XML Has Rules Daabase PublishingXML As Daa ranspor XML Suppors Reuse XML Inegraes Wih Localizaion Processes XML Suppors Collaboraion

Why Use Srucured FrameMaker? 10

Auhoring Visually Ediing XML Code Excellen Prin and PDF Oupu

Auomaic and Enforced Formaing On-he-Fly Validaion (Guided Ediing) Relaively Low Licensing Cos

Why Use FrameMaker XML Auhor? 14

Componens of a Srucured Auhoring Environmen 15

Auhoring Only in Srucured FrameMaker Srucured Auhoring and XML

Using FrameMaker Srucure and XML 17

Conen Analysis Building he Proposal EDD Adding Formaing o he EDD

Building a Srucured Applicaion Migraing Unsrucured Files o Srucure 29

Cleaning Up Legacy Documens Creaing he Conversion able Conversion Example

Conclusion 36

Where o Go From Here 37

Adobe Whie Papers Recorded Adobe Webinars Docbook raining Consuling


3/39


XML Authoring

Te Hitchhikers Guide to XML AuthoringIf youre a echnical publicaions professional, youve undoubedly heard alk abou srucured documenaion

XML, and Srucured Adobe FrameMaker. You may be hinking abou hese echnologies, and wonderinghow you can pu hem o use.

his guide will answer quesions you migh have, and give you informaion abou:

How srucured and unsrucured documens compare

he benefis of srucure and XML

How Srucured FrameMaker fis in

Srucured auhoring environmens

Convering unsrucured documens

Where o go from here

Does My Organizaion Need XML?

his is he firs quesion o ask before embarking on seing up an XML auhoring sysem. Or a he very leas

you should ask wheher your organizaion could ge value from using XML. here is no quesion ha here i

a cos o seing up an XML sysem. Before making he invesmen, you should be sure ha i will benefi you

organizaion, boh wihin i self, and hrough he sharing of your asses wih oher organizaions.

Some quesions you can ask include:

Is our auhored conen an imporan business asse?

Mus we comply wih exising sandards (SD, Docbook, DIA, ec.)?

Is i imporan o share informaion asses wih oher organizaions?

Is collaboraive auhoring imporan?

Do we need o suppor differen auhoring/managemen ools o operae on he same conen?

Is i imporan o merge auhored conen wih oher informaion asses?

Do we deliver he same informaion in muliple oupu formas?

Do we need o mix and mach conen in differen publicaions?

Are we rying o improve or personalize he cusomer experience?

Are we ineresed in inelligen conen or adapive conen?

Do we localize our conen? Do we need o manage our conen in source conrol, or in even more powerful conen

managemen sysems?

Is difficul o say how many Yes answers mean your organizaion needs o manage is conen in XML

Bu he more you can answer Yes o hese quesions, he more you should consider XML as an enabling

echnology ha will have a good ROI for your organizaion, and for your inernal and exernal cusomers.

Srucure and XMLTe Business Case

Before embarking on a conversion from unsrucured documenaion o srucured and XML, you should

have an idea of he value i will add o your business. Informaion is an increasingly imporan business asse

Test drive Adobe FrameMaker 12

Try the ull unctionality o

FrameMaker 12 (as a part o

Adobe Technical Communication

Suite 5 sofware) in minutes

and without downloading the

sofware. Tutorials are also

included. Test-drive it now at

www.runware.com/clients/adobe/

techsuite.
http://www.runaware.com/clients/adobe/techsuite/http://www.runaware.com/clients/adobe/techsuite/http://www.runaware.com/clients/adobe/techsuite/http://www.runaware.com/clients/adobe/techsuite/http://www.runaware.com/clients/adobe/techsuite/


4/394


XML Authoring

he abiliy o manage and process asses is always an imporan par of any business. I follows ha improved

managemen and processing of informaion adds value o your informaion asses.

o answer modern informaion requiremens, we see new posiions wihin he enerprise, including:

Informaion Archiecure

Informaion Design

Informaion Engineering

hese posiions have one hing in common; hey focus on how compuer processing can improve he

delivery, managemen, and creaion of informaion asses. One oher hing hey have in common is his

Selecive Feaure Capabiliy Comparison

. You can publish o muliple formas auomaically. Oucomes: Wih he same conen, you can easily

produce PDF, online, and mobile oupu. You can se up a single build process ha publishes muliple

formas a once. Responsive conen.

. Your conen becomes more consisen, lowering coss and increasing flexibiliy. Oucomes: emplaed

informaion such as knowledge-base aricles, mainenance procedures, or proposals can be

auomaically verified for compleeness. ools can more easily process consisen daa.

. Your auhors can ge back o wha hey do bescreaing qualiy conen. Oucomes: Less ime spen onformaing decisions. Beer division of labor in he organizaion.

. Your conen becomes more predicable, herefore more usable. Oucomes: Users know wha o expec

and where o look in he informaion produc. Increased usabiliy increases user base and revenue.

. You can inegrae informaion flows for more accurae, complee conen and beer producs.

Oucomes: Breakdown of informaion silos. Auomaed processes o inegrae informaion from

differen deparmens.

. You can auomae and improve your business processes. Oucomes: Documenaion daa inegrae

wih oher daa processing. Auomaed ranspor of daa beween deparmens and processes. Provide

a single informaion f low o suppliers and cusomers. Reduce localizaion cossinegrae wih

localizaion processes.

. Your conen becomes inelligen and adapive, supporing more argeed markeing. Oucomes: he

righ informaion for he righ user. Conen adaps o readers role and conex.

. You can use a conen managemen sysem for unprecedened efficiencies. Oucomes: Manage

invenory of informaion asses. rack informaion changes and versions. Manage references and oher

dependencies auomaically. Assemble documen deliverables from a pool of opics. Reuse conen.

. You can personalize your conen, increasing response raes. Oucomes: Increase consumer ineracion

by responding o preferences, roles, and conex. Include user-auhored conen (commens, ips,

raings, ec.).

. You can reuse your conen, lowering coss while improving qualiy. Oucomes: Wrie opic once, use

ofen. Reduce localizaion cossranslae once per language, use of en.

For furher reading , you can see he Adobe blog pos, en Reasons o Srucure Your Conen ahttp://blogs

adobe.com/techcomm/2013/09/white-paper-ten-reasons-to-structure-your-content.html . his includes a

link o he full whie paper of he same name.
http://blogs.adobe.com/techcomm/2013/09/white-paper-ten-reasons-to-structure-your-content.htmlhttp://blogs.adobe.com/techcomm/2013/09/white-paper-ten-reasons-to-structure-your-content.htmlhttp://blogs.adobe.com/techcomm/2013/09/white-paper-ten-reasons-to-structure-your-content.htmlhttp://blogs.adobe.com/techcomm/2013/09/white-paper-ten-reasons-to-structure-your-content.htmlhttp://blogs.adobe.com/techcomm/2013/09/white-paper-ten-reasons-to-structure-your-content.htmlhttp://blogs.adobe.com/techcomm/2013/09/white-paper-ten-reasons-to-structure-your-content.html


5/395


XML Authoring

Preparing For Te JourneyUndersanding Srucure and XML

Before you sar working wih srucured documens, you need o ge ready. A good sar is o undersand

wha srucure is all abou, and he value you can ge ou of incorporaing srucure and XML in your work

flow.

If you are a FrameMaker user hen you should already be familiar wih he idea of srucuring your wriing

You adhere o your emplae design, and you use headings, liss, and oher formaing o caegorize and

organize he ideas in your work. In oher words, you give your work a concepual srucure. As a user ofunsrucured FrameMaker you capure ha srucure by using he emplae consisenly.

Using he emplae correcly no only helps you wrie in a srucured way, bu i also makes i easier fo

FrameMaker o process he documen. Consisen use of paragraph formas ses up ables of conens and

liss of figures, and paragraph formas can be used o auomaically apply maser pages. FrameMaker also

uses he documens srucure when saving a documen as HML, breaking he documen ino separae

HML files, or exracing conen o pos in header or fooer areas of each page.

For all he ways FrameMaker can process unsrucured documens, imagine how much more processing you

could perform if you capured more informaion abou he documen. Srucure is a way o capure exra

informaion abou a documen so ha a compuer can process he documen in more ways.

Inroducing Srucured FrameMaker

For a FrameMaker user, Srucured FrameMaker is he easies way o experimen wih srucured documens

I comes wih ready-made emplaes ha illusrae he exra value srucure gives you. If you currenly use

unsrucured FrameMaker, jus open he Preferences dialog box and se he Produc Inerface o Srucured

FrameMaker. his won change any of your exising work, and you can sill use all he unsrucured feaure

you know. he Srucured FrameMaker inerface simply enables exra feaures ha work wih srucure.

Seting he user inerface o Srucured FrameMaker

When you run Srucured FrameMaker, you can open samples of srucured emplaes and view he srucure

in he user iner face. o open a srucured emplae, choose File > New > Documentin he dialog box, click

Explore Srucured emplaes o open he srucured emplae browser. From here you can open sampleof many differen srucured emplaes.

A srucured emplae includes a definiion of he srucure a documen can have. his includes he names

of he differen srucure elemens, rules for wha an elemen can conain, aribues ha describe various

aspecs of he elemens, and rules o auomaically apply formaing o elemens depending on where he

are in he documen.


6/396


XML Authoring

Srucured FrameMaker is like an ouliner running on hyper-drive. In fac, he srucured emplae browse

includes ouline samples you can open and explore. he Srucure View shows he ouline opics in a

hierarchical ree ha corresponds wih he oulines hierarchy (choose StructureTools>Structure View).

Srucure View for an Ouline

In he Srucured View, you can drag opic bubbles o differen locaions o promoe or demoe a opic, or o

move a sub-opic ino a differen paren opic. Each bubble indicaes a srucure elemenelemens conain

documen conen or oher srucure elemens. When you drag an elemen o anoher locaion, FrameMake

updaes he formaing.

In addiion o hierarchy, srucure assigns aribues o elemens. In he ouline sample, you can see a ype

aribue (click he righ-hand PLUS mark in he bubble). Double-click he aribue o choose among prese

ouline ypes, and FrameMaker auomaically changes he ouline forma. his shows more of FrameMaker

formaing poweri can se documen formaing according o elemen aribues and documen srucure

he lis of sample emplaes includes more complex documens such as repors or muli-chaper books. Yo

should explore hese samples o see more of he hings you can do wih srucured documens.

his is a very brief inroducion o srucure in FrameMaker. he imporan poins o undersand are:

A srucured emplae can define he hierarchy a documen will have

he srucure view displays documen hierarchy as a ree of elemens

You can reorganize enire blocks of he documen by dragging elemens wihin he Srucure View

he emplae includes formaing ha auomaically adjuss according o elemen posiion

Elemens can have aribues ha af fec formaing or oher processing of he documen

Bu he mos imporan poin is hisbecause a documen includes srucure as meadaa, or informaion

abou he documen, his gives FrameMaker more opporuniies o auomaically process he documen

Elemen posiion can drive formaing of he ex. Elemen aribues can drive auomaic processing such

as formaing, condiional ex (or filering), header/fooer display, links, or even cusom implemenaions

ha perform documen processing. he informaion in srucure simply provides ha many more hooks a

compuer can use o auomaically process he documen. Auomaion means cos savings, fewer misakes

and less ime when creaing and mainaining mos ypes of echnical documenaion.


7/397


XML Authoring

Inroducing XML

he descripion of srucure above is focused on Srucured FrameMaker, one specific implemenaion ha

uses he added value of srucure. Exensible Markup Language (XML) is a vendor-neural, open forma

managed by he World Wide Web Consorium (WC). I also expresses he srucure of a documen, bu

hrough an open sandard. his means wo imporan hings:

Anybody can implemen a process ha complies wih he XML sandard

Any processes ha comply wih he sandard can share documen daa

If youve looked a HML source, XML will seem familiar o you. Like HML, XML consiss of ags enclosed in

angle brackes (such as ), and is sored in a ex f ile. he ags declare specif ic elemens, he same

as he bubbles in he FrameMaker Srucure View show he documen elemens.

Jus as a FrameMaker srucured emplae includes informaion o declare he elemens a documen can

have, you can declare he se of elemens for an XML documen ype, including rules for wha he elemen

can conain, and aribues for he elemens. In fac, XML is very much like Srucured FrameMaker, bu wih

wo major differences:

XML is an open sandard ha uses ex f iles o sore documen daa

Unlike Srucured FrameMaker documens, XML files do no include formaing

An XML file migh look like he following:

You can see ha he documen file is made up of ex characers. his has wo major advanages:

Firs, you can open he file in any ex edior, and you can modify he f ile wih any ex ediing process. he file

is said o use an open sandard, and anybody can creae sof ware o edi XML f iles. No only can a company

sell auhoring sofware, bu programmers can implemen ools o modify he documen in differen ways

hanks o his openness, you have probably loaded many XML f iles in your web browser or oher sofware

wihou even knowing i.

On he oher hand, because he file is in plain ex, bu i includes elemens, aribues, and oher daa, i is

very diff icul o work wih raw XML. he above example is very small, bu even ha is hard o read. Imagine

a full echnical manual for a sewage reamen plan in raw XML. Reading and auhoring so much XML isn

pracical wihou he help of sof ware o forma he documens and manage he meadaa.

Why Use XML?

If you made i his far, hen you have an idea abou wha a srucured documen is, and you know ha XML is

ye anoher forma o capure documen daasrucure and conen. Bu you should pause o undersand

wha XML can do for you, and be clear abou why you wan o embark on migraing from unsrucured

FrameMaker documens o Srucured FrameMaker and XML.


8/398


XML Authoring

XML is Open, No Proprieary

From he sar, a primary goal of XML has been o promoe ineroperabiliysharing of daa beween

differen processes. his means ha you can creae a documen wih one sofware applicaion, and open i

or process i in anoher. Many organizaions choose o use XML because i frees hem from relying on one

specific applicaion.

he openness of XML also makes i easier o creae exra ools o process documens. he mos commonly

used open source ool is he DIA Open oolki, which convers DIA XML o differen formas, includingCHM, PDF, WebHelp, and Eclipse Help. he poin is, he XML communiy is large, and i has many conribuors

XML Suppors Sandards Like DIA, DocBook, or S1000D

here are a number of exising XML sandards ha focus on documenaion for specific indusries. For

example, he SD sandard was developed for miliary aircraf, and has since been expanded o suppor

documenaion for land, sea, and commercial equipmen.

For each sandard, here is a robus communiy ha can offer wisdom via forum poss, emplaes, open

source ools, and producs ha focus on geing he mos ou of hese sandards. Many indusries expec

documenaion o suppor hese sandards, and you migh be planning o migrae your documenaion ino

compliance.

XML Has Rules

XML includes rules ha describe he required organizaion of each elemen in he documen. An XML file

ha follows hese rules is valid, and you can use sofware o auomaically make sure a documen or book

is valid.

For example, you migh specify ha a simple proposal should have he following conen sequence:

. Proposal ile

. Execuive summary

. Projec descripion

. Schedule

. Cos

Wih unsrucured documens you can sugges his srucure, bu you can enforce i. Wih XML he conen

rules can be enforced, and a parser can verify ha he documen is valid. For documenaion ha mus

comply wih sandards, his can grealy reduce errors and cos.

Human vs. Auomaic Validaion of Srucure


9/399


XML Authoring

Daabase PublishingXML As Daa ranspor

XML is increasingly pu o work as a way o send daa from one applicaion o anoher. Using srucure o

sore conen in elemens ranslaes easily ino a daabase srucure. Mos daabases can expor daa as XML

which can hen be brough ino a documen. XML is a perfec medium for daabase publishing. For example

you can use XML as an inermediary o publish a daabase in Srucured FrameMaker.

Daabase Publishing wih FrameMaker

XML Suppors Reuse

here are a number of ways o reuse XML documens. he boom line is ha you can wrie somehing once

and use i ofen. We all know abou he use of boilerplae conen. Re-use akes ha idea o a higher level.

Same opic/Muliple Documens

XML sandards suppor opic-based wriing. XML makes i easy o build and manage muliple documensha share he same opic. For example, if you have many producs ha include he same login procedure

you only wrie ha once, and use i for every produc.

Filered Conen

By using aribues and oher meadaa in XML, you can fine-une your oupu. For example, DIA include

feaures o filer conen based on audience or plaform, and ways o manage cross-references or oher

referenced conen for differen oupus. For prined oupu a documen can include he full conen, bu fo

mobile oupu you migh choose o limi i o shor descripions. Because XML describes srucure, his is

easy o do.

Or consider he problem of cusomized sofware developmen. If your company cusomizes is producs fo

each clien, you need a way o publish differen versions of he same documen. Using meadaa, you canspecify which cliens each opic applies o. When you are ready o deliver he informaion, you f iler based on

he meadaa o creae he appropriae oupu.

Filering by atribue for clien-specific deliverables

Muliple Oupus


10/3910


XML Authoring

You can use he same conen o generae documens for prin and online use. ooling exiss for XML

sandards like DIA and Docbook o publish he same conen o many oupus. If exising ools don give

he oupu you need, you can use open source echnologies o implemen cusom oupus. From he same

source, you can creae oupus for prin, deskop, or mobile devices, and use filering o f ine-une he resuls

Generaing differen oupus from XML source

XML Inegraes wih Localizaion Processes

Conen localizaion can represen a large par of publishing coss. E xac numbers vary for produc localizaion

bu as a general rule abou a hird of he oal localizaion cos is for publishing and producion. A publishing

work flow buil on XML and srucured auhoring les you auomae much of he publishing effor, so you cangrealy reduce he ongoing coss associaed wih localizaion.

In addiion, mos localizaion vendors use ools ha inegrae wih XML. Especially for publicaions ha use

XML sandards such as DIA or SD, he ooling is in place o sreamline localizaion projecs . When you

couple his wih he benefis of re-use, XML provides a signif ican ROI for localizaion of conen.

XML Suppors Collaboraion

Because XML is an open sandard, i is a perfec medium for collaboraion. An XML edior like Adobe

FrameMaker can provide full-blown publishing capabiliies, or an edior like FrameMaker XML Auhor can

provide jus collaboraion feaures a a lower cos. You can even find XML ediors ha work on he web, o

you can use a ex edior running in a programmers inegraed developmen environmen. he imporan

hing is ha wih XML you are free o mix and mach your auhoring ools, and you can choose he ool hais mos appropriae for each individual conribuor.

Why Use Srucured FrameMaker?

Srucured FrameMaker is a full-feaured XML publishing package. No only does i offer ools o edi XML

hrough a rich user inerface, bu i maps your XML o he powerful FrameMaker formaing capabiliies you

already knowyou can use ools you already know o design he look of your final documens.

Boh he srucured and unsrucured versions of FrameMaker excel in creaing, ediing, and producing

complex conen, so auhors can easily creae PDF files wih linked bookmarks, cross-references, ables o

conens, and indexes. Moving o srucured FrameMaker gives you he bes of boh worldsyou can ake

full advanage of XML wihou giving up he powerful auhoring environmen you appreciae in unsrucured

FrameMaker.

Auhoring Visually

Srucured FrameMaker gives you several differen ways o look a your documen. he documen window i

almos idenical o he documen window in unsrucured FrameMaker. he documen displays in WYSIWYG

showing he formaing you have designed for prined oupu.

Inside he documen window, you have he opion o display elemen ags for a srucured documen. he ag

boundaries include conrols o expand and collapse elemen conen. For example, you can collapse enire

secions o keep your focus on one specific secion.


11/3911


XML Authoring

Showing elemen boundaries, wih a collapsed secion ag

In addiion, FrameMaker includes he Srucure View, which shows he documen elemens in a hierarchica

ree. You can expand and collapse he elemens, and drag hem o rearrange he documen srucure.

Te Srucure View

Ediing XML Code


12/3912


XML Authoring

here are imes when is more useful o edi raw XML code. You can swich your documen o he XML view

o edi XML code, run XSL rans forms on he documen, or use XPah o search for specif ic ypes of conen in

he documen. XML View is a powerful way o dig in and hack a he XML code of your documen. Srucured

FrameMaker doesn require you o work his way, bu i doesn sop you, eiher.

Ediing in XML View, using XPah o find all figure elemens in he documen

Excellen Prin and PDF Oupu

Srucured FrameMaker provides everyhing you need o creae high-qualiy prin and PDF oupu. Many

oher XML auhoring ools do no include a high-qualiy prin soluion, and designing XML layou for prin

and PDF is much more complex han publishing o he web. emplae design for srucured FrameMaker i

similar o wha you already know for unsrucured FrameMaker. Wih Srucured FrameMaker you can apply

your curren knowledge and abiliies o formaing XML documens for prin or PDF oupu.

Saving XML as PDF is easier wih srucured FrameMaker han i is wih any oher ool. FrameMaker

auomaically creaes bookmarks and links in PDF based on he elemens in your documen.

You can also use FrameMaker o generae a CSS syle shee ha maches he documens WYSIWYG

formaing. Any XML processor ha suppors CSS can use he syle shee o reproduce he look and feel o

your documen.


13/3913


XML Authoring

Auomaic and Enforced Formaing

In srucured FrameMaker, auhors don forma heir documens wih paragraph and characer ags

Insead, hey inser elemens and elemen conen ino heir documens. Documen formaing is applied

auomaically based on formaing informaion ha is embedded in he srucured emplae. he srucured

emplae includes srucure definiions in an Elemen Definiion Documen (EDD). his EDD references

formaing informaion such as paragraph or characer formas, and applies ha formaing o elemens in

he documen.

Elemen formaing is conex-sensiive; ha is, a single elemen can appear wih differen formaing in

differen srucured posiions. A single LisIem elemen, for example, can replace half a dozen (or more)

paragraph ags. he following figure shows how formaing of he LisIem elemen changes based on is

posiion and he value of he paren Lis elemens ype aribue.

NOE: Formaing in his example is conrolled boh by he nesing level of he LisIem and by he value o

he ype aribue on he conainer elemen Lis .

Lis iem formating in differen conexs

As you posiion informaion in he s rucure, he conex-sensiive formaing updaes immediaely according

o he elemen posiion. his dynamic formaing is exremely powerful when combined wih FrameMaker

WYSIWYG inerface.

On-he-Fly Validaion (Guided Ediing)

We have already seen ha XML can include rules ha deermine a required order and hierarchy of elemens

For example, a proposal documen could require a Proposal elemen for he documen roo, followed by

a ile elemen, hen an ExecuiveSummary, a ProjecDescripion, a Cos elemen and a Schedule. he

ExecuiveSummary could require a ile, followed by any number of Para elemens.

A documen ha omis one of hese elemens, or uses he elemens in a differen order, violaes hese rules

he documen is said o be invalid. FrameMakers Srucure View shows in real ime where required conen

is missing, and which elemens are valid o inser a he curren locaion.


14/3914


XML Authoring

FrameMakers Srucure View indicaes ha a required elemen is missing wih a small red square

Te Elemens caalog indicaes ha a Para elemen is allowed here.

A he same ime, FrameMaker doesn ie you o always creaing valid conen. As you edi, you can add

conen ou of sequence. FrameMaker will show where he documen srucure is invalid, bu i will no sop

you from working jus o require ha he documen is always valid.

Relaively Low Licensing Cos

FrameMaker gives you everyhing you need o build a srucured auhoring environmen. Srucured

Applicaions auomaically recognize documen ypes, and load XML ino he appropriae documen

emplaes. hese emplaes give you a WYSIWYG auhoring environmen ha you can use wih Srucured

FrameMaker, or deploy o conribuors using FrameMaker XML Auhor. he emplae auomaically applie

formaing o your documen according o he XML srucure.

Srucured FrameMaker includes ools o process he XML. hese include inegraion wih XSL (syleshee

o ransform your XML), inegraion wih he DIA Open oolki, XPah processing, Srucured FrameMake

read/wrie rules, FrameMaker ExendScrip, and he FDK.

You also ge ools o creae your Srucured Applicaion, and ools o conver unsrucured documens o

srucure. If you currenly use unsrucured FrameMaker, hen you already have all hese capabiliies a hand

Why no se he preference o use he Srucured FrameMaker produc inerface, and ake advanage o

hem?

Why Use FrameMaker XML Auhor?

Srucured FrameMaker gives you he ools o creae a full XML auhoring environmen, as well as he

auhoring sofware and he capabiliy o prin or generae PDF versions of your documens. Wha if some

members of your eam only need o add conen o an exising XML publicaion? For hese eam membersFrameMaker XML Auhor is he perfec soluion.

For example, assume you need o include produc specificaions in your final publicaion. You migh

wan produc engineers o direcly mainain he produc specificaion documens, because hey own ha

informaion. Wih XML Auhor, you can give hem access o Srucured FrameMaker emplaes, and have

hem work wih an already def ined FrameMaker srucured applicaion. hey can hen auhor he conen in

valid XML ha you can include in he final publicaion.

XML Auhor suppors enough feaures o creae and edi XML documens ha comply wih a defined

srucured applicaion. A he same ime, is fully compaible wih he Srucured FrameMaker emplaes yo

have creaed. And i suppors any oher processing you have se up in a srucured applicaion, including XSL

processing, read/wrie rules, or any FrameMaker plug-ins you may have included in your work f low.


15/3915


XML Authoring

Licensing cos for FrameMaker XML Auhor is even lower han he cos for FrameMaker. his makes XML

Auhor an excellen ool o promoe collaboraion wihin your organizaion.

Componens of a Srucured Auhoring Environmen

For unsrucured FrameMaker, you se up he auhoring environmen by implemening your documen

emplaes. Once you define a emplae and disribue i, auhors are ready o begin work. Wih srucured

FrameMaker he auhoring environmen is more powerful, and you mus implemen and deploy more file

o pu he environmen ogeher.

Auhoring Only in Srucured FrameMaker

You can implemen srucure in FrameMaker wihou providing suppor for XML ediing. If you have no

immediae need for XML, you can sill ge value from srucured auhoring by imposing a srucure on you

publicaions, formaing documens auomaically, and using aribues o filer your conen.

o esablish a basic srucured auhoring environmen in FrameMaker, you mus creae an elemen definiion

documen (EDD) ha declares he elemens in your srucure. Addiionally, you need o link he elemen

definiions wih forma ing informaion. here are hree ways o link elemens in he EDD o formaing:

Formatting template

You can assign formaing based on he various ags (paragraph ags, characer ags, and so on)

in a emplae. If you already have a formaing emplae, you can reuse he ags in ha emplae.

Format change lists

You can creae named formaing definiions in he EDD. hese forma change liss provide parial

formaing specifica ions and inheri he res from a few base paragraph ags. For example, you can

specify one Heading paragraph ag ha specif ies fon size and inden for H. For nesed heading

elemens, you can call a forma change lis ha uses he same paragraph ag, bu reduces he fon size

and increases he inden.

Embedded formatting

You can specify formaing by wriing he formaing ino each elemen definiion.

Comparing hree ways o specify bulle formating in he EDD

If you choose o use forma change liss or embedded formaing , you will sill need emplaes o se up basic

formaing such as maser page layous and cross-reference formas.

Once you creae he EDD and specify your formaing in a emplae, you hen combine he wo componen

o creae a single, srucured emplae. o do his, you open he formaing emplae and impor elemen

definiions from he EDD (using File>Impor>Elemen Definiions). he resuling file is your srucured

emplae which you disribue o documen auhors. Remember o keep a separae copy of he EDD so ha

you can make updaes and impor hem ino your se of emplaes.


16/39


17/3917


XML Authoring

Te Srucured Applicaion ranslaes XML ino WYSIWYG

Using FrameMaker Srucure and XML

o show wha goes ino seing up a srucured auhoring projec , we can look a a simple proposal. Assume

your eam produces hundreds of proposals a year. Furher assume ha in he fuure your company wans o

process archived proposals o exrac merics and rends. o simplify proposal auhoring, and o normalize

he proposal daa a creaion ime, you decide XML gives you a perfec soluion. Your auhors can use a

familiar ool (you already use FrameMaker in your eam), you don need o purchase new ools, he resuling

files can be sored as XML (ex-based), and managemen can access and process proposal daa in he fuure

NOE: here are a number of open source XML daabases ha you could use o exrac specif ic conen from

a collecion of XML f iles. For example, you could use a daabase o exrac cos esimaes from all he savedproposals.

Conen Analysis

Before building he srucured applicaion for your proposals, you should analyze exising proposals o

idenify heir componens and srucure.

Reviewing exising proposals


18/3918


XML Authoring

Based on analysis, you can creae a conen map. Analysis of your proposals resuls in he following sequence

ile

Execuive Summary

Execuive Summary:ile

Execuive Summary:Paragraph (one, only)

Projec Descripion Projec Descripion:ile

Projec Descripion:Paragraph (one or more)

Cos

Cos:ile

Cos:Paragraph (one or more)

Schedule

Schedule:ile

Schedule:Paragraph (one or more)

his is a simple exampleyou could probably build he srucured applicaion for his proposal wihou h

benefi of a formal analysis. For larger projecs you will see ha formal analysis is a crucial firs s ep.

Choosing an EDD Sraegy

he EDD defines he s rucure ha FrameMaker will use when i loads he srucured documen. I also map

he srucure o FrameMaker formaing. here are several ways o sar building your EDD. You can:

Creae he EDD yourself, saring from scrach

Impor a DD or Schema o creae an EDD wih srucure definiionsyou hen add formaing rules ohose srucure definiions

Modify an exising EDDFrameMaker ships wih a number of EDDs you can use as saring poins

Use an exising Srucure ApplicaionFrameMaker ships wih Srucure Applicaions for sandards suchas DIA, XHML, SD, and ohers. You can use hose applicaions as-is, or modify he emplaes and

EDDs o refine he documen formaing.

For he Proposal projec, we will creae an EDD from scrach. his bes illusraes he workings of an EDD

wihin a Srucure Applicaion.

Building he Proposal EDD

Now ha we have analyzed our proposals and decided on he way for ward, les build he EDD. o do his:

. Make sure youre using Srucured FrameMaker. If he menu bar doesn include he Elemen and

Srucureools Menus, you mus swich o he Srucured FrameMaker produc inerface. Don worry

you can always swich back o unsrucured, and his will no affec your abiliy o edi unsrucured

documens. Choose Edit>Preferences>Global>General. For Produc Inerface, choose Structured

FrameMaker.

. Creae a new EDD

Choose StructureTools>New EDDo open a new EDD file.

. Open he Srucure View and Elemen Caalog. If hey are no already open, chooseStructureTools>Structure

View, and hen choose Element>Element Catalogo open hem.


19/3919


XML Authoring

Geting sared wih an EDD

4. In he Srucure View, click o he righ of he red box (which indicaes ha addiional informaion is

required). Noice ha he conens of he Elemens caalog change because of he new cursor locaion

In he Elemens caalog, selec Conainer and click Inser. he Conainer elemen and a child GeneralRule

elemen are insered (as shown in he following figure).

Adding he general rule for Proposal

. Click o he righ of ag and ype Proposal o give his elemen a name. Noe ha elemen names canno

conain spaces.

. Ener he Proposal elemens general rule o define he proposal conen. his should be he op-leve

elemens we idenified in he documen analysis. Click o he righ of GeneralRule and ener:

ile, ExecSummary, ProjecDescripion, Cos, Schedule


20/39


21/3921


XML Authoring

. Using he Elemens caalog, inser an Elemen bubble. Name he elemen ExecSummary, make i a

conainer, and specify he following as he general rule: ile, Para+

Defining he ExecuiveSummary elemen

Repea hese seps o define he remaining elemens. Give hem he following names and general rules:

Elemen General Rule

ProjecDescripion ile, Para+

Cos ile, Para+

Schedule ile, Para+

ile

(ype he word EX, surrounded by angle brackes)

Para

(ype he word EX, surrounded by angle brackes)

Be sure o save your EDD as ProposalEDD.fm.

he EDD now conains he srucure you wan for proposals, bu wih no formaing. Before adding he

formaing informaion, i s a good idea o es he srucure.

esing he EDD

o es he EDD, impor i ino a documen and hen verify ha you can creae he srucure you expec. A his

poin he documen will no have any formaing, bu you can verify ha he srucure is working as expeced

. Creae a new, blank documen. Choose File>New>Document, and hen click Porrai.

. Impor he EDD ino he new documen. Make sure he new documen and he EDD are boh open. Wih

he new documen acive, choose File>Import>Element Definitions. In he Impor From drop-down

selec your proposal EDD, hen click Impor . If your EDD doesn appear in he drop-down lis, make sure

ha he EDD file is open, and ha you have saved i.


22/3922


XML AuthoringImporing he EDD

. Now ha he elemen definiions are impored in your documen, you can sar adding srucure o i

Click in he new documen and open he Elemen Caalog. I will show he Proposal elemen as he only

valid elemen a ha locaion. Inser he Proposal elemen, and hen inser a ile elemen.

he Elemen Caalog, showing he Proposal as he valid op elemen in he new documen

. Coninue insering elemens unil he proposal srucure is complee. You can add ex conen if you like

bu you don need o a his ime. he final resul will appear as follows in he Srucure View:


23/3923


XML Authoring

Te complee Proposal srucure

. Save your work! Save he new documen as srucured_proposal.fm

If your srucure doesn mach his f igure, go back o your EDD and correc i. hen impor he EDD ino you

documen again.

Adding Formaing o he EDD

You have now buil an EDD ha provides srucure for a simple proposal. However, when you ype conen

no formaing is applied. By defaul, FrameMaker applies a basic Body paragraph forma o any ex conen

his secion describes how o provide formaing, and how o auomaically inser he correc ex for he

various iles.

Before assigning formaing o he EDD, you should define he basic formas you will use in your documen

ype placeholder ex in your proposal documen and use sandard FrameMaker echniques o modify he

Body and Heading paragraph formas . Make sure o Apply All o ge your changes ino he paragraph forma

caalog.

Choose Format>Paragraphs>Designero make your changes. he EDD will use Body and Heading as he

basis for all oher formaing. When you have your basic Body and Heading formas he way you wan hem

is ime o se formaing in he EDD.

Specify Formating for Para

In proposalEDD.fm, modify he Para elemen definiion o include a formaing rule. o specify ha Para

should always use he Body paragraph ag, click under he GeneralRule elemen, add a exFormaRule

elemen, and hen add an ElemenPgfFormaag elemen. ype Body as he ex for he ElemenPgfFormaag

elemen.


24/3924


XML Authoring

Adding formating rules o he EDD

Specify Formating for ile

For his elemen you need more complex formaing rules. ile should auomaically display secion iles

such as Execuive Summary, Projec Descripion, and so on. You mus wrie a conex rule ha specifies wha

ex o display for each ype of heading, and specif y ha ile uses he Heading paragraph ag.

In proposalEDD.fm, modify he ile elemen definiion o use he Heading paragraph ag. Add he same

exFormaRules and ElemenPgf Formaag elemens as you did for he Para elemen, bu give he forma

name, Heading. Remember ha in FrameMaker paragraph forma names are case-sensiive. For example

Heading and heading are no equivalen.

Nex, add a prefix rule o he ile elemen. Prefix rules specify ex ha should appear a he beginning of he

elemen. Based on he iles posiion, youll specify which ex o display. his will auomaically provide h

iles according o he proposal srucure.

o add a prefix rule o he ile def iniion in he EDD:

. Posiion he cursor in he ile elemen definiion o inser a bubble wihin Conainer, and afe

exFormaRules. his will be a child of Conainer, and a sibling of exFormaRules.

. Inser a PrefixRules elemen.

. Inser a ConexRule elemen. he If and Specificaion elemens are insered auomaically. h

conex rule will deermine which ile conen you wan.

. For Specificaion, ener ExecSummaryhis rule assigns ex o he Exec-Summary ile.

. Posiion he cursor as a child of If, afer Specificaion, and inser a Prefix elemen.

. For he Prefix elemen, ype Execuive Summary

. Add ElseIf elemens o he conex rule o repea hese seps for he oher elemens ha need

iles. Creae ElseIf saemens for ProjecDescripion, Schedule, and Cos. Give each prefix he

appropriae ile ex.


25/3925


XML Authoring

Your resuls should be similar o he following:

ile formating rules

Be sure o save your work!

es Te Formating

o es your formaing , impor he changed EDD ino your exising proposal documen. Each secion should

now display he ile ex you specif ied. Bu he main proposal ile should be blank (you can ype whaeve

ile you wan).

Te formated Proposal documen


26/3926


XML Authoring

Building a Srucured Applicaion

So far you are se up o creae a proposal as a srucured documen. Bu o se up a work f low ha include

auhoring and soring he proposals as XML, you need o build a srucured applicaion. his applicaion lis

he componens of he srucured auhoring environmenone of hose componens will be a emplae

documen ha uses he EDD you jus creaed. Bu you will also need oher componens.

For his exercise well build he minimal srucured applicaion, which includes he following files:

DD, o declare srucure rules for he XML

emplae file, o combine sruc ure rules and formaing in FrameMaker

When we have he DD and emplae file in place, well add hem o a srucured applicaion, and read ha

applicaion ino your FrameMaker session. hen well es i for ediing XML documens.

Creaing a DD

We can creae an XML DD from he EDD you jus creaed. o do his:

Open he EDD f ile you jus creaed (ProposalEDD.fm).

Wih he EDD file acive, choose StructureTools>Save As DTD. Specify he file name (proposal.

dd) and where you wan o save he file, and hen click Save. In he Use Srucured Applicaion dialog box, leave he defaul selecion, , and click

Coninue.

In he Selec ype dialog box, selec XML and hen click OK. he DD file is wrien ou o he locaion youspecified.

has all here is o i. Remember he DD file locaion so you can add i o he srucured applicaion laer.

Creaing a Srucured emplae

he applicaion will use your srucured emplae when you open an XML file. FrameMaker reads he XML

srucure, hen uses he emplaes EDD o map he srucure o he emplaes formaing.

o creae a s rucured emplae:

Open he srucured proposal documen you jus creaed (srucured_proposal.fm).

Delee all he conen from he emplae. his emplae will now be empy.

Use File > Save Aso save a version of he file named proposal_emplae.fm.

Now you have a srucured proposal emplae, ready o use. Remember ha his emplae already has he

EDD informaion impored ino i. If you decide o change he EDD, you can always impor hose changes ino

he emplae file a a laer dae.

Creaing a Proposal Srucured Applicaion

Now ha you have he DD and emplae file, you can make a srucured applicaion. o do his, you wil

specify he DD and emplae files in he Srucured Applicaion Designer o creae he applicaion enry in

he Srucured Applicaions file. When has complee, you will load he modified applicaion file ino you

curren session. For subsequen sessions, FrameMaker will load he new applicaion auomaically.


27/3927


XML AuthoringTe Srucured Applicaion Designer

Choose StructureTools>Structure Application Designer.

Specify he locaions of he DD and he emplae files. hen give a name for he srucured applicaion. Inhe above figure, he name is Proposal.

Click Save. By defaul he designer saves your applicaion in he roaming srucured applicaions f ile. Afesaving your applicaion, click Close.

esing he XML Auhoring Environmen

Now ha we have defined he s rucured applicaion for a proposal, we can edi he proposal as an XML f ile

We can use FrameMaker o save he srucured documen as XML, and from hen on we can keep he daa in

XML. We can open i in FrameMaker whenever we like, or edi he f ile in any oher XML edior.

he firs sep is o load he Proposal srucure applicaion ino he FrameMaker session. When you saved

he applicaion definiion, by defaul FrameMaker saved i o he Applicaion Definiions file for your user

accoun. Whenever you log ino FrameMaker, ha applicaion definiions file loads, and you can use he

Proposal applicaion.

o load i for he fir s ime, well load he applicaion definiion wihou resaring FrameMaker:

. Choose StructureTools>Edit Application Definitions o open he Applicaion Definiions file. his file is

named srucapps.fm. A he boom of he f ile, in he las secion before Defauls, you should see you

Proposal applicaion definiion.

. Wih he Applicaion Definiions file acive, choose StructureTools>Read Application Definitions. his

loads he new definiion ino your FrameMaker session. Now you can close he srucapps.fm fi le.

he nex sep is o open your srucured proposal and save i as XML. Wih he srucured proposal acive

choose File>Save As. A he boom of he dialog box, se he Save As ype o XML, hen click Save. A dialog

box appears asking you which srucured applicaion you wan o use. Be sure o choose he Proposa

applicaion. (You will see ha FrameMaker ships wih a long lis of ready-made srucure applicaions.)


28/3928


XML Authoring

Choosing he Proposal applicaion

FrameMaker saves an XML version of he file o your disk. Go ahead and close he srucured_proposal.fm

file (he FrameMaker documen) and open srucured_proposal.xml. he same dialog box appears asking

which srucured applicaion o usebe sure o use Proposal.

he XML version of he documen should look jus like he srucured .fm documen. Bu his documen is in

XML. Add some conen o he documen. hen wih he XML documen acive, swich o XML view o see

he raw XML for your proposal documen. You can also open he XML file in a ex edior if you wish . Use he

XML view o run ransforms on he conen, or use XPah o search hrough your documen.

Viewing he proposal XML

Wrap-up

Youve jus walked hrough he process o design, implemen, and use a srucured applicaion o edi XML

files. his was a very simple case, bu i illusraes he basic seps. You should be able o see ha Srucured

FrameMaker is a powerful ool for ediing XML documens, and producing formaed oupu.

here is some effor in creaing a srucured applicaion, bu once you have he applicaion in place, he

benefis o your work flow become apparen. If you wan o work wih XML, Srucured FrameMaker gives

you everyhing you needunparalleled formaing capabiliies, bes of breed documen processing, and a

full range of XML processes including XSL, XPah search, and inegraion wih he DIA Open oolkio recap, he seps o se up XML ediing in FrameMaker include:

Perform conen analysis

Decide on srucure

Implemen he XML srucure (a DD or Schema)

Implemen he Srucured FrameMaker emplae, including srucure (he EDD) and formaing

Creae he srucured applicaion

es he applicaions handling of XML and formaing


29/3929


XML Authoring

When planning a srucured applicaion, you should consider a few poins.

Documen srucure can be sric or loose. Very sric srucure rules may disallow elemen combinaions ha

auhors will need. hese limis can make i difficul o auhor a documen. On he oher hand, a very loose

srucure is necessarily more complex, and he DD and EDD migh be diff icul o mainain. his is because

more elemens are required as you increase he number of possible combinaions and srucures. Finding

he balance beween hese exremes can be difficul. his is one reason ha many organizaions prefer o

use an exising sandard.

here are many exising XML sandards you can use. One significan advanage of using sandards is sharing

you can easily share your files wih any oher organizaion ha uses he same sandard. Anoher advanage

is ha much of he work o implemen your ediing environmen is already done for you. Srucured

FrameMaker ships wih srucured applicaions already in place for many sandards, including DIA . and

., Docbook, SD, and XHML. Before invesing in creaing your own DD, is always a good idea o

look a hese sandards and see wheher hey will sui your purpose.

Migraing Unsrucured Files o Srucure

Migraing legacy documenaion o XML is a common requiremen once you decide o work in XML. If

srucure and XML can add value o your planned informaion asses, hen i follows ha migraing legacy

asses o XML can add even more overall value.

Srucured FrameMaker includes a conversion able uiliy ha you can use o ransfer unsrucured

FrameMaker files over o whaever srucure is defined in your srucured applicaion. Once convered o

srucure, you can save he documens as XML o complee he migraion.

he conversion able maps formaing componens in your documen o an elemen srucure. he

componens i can map include paragraph ags, characer ags, markers, cross-references, and able

componens. You can creae a conversion able ha works wih a given emplae, and auomaically generae

srucured copies of any documens ha use ha emplae.

he conversion resuls you can achieve depend on he following facors:

consisencyDocumens Documens ha use a FrameMaker emplae consisenly, wih few orno formaing overrides, will conver beer han documens ha are full of overrides and cusomparagraph or characer ags.

Similariy beween unsrucured and srucured documensWhen you perform your documenanalysis and se up he EDD for your srucured applicaion, you can choose o implemen a

srucure ha is similar o your legacy documens. he more similariy you can achieve, he easier he

conversion process.

IP: Wha if your legacy documens don mach your desired srucure? For example, wha if you wan o

use an XML sandard ha is unlike your legacy documens? In ha case, you can creae an inerim EDD ha

maches your documen srucure, and hen conver he documens o ha XML. Once in XML, you can use

exising ools such as XSL o furher modify your XML documens and bring hem ino compliance wih he

sandard you chose.

he seps you ake o migrae your legacy documens include:

Clean up he legacy documens

Creae he conversion able

Generae your srucured documens

Save he srucured documens as XML

he following secions illusrae hese seps.


30/3930


XML Authoring

Cleaning Up Legacy Documens

Unsrucured FrameMaker auhors are no srangers o he idea of srucured documenaion. FrameMake

includes repor and book emplaes ha encourage you o order documens via headings, liss, and charace

ags. For example, headings creae a hierarchical srucure which is no unlike he srucure you would declar

in XML.

he firs sep for conversion is o make sure your documens use he emplaes as hey were designed. You

should check he following:

Make sure variable definiions are up o dae. In addiion, i s bes o use variable names wih no spaces inhem.

Updae all references in your documens, including cross-references and ex inses. Correc any unresolvedreferences.

For documens wih condiional ex, show all condiions. Srucured FrameMaker creaes XML hamainains your condiional ex se ings. Bu when convering o s rucure, you need o show all condiiona

ex o make sure i ges wrapped correcly in srucure elemens .

Make sure he ordering of your conen is correc. For example, heading s rucure should no skip headinglevels. Heading, Heading, Heading is correc, bu Heading, Heading is no.

Eliminae forma overrides for paragraph, characer, and able formas. You can use he Find/Change dialogbox o search for hese overrides.

Creaing he Conversion able

he conversion process creaes srucured elemens from FrameMaker formaing componens such as

paragraph ags, characer ags, markers, cross-references, and able componens. o begin he conversion

selec a documen ha is represenaive of your ypical conen. his documen should conain examples

of all of he formaing ags ha would occur in your documens. hese ags should be used in heir logica

sequences (as hey would occur in documens), so a formaing emplae ha shows examples of each

paragraph ag in alphabeical order is no a good example documen.

o begin building he conversion able:

. Open he example documen you wan o use, and save a copy of i. his will be your working documen

. Open he EDD for he srucured applicaion ha you are convering o, and impor he elemen definiions

ino your working documen.

. Wih he working documen acive, choose StructureTools>Generate Conversion Table. Selec Generae

New Conversion able, and hen click Generae.

Creaing a new conversion able

FrameMaker scans he working documen and creaes a lis of he formaing componens ha occur in his

documen. Any ags ha are defined in a forma caalog bu no used in he documen are no included in

his lis.


31/3931


XML Authoring

Excerp of a new conversion able

he enries in he conversion able idenify he ype of formaing objec o map, and give defaul names fo

he elemens. In he above example, a paragraph agged as Reporile will ge wrapped in he Reporile

elemen, and a variable named able Coninuaion will ge wrapped in he ableConinuaion elemen.

If you use he defaul generaed able, he resuling srucure will probably no mach he EDD for you

srucured applicaion. o change he able, you will add srucure rules in he firs column, and change he

names of elemens in he second column. You can also add qualif iers o fine-une he conversions.

For example, you can change he P:Body enry o wrap body paragraphs in a Para elemen. You can also

change he able o wrap P:Heading in a Heading elemen, and hen wrap any Heading elemen and he

following Para elemens in a Secion, as follows:

As you make hese changes, you should save and es he able. o es i, make your working documen acive

hen choose StructureTools>Utilities>Structure Current Document. Selec he conversion able documen in

he drop-down lis, and hen click Add Srucure. FrameMaker creaes a new, uniled, srucured documen

Display he srucure view for ha documen and verify ha you go he srucure you wan.

Keep on refining and esing he conversion unil you are saisfied wih he resuling srucure.


32/3932


XML Authoring

If you need o map several paragraph ags o he same elemen and hen wrap hem ino differen parens

you use he hird column for a qualifier. Is common, for example, o have a LisIem elemen has used

for boh bulleed liss and numbered lis s. Once he bulle and sep paragraphs are wrapped in he LisIem

elemen, you need a way o disinguish wheher hey belong in OrderedLis or UnorderedLis. o make hi

disincion, you use he qualifier column, as shown in he following example:

here are many oher deails abou creaing conversion ables. FrameMaker ships wih he online Srucure

Applicaion Developers Guide, which includes all you need o know abou creaing conversion ables and

wrapping elemens according o conen rules.

Conversion Example

he bes way o illusrae he way a conversion able wraps unsrucured conen in elemens, and builds he

documen ino a hierarchical srucure, is o show an example. We can sar wih an unsrucured ouline

aken from he sandard emplaes, generae a conversion able, hen modify i o build a ree of elemens

ha correcly represens he oulines hierarchy.

Open he Ouline Documen

Firs, les sar wih he ouline documen. Open he emplae browser (choose File>New>Document, hen

click Explore Standard Templates), and open a sample of he Harvard ouline.

Te sample Harvard ouline


33/3933


XML Authoring

Creae he EDD

Analyzing he ouline, you can see ha i needs jus a small number of elemens in he EDD.

he EDD defines he elemens, conainmen rules for each elemen, and he formaing for heir ex. he

elemen lis and heir conainmen rules are:

Ouline (he roo elemenconains a ile, followed by Auhor, hen followed by he ouline BodyGeneral Rule: ile, Auhor, Body

Body (conains any number of ouline iems)General Rule: iem*

ile

General Rule:

AuhorGeneral Rule:

p (for paragraphs wihin each iem)General Rule:

iem (conains he iem ex, followed by any number of paragraphs, hen followed by an number of ohe

iems)General Rule: , p*, iem*

In addiion, he EDD specifies paragraph formaing for he ouline. his is mos imporan for he ouline

iems and paragraphs because ha is wha deermines iem indens and numbering. he EDD uses he same

paragraph formas ha exis in he emplae, and uses forma rules o deermine how o apply hose forma

according o iem nesing:

A forma rule o assign paragraph formas according o nesed iems

Before you conver he ouline o srucure, you will impor he EDDs elemen definiions ino your ouline

documen.

Generae he Defaul Conversion able

he nex sep is o creae he conversion able. Wih he ouline documen acive, choose

StructureTools>Generate Conversion Table. he resul is a defaul conversion able:


34/3934


XML Authoring

Defaul conversion able for an ouline

If you were o run his conversion able on he ouline, you would ge he following resuls, which are

obviously incorrec:

Edi he Conversion able

o generae correc srucure for he ouline, you have o specify ha he ouline paragraphs ge wrapped in

he elemens in your EDD. You also have o specify conainmen rules o ell FrameMaker o properly nes

he elemens as i convers he documen.

If you look a he forma caalog in he ouline documen, or if you look a he defaul enries in he generaed

conversion able, you will see ha each level of he ouline is deermined by he paragraph forma: Level

Level, Level, and so on. For he paragraphs conained by each ouline iem, here is a coninued forma

LevelConinued, LevelConinued, and so on. Bu he EDD declares only a single iem elemen and a single


35/3935


XML Authoring

p elemen. We need o find a way o map all he ouline iems ino hese iem and p elemens in such a way

ha hey capure he nesed ouline srucure, and FrameMaker can auomaically apply he correc forma

(indening and numbering).

o do his, we will use qualif iers in he conversion able ha idenif y he level for each iem and p. In addiion

we will use conainmen rules o specify wha each level of an iem can conain. he final conversion able

looks like he following:

Te edied conversion able

he able works as follows: For each Level paragraph, wrap he paragraph in an iem, and mark i as a (fo

he level). For each LevelConinued paragraph, wrap i in a p and mark i as a . So far his is easy o follow

Now, for a Level paragraph, we wan o consruc an ouline iem ha could possibly conain any numbe

of -level iems. he Level rule says, wrap a Level paragraph in an iem marked . If he Level paragraph

is followed by one or more p elemens marked as , include hose in he iem. And if he las p[] elemen i

followed by one or more iem[] elemens, include hose in he iem[] as well. his rule consrucs -leve

iems wih all heir conen properly srucured.

For he res of he ouline levels, you can see ha he rules are prey much he same. hen, for one o

more iem[] elemens, wrap hem all in a Body elemen. he Body elemen is almos a he op level of he

hierarchy. he conversion able also creaes ile and Auhor elemens a he same level as Body. When a

his is done, he conversion able wraps everyhing up in he Ouline elemen, which is he documen roo


36/3936


XML Authoring

he resul of running his conversion is as follows:

Now you have a conversion able ha works wih any oulines ha use he emplae correcly. You can use

his o conver a collecion of unsrucured oulines o XML. Firs run he conversion on your oulines, and

hen save he srucured oulines as XML.

IP: You can use FrameMaker ExendScrip o make a bach process ha saves a collec ion of srucured files

as XML.

Conclusion

Unless you are seing up a publicaion environmen from scrach, is very likely ha you will have legacyunsrucured documens. If is worh he effor o creae an XML auhoring environmen, hen i is probably

jus as worhwhile o conver your legacy o XML.

In many organizaions, he requiremen is o implemen XML auhoring for exising unsrucured publicaions

In ha case, you should consider running a pilo projec firs, as a proof of concep. Begin wih analysis and

creae an EDD. hen ry o manually reproduce a represenaive documen using ha EDD. his is a good way

o verify ha he EDD suppors he documen consrucs ha you need.

Once you have verified he EDD, you can begin building he conversion able. his is usually an ieraive

process, where you conver a porion of a documen, check he resuls , hen move on o conver more.


37/3937


XML Authoring

Is possible ha some of your legacy consrucs are so complicaed ha is difficul o build a working

conversion. A good rick is o build a conversion able ha handles mos of your documen, and hen you can

use FrameMaker ExendScrip o auomaically find and fix any invalid srucure.

Remember he / rule: I akes % of he ime o auomae % of your work. Bu o auomae he

las % of your work will ake % of he ime. If you have hi a wall wih he conversion able, maybe

ExendScrip can ake over. If even ha is oo difficul o program, hen you can search for invalid srucure

in your documen and fix i manually. he amoun of manual fixes you need o make should be very smal

Remember, convering a body of documens o srucure is a one-ime ef for.

Where o Go From Here

As you move ino srucured auhoring, you may wan consul some of he resources lised in his secion.

Adobe Whie Papers

Visi our FrameMaker sie (www.adobe.com/producs/framemaker/) for links o addiional whie papers

cusomer success sories, and more.

Recorded Adobe Webinars

A he following websie, you will find many recorded Adobe ech Comm webinars ha have XML or DIA

as a heme:

hp://adobe.ly/PbdpJ jus search for XML or DIA.

You will al so find he following blog o be of grea ineres:

Classic -Par Aldous series on Unsrucured o XML webinar series republished

his blog has links o a seven-par recorded webinar series on all he seps required o migrae from

unsrucured o srucured or XML documens in FrameMaker. Alhough his webinar was creaed for an

earlier version, i is sill highly relevan for he laes release of FrameMaker. You can find his blog a:

hp://blogs.adobe.com/echcomm///classic--par-aldous-series-on-unsrucured-o-xml-webinar

series-republished.hml

Srucure Developers Guide

he Srucure Developers Guide, found in he OnlineManuals folder of he FrameMaker insallaion

direcory, provides deailed informaion abou building srucured applicaions in FrameMaker. I also

conains a complee read/wrie rules reference.

DIA

You can f ind more informaion abou he Dar win Informaion yping Archiecure a his sie:

www.oasis-open.org/commiees/c_home.php?wg_abbrev=dia

Docbook

For more informaion abou DocBook, visi he off icial DocBook sie:

www.oasis-open.org/commiees/c_home.php?wg_abbrev=docbook
http://www.adobe.com/products/framemaker/http://adobe.ly/Pbdp0Jhttp://adobe.ly/Pbdp0Jhttp://blogs.adobe.com/techcomm/2013/06/classic-7-part-aldous-series-on-unstructured-to-xml-webinar-series-republished.htmlhttp://blogs.adobe.com/techcomm/2013/06/classic-7-part-aldous-series-on-unstructured-to-xml-webinar-series-republished.htmlhttp://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ditahttp://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbookhttp://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbookhttp://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ditahttp://blogs.adobe.com/techcomm/2013/06/classic-7-part-aldous-series-on-unstructured-to-xml-webinar-series-republished.htmlhttp://blogs.adobe.com/techcomm/2013/06/classic-7-part-aldous-series-on-unstructured-to-xml-webinar-series-republished.htmlhttp://adobe.ly/Pbdp0Jhttp://www.adobe.com/products/framemaker/


38/39

Adobe, the Adobe logo, and FrameMaker are either registered trademarks or trademarks of Adobe Systems Incorporated in the United Statesand/or other countries. All other trademarks are the property of their respective owners.

2014 Adobe Systems Incorporated. All rights reserved. Printed in the USA.

XXXXXXXX 1/14

Adobe Systems Incorporated345 Park Avenue

San Jose, CA 95110-2704

USA

www.adobe.com

raining

You can search our sie for an auhorized raining provider in your area. Vendors offer scheduled public

classes wih open enrollmen and privae classes a your sie or heirs. Some vendors also offer disance

learning or self-sudy maerials. You can search for an Adobe auhorized raining provider here:

parners.adobe.com/public/parnerfinder/p/show_find.do

Alernaively, please reach ou o Adobe echnical Communicaion a [email protected] for raining

references.

Consuling

Adobe mainains a lis of FrameMaker consulans. Please reach ou o Adobe echnical Communicaion a

[email protected] for consuling references. You can also find qualified consulans by searching fo

hem on he web. In addiion, many auhorized raining providers also provide consuling services.

Adobe FrameMaker XML Author 12

To find out more about and try Adobe

FrameMaker XML Author 12, please visit

the website now at www.adobe.com/

products/ramemakerxmlauthor.
http://training.adobe.com/training/partner-finder.html#p=1http://mac%20os/Users/sanjay.vibhandik/Library/Caches/Adobe%20InDesign/Version%208.0/en_GB/InDesign%20ClipboardScrap1.pdfhttp://mac%20os/Users/sanjay.vibhandik/Library/Caches/Adobe%20InDesign/Version%208.0/en_GB/InDesign%20ClipboardScrap1.pdfhttp://mac%20os/Users/sanjay.vibhandik/Library/Caches/Adobe%20InDesign/Version%208.0/en_GB/InDesign%20ClipboardScrap1.pdfhttp://mac%20os/Users/sanjay.vibhandik/Library/Caches/Adobe%20InDesign/Version%208.0/en_GB/InDesign%20ClipboardScrap1.pdfhttp://mac%20os/Users/sanjay.vibhandik/Library/Caches/Adobe%20InDesign/Version%208.0/en_GB/InDesign%20ClipboardScrap1.pdfhttp://training.adobe.com/training/partner-finder.html#p=1


39/39

ry now

Experience best-in-class XML/DITA authoringwith complete DTD support

Announcing Adobe FrameMaker XML Author 12Now available a a monhly subscripion of .

Documents

The Hitchhikers Guide to XML Authoring