[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: linuxdoc to docbook migration
Dear Docbook users, I'm a Docbook beginner. I have a 300-odd page scientific software manual which I migrated to a minor variant of the linuxdoc.dtd several years ago. For the next version, I would like to migrate it to the docbook.dtd. The primary objective is nicely formatted HTML output. The manual in question documents the functionality and control of a program that is almost entirely controlled by ASCII options and commands contained in a command file. I have already used a linuxdoc to docbook convertor to convert the gross structure of the document. But still I have a very large number of errors (>7000) trying to parse the document thru jade (using the docbook2html convertor in the debian woody distribution) Some additional background - this is a GPL-ed software package, which I am reluctant to spend any money on. I was intending to use the xemacs psgml mode editor to help with the editing process. Most of my document errors stem from about 3 basic failings. (1) <sf> default program values (2) [ ] formulae (i) super/sub scripts (ii) iso entities greeks/symbols (3) <dm> equations (display math?) (1) The control file for the program caters for a huge variety of alternative behaviour. A very large number of default options are built into the program and these often have a redundant "command argument" which forces the required behaviour. In the original linuxdoc document I used the <sf> serif font tag to identify such default command arguments. I am hoping there will be a more apropriate docbook alternative to highlight user commands which are defaults. (2) (i) to get html superscripts and subscripts for both footnotes, table footnotes (e.g. [<sup>1</sup>]) and mathematical notation (e.g. [F<sup>2<sup>]), I abused the linuxdoc.dtd <f></f> notation. (remapped as []) (ii) I also had to abuse the [] notation to get greek symbols in the body of the text e.g. [α] . (3) <dm> was just a glorified version of [] which got a line to itself. (Correct rendering of the manual into HTML required sgmltools and a good deal of post processing.) Now of course I would like to learn the more appropriate ways of doing these things with the docbook.dtd. My initial skimming of "DocBook: The Definitive Guide " seems to suggest that each instance of linuxdoc "[]" element abuse will blow out into a 20 element, 40 line essay using <equation> or <inlineequation> and MathML or LATEX. That's rediculous. I can't believe this is how it has to be. Isn't there an easier way? If it really has to be this way, is there a standard way to simplify it greatly using entity references, because something like F^2 = [F<sup>2<sup>] is probably used more than 100 times. Also I read someplace (the w3c MathML site) that there may be some free software for authoring equations which could be cut and paste into documents. Any recommendations? Any constructive advice welcomed. Thank you Doug P.S. If it helps to see where I am coming from, the original bastardized HTML-ised linuxdoc.dtd version can be seen here: http://xtal.crystal.uwa.edu.au/man/xtal3.7.html
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC