Menu
▾
▴
[Plplot-cvs] SF.net SVN: plplot:[12497] trunk/doc/docbook/README.developers
|
From: <ai...@us...> - 2013-08-24 22:39:25
|
Revision: 12497
http://sourceforge.net/p/plplot/code/12497
Author: airwin
Date: 2013-08-24 22:39:23 +0000 (Sat, 24 Aug 2013)
Log Message:
-----------
Update these developer directions based on the current xmlto backend
tools that are being used. Also include some plans about further
changes once we allow UTF-8 strings in our documentation.
Modified Paths:
--------------
trunk/doc/docbook/README.developers
Modified: trunk/doc/docbook/README.developers
===================================================================
--- trunk/doc/docbook/README.developers 2013-08-24 22:36:57 UTC (rev 12496)
+++ trunk/doc/docbook/README.developers 2013-08-24 22:39:23 UTC (rev 12497)
@@ -12,7 +12,7 @@
(README.developers) instructions for building the documentation from the
DocBook source files in this directory. The documentation that is built
includes man pages of the API as well as complete versions of the
-documentation in html, dvi, postscript, pdf, and info form.
+documentation in HTML, dvi, PostScript, PDF, and info form.
Configuring and Building
========================
@@ -21,14 +21,17 @@
the documentation from the DocBook source so you can immediately see and
evaluate the results of your efforts.
-Here is how. Simply add the cmake option -DBUILD_DOC=ON to your normal
-cmake command-line options for the PLplot build. The resulting cmake step
-looks for all the tools required for the documentation build and turns off
-the documentation build and gives WARNING messages if any of those required
-tools are missing. Those messages should be sufficient for you to figure
-out what DocBook/XML related tools you need to install in order to build the
-documentation. N.B. As far as we know, the complete set of required tools
-is only available on Linux so you will need a Linux system to do a
+Here is how. Simply add the cmake option -DBUILD_DOC=ON to your
+normal cmake command-line options for the PLplot build. The resulting
+cmake step looks for all the tools required for the documentation
+build and turns off the documentation build and gives WARNING messages
+if any of those required tools are missing. Furthermore, at run-time
+xmlto (used below) checks for required backend tools. So cmake
+messages with the -DBUILD_DOC=ON option _and_ run time messages from
+xmlto should be sufficient for you to figure out what DocBook/XML
+related tools you need to install in order to build the documentation.
+N.B. As far as we know, the complete set of required tools is only
+available on Linux so you will need a Linux system to do a
documentation build.
The DocBook Back-end Tool Chains
@@ -57,27 +60,103 @@
db2x_xsltproc limitations. db2x_xsltproc and db2x_texixml are from
the docbook2x package.
-3. web pages.
+3. Our HTML and print(dvi, PostScript, and PDF) results are all generated
+with xmlto using respectively no special options and the html subcommand,
+the experimental --with-dblatex option and dvi subcommand, and
+the experiemtnal --with-fop option and the ps and pdf subcommands.
-Our web pages are generated with openjade.
+N.B. for the dvi results to work as of this date (2013-08) it is
+necessary to apply the dblatex patch given at
+http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=720624
-4. dvi file
+The backend tools that the xmlto convenience script selects are
+all XML/XSL as opposed to the previous set of SGML/DSSSL backend
+tools used to create the HTML and print results. For more information
+see "Further notes on the backend tools" below.
-Our dvi file is generated by
-openjade --> jadetex
+Further notes on the backend tools
+==================================
+Note from AWI on the project he just completed (as of 2013-08) to use
+xmlto (a shell script that gives convenient access to a wide variety
+of XML/XSL DocBook backend tools) as the DocBook backend generator for
+HTML and print (dvi, PostScript, and PDF) forms of our documentation.
+(The man and info forms of our documentation are already prepared
+using XML/XSL DocBook backend tools.)
-5. PostScript file
+One immediate advantage of xmlto is that it detects
+(at run time) whether all the software components it needs are installed
+so this substantantially reduces the testing for DocBook backend components
+required of our build system.
-Our PostScript file is generated from the above dvi file
-using dvips.
+The use of the old/deprecated SGML/DSSSL backend tools for HTML and
+print are still available (as of 2013-08) if the developer
+specifies the PLplot cmake option -DDOCBOOK_XML_BACKEND=OFF along with
+-DBUILD_DOC=ON. However, the HTML results from that option are not
+very good (the Greek characters in the table giving Roman-Greek
+equivalents are gibberish) presumably because bit-rot has set in for
+the SGML/DSSSL tools in the decade since there has been any upstream
+development for those tools. So at the start of the next release
+cycle the plan is to drop use of the SGML/DSSSL backend tools
+altogether.
+The only limitation of the current xmlto backend results that I am
+aware of is the representation of S̅(f̲r̲e̲q̲) is not done very well in
+HTML (an empty string is used rather than S̅(f̲r̲e̲q̲)) or the print
+results (S(freq) is used rather S̅(f̲r̲e̲q̲)). Note that overlining and
+underlining do not work at all for modern PLplot device drivers such
+as cairo and qt so a much higher priority should be given to fixing
+those issues rather than fixing the issue of representing overlining
+and underlining in the generation of the documentation! Furthermore,
+instead of using special tricks for dealing with the representation of
+overlining/underlining (as was done for the SGML/DSSSL backend tools),
+the correct thing to do in the long term (i.e., after the use of
+SGML/DSSSL backend tools is completely removed since SGML is not
+compatible with UTF-8) is to make the tool chain used to convert our
+DocBook documentation to various formats completely UTF-8 aware so
+that, for example, UTF-8 glyphs for underlining overlining as well
+as UTF-8 strings such as occur in our unicode examples
+23, 24, and 26 could be included directly in the DocBook source of
+our documentation.
-6. pdf file
+As if this date (2013-08) it appears to me the best UTF-8 way forward
+for html is the current html method (which should be transparent
+to UTF-8 strings although I haven't tested that in detail with
+truly exotic UTF-8 strings). And the best UTF-8 way forward for
+print results is the experimental --backend=xetex option for the
+dblatex command.
-openjade --> pdfjadetex
+To demonstrate the UTF-8 power of xelatex try the xelatex command on
+the example given at http://en.wikipedia.org/wiki/XeTeX. All those
+non-Western glyphs _and_ scripts seem to come out fine in the
+resulting pdf and conversion to an equivalent PostScript result with
+pdf2ps seemed to preserve all those glyph and script results as well.
+Furthermore, I recently tried
+dblatex --backend=xetex -o plplotdoc.xetex.pdf --pdf plplotdoc-print.xml
+
+and the resulting plplotdoc.xetex.pdf document looked good (both Greek
+table and function API) with the default style. Although currently
+unnecessary from my perspective, it looks like the dblatex -p option
+is what you should use to style such results further if anyone feels
+the need. (Note that the --backend=xetex dblatex option is not
+accessible from the xmlto --with-dblatex command.)
+
+The only drawback of this xetex approach that I can determine at the
+present time is you can only produce PDF with it. PostScript could
+then be generated using pdf2ps, but there is absolutely no way to
+produce dvi results using xelatex or the --backend=xetex option for
+the dblatex command. So if we do start inserting general UTF-8
+strings into our DocBook source (say a table of Math symbols or
+comments concerning our multilingual Peace flag example), we would
+have to complete drop dvi, but I think that is an acceptable price to
+pay for the huge range of glyphs that are available with UTF-8. So I
+believe that dropping dvi and moving to the above command to generate
+our PDF documentation is something we should consider for the near
+future (when the possibility of using of the SGML backend tools is
+completely removed from our build system).
+
Validation
==========
@@ -96,6 +175,15 @@
files in doc/docbook/src, and you don't really feel it is necessary to check
every change by doing a complete documentation build.
+In addition, the xmlto commands used to build the HTML and print
+part of the documentation automatically include a validation step
+with xmllint. It turns out that xmllint is more sensitive than onsgmls
+to DocBook XML errors. On the other hand, onsgmls handles any
+errors it finds with ease while xmllint tends to segfault when there
+is a validation error. So use "make validate"
+first to detect any obvious validation errors using onsgmls to avoid
+situations where xmlto's call to xmllint will segfault.
+
Testing the documentation that has been built.
==============================================
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
