THIS FILE IS OUTDATED ! PLEASE look at the directory http://tecfa.unige.ch/guides/xml/frame-sgml/ ************************************************** XML with FrameMaker + SGML 6 (F+S) quick guide ************************************************** http://tecfa.unige.ch/guides/xml/frame-sgml/ quick-guide.text version 0-1 - July 21 2000 (unfinished) Version 0.2 - July 26 2000 (a bit less unfinished) version 0.3 - October 26 2000 (minor fixes) version 0.4 - October 27 2000 (it's usable in beta) THIS FILE IS OUTDATED ! PLEASE see INSTEAD file: http://tecfa.unige.ch/guides/xml/frame-sgml/quick-fm-xml-guide.pdf Made by Daniel Schneider (http://tecfa.unige.ch/tecfa-people/schneider.html). New (oct/00): Got Frame Solaris now and can use my little Sun. SO much less in the pain than Windoze :) Rearead all the stuff and figured that I must learn about SGML declarations. That might fix the incompatible DTDs problem (at least).... [update soon] I am a total newbie to F+S and SGML and opened the F+S box a few days ago. I know standard Frame and XML. This is not a tutorial, but may help you a bit wading through the official documentation (a >550 page PDF file called FMSGML_Dev_Guide.pdf). I takes you about 2 days 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). Just to be clear: F+S makes a big distinction between the author (i.e. end-user, who should *not* read this) and the "SGML developer, (or the author who wants to be both). I assume that you are familiar with (simple) FrameMaker and XML DTDs. Also if you just opened the F+S Box (like me), 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 :). I don't know how much time it would take you learning frame from scratch, 1 day maybe with some help. Short summary: XML support with F+S does not exist for real. You have to learn Frame's EDD language plus a little bit of SGML. This will allow you author in Frame with your own DTDs and export to XML (that's it!). Why should want to do this ? (a) only do it if you want to write real text (not just address cards); (b) Structured text is good for various reasons (c) doing it with Frame is much better than with a tree editor à la Spy (I even prefer naked emacs to these tools). In addition paper versions will look really nice (d) note that XML will be structured (unlike the totally useless standard Frame XML export). Examples (not finished, formatting rules are missing): http://tecfa.unige.ch/guides/xml/frame-sgml/fx-ex/ I just took a random DTD we use. It's in production here: http://tecfa.unige.ch/tecfa/teaching/formcont/genInfo/formcont.sxml NOTE: Nothing is guaranteed to work, because I may work real time on them and I am NOT done yet !! ---------------------------------------------------------------------- STEP 1: Find the Manual It's inside the frame installation: e.g. xxx/frame_6.0/fminit/usenglish/OnlineManuals/FMSGML_Dev_Guide.pdf Then, get a double monitor system (20' or better) and launch acroread. Else print the 570 pages (both will also do). ---------------------------------------------------------------------- STEP 2: Make your own SGML Declaration Unlike XML, SGML seems to be configurable. In other words you can have variants of different DTD grammars. So when you configure your SGML app (see below), you tell it to be XML compatible as best as you can figure ;) (1) Get the one that is in docbook e.g. cp /unige/frame_6.0/fminit/usenglish/sgml/docbook/app/sgmldcl . (2) Make sure you have OMITTAG = NO defined, e.g. MINIMIZE DATATAG NO OMITTAG NO RANK NO SHORTTAG YES Rationale: 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 is SGML, but I call it that way). ---------------------------------------------------------------------- STEP 3 FIX THE XML DTD and make an SGML version (1) Validate your DTD, e.g. with a small test file 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 it is STRICT, no mistakes. (2) Capitalize ALL your Element and Attribute names Frame just randomly decides to Capitalize elements when it builds an EDD file (see below), and of course when later you export a DTD or XML you are stuck with this. This is a major hassle and I don't know if it can be avoided (except by writing tons of rewrite rules) Hint: learn some Xemacs and you do it with a simple keyboard macro. (3) Rather use elements than attributes. The philosophy of SGML publishing tends to see attributes rather as meta information. E.g. you can use them for hidden authoring comments, for display hints (bullets or numbers in a list), for internal refences, etc. (4) Add an ID attribute to each element. This is needed if you want to use Frame's crossreferencing features. It will NOT do it for you [$verify]. SKIP TO STEP 5 ---------------------------------------------------------------------- STEP 4 Make an SGML version of your DTD (NOT recommended) If you DON'T have an SGML declaration F+S does not read XML DTDs, so you need to fix a few things. Just "got" the syntax from the included DocBook DTD... (1) Don't use "-" (hyphens) and "_" in DTDs [ not sure about this] (2 ) Change the ELEMENT declarations in the following way .... I am working on a better solution (a) normal ones: before: after: (b) empty ones: before: after: "O" is a OHHH not a zero ... further down we will call this DTD SGML DTD. ---------------------------------------------------------------------- STEP 5 Create an SGML application (whatever that means ....) [chapter 3, page 32] 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) (1) Open the SGML application file Menu: File->Developer Tools->Edit SGML Application File Note: It might be a good idea to make a COPY of this file since it is read on startup. (a) On PCs it is in the SGML subdirectory: smglappps.fm (probably) Ok, so if 2 people use your machine, coordinate a bit here ... (b) Under Unix, you have to do the following the first time you use F+S: (a) Menu: File->Developer Tools->Edit SGML Application File (b) It will complain that you can't write (at least with our site thing) (c) Save the file to your own "fminit" in the following way (roughly) Figure out what version of FrameMaker you use, because FrameMaker reads different init files according to the language version of the Interface..... File must go to: ~/fminit//sgml/sgmlapps.fm E.g. /home/schneide/fminit/ukenglish/sgml/sgmlapps.fm /home/schneide/fminit/usenglish/sgml/sgmlapps.fm (MAKE the xxx/sgml directory if it doesnt't exist yet ...) A good test to know what language you have got is to create a Templatex directory, put a file there, then click on "New" in FrameMaker main menu and see if its there. E.g. home/schneide/fminit/usenglish/Templates/manuel.fm (d) RESTART Framemaker (well maybe there is another way) (e) Menu: File->Developer Tools->Edit SGML Application File [ ... now its time to learn how to edit with FrameMaker. Look at the printed Frame+SGML doc and play a bit (unlike the developer doc its sort of usable, tho 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.... ] (2) Insert a new application in this file (you can kill or leave the existing DocBook thing, this file will hold ALL your SGML applications so I would leave it !). (e.g. 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 things (but LEARN using F+S before, IMHO these elements are enough for a start. Replace ALL the values with your preferences ! Application name: FormCont [REPLACE with your name] XML character encoding: ISO Latin1 SGML character encoding: ISO Latin1 DOCTYPE: Trainingcourse [REPLACE with your root element] DTD: /home/schneide/test/frame-sgml/formcont.dtd SGML declaration: /home/schneide/tmp/frame-sgml/sgmldcl Note: On a PC use PC style for this filename, e.g. DTD: i:\web\guides\xml\frame-sgml\fc-ex\formcont-sgml.dtd (3) Then validate/test/save a bit and set SGML application Menu: Element->Validate (will validate your entries) Save this file (4) Reload and set you current application !! Menu: File->Developer Tools->ReRead SGML Application File Menu: File->Set SGML Application (should offer your application now too) ---------------------------------------------------------------------- STEP 6 Load the DTD / make the skeleton of EDD file Frame 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 ... (1) Load SGML DTD (the one you did in step 1) into Frame Menu: File->Developer Tools->Open DTD This will hopefully create an EDD file (page 24, item 3) (2) Fix errors at the syntax level Most likely you have to fix errors in the DTD. I think you can ignore LOTS of strange messages like "Length of name, number, token exceeded the NAMELEN limit" ... fix these later [there is some mysterious SGML declaration file that can be configured, $DOIT], but do not ignore serious looking ones. Menu: File->Developer Tools->Import DTD (with the EDD active) Now check the EDD file (which is in typical Frame+SGML format). Contents so far need to have the same information as a DTD, i.e - each element has a General rule (like the ELEMENT) - some have an Attribute list (like ATTLIST) ... no association between elements and frame paragraphs (yet) (3) Told you about this before, but just in case: Now there is some stupid hassle the FrameMaker people impose on us (at least by default). Element names change bloody case (capitalization) e.g. trainingCourse becomes Trainingcourse ... SAVE your as e.g. formcont.edd.fm (3b) ONLY IN CASE you loaded a SGML tradiditional DTD WITHOUT defining an application: Go back to your EDD file, insert the application name and export DTD Edit "SGML Application" [e.g. FormCont in my cas] SAVE it as e.g. formcont.edd.fm ---------------------------------------------------------------------- STEP 7: Export the EDD as DTD [ This step is not necessary ] (1) Menu: File->Developer Tools->Save as DTD (2) Now compare the 2 DTDs (your orginal XML or SGML and the generated). If something is missing in the generated 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), so compare taking into account this differece. (see obsolete STEP 2b for this) (3) Maybe fix things ... like change cas in you original XML DTD. (4) Then do not open DTD, but import into your EDD (unless you want to restart if things are too messy) Menu: File->Developer Tools->Import DTD (with the EDD file active) ... DO NOT THINK that you are done yet ! ---------------------------------------------------------------------- STEP 8 Create a Frame Template File: ... e.g. manufacture the usual starting point for an author (like with standard Frame, but with elements rather than paragraphs). (0) Make sure that your EDD has a root element Maybe in SGML you can have several root elements (in XML it is self-explaining from the DTD). In EDD you can have several root elements (which is handy if you the same template for chapters and books for example). If NEEDED only (if you followed all the step, it's not necessary) add to top element in EDD: "Valid as the highest-level element", e.g. Element (Container): Trainingcourse General rule: Tccourses+ Valid as the highest-level element. (1) File->New Document, I suggest to start with a blank (Portrait) (2) Now import Elements from the EDD file into this Template file Menu: File->Import->Element Definitions (3) Test quite a bit if you can edit and if you can see the structure (note that all text looks the same which is normal since you didn't do STEP 5 yet). BEFORE editing formatting rule, I suggest that you try to add content if your DTD is new. Make the XML tags visible (View Menu) for this. (4) REDESIGN your DTD because probably you don't want as many attributes as you are used to have in your XML world. You can't see them as easily in Text world. Also some elements better become attributes if before they have been filtered out with XSLT. You don't want to generate PDF from XML but rather do it directly from Frame .... [$TODO: I did not read about EDD attributes (and their formatting) yet, so the above stuff may be wrong] ---------------------------------------------------------------------- STEP 9: EDD or XML DTD ? 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 its 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) - page 106 ---------------------------------------------------------------------- STEP 10: Associate formatting rules with Elements This is a NEW DOCUMENT: quick-guide-edd.text ---------------------------------------------------------------------- STEP 11: ??? ... probably I miss some other story so far .. ---------------------------------------------------------------------- STEP 12 : Export to XML works :) .... though my XML DTD has wrong case ... ----------------------------------------------------------------------- ----------------------------------------------------------------------- VARIOUS NOTES: ----- Using F+S VIEW MENU: ********** If you are confused in the beginning you can Menu:View:Element Boundaris as Tags Structure View: *************** To manipulate an element left-click in the tree or 2-3 times in the text window, then right-click and you get a context menu: - 'unwrap' deletes a parent To insert an element, click before the element where you want to insert something (+ marked elements can be opened), and select from the Elements Menu To move an element, click inside the round box (NOT on the +/-) and MOVE it Note: If lines a red you made a mistake, fixit :) Elements Menu: *************** ----------------------------------------------------------------------- ----------------------------------------------------------------------- FOUND on the net and xml-doc@egroups.com ----------------------------------------------------------------------- Comparison of SGML and XML World Wide Web Consortium Note 15-December-1997 http://www.w3.org/TR/NOTE-sgml-xml ----------------------------------------------------------------------- From Marcus Carr email: mrc@allette.com.au > FrameMaker/FrameMaker+SGML will not import existing XML documents. > You must continue to maintain your document sources in FrameMaker (or > possibly SGML, if you are using FrameMaker+SGML). Perhaps it's splitting hairs, but it might be more correct to say that the files must look like SGML, which plenty of XML files do. We have a production system in place that produces mortgage documentation out of XML data - it's not that difficult, aside from some niggling issues like empty element syntax. > FrameMaker/FrameMaker+SGML does not support XML DTDs. If you need to > validate your XML against a DTD, you must do so outside FM/FM+SGML. Again, a DTD can be both SGML and XML compliant quite easily. Start by providing an SGML declaration that has OMITTAG set to NO (so you don't need the minimisation indicators) and get rid of any inclusions and exclusions. ----------------------------------------------------------------------- Subject: RE: [xml-doc] XML export capabilities of FrameMaker Date: Thu, 19 Oct 2000 16:20:22 -0500 From: "Mallet, Cathy" We are using FM+SGML, without using SGML, to produce XML. It works very well, although it does have a few minor quirks. You can import your XML DTD into what FM+SGML calls an EDD (element definition document). (You can also in theory create your DTD from scratch within the EDD, but it doesn't entirely work perfectly.) Then, in the EDD, you can map the paragraph and character tags from your FM+SGML templates to the XML elements, so that formatting occurs within your FM+SGML documents as a by-product, so to speak, of applying the structure. You can set up context rules so that a single element might map to this paragraph tag in this context, but to a different paragraph tag in a different context. The EDD also lets you do additional things that can tie your XML elements to particular FM+SGML capabilities, such as designating an element to function as an index marker in FM+SGML. Once your EDD is all set, you import it into your FM+SGML document using File/Import/Element Definitions - much the same way you'd import formats from a template or another document. We found that getting the EDD sorted out was an iterative process; it took a few rounds of importing it into a document, doing some writing, then finding something that wasn't quite right and revising the EDD, before we got to an EDD that we could stick with. Once you've got your EDD sorted out, it's very easy to apply the XML structure to the documents as you write. You simply choose elements from a palette, instead of choosing paragraph or character tags from the designer windows. FM+SGML can give the writer guidance by indicating within the element palette which elements are valid in which parts of the document, etc. A "structure view" window shows you the structure of the document, and highlights in red any area where the structure is not correct. Generating the XML is a snap - you just use FM+SGML's "save as XML" feature. FM+SGML will, however, save each file of a multi-file book as a separate XML file, which is not altogether convenient; if you want one big XML file for your book, you have to find a way to integrate all those component files yourself. We did find that FM+SGML has one or two little quirks to be aware of, though. If you don't have the exact same EDD imported into every one of the files inside a book (this includes having a different versions of the same EDD imported into the same documents, an easy mistake to make if you fine-tune your EDD during the writing process), the XML you produce won't slways be valid (elements appear to get dropped at random), and it can be quite hard to tell where & why there are problems in the XML if this happens. Also, FM+SGML's "validate" option is supposed to be able to validate an entire book against the DTD (as represented in your EDD). We found one oddball problem: if you specify that an attribute needs to have a unique value in it (in the EDD you specify this as being a "uniqueid"), FM+SGML's validate will NOT catch duplicates for you. So if you use unique IDs, e.g. for targets of cross-references/links, you will probably want to find some kind of validation tool beyond Frame's own validation to verify these. Hope this isn't more information than you wanted! Overall using FM+SGML to generate our XML from our own DTD has been a good experience, and I recommend it to anyone who needs to produce both a decent-looking printed doc and an XML version of the same doc from a single environment.