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

Re: Patches



On 2006-05-05 09:46:56 +0000, Rocco Rutte wrote:
> Maybe "layout" is the wrong word. DocBook is very much designed
> towards HTML outpu

This is wrong. It is also used very much to produce PDF. DocBook is
designed to write documentation (hence the "Doc").

> and includes features which are present in HTML, too.

This is not surprising. One could say the same thing with LaTeX.

> >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.

I'd say the opposite. Reusing DTD's is one of the goals of XML.

> >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.

Wrong. Links are logical information: they make sense for any medium.
roff is designed for text layout. PS is for graphical media. BTW, PS
and PDF are basically the same thing (though PDF has some additional
features, such as links); you can't say that PS doesn't depend on the
medium while PDF does!

> 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.

Then propose a solution. But DocBook allows to do much more things
than generating HTML, possibly by extended it.

> >>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,

No.

> why do it only for links and options and not just pretty much
> everything else which could be beautified?

This was an example. You can do other things.

-- 
Vincent Lefèvre <vincent@xxxxxxxxxx> - Web: <http://www.vinc17.org/>
100% accessible validated (X)HTML - Blog: <http://www.vinc17.org/blog/>
Work: CR INRIA - computer arithmetic / SPACES project at LORIA