OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[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. [&alpha;] .
(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

P.S. If it helps to see where I am coming from, the original 
bastardized HTML-ised linuxdoc.dtd version can be seen here:

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC