Merge pull request #705 from N0NB/doxygen_work

Enable optional generation of the PDF manual

README.developer

@@ -267,10 +267,6 @@ Optional, but highly recommended:
 N.B.:  The libusb-1.0 package is required for building most of the 'kit'
 backend.  The older version of libusb 0.1.x is no longer supported.
 
-Documentation:
-* Doxygen
-* GNU Source-highlight
-
 N.B.:  Some systems can have several versions of the autotools installed. In
 that case, autoconf may be called "autoconf2.59", autoheader
 "autoheader2.59", and automake "automake-1.9", aclocal "aclocal-1.9" or a
@@ -376,6 +372,44 @@ then 'ldconfig' will need to be run as the root user so that applications
 using the Hamlib libraries can find them.
 
 
+1.3.1 Doxygen generated reference manual
+
+The following packages need to be installed:
+* Doxygen
+* GNU Source-highlight
+
+1.3.1.1 HTML manual
+
+In the top level of the build directory:
+
+    cd doc
+    make doc
+
+will build the HTML manual.  The resulting 'doc/html' directory contains all
+of the files needed for the HTML manual.  The 'index.html' file is the entry
+point to the manual.
+
+1.3.1.2 PDF manual
+
+To generate the PDF version of the reference manual the following texlive
+packages are required (Debian package names shown):
+* texlive-latex-base
+* texlive-latex-recommended
+* texlive-latex-extra
+
+Set GENERATE_LATEX in 'doc/hamlib.cfg.in' to 'YES' which will enable the LaTEX
+build.  Then run:
+
+    make doc
+
+as above and once the run is complete:
+
+    cd latex
+    make
+
+The resulting generated document in the 'latex' directory is 'refman.pdf'.
+
+
 1.4. Feedback
 
 The Hamlib team is very interested to hear from you, how Hamlib builds and

doc/Makefile.am

@@ -14,10 +14,12 @@ SCRIPTSLST = build-w32.sh build-w64.sh
 # Use GNU source-highlight to generate highlighted shell scripts for the
 # Doxygen manual.
 doc: hamlib.cfg $(SRCDOCLST)
-	for script in $(SCRIPTSLST) ; do \
-		source-highlight -n -i $(top_srcdir)/scripts/$${script} -o $(top_builddir)/scripts/$${script}.html ; \
-	done ; \
+	for script in $(SCRIPTSLST) ; \
+	  do \
+	    source-highlight -n -f html -i $(top_srcdir)/scripts/$${script} -o $(top_builddir)/scripts/$${script}.html ; \
+	    source-highlight -n -f latex -i $(top_srcdir)/scripts/$${script} -o $(top_builddir)/scripts/$${script}.tex ; \
+	  done
 	doxygen hamlib.cfg
 
 clean-local:
-	-rm -rf $(top_builddir)/doc/html $(top_builddir)/scripts/build-w*.sh.html
+	-rm -rf $(top_builddir)/doc/html $(top_builddir)/doc/latex $(top_builddir)/scripts/build-w*

doc/hamlib.cfg.in

@@ -14,6 +14,15 @@ GENERATE_RTF    = NO
 GENERATE_MAN    = NO    # User can set to YES for local man pages
 MAN_EXTENSION	= .3
 
+# Set GENERATE_LATEX to YES to generate the needed files for the PDF manual
+# and run 'make doc'.  Then 'cd latex ; make' to generate the PDF manual.
+#
+# See section 1.3.1.2 in @top_srcdir@/README.developer for the needed LaTEX
+# packages.
+USE_PDFLATEX    = YES
+PDF_HYPERLINKS  = YES
+EXTRA_PACKAGES  = pmboxdraw
+
 # Input
 CASE_SENSE_NAMES = YES
 FULL_PATH_NAMES  = NO
@@ -29,9 +38,8 @@ INCLUDE_PATH     = @top_srcdir@/include
 
 EXAMPLE_PATH     = @top_srcdir@/tests/testrig.c \
                    @top_srcdir@ \
-                   @top_srcdir@/scripts/README.build-Windows \
-                   @top_builddir@/scripts/build-w32.sh.html \
-                   @top_builddir@/scripts/build-w64.sh.html
+                   @top_srcdir@/scripts \
+                   @top_builddir@/scripts
 
 
 QUIET            = YES

doc/index.doxygen

@@ -87,8 +87,10 @@ GNU/Linux.
 \verbinclude README.build-Windows
 \subsection W32 The build-w32.sh script
 \htmlinclude build-w32.sh.html
+\latexinclude build-w32.sh.tex
 \subsection W64 The build-w64.sh script
 \htmlinclude build-w64.sh.html
+\latexinclude build-w64.sh.tex
 */
 
 /*! \page Rdmeosx README.osx