Docbook documentation: Improve directions for testing results

Alan W. Irwin · Alan W. Irwin · commit 6adfdb303975 · 2015-04-07T17:03:03.000-07:00
diff --git a/doc/docbook/README.developers b/doc/docbook/README.developers
@@ -30,11 +30,11 @@ XML::Parser and XML::DOM (man); xmlto (html); and dblatex and xelatex
 
 After the cmake step using -DBUILD_DOC=ON you must run either
 
-make all
+make -j4 all >& all.out
 
 or
 
-make build_docbook_documentation
+make -j4 build_docbook_documentation >& build_docbook_documentation.out
 
 to build the DocBook documentation.  (The former builds all aspects of
 PLplot including the documentation, while the latter is quicker
@@ -225,29 +225,35 @@ paragraph just after Table-3.5.
 
 1. man pages.
 
-(for MANPAGE in *.3plplot; do nroff -man $MANPAGE ; done) |less
+I cannot figure out how to get nroff to work properly with utf8 man pages
+so use the man command to test the generated man pages as follows:
+
+From the top of the build tree....
+
+mkdir -p man/man3
+ln -s $(find $(pwd) -name "*.3plplot") man/man3
+for MANPAGE in $(find man/man3 -type l|sort|grep -E '(plot3dcl|plsurf3dl)'); do MANPAGE1=${MANPAGE##*/}; man -M./man ${MANPAGE1%%.3plplot} ; done
 
 Two of our man pages (plot3dcl.3plplot and plsurf3dl.3plplot)
-currently contain utf8 symbols (for the math symbols &le; and &ge;).  Those
-symbols do not render correctly using nroff -man (or any other
-recommended nroff options such as -Tutf8).  However, they display
-without issues if viewed with man (by copying the files to a temporary
-directory man/man3 and viewing them with, e.g., "man -M./man
-plot3dcl").
+currently contain utf8 symbols (for the math symbols &le; and &ge;) so I have selected those in the
+above example, but if you prefer to look at all man pages that "|grep -E '(plot3dcl|plsurf3dl)'"
+stanza should be dropped.
 
 2. info pages.
 
-info --file plplotdoc.info
+info --file doc/docbook/src/plplotdoc.info
 
 3. web pages.
 
-Browse with your favorite browser the index.html file that is generated
-by xmlto.
+Browse with your favorite browser the
+doc/docbook/src/index.html file in your
+build tree.
 
 4. pdf file
 
-Browse with your favorite browser the plplot-$version.pdf file that
-is generated by dblatex.
+Browse with your favorite browser the 
+doc/docbook/src/plplot-$version.pdf file
+that is generated in your build tree.
 
 UTF-8 limitations of the current set of backend tools
 =====================================================
