[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: documentation types

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

Thaddeus H. Black
508 Nellie's Cave Road
Blacksburg, Virginia 24060, USA
+1 540 961 0920, t@b-tk.org, thb@debian.org

Attachment: signature.asc
Description: Digital signature

Reply to: