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

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!