commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <stei...@yahoo.com>
Subject Re: [math] documentation principles
Date Fri, 16 May 2003 18:48:26 GMT

--- "O'brien, Tim" <tobrien@transolutions.net> wrote:
> On Fri, 2003-05-16 at 13:00, Phil Steitz wrote:
> > --- robert burrell donkin
> > <robertburrelldonkin@blueyonder.co.uk> wrote:
> 
> > > On Thursday, May 15, 2003, at 10:34 PM, Phil Steitz
> > We can look into this as we get further along.  For
> > now, I assume it is OK to add links to external
> > sources as appropriate in the javadoc. 
> 
> Not to sound like a Maven partisan, but linkcheck is
> integrated as a
> Maven report,
> http://jakarta.apache.org/commons/codec/linkcheck.html. 
> I
> think it is fine to add references to external
> documentation as long as
> we make sure that our links are working - i.e. make
> getting linkcheck
> down to zero errors a condition for a release.

Excellent. That will make documentation much easier.

> ( Question, so why doesn't codec have a zero length
> linkcheck?  I plead
> guilty. )
> 
> > Here again, something to think about as we get further
> > along. One last point before letting this drop (for
> > now).  Mathematical documentation in HTML is painful,
> > trying to embed it in javadoc is cruel and unusual
> > punishment. This is another reason to externalize the
> > user's guide.  The eventual user's guide will need to
> > include images and/or possibly be distributed as pdf,
> > tex, or postcript.  Probably should not have just
> > opened up that can of worms...Something to think about
> > down the road.
> 
> I remember that Forrest has a nice little feature of
> converting your
> xdoc to PDF - click on the PDF link on
> http://xml.apache.org.  Although
> it seems a little twisted, we could use Maven for site
> generation, and
> Forrest for documentation - unless I'm missing some Maven
> plugin that
> generates PDF output.
> 
The problem is how to get the math goodies into the xdoc. 
Maybe brings us back into a MathML discussion. I haven't
looked into this in a while, but in the past, I have always
preferred tex for math composition, which can be rendered
into postcript or pdf. Looks like MathML is effectively
obsoleting tex. There are browser plug-ins, but I doubt we
can count on these.  This leads to the need for pdf or
postscript -- or some engine that generates images + html
from MathML.  It's not the pdf format that I care about,
just the ability to produce reasonable math docs in a
platform-independent way. 
> 
> 
>
---------------------------------------------------------------------
> To unsubscribe, e-mail:
> commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail:
> commons-dev-help@jakarta.apache.org
> 


__________________________________
Do you Yahoo!?
The New Yahoo! Search - Faster. Easier. Bingo.
http://search.yahoo.com

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message