Re: Patches
Hi,
* Vincent Lefevre [06-05-04 13:29:29 +0200] wrote:
On 2006-05-04 07:48:34 +0000, Rocco Rutte wrote:
The version doesn't match. However, I don't think this could lead
to errors. Are you sure you don't have incorrect catalog files?
It leads to errors (>1500) and my catalog files are correct. I just
don't have docbook 4.1.x installed since I don't need it (because the
DTD URL implies it's DocBook 4.2). So there's no catalog entry for 4.1.x
but for 4.2 (and thus the errors disappear with the fix).
[...]
which is ugly. Also, personally I don't like being limited to DocBook
only. In my opinion, DocBook is an intermediate format people convert to
to get fancy HTML output, but it's not really suitable for humans to
write docs in.
Well, DocBook + PIs may be sufficient.
My point is that I don't like mixing up markup and layout as DocBook
does. For people writing documentation only the markup is of interest
and the rest should be hidden as much as possible.
"Hidden" means to generate all the layout information for DocBook from
the markup (i.e. mutt's own XML dialect) via XSL so there're no
inconsistencies possible (well, almost, of course).
IMHO it would be cool to have just:
<option>header_cache_verify</option>
I think this should be <varname>header_cache_verify</varname>.
and let XSL expand it to:
<link
linkend="header-cache-verify"><literal>$header_cache_verify</literal></link>
because that's what it's for.
But the source would still be DocBook.
Not the way I'd like to have it. I want to add the layout by
transforming mutt's custom XML dialect to DocBook which then gets
processed to HTML.
One could also write:
<varname><?makelink?>header_cache_verify</varname>
and process the makelink PI to generate the link.
That's a good example for the separation I'm talking about. For me, the
concept of a link or hyperlink is layout because the target medium must
support it (like in LaTeX where the hyperref package supports links with
a pdftex engine and not with a plain tex engine but that is hidden from
the author).
In your example, you'd have to add the <?makelink?> sequence to every
variable/option you use in the text. I'd like to add DocBook's <link/>
tag via XSL because I only need to do it once in the XSL file and not
once per <varname/> usage in the manual itself.
The cool thing is that once one has taken the time to properly add
markup sequences to the manual, a modification like printing variable
names in typewriter for DocBook is just a one-line change in the XSL
file. I.e. from there on you can do everything with it what you like
without having to touch the manual source.
bye, Rocco
--
:wq!