On 2013-09-06 09:57-0700 Alan W. Irwin wrote: > On 2013-09-06 10:09+0100 Andrew Ross wrote: >> Some comments: >> >> The cmake support is not too robust at the moment as my testing shows. We >> probably need to test for e.g. fop if that is required so that it fails >> gracefully (and with a helpful error message!) >> >> Fop seems to be required at the moment. This is quite a hefty requirement as >> it pulls in java and quite a number of added packages. This is probably ok >> since we're not building the documentation all the time. > > The next change I have planned (moving to a pure UTF-8 approach just > after the release) is going to be pretty big. xmlto will be used just > for html results. dblatex with xetex backend will be used to generated > PDF and PostScript. DVI will be dropped. There should be no more need > for passivetex (which is deprecated in any case since it is a package > with many bugs and no upstream development for many years) or fop. > Those dependencies will get replaced by the xetex dependencies which > is most of texlive, but presumably that was a dependency in any case. > I suggest for now we should stick with the current non-robust cmake > support until we make this further planned change to a pure UTF-8 > approach. > > I am very much looking forward to that further change since it will > give us access to a huge range of mathematical and human-language > glyphs in our DocBook source documentation. It also finally makes our > documentation build rely on UTF-8 clean backend tools which I am > pretty confident (because there is a lot of interest in UTF-8) will be > well supported for many years to come. I am actually tempted to move > ahead with the pure UTF-8 approach now, but that is clearly too much > change just before a release so I will stick with the plan of doing > this change just after the release which will give us a full release > cycle to evaluate it.
As of revision 12582, I have implemented this change which I hope is the last fundamental change in how we generate our documentation for years to come. I have also substantially updated doc/docbook/README.developers and disabled the SGML/DSSL backend tools we used for 5.9.9 and previous releases and which were deprecated for 5.9.10. The summary is the results for UTF-8 documentation are much improved compared to previously, and we are probably doing the best that is possible. Nevertheless, there are still some limitations due to system and tool issues. See the updated doc/docbook/README.developers for discussion of those UTF-8 details. There may also be some style issues in the present results that need to be addressed since I used default style virtually everywhere except the part of the HTML styling that was done with a cascaded stylesheet. One known limitation of the present method of using dblatex with the xetex backend is the only way to generate PostScript results is to use pdftops to convert the generated PDF results to PostScript. I implemented that method in the CMake code, but after one look at the results (which were 50 (!) times larger than the corresponding pdf results, slow to generate, slow to execute, and ugly as well) I disabled it. This disabling of PostScript results means our next PLplot release would not have documentation in PostScript form. I think that is probably OK since PDF readers are widely available to read the PDF form of our documentation, but I welcome additional comments on dropping PostScript from anybody here who might still care about that form of our documentation. @Andrew and Orion: I would appreciate your comments on this change in the way we generate the pdf form of our documentation. In particular does it build well and give good looking results on the various Linux platforms accessible to you? For example, Andrew, I think you expressed some concern before about cross-references not being in red for the pdf version? I am happy to report that red cross-reference links are present (as a result of the default style) with this new method of generating the pdf form of our documentation. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); the Time Ephemerides project (timeephem.sf.net); PLplot scientific plotting software package (plplot.sf.net); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ ------------------------------------------------------------------------------ October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60134791&iu=/4140/ostg.clktrk _______________________________________________ Plplot-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/plplot-devel
