On Sat, Sep 10, 2011 at 07:23:29PM -0500, Jon Elson wrote:
> I just had a very worrisome message from John Thornton about the state
> of the documentation, and would like to find out if anyone knows what is
> going on? Apparently, Kim Kirwan took upon himself the task of
> revitalizing the whole documentation preparation system, but at least right
> now the future docs are not in good shape. I have identified 3 areas where
> there are serious problems.
> 1. Many places in the docs, latexmath is used to format special math
> symbols
> and formulas (sqrt symbols and fractions, mostly). These still work fine in
> the PDF output, but in the HTML docs, depending on exact syntax, you either
> get the LaTeX commands verbatim or nothing at all.
There is problem with math formulas... One workaround is to generate images
for each formula. I'll look into it this week.
> 2. The entire section on hardware interfaces that used to be in the
> Integrator's
> Manual is missing from the PDF's, as far as I can tell, it appears
> nowhere in
> any manual, although it SHOULD appear now in the HAL manual, I think,
> based on the HTML version.
That's may be easily fixed by just adding several lines to Master document.
> 3. This can probably be fixed easily, but there is a main HTML table of
> contents, and then each major manual section has its own TOC. The
> individual
> TOC's apparently don't get updated by the build process, so a number of the
> entries just go back to the linuxcnc.org home page.
That's caused by incorrect xml:base attribute in .html docs. Pages are included
into linuxcnc.org template files and thus all relative links (a href='#xxx')
are broken. It should be fixed site-wide and not found if you host docs without
such additions.
> Since the 2.5 release is (hopefully) close at hand, and since the 2.5
> manual set
> and the development master docs are now on the documentation page, these
> problems are now apparent to general users as well as the developers.
> Specifically,
> I'm trying to fix a bunch of omissions and outright mistakes in my PPMC
> documentation,
> and there is now no cogent version of that doc available at all! The
> HTML have this
> latexmath problem so all the formulas are missing. And, there is NO PDF
> at all
> being built from the ascii file.
Currently all PDF's are built from asciidoc files.
Also not mentioned is that many PDF internal links are broken...
Pavel
------------------------------------------------------------------------------
Using storage to extend the benefits of virtualization and iSCSI
Virtualization increases hardware utilization and delivers a new level of
agility. Learn what those decisions are and how to modernize your storage
and backup environments for virtualization.
http://www.accelacomm.com/jaw/sfnl/114/51434361/
_______________________________________________
Emc-developers mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/emc-developers
