Re: documentation types
"Thaddeus H. Black" <t@b-tk.org> writes:
> On Fri, Feb 10, 2006 at 01:47:11PM +0100, Remi Vanicat wrote:
>> Well, i personally like very much to have all (well a lot of) my
>> documentation accessible, and searchable by dwww. For this I would want
>> the html to be already generated, and I'm probably not the only
>> one. Why not just create a -doc package that contain the tree of them,
>> or may be only pdf and html (but there will be people to disagree with
>> me on this).
>
> Hello Remi. Question please, for you and anyone else who cares to
> comment. I happen to maintain some documentation which has lots of
> mathematical formulas, geometrical diagrams, etc. I also happen to be
> upstream for this document. Docbook and other generic markups have
> always seemed to me a poor solution for the document, which currently is
> marked up only in LaTeX---but this also means that no general
> html/dhelp/dwww version of the document exists, and furthermore that the
> document's text is hard to grep.
Note that you could try hevea/latexhtml to transform you documentation
to html. It might even lead to good result. Just try (it might not be
very good, but it might be good, hevea do a lot of good work for such
translating).
> Regrettably but naturally, it also means that (unless the user is
> an odd sort who likes reading raw LaTeX source) the user cannot view
> the document on the console.
>
> At present the document is installed as a *.ps.gz and a *.pdf.gz only
> (there is a manpage, too, but it is brief and has no formulas or
> diagrams). Is this right in your view? Or would you advise maintainers
> like me to do otherwise? If there existed a better solution which did
> not greatly increase the labor of maintaining such documentation, I
> would be interested to learn of it. Maybe MathML is the answer---I have
> not tried it so I am not sure---but when it comes to numbering
> equations, stacking subscripts, formatting formulas too long to fit on
> one line, tracking citations, referring to figures, specifying vector
> graphics in diagrams, etc., one gets the impression that MathML and the
> associated tools may not quite be up to the job. In fact it is hard for
> me to imagine that any generic markup could do the job right. But I
> don't know and would be pleased to hear contrary advice in the
> matter.
Well, when i wrote mathematical formula, it is in latex. I've heard of
latex to MathML translator for formula that give you the possibilities
to do wrote mathematical formula using the good old latex way, then
translating it to MathML.
--
Rémi Vanicat
Reply to: