On 2013-09-06 10:09+0100 Andrew Ross wrote: > On Friday 30 Aug 2013 23:43:55 Alan W. Irwin wrote: >> On 2013-08-24 16:50-0700 Alan W. Irwin wrote: >>> On 2013-08-21 16:24-0700 Alan W. Irwin wrote: >>>> In the next day or so I plan to play a bit more with dblatex to see if >>>> I can generate dvi results with it, and I am also ready to deal with >>>> any issues you find as well, but otherwise I believe I have completed >>>> this project. >>> >>> Hi Andrew: >>> >>> It turned out the source of the dvi issue was a dblatex bug (see >>> http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=720624 for a >>> description of the problem and a patch to fix it). Once I applied >>> that patch, the dblatex command finally started working properly to >>> generate dvi results both when dblatex was invoked directly >>> or indirectly via "xmlto --with-dblatex". >>> >>> Please give the updated documentation build a spin following the >>> (newly updated as of revision 12497) directions in >>> doc/docbook/README.developers. Also, please feel free to update that >>> file if you feel more details about the packages required by xmlto are >>> needed. >>> >>> Revision 12497 is the last commit I plan to do in the near term >>> concerning the DocBook backend tools that we use unless you find some >>> easily fixed issue in the documentation build. >> >> Hi Andrew: >> >> One additional piece of news for this thread is that Orion kindly ran >> a number of tests, and as a result I made some additional fixups (as >> of revision 12501) of the Docbook documentation build. One of those >> fixups was to empty DESTDIR before each call to xmlto. That works >> around a bug in xmlto or one of its dependencies (see >> http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=721366) for the case >> when DESTDIR is set for the overall build. As a result of these >> fixups, I get good results for the documentation build and install >> both with and without DESTDIR set for the overall build. Furthermore, >> Orion now reports complete success with a build and install (using >> DESTDIR) of our DocBook documentation on Fedora. (His test was >> without dvi which will probably be removed, in any case, right after >> the upcoming release when I hope to move to the pure UTF-8 approach I >> described in a previous post in this thread.) >> >> So I think I am done with refining the documentation build process for >> this release cycle, but any additional testing by you of the new >> documentation build on platforms accessible to you would be >> appreciated so we don't get any last-minute documentation build >> surprises just before the release. >> > > Alan, > > Thanks for this. After a fair bit of playing around I've got this working on > by Ubuntu system. Since this wasn't entirely trivial and involved installing a > number of new packages I think it is probably worth documenting to help > others.
Currently this is covered in doc/docbook/README.developer by saying essentially pay attention to the run-time errors from xmlto. I don't think we should bother with anything more than that since a further large change (the pure UTF-8 approach see below) is planned right after the release. > > When I initially tried, the doc build was mostly disabled until I installed > xmlto (not surprising!). Having done that the build failed on the dvi with > some undefined latex sequences (e.g. \Epsilon, \Tau,\ texttheta). I didn't > probe too far into this, but disabled the dvi build. Is this the same problem > you encountered? Yes. The dblatex patch should fix this issue, but I would not bother with it, see below. > > The build then failed on the pdf docs with an error about passivetex being > missing. A quick package search suggested I should install xmltex (which I > did). This got me further, but still failed with a warning about fop not being > found. It seems xmlto then used some alternative which didn't work. I > installed fop and I can now build all the documentation except for the dvi. > > I still got a warning about "unable to locate servlet-api in /usr/share/java". > Installing libservlet2.5-java fixes this, but seems to make no discernable > difference to the results. > > I'm not too worried about dvi to be honest. I don't see we need this AND pdf > built by default, though it would be nice to fix it. The dblatex patch I mentioned fixed it for me, but I think the proper thing to do is simply to abandon DVI now since DVI is badly supported (presumably because few are interested in that format any more since it is not UTF-8 aware) and the next change I have in mind (right after the release) to move to a pure UTF-8 approach will force us to drop DVI in any case. So unless I hear differently from you in the next few days I plan to go ahead and completely disable DVI production, and drop it from our website for the current release. > > The conclusion is that the new pdf output looks good (no problems I've noticed > with special characters including greek). The tool chain looks like it is > better supported going forward. Thanks for this work! Thanks for that evaluation, and I am glad the new backend tools are giving good results on your platform. > > 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. 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 __________________________ ------------------------------------------------------------------------------ Learn the latest--Visual Studio 2012, SharePoint 2013, SQL 2012, more! Discover the easy way to master current and previous Microsoft technologies and advance your career. Get an incredible 1,500+ hours of step-by-step tutorial videos with LearnDevNow. Subscribe today and save! http://pubads.g.doubleclick.net/gampad/clk?id=58041391&iu=/4140/ostg.clktrk _______________________________________________ Plplot-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/plplot-devel
