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

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!