XML with FrameMaker + SGML Quick Guide Daniel K. Schneider, TECFA, University of Geneva http://tecfa.unige.ch/guides/xml/frame-sgml/ Version 1.1 - May 25, 2001, Version 0.5 was the first version written in FrameMaker. Version 0.6 and 0.7 have minor corrections. Version 0.8 adds simple read/write rules for special elements and some HTML mapping rules. Version 0.9 adds external HTML links. Version 1.0 makes several important corrections. Version 1.1 adds display of attributes. This thing is still a draft version (and maybe will remain one forever). Particular thanks go to Jan den Hartog ( objective i) who pointed out a lot of major trouble spots in 0.9. Thanks to Kevin Lossner (Easy Software AG), Marcus Carr (Allette Systems) , Ceryle Gaehl (Australian Medicines Handbook) for other helpful comments. Read the PDF or the FM version of this text. The other versions (*.html, *.xml, *.sxml) may lack style or worse.Note: A while ago I started writing my first real text with FM+SGMLand I wrote an EDD for Norman Walsh’s Simplified Docbook XML DTD. The EDD is in http://tecfa.unige.ch/guides/xml/frame-sgml/sdocbook/. Also needs work (e.g. forget about deep nestings), but it’s a start. (deals somewhat with tables and figures and such). This little document should help you to get started with FrameMaker + SGML (“F+S”) and XML publishing. F+S is a Word processor/DTD product from Adobe meant for SGML publishing, but it can be used in “XML world” with some restrictions. This text comes along with all source files (FrameMaker files and XML DTD) used to produce this document. Note: You need F+S version 6 to read the *.fm files. I believe that the general ideas also apply to F+S 5.5. Why would you want to buy, learn and use F+S? You can produce real and large structured text (not just address cards) You believe that semantically structured text is good (not just style sheets à la standard Frame or Word You hate to write text with XML tree editors à la Spy or Xeena (I even much prefer emacs/psgml mode to these tools) You want good looking paper versions (and don’t have time to write XSL/FO rules) You can only think straight when you can easily reread your text on the screen. F+S is a good product combining the power of an excellent word processor (better than MS Word) with a good structure editor.Now the bad News:F+S does not support what I call the core XML Framework. F+S doesn’t read XSL/FO or even CSS. You have to learn FrameMaker’s EDD language plus a little bit of SGML. This will allow you to author in FrameMaker with your own DTDs and export to XML and CSS (that’s it, no XSL/FO or XSLT!). Once you suffered though the process of learning and setting up an EDD you will be very productive, but it sure is a shame that “XML world” imports (only DTDs and somewhat XML) and exports are so poor ! Of course, HTML (rather poor) and PDF (great) support constitutes another reason why you may want to learn F+S. About the Author: I am a total newbie to both F+S and SGML. I opened the F+S box sometimes in July 2000 and tested it on a PC for 2 days. I know standard FrameMaker pretty well. I have experience with server-side XML+XSLT (e.g. with Cocoon). I am interesting in “single-sourcing”, i.e. maintaining and producing text (in different formats) in a most painless way. I now have F+S 6.0 for Solaris and am writing this on a comfortable Ultra 10 double monitor system. FrameMaker is one of the reasons why I don’t switch to Linux. Btw. Windows is not an answer, it’s a question and my answer is “no”. So all my explanations center on a Unix installation but can be easily adapted to Windows. All the documents produced will be available in http://tecfa.unige.ch/guides/xml/frame-sgml/. In particular you may be interested in the following files: My SGML application file ./Stepbystep/sgmlapps.fm The template file for authors: ./Stepbystep/Stepbystep-template.fm The EDD definition file: ./Stepbystep/Stepbystep-edd.fm Special definitions (defunct): ./Stepbystep/Stepbystep-edd-xref.fm A file with a few para defs ./Stepbystep/Stepbystep-paras.fm The SGML declaration: ./Stepbystep/Stepbystep-sgmldcl The read/write rule file: ./Stepbystep/Stepbystep.rules The XML DTD ./Stepbystep/Stepbystep.dtd The generated SGML DTD ./Stepbystep/Stepbystep-sgml.dtd (old?) The CSS for the XML file: ./quick-fm-xml-guide.css The XML output of the guide ./quick-fm-xml-guide.xml The PDF version of the guide ./quick-fm-xml-guide.pdf You may also find something in ./html I wrote this to help you a bit with X+F to produce XML/HTML/PDF documents based on your own XML DTD ... and to make sure of what I learnt myself. Teaching is one of most efficient learning methods, so I do this kind of thing in one way or another for most technologies I am learning and teaching. It took me about 5 days to produce this document, including learning F+S and coming up with the Stepbystep DTD and EDD (F+S’s own schema language) for this very document. So this is not a fancy tutorial, but may help you a bit wading through the official documentation (a >550 page PDF file called MSGML_Dev_Guide.pdf). Plan 5 days too: It takes you about 2 days to get something going if you are good at reading technical documentation (I have rarely seen something as bad coming from a major company, however all the information is there). Then rest a bit (I waited until October after my 2-day stint in July) and then plan at least another 3-4 days to have a setup for producing something like this document (written exactly in FrameMaker as described below) in production. Add more days if you need a good XSLT style-sheet in production, if you want to deal with graphics and crossreferences, etc. I wrote this very document with F+S using a DTD I made just for this called Stepbystep.dtd. It’s freeware btw and will allow you to write short “how-to in X steps” documents like this one. All files used are available and should in work in any F+S version 6.0 system. Expect trouble with fonts tough. I assume that you are familiar with (simple) FrameMaker usage and the design of simple XML DTDs. I don’t know how much time it would take you learning FrameMaker from scratch, one full day maybe with some help. The same goes for XML (if you are familiar with the idea of grammars and data-structures). Otherwise count more ! Also, if you just opened the F+S Box, you might want to learn how to use F+S as an author (there is a printed book for that). It will take you about an hour to get the idea: instead of defining and using paragraph tags you will use a structure view and an elements list that someone designed for you:). Make sure that you understand: when to use View->Element Boundaries as Tags (always in the beginning!) the Elements Window the Attribute Window the Structure View Make sure that you know to insert, delete and move elements and attributes. I found inserting particularly difficult. Moving and deleting is easy, particularly if you configure the Text Window with Menu: View->Element Boundaries [as tags]. I also did short tutorial called“FrameMaker + SGML Quick Guide”. See: http://tecfa.unige.ch/guides/xml/frame-sgml/ which you may want to consult The real (developer) manual is inside the FrameMaker installation, e.g. on our site it is: /unige/frame_6.0/fminit/usenglish/OnlineManuals/FMSGML_Dev_Guide.pdf Once you found it, get a double monitor system (20’ or better) and launch Acroread. Else print the 570 pages (both will also do). Just to make sure: There is NO printed manual you get which is of any use for the task of setting up an SGML Application (fancy word for the many things you have to declare and define before you can start writing). The books you get are only good if somebody at your place already did what you hopefully will learn here. Unlike XML, SGML is configurable. I.e. you can have different sorts of DTD grammars (and the default does NOT work with XML) . So when you configure your SGML application (see “Create an SGML application” on page 7), you tell the SGML parser to be as XML compatible as you can figure;) Here is what I did: e.g. cp /unige/frame_6.0/fminit/usenglish/sgml/docbook/app/sgmldcl StepbyStep-sgmldcl Edit this file according to the next step. Or better, just use file “Stepbystep-sgmldcl” that comes with this tutorial (made by J. Hartog and not myself). Later you will have to reference this file from an SGML declaration, but for now move on. This will allow you to read an XML DTD, else you will have to come up with a "standard" SGML DTD instead (sorry don’t know what and if there is a default/standard way for defining DTDs in SGML, but I call it that way). Make sure that you have at least: MINIMIZE DATATAG NO OMITTAG NO RANK NO SHORTTAG YES NAMECASE GENERAL NO ENTITY NO Your really must do this. E.g. if you don’t make sure that “NAMECASE GENERAL NO”, FrameMaker will Capitalize elements when it builds an EDD file from a DTD, and of course when later you export a DTD or an XML file you are stuck with Capitalized elements and your original XML DTD won’t fit anymore. In "XML let’s publish text on the web" world, a lot of people just use DTDs to make sure that XML files roughly correspond to some structure (e.g. one wants to be sure that XSLT rules fire), here no mistakes please! In addition F+S has some ugly habits to which you have to adapt (unless this can be configured some place, HELP me if you know please). So, do the things below (or preferably find a better solution) E.g. write a small example with an XML editor like PSGML Mode in Emacs (if you know Emacs, else look for something else) and see at least if your tool can read your DTD. F+S can do the same of course, but you may not be sure why it complains (bad DTD or bad configuration or your SGML application) The philosophy of SGML publishing tends to see attributes rather as places to hold meta information. E.g. you can use them for hidden authoring comments, for display hints (bullets or numbers in a list), for internal references, etc. Attributes can be printed as prefixes or postfixes of an element. However this is not totally trivial, since you also must write a rule that tests the existence of a value.Maybe you can use attributes in other places too, but I don’t know. This is needed if you want to use FrameMaker’s cross referencing features. It will not do it for you. If you define ID/IDREF attributes, FrameMaker will add unique ID’s automatically. You do, of course, have to define ID/IDREF (ID on the target element, IDREF on the source element) in your DTD for this to work. As explained in “Edit the read/write rules file.” on page 10you will have to modify the r/w file to tell it that a given element is an Xref element. If you set them to #IMPLIED they can be empty unless, of course, you create a link, at which point Frame will add the values Frame will export <,>,&,” as special entities, other characters will appear as as things like #8217; Latin characters will appear as entities: e.g. é as &#233; You very likely will need this in many cases. However you can come back to this later (this is actually what I suggest). This step must be planned together with step 8 [p. 10] anyhow. FrameMaker has a very good cross-referencing system which is used a lot by typical FM users. To represent cross-references, F+S will produce by default a Xref element (together with a “Reference” attribute) which of course will not be in your DTD. In other words, unless you add a definition for crossrefs in you DTD, your generated XML will not be valid. So in one way or another you must deal with this. Here is an example of an element you could add to your DTD: <!ELEMENT Xref EMPTY> <!ATTLIST Xref href IDREF #REQUIRED link CDATA #FIXED "locator" show CDATA #FIXED "replace" actuate CDATA #FIXED "user" > Warning: Crossrefs to other files will not work. These external links will be resolved to the text string as displayed when you create the link. [Hint from J. Harog: FameMaker understands a ’document’ to be anything that lives as a single SGML file (even though, using r/w rules, you may display it in F+S as a book file with several chapters/sections)]. So you have 2 options make a book + r/w rules, or reference to other documents with hand-made links. So, be aware that managing Crossrefs is a hassle ! Also don’t hurry: if you started using Crossrefs in a file without having defined Xrefs in a DTD and without fixing rewrite rules below (see step 8 [p. 10]), you are in slight trouble, i.e. you have to kill those Crossrefs and enter them again. Dealing with graphics (and even other “weird” elements is also pretty bad. Same problem as above. When you insert a anchored frame in F+S it will create a (unfortunately quite outdated sort of) XLink like: <GRAPHIC xml:link="locator" href="graphic3.gif" show="embed" actuate="auto"></GRAPHIC> Provisionally, I created a Graphics element (shown with an example): <!ELEMENT Graphics (#PCDATA)> <!ATTLIST Graphics link CDATA #FIXED "locator" href CDATA #REQUIRED show CDATA #FIXED "embed" actuate CDATA #FIXED "auto" > <Graphics xml:link="locator" href="graphic3.gif" show="embed" actuate="auto"></Graphics> Note: When I tried to import an attribute with a namespace (i.e. xml:link) F+S freaked out. Maybe there is solution, but I don’t have it (yet) The “real” XML xlink is shown below (for comparison). You certainly can write a XSLT rule to translate Frame’s output, but it would be better if I’d manage to configure the SGML declaration to read in elements with namespaces, write translation rules, etc. Postprocessing stinks if you just want to author like you’d author simple HTML, Ideally you say “save” and it’s on the web. <!ELEMENT Graphics EMPTY> <!ATTLIST Graphics xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink" xlink:type CDATA #FIXED "simple" xlink:href CDATA #REQUIRED xlink:show CDATA #FIXED "onLoad" xlink:actuate CDATA #FIXED "embed" > If you don’t have an SGML declaration, F+S will not read XML DTDs. If you really don’t want to configure your SGML as described in “Make your own SGML declaration” on page 3, you need to fix a few things. I just "got" the syntax from the included DocBook DTD. I did this before I figured out the importance of defining first an SGML application and it sort of worked ... Don’t use “_” (underscores) in Element and Attribute names . You can configure the SGML declaration to support "-" (hyphens) and “.” (dots) (a) Normal ones: before: <!ELEMENT trainingCourse (tcCourses+)> after: <!ELEMENT trainingCourse - - (tcCourses+)> Empty elements: before: <!ELEMENT modResponsible EMPTY> after: <!ELEMENT modResponsible - O EMPTY> Note: “0” is the letter “Ohh”, not a Zero ! In F+S you got to declare a SGML application in some special central place. The place depends on your system (I have both a Windoze individual and a Solaris site installation). The purpose of this is to identify the SGML declaration file, the Root Element, the Doctype, etc. Menu: File->Developer Tools->Edit SGML Application File This will automatically open your central “SGML applications” configuration file. It is called sgmlapps.fm (probably). It might be a good idea to first make a COPY of this file since it is read on startup (see below where you can find it). Under Windows you can find this file in the SGML installation directory: smglappps.fm [probably]. Warning: If you are 2 people using F+S on the same machine, coordinate a bit here Under Unix, the procedure is a bit more complicated when you do it the first time, because each user can have his own SGML application file (as it should be). Here are the steps: Menu: File->Developer Tools->Edit SGML Application File It will complain that you can’t write (at least with our site thing) because you are dealing with a system-wide installation. So you have to save the file to your own "fminit" directory in something like the following way (roughly). It must go to: ~/fminit/<your_language_version>/sgml/sgmlapps.fm E.g. /home/schneide/fminit/ukenglish/sgml/sgmlapps.fm /home/schneide/fminit/usenglish/sgml/sgmlapps.fm If the xxx/sgml directory does not exist you have to make it of course. Before you do so figure out what language version of F+S you use. A good test to know what language version you have got is to create a fminit/xxx/Templates directory, put a file there, then click on "New" in FrameMaker main menu and see if the file is there. E.g. home/schneide/fminit/usenglish/Templates/manuel.fm Now it is really time to learn how to edit with FrameMaker. Consult companion document “fm-user-quick-guide” and look at the printed FrameMaker+SGML doc and play a bit (unlike the developer doc its sort of usable, though much to verbose ...). The authoring interface is quite intuitive and can be learnt quite fast. Note that you can use the structure view to kill and move around elements and that you need the Element menu to insert elements. I suggest that you configure the elements menu (see the Options) to “valid elements for working start to finish” This is an important step. If you don’t do it right, you will suffer later! You can kill or leave the existing definition for DocBook. Since sgmlapps.fm and only this file will hold all your future SGML applications I suggest that you leave it. Ok, now let’s edit this file: Insert your mouse after "Application Definition Version". This will show a SOLE SGML "Application" element in the Element menu. Select SGMLApplication and click on insert Then add a few definitions. IMHO the following ones are good enough for starters. Replace ALL the values (text after “:”) in the following example with your preferences: Application name: Stepbystep Read/write rules: /home/schneide/xml/frame-sgml/Stepbystep.rules XML character encoding: ISO Latin1 SGML character encoding: ISO Latin1 DOCTYPE: Stepbystep DTD: /home/schneide/xml/dtd/Stepbystep.dtd SGML declaration: /home/schneide/xml/frame-sgml/Stepbystep-sgmldcl Note: On a PC use PC style for this filename, e.g. E.g. i:\web\guides\xml\frame-sgml\fc-ex\formcont-sgml.dtd For your application name, you can just choose any name. See step 8 [p. 10] for explanations on Read/Write rules (you can add these later). The DocType corresponds to the root of your XML DTD. Defining SGML declaration has been shown in step 2 [p. 3]. The following steps are needed: Menu: Element->Validate (will validate your entries) Each F+S document (include the SGML application file), the Edd file (see below) and your own SGML/XML files can and must be validated. If validation is ok, save the file, then set your new SGML application. Menu: File->Developer Tools->ReRead SGML Application File Your application should be in the menu, select it: Menu: File->Set SGML Application If you can not see your application in your Set SGML application menu, you did something wrong. Fix it, or else forget about the rest! FrameMaker does not really work with DTDs but they have their own format (EDD = Element Definition Documents). These are F+S files that have rules analogous to DTDs plus lots of additional stuff like formatting rules. So a EDD covers what does DTD + XSL/FO + applications in XML world ... Now you can load the DTD you did in step 3 [p. 4] Menu: File->Developer Tools->Open DTD To load again: File->Developer tools->Import DTD Contents so far need to have the same information as a DTD, i.e each element has a General rule (equivalent to the DTD’s element definitions) some have an Attribute list (like ATTLIST) Here is an example, the following XML DTD entry: <!ENTITY % Standard-attrs "Id ID #IMPLIED"> <!ELEMENT Stepbystep ( Doctitle, Info?, Abstract?, Intro?, Prereq?, Steps+, Comments?, Conclusion?, Open? )> <!ATTLIST Stepbystep %Standard-attrs; > translates to: Element (Container): Stepbystep Valid as the highest-level element. General rule: Doctitle, Info?, Abstract?, Intro?, Prereq?, Steps+, Comments?, Conclusion?, Open? Attribute list Name: Id Unique ID Optional I think it is a good policy to give some similar extension to all your FrameMaker files. [though I should probably distinguish between normal and SGML versions]. E.g. do: File->SAVE AS xxx (e.g. Stepbystep-edd.fm Usually, you don’t need to do this, but if you imported a DTD without having defined a SGML application for it, you can catch up a little. The beginning of your EDD file must have something like this: SGML Application: Stepbystep Element (Container): Stepbystep Valid as the highest-level element. General rule: Doctitle, Info?, Abstract?, Intro?, Prereq?, Steps+, Comments?, Conclusion? Save it If everything went well you can use F+S as an XML editor for simple structured text, but before we explain this in step 10 [p. 11], let’s first handle special elements (Xrefs, graphics and such) and then do some more testing Some elements are really special. They are not considered as containers (i.e. standard DTD elements) and can not be imported as is. You must handle Cross-references, graphics and such in some special way. The dumb way to handle this is to manually redefine elements like cross refs and graphics. You can copy the element definitions to a special file once you got it right and copy it back each time you re-import the DTD (I did that the first day). I strongly suggest that you define a read/write rules file. This file must be declared in the SGML application. Edit this rule file with a standard programming editor (e.g. the NotePad on Windoze) and make sure to save as Ascii! Here is the contents of my file which I called Stepbystep.rules fmsgml version is "6.0"; #include "isoall.rw" element "Xref" { is fm cross-reference element "Xref"; attribute "href" is fm property cross-reference id; attribute "link" is fm attribute "Link"; attribute "show" is fm attribute "Show"; attribute "actuate" is fm attribute "Actuate"; } element "Graphics" { is fm graphic element "Graphics"; attribute "link" is fm attribute "Link"; attribute "href" is fm property file; attribute "show" is fm attribute "Show"; attribute "actuate" is fm attribute "Actuate"; attribute "Entityref" { is fm property entity; is fm attribute; } } You can read the documentation spread over chapters 15,16 and 20 (at least!). Basically what you must do, is to map what Framemaker exports such as cross-references and graphics to an XML DTD. I tried to come up with a pretty uncreative 1 to 1 mapping, because I do not understand certain things. I also have other problems, i.e. F+S wil write out xml:link in Xrefs, but can’t import this namespaced attribute from a DTD. At least once more, this is just a reminder that you can update your EDD by reading in the the DTD again. Of course, if you have major changes things can get tricky, but IMHO F+S handles DTD importing just fine: File->Developer tools->Import DTD In principle this step is absolutly not necessary, but it is easier to compare an SGML DTD with your XML DTD than an EDD with a XML DTD. Menu: File->Developer Tools->Save as DTD Now compare the 2 DTDs (your original XML or SGML and the generated). If something is missing in the generated one, fix the original DTD, then redo STEP 6, else you will get out of sync. Note that the exported DTD is SGML (unless there is a parameter in the SGML declaration I did not find). Therefore compare taking into account this difference. Also, all entities you used will be expanded. e.g. you get this sort of thing: <!ELEMENT Step - - (Title, Goal?, Prereq?, ((Para | List | Listing)* | Substep)*, Comments?) > <!ATTLIST Step Id ID #IMPLIED > <!ELEMENT Para - - ((#PCDATA | A | Strong | Emph | Code)*) > instead of: <!ENTITY % Standard-attrs "Id ID #IMPLIED"> <!ELEMENT Step (Title, Goal?, Prereq?,( %Content; | Substep)*, Comments?) > <!ATTLIST Step %Standard-attrs; > <!ELEMENT Para (#PCDATA | A | Strong | Emph | Code)*> Go to step 10 [p. 11] if things look reasonably well. You can always make changes later. However, if you want to fix something have a glance at step 11 [p. 12]. Manufacture the usual starting point for an author (like with standard FrameMaker, but with elements rather than paragraphs) This step is not necessary if you did everything in the right order so far. Anyhow you need to specify a root, e.g. have something like this in your EDD file: Element (Container): Stepbystep Valid as the highest-level element. General rule: Doctitle, Info?, Abstract?, Intro?, Prereq?, Steps+, Comments?, Conclusion? File->New Document I suggest to start with a blank page (Portrait) Import the definitions from the EDD file into your template file. This is roughly the same as entering <!DOCTYPE Stepbystep SYSTEM "/home/schneide/xml/dtd/Stepbystep.dtd"> in a standard XML file. In the blank page (!) do: Menu: File->Import->Element Definitions You can repeat this step each time you change something in the EDD If everything went well you can use F+S as XML editor. Since we didn’t define any formatting yet, I suggest that you turn on Element Boundaries Viewing: Menu: View->Element Boundaries (as tags) You can author XML now and export as XML I suggest to test quite a bit now if your DTD is brand new. Now that you understand how to import a DTD into F+S, it is time to be sure of your Schemas. Make sure that F+S understands 100% of your DTD, i.e. that there is a good match between EDD and DTD (IMHO this is not a problem for beginners, problems start when you want to use advanced Schema features of F+S). Probably you want to make changes to your DTD. There is even a chance that you will have to redesign your DTD. You can’t use attributes as you are used to have in your XML world. Also some elements better become attributes if they are not meant for printing, e.g. before you filtered these out with XSLT (else you have to learn additional F+S techniques). You don’t want to generate PDF from XML but rather do it directly from FrameMaker Unless you did something completely wrong so far in which case you might want to restart with a new EDD, you can import (instead of opening) your DTD. F+S will automatically adapt the EDD to the new DTD structure. I made several important modifications and everything went well. You modify your EDD anytime you want (even while you are authoring), however you may loose formatting information and may need to adapt your text to a new DTD/EDD. Menu: File->Developer Tools->Import DTD (with the EDD file active!) I think you should make reasonable sure that things are roughly well, you can fix your DTD later, so I suggest that you quickly move on and test editing, but if you want to start to redesign now, here are the major steps of the editing/test/editing cycle: Edit DTD Import DTD to EDD Fix Crossrefence Definition (have to look into this!) Validate EDD Import EDD to FM text file Validate FM file Import EDD to template file Now you [optionally] can make a major decision: break the XML round trip. EDD lets you write much more powerful structure rules than you can do in a XML DTD, e.g. you can have "ORs" (see chapter 6)These probably will partially export to SGML but never to XML. Up to you to decide. I (right now) think that in most cases one should NOT use these features if you are working in XML world, because it is nice if generated XML is valid (fits a real DTD) for various reasons not explained here.Well you might want to use automatic insertion of descendants (makes writing easier, see page 106 in the manuel). Anyhow I choose not to use all this for the moment. The extreme other option is to never work with a DTD again. You can do everything with EDD’s. This is described in a separate document called “Formatting with FrameMaker + SGML’s EDD” . Basically all you can do now is author XML like you would with a typical good XML structure, tree or box editor. If you want to print nicely (with PDF), or have some basic CSS information generated you are absolutely not done yet. Anyhow, before you learn EDD formatting rules, move to the last step and export to XML. You’ll have some feeling of success. Here I just outline the options of this multi-channel publishing framework. You may want to move onto the companion document on EDD formatting. File-Save as .. Select XML as format It should work, i.e. you will have a file with the XML contents. The XML file has a style sheet declaration that points also to the generated CSS file (not XSL/FO!) <?xml version="1.0" encoding="ISO-8859-1"?> <?xml-stylesheet href="Stepbystep.css" type="text/css"?> <Stepbystep><Doctitle>XML with FrameMaker + SGML Quick Guide</Doctitle> .... The next steps are optional. I recommend learning how to author EDD formatting rules before you think about printing and exporting to PDF. EDD rules are not necessary for HTML and XML production only since you have to rewrite the CSS rules anyhow, so can as well do your CSS from scratch :). WARNING: The stylesheet declaration in the generated xml file is wrong. It should read <?xml-stylesheet ...>and not <?xml-stylesheet href="quick-fm-xml-guide.css" type="text/css"?> (a “-” instead of “:”). Yet another annoying little “feature” of F+S. Don’t forget this ! This is really important if you plan use XML client-side, because your document will really look ugly. Note that the HTML CSS is NOT the same as the XML CSS, so do NOT put the files in the same directory. I strongly recommend to lock the CSS file once you fixed it (or/and make a copy of it). The risk that you overwrite it when you generate a new XML file is important since each time you save xml as XML or Html you always create a CSS file too. This is not supported by F+S. You have to do it yourself. Now what I want is a semi-automatic xml+css -> XSLT (XHtml) translator .... This works well and you can define PDF bookmarks with XML elements You can directly export to HTML (similar functionalities as in standard F+S, i.e. you can map SGML elements to HTML tags). See Menu: File->Utilities->HTML Setup. Map the elements. Then you can read some documentation and edit directly the Reference Pages (there you can define sub-page generation and such). Not very flexible editing rules, but somewhat acceptable (since you can catch up a bit with CSS). Menu: View->Reference Pages This is one important thing that must do. In standard FrameMaker you can define external links by using Markers (e.g. via the Special->Hypertext or Special->Marker Windows). You mark some text with a special character tag and then enter “message URL .....” (read the doc please). Well this will not work in Frame+SGML (unless there is some configuration, read/write etc. stuff to do I did not understand). Again: bad bad documentation. Anyhow, here is my solution just for HTML (nothing for PDF !) : In your DTD define a A Tag (or do something with XLINK, have to think about this). Then edit the Reference Page like this (provided you got a simple <a href=””></a> kind of element. FrameMaker XML Item Source Item Element E:A N N N A:Href href A:Name name This solution is half-baked, because PDF will not have links ... Help me please ! Needs configuring plus CSS post editing. This is really important if you work for a business, because your HTML will really look ugly. I used standard Framemaker a lot to write slides for my teaching and it can be quite productive (see: http://tecfa.unige.ch/guides/tie/tie.html) Note that the HTML CSS is NOT the same as the XML CSS, so do NOT put the files in the same directory .... You also can import XML, although I have not fully tested this and I was getting error messages when I re-imported (the previously exported XML file) about undeclared entities but they seemed to be there at first glance. Anyhow, here is basically what you have to do: <!DOCTYPE Stepbystep SYSTEM "/home/schneide/xml/dtd/Stepbystep.dtd"> As you would, say a Word File: Menu: File -> Open [ enter your XML document ] Note that you must have both of these files opened in F+S (!) Menu: File -> Import Element Definitions Menu: file -> Import Formats You will notice that some things are wrong or missing, e.g. crossreferences. I don’t know yet if a complete round-trip without loss is possible for simple (no frills, no nothing added from Framemaker) XML. It makes sense to investigate if you collaboratively work on some text and some guys prefer to work with a plain structure editor (I need some time to investigate this). I have just found (from M.Carr) out that there is an XML plug-in (not installed yet): http://partners.adobe.com/asn/developer/framefdk/fdk.html To do things (soon if I find time): external URLs. While it is easy to create links that export to XML (.e.g for simple server-side XML you simply can use the A tag), I have NO damn clue how to make them appear in the HTML version. Tables General questions Who can actually use this document (feedback please) and what needs to be done to make it acceptable to most people who can read technical documentation ? How many errors are in here and how many stupid things do remain ? Is it possible to write rewrite rules in order to achieve a total (or almost total XML->Frame->XML-Frame roundtrip ? Why should I use this or rather when ? How much time would it take to come up with a total publishing solution let’s say for instructioncal text ? Setting up a DTP environment with F+S is quite a lot of work, but IMHO worth the trouble, if you take the time to define a certain amount of DTDs/EDDs that fit the requirements of your work. Of course, plan to reuse a DTD/Edd several times (at least).