Re: [docbook-apps] DocBook/XML --> [tgn]roff

[Tilly Bayard-Richard <Tilly dot Bayard-Richard at Jaluna dot COM>]

Bonjour,

>So I want to switch to DocBook/XML for the page and produce both HTML
>and roff out of it.
>Have anyone done that?

I am your man ;-)

I (with my friends...) maintain/author a collection of (~800) man pages in 
DocBook/XML.

To produce HTML output I have been using, docbook-xsl-1.60.1, and xsltproc.
The results were looking good (you'll see later why I am using the past).

Since the Linux man command does not take docbook-xml or sgml, I also have to 
convert to groff. I use  /usr/local/share/xml/docbook-xsl/manpages/docbook.xsl
with a temporary fix for the tables, and xsltproc (see
http://www.sagehill.net/xml/docbookxsl/SpecialHandling.html#RefentryToMan , and 
http://lists.oasis-open.org/archives/docbook-apps/200304/msg00044.html)

The result is quite good (using man on Linux, or on Solaris). Of course, I had 
to "normalize" some of the docbool-xml code for a number of pages, but that was 
far from a disaster.

Recently, I was faced to a new challenge that is, to also publish another 
collection of man pages in groff source (that we do not write) and find a way to 
present the two collections of man pages on-line with a unified look.

I had to find a tool to convert groff to html. I chose vh-man2html 
(http://www.linuxjournal.com/article.php?sid=1343 by Michael Hamilton).

With much help from my friends (for C code, shell scripting, etc.) we featured 
and adapted to our needs a new process to handle our man pages:
1/ convert the docbook-xml man pages in groff using docbook-xsl and xsltproc
2/ run our "customized" vh-man2html on the two collections of groff man pages to 
   produce the html ouput; in addition vh-man2html generates the alphabetical    
   indexes of man page names with their refpurpose.

We are still working on this, but what remains to be done is mainly cosmetic 
improvements of the html output.

I am not a docbook expert, rather experimenting/learning the subject step by 
step, but I am really enthusiastic about the tools, and the information, tips 
and help I found on this mailing list. That's why my advice is, go ahead for 
your man page(s) in docbook-xml, and use docbook-xsl with xsltrpoc to produce 
html and *roff!

BTW, I have a new question which I am going to send later separately, because I 
am not sure yet of how to make cross-links from our books to the man pages!

Tilly



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe at lists dot oasis-open dot org
For additional commands, e-mail: docbook-apps-help at lists dot oasis-open dot org