Re: Patches
Hi,
* Vincent Lefevre [06-05-04 17:07:29 +0200] wrote:
On 2006-05-04 12:18:23 +0000, Rocco Rutte wrote:
* Vincent Lefevre [06-05-04 13:29:29 +0200] wrote:
>[...]
>>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.
I'm not only talking about the manual, but the documentation in general.
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.
AFAIK, DocBook doesn't mix up markup and layout. However there could
be several levels of markup.
Maybe "layout" is the wrong word. DocBook is very much designed towards
HTML outpu and includes features which are present in HTML, too.
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.
You can transform DocBook + possible PIs into DocBook (by processing
the PIs and generating other information), then transform the result
into HTML. I mean, Mutt doesn't need to have its own DTD for its
documentation.
I think it needs it. Right now, the use of XML actually is heavy abuse.
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).
This is not layout: it is purely logical information and doesn't depend
on the medium. But some links may be redundant in the source.
Well, links do depend on the medium: roff doesn't, text doesn't, PS
doesn't, only PDF and HTML do.
What I mean with XML abuse is this: there's a number of destination
formats we now generate documentation for: man pages, text (template
Muttrc), manual (HTML + text) generated by different algorithms. But as
we currently only use XML to generate HTML it's okay to assume the
destination format has links.
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.
For example, in init.h for an option's description, we could want to
link to a manual section for further details or a discussion or the
like. With XSL from just one source this means to write just one
template per destination: if the options section is embedded in the
manual, a link is produced, for muttrc(5) we could point to muttall(1)
which doesn't exist yet, for Muttrc we could point to
/path/to/manual.txt and much more.
Now we have more or less distinct mechanisms to generate docs. I'd like
to use only one XML file as the basis to generate the rest from (because
that's what XML is for).
If you worry about the work it takes: with XSL you can tell the
processor to just copy everything as-is for which there isn't a
template. That means the transition to a custom XML dialect could be
made slowly and step by step "in place" easily. A DTD (for which I know
someone who'll write it) can be added as the last step after we're done.
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.
Well, in fact, the PI would be unnecessary here. Searching for all
varname elements and transforming them would be sufficient.
But once you need to process it twice from XML source to HTML, why do it
only for links and options and not just pretty much everything else
which could be beautified?
bye, Rocco
--
:wq!