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!