Better documentation

Sunday, October 9. 2005

As readers of the mailing lists and/or ChangeLogs may have noticed, some time ago I added an ad-hoc stylesheet to transform the DocBook/XML based manual into LaTeX.

As the manual itself isn't valid and plain DocBook but contains some goodies to make it more consistent and easier to write, so does the LaTeX (stylesheet) file. That means it's not a general DocBook to LaTeX conversion solution.

At our Berlios site, there're two links given: one for a PDF generated by pdflatex(1) and one PostScript file generated by latex(1).

The Makefile in the source's doc subdirectory contains two targets to build them: manual-ng.pdf and manual-ng.ps whereby for the latter the breakurl.sty package is required which doesn't seem to be installed by default everywhere.

I'm writing all this because I already started an attempt to continue with LaTeX instead of SGML back then. It would be really nice if people/users could provide input (in any way) on which direction to go...

Posted by Rocco Rutte at 15:39 | Comments (3) | Trackbacks (0)

Trackbacks

Trackback specific URI for this entry

No Trackbacks

Comments

Display comments as (Linear | Threaded)

You may want to have a look at our transform process. We're writing on a manual for recent stable GIMP versions. The module is called 'gimp-help-2' and it's available at cvs.gimp.org and docs.gimp.org.

I still would stick to use DocBook/XML instaed of plain LaTeX. Not that the latter one is bad, it's just the choices you have by using XML. The transformation from LaTeX to HTML is uglier in my opinion, than XML to HTML (well, surprise) and other markup languages.

#1 Roman (Homepage) on 2005-10-10 11:24 (Reply)

I guess there's nobody really accepting a dependency on a full TeX system in order to be build the manual so I guess we'll really (have to) keep it this way as XML to LaTeX works already.

When I have some more time, I'll see what tex4ht can do about it. From what I can tell after lots of experience with it, only the table of contents could look nicer but that's it (we tidy for cleanup anyway).

Also, there're many more things I'd like to see in the manual like when providing longer example configs: in LaTeX we could do a table of contents for them, correctly number them and do syntax highlighting all with just a few lines of LaTeX code I could type within a few seconds. But to have this via our custom XML to LaTeX stylesheet is not really nice for HTML readers...

We'll see and thanks for your pointers and comment!

#1.1 Rocco Rutte on 2005-10-10 21:47 (Reply)

LaTex would still be a perfect fit. I had nasty experiences using Doc/XML. By the way thanks for providing this information.

#2 Wong PoKér Hu (Homepage) on 2005-11-10 04:43 (Reply)

Add Comment

Name
Email
Homepage
In reply to
Comment	To prevent automated Bots from commentspamming, please enter the string you see in the image below in the appropriate input box. Your comment will only be submitted if the strings match. Please ensure that your browser supports and accepts cookies, or your comment cannot be verified correctly. Enter the string from the spam-prevention image above: Standard emoticons like :-) and ;-) are converted to images.
	Remember Information? Subscribe to this entry