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

Re: Patches



Hi,

* Vincent Lefevre [06-05-09 23:27:21 +0200] wrote:
On 2006-05-07 10:44:12 +0000, Rocco Rutte wrote:

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

Is there any reason?

I only have seen FOP when it came to XML->PDF. I prefer a TeX engine which has proven to be good at typography.

And for TeX I prefer LaTeX instead of automatically generated plain TeX since then I can more easily use my own macros.

This (for me and my purposes) makes sence as I usually do it like this: write in some meta-format, use XSL to generate DocBook and use XSL to generate LaTeX while I reimplement the XSL logic in LaTeX macros.

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).

I don't think so. What would be the gain with a docbook -> plain text
direct convertor?

It's IMHO much more straight forward and the right thing to do. My problem is that HTML has features which text doesn't and that it's required to implement some more logic than a HTML browser could do.

A direct converter can be made to make a high quality transition.

For example, when you use a link in DocBook it works in HTML. But when converting to text then you loose the information. Of course, you could still do highlighting or something like that to point out that it's not a simple word but used to be a link. By direct conversion you could add a section or page number in brackets so that it's easier to look up.

In HTML the section and page numbers don't really make sense (except for printing).

My point basically is that now it works, but the quality could be much much better if we didn't just only stick with the tools available but use some of our own that do _exactly_ what we need (another example: to improve quality I've made another patch and branch properly using tables instead of <screen/> tags for things which really should be presented by use of tables).

To illustrate what I'm talking about, I've created another branch in my git tree:

  
<http://user.cs.tu-berlin.de/~pdmef/gitweb.cgi?p=mutt/.git;a=shortlog;h=pdmef%2Bpatch%2Bmanualng>

which adds the 'mutt:' namespace and a <mutt:optref/> tag for now. Somebody writing documentation just needs to know about this and not about the concept of creating a link or an index entry (because this, as I wrote, IMHO depends on the target medium). Also, the writer doesn't need to care about such details like that we need use dashes instead of underscores for creating/refering to section IDs for option names because this is not content- but DocBook-related.

The manual is now created as 'manual-pre.xml' and converted to DocBook with this XSL file:

  
<http://user.cs.tu-berlin.de/~pdmef/gitweb.cgi?p=mutt/.git;a=blob;h=90e185739e6bc6daa2dc656a6b69c110d7710046;hb=pdmef%2Bpatch%2Bmanualng;f=doc/mutt2db.xsl>

to manual.xml. This is processed as usual.

For me, this is the way to go because it's shorter and focuses more on the content instead of details such as links or an index.
  bye, Rocco
--
:wq!