<<< Date Index >>>     <<< Thread Index >>>

Re: Patches



Hi,

* Vincent Lefevre [06-05-06 20:18:50 +0200] wrote:
On 2006-05-05 09:46:56 +0000, Rocco Rutte wrote:

Maybe "layout" is the wrong word. DocBook is very much designed
towards HTML outpu

This is wrong. It is also used very much to produce PDF. DocBook is
designed to write documentation (hence the "Doc").

Hmm. I know that my ideas are sometimes very strange. But DocBook is certainly not what I would use to produce PDF with.

For HTML it's okay since the actual "rendering" (paragraphs, line breaks and all that) is up to the browser. But for PDF I wouldn't want to go with FOP or the like. I prefer a TeX engine and TeX can be produced from a custom XML dialect (getting the tables right generically from DocBook is difficult).

For mutt-ng I hacked up XSL to do that:

  <http://mutt-ng.berlios.de/manual/manual.pdf>
  <http://mutt-ng.berlios.de/manual/manual.ps>

(If one is actually interested in that, the PS version has an index, too, which would be hyperlinked in the PDF)

I think it needs it. Right now, the use of XML actually is heavy abuse.

I'd say the opposite. Reusing DTD's is one of the goals of XML.

I'm not that much of an XML expert. But aren't DTDs obsolete in favor of more powerful validation techniques (since the DTD was there before XML)?

Once we already have XML, we could use it to generate everything else from it (muttrc(5), the manual, the template Muttrc file, etc). This would allow us to have more powerful (and in the end more consistent) documentation in init.h for the options.

Then propose a solution. But DocBook allows to do much more things
than generating HTML, possibly by extended it.

What else can you generate without pain (I consider the PDF output from DocBook sources "pain" since I'm used to see TeX-generated PDF output)? Is there even an easy way to generate plain text?

With Brendan I had a short discussion on IRC and he mentioned asciidoc as an alternative. I haven't really used it but maybe that is an option, too.

The real problem I think we have right now is that I see the need for rethinking the way we generate docs in general while others (like you) don't. I only mentioned a custom XML dialect as one possibility to make writing documentation easier but am, of course, open to other ways such as asciidoc. I just want to have a solution that is abstract enough to easily generate all types of documentation from (and the kludge to use w3m or lynx to dump the HTML manual to plain text is already a hint that DocBook maybe lacks capabilities).

At least there's plenty of room for improvements (like replacing the <screen/> sections in the manual by tables for the function reference, etc.) so some smaller steps could be made without moving away from DocBook...

  bye, Rocco
--
:wq!