[gcc r11-9138] libstdc++: Allow lualatex to be used for Doxygen PDF

[gcc r11-9138] libstdc++: Allow lualatex to be used for Doxygen PDF

[Jonathan Wakely]

https://gcc.gnu.org/g:4407f0d739c25021665f26d7666ace0258e45ca3

commit r11-9138-g4407f0d739c25021665f26d7666ace0258e45ca3
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Fri May 14 14:19:50 2021 +0100

    libstdc++: Allow lualatex to be used for Doxygen PDF
    
    This allows the Doxygen PDF to be built using lualatex instead of
    pdflatex, which solves a problem with pdflatex running out of memory
    sometimes. This is done by adding a --latex_cmd option to the
    run_doxygen script, which then sets the specified command in the
    generated user.cfg file used by Doxygen. The makefile is adjusted to
    pass --latex_cmd=$(LATEX_CMD) to the script, so using running make with
    LATEX_CMD=lualatex will override the default.
    
    Additionally, this does some refactoring of the doc/Makefile.am rules
    and the run_doxygen script.
    
    libstdc++-v3/ChangeLog:
    
            * doc/Makefile.am: Simplify doxygen recipes and use --latex_cmd.
            * doc/Makefile.in: Regenerate.
            * doc/doxygen/user.cfg.in (LATEX_CMD_NAME): Add placeholder
            value.
            * scripts/run_doxygen (print_usage): Always print to stdout and
            do not exit.
            (fail): New function for exiting on error.
            (parse_options): Handle --latex_cmd. Do not treat --help the
            same as errors. Simplify handling of required arguments.
    
    (cherry picked from commit e3b6d3a887fc0df09ea742c9c5a5acbc27c11ea7)

Diff:
---
 libstdc++-v3/doc/Makefile.am         | 30 +++++++--------
 libstdc++-v3/doc/Makefile.in         | 30 +++++++--------
 libstdc++-v3/doc/doxygen/user.cfg.in |  2 +-
 libstdc++-v3/scripts/run_doxygen     | 75 ++++++++++++++++++++++--------------
 4 files changed, 78 insertions(+), 59 deletions(-)

diff --git a/libstdc++-v3/doc/Makefile.am b/libstdc++-v3/doc/Makefile.am
index 2f8bb0770f3..487e8621b23 100644
--- a/libstdc++-v3/doc/Makefile.am
+++ b/libstdc++-v3/doc/Makefile.am
@@ -226,10 +226,10 @@ ${doxygen_outdir}/man:
 	mkdir -p ${doxygen_outdir}/man
 
 stamp-xml-doxygen: ${doxygen_outdir}/xml
-	-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
-	  builddir=`cd ..; ${PWD_COMMAND}`; \
+	@builddir=`cd ..; ${PWD_COMMAND}`; \
 	  ${SHELL} ${doxygen_script} \
-	  --host_alias=${host_alias} --mode=xml $${srcdir} $${builddir} NO)
+	  --host_alias=${host_alias} --mode=xml \
+	  "${top_srcdir}" "$${builddir}" NO || true
 	$(STAMP) stamp-xml-doxygen
 
 stamp-xml-single-doxygen: stamp-xml-doxygen
@@ -239,29 +239,29 @@ stamp-xml-single-doxygen: stamp-xml-doxygen
 	$(STAMP) stamp-xml-single-doxygen
 
 stamp-html-doxygen: ${doxygen_outdir}/html
-	-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
-	  builddir=`cd ..; ${PWD_COMMAND}`; \
+	@builddir=`cd ..; ${PWD_COMMAND}`; \
 	  ${SHELL} ${doxygen_script} \
-	  --host_alias=${host_alias} --mode=html $${srcdir} $${builddir} YES)
+	  --host_alias=${host_alias} --mode=html \
+	  "${top_srcdir}" "$${builddir}" YES || true
 	$(STAMP) stamp-html-doxygen
 
 stamp-latex-doxygen: ${doxygen_outdir}/latex
-	-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
-	  builddir=`cd ..; ${PWD_COMMAND}`; \
+	@builddir=`cd ..; ${PWD_COMMAND}`; \
 	  ${SHELL} ${doxygen_script} \
-	  --host_alias=${host_alias} --mode=latex $${srcdir} $${builddir} NO)
+	  --host_alias=${host_alias} --mode=latex --latex_cmd=$(LATEX_CMD) \
+	  "${top_srcdir}" "$${builddir}" NO || true
 	$(STAMP) stamp-latex-doxygen
 
 # Chance of loooooonnggg creation time on this rule.  Iff this fails,
 # look at refman.log and see if TeX's memory is exhausted. Symptoms
 # include asking a wizard to enlarge capacity. If this is the case,
 # find texmf.cnf and add a zero for pool_size, string_vacancies,
-# max_strings, and pool_free values. A much simpler workaround is to install
-# lualatex and set LATEX_CMD_NAME = lualatex in the doxygen user.cfg file.
+# max_strings, and pool_free values. A much simpler workaround is to
+# install lualatex and set LATEX_CMD=lualatex when running make.
 # Errors like "File `foo.sty' not found" mean a TeX package is missing.
 stamp-pdf-doxygen: stamp-latex-doxygen ${doxygen_outdir}/pdf
-	-(cd ${doxygen_outdir}/latex && $(MAKE) -i pdf;)
 	@echo "Generating doxygen pdf file...";
+	-$(MAKE) -C ${doxygen_outdir}/latex -i pdf
 	@if [ -f ${doxygen_pdf} ]; then \
 	  mv ${doxygen_pdf} ${api_pdf} ; \
 	  echo ":: PDF file is ${api_pdf}"; \
@@ -274,10 +274,10 @@ stamp-pdf-doxygen: stamp-latex-doxygen ${doxygen_outdir}/pdf
 	$(STAMP) stamp-pdf-doxygen
 
 stamp-man-doxygen: ${doxygen_outdir}/man
-	-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
-	  builddir=`cd ..; ${PWD_COMMAND}`; \
+	@builddir=`cd ..; ${PWD_COMMAND}`; \
 	  ${SHELL} ${doxygen_script} \
-	  --host_alias=${host_alias} --mode=man $${srcdir} $${builddir} YES)
+	  --host_alias=${host_alias} --mode=man \
+	  "${top_srcdir}" "$${builddir}" YES || true
 	$(STAMP) stamp-man-doxygen
 
 doc-xml-doxygen: stamp-xml-doxygen
diff --git a/libstdc++-v3/doc/Makefile.in b/libstdc++-v3/doc/Makefile.in
index 18a6a9994b4..fe1113eda34 100644
--- a/libstdc++-v3/doc/Makefile.in
+++ b/libstdc++-v3/doc/Makefile.in
@@ -917,10 +917,10 @@ ${doxygen_outdir}/man:
 	mkdir -p ${doxygen_outdir}/man
 
 stamp-xml-doxygen: ${doxygen_outdir}/xml
-	-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
-	  builddir=`cd ..; ${PWD_COMMAND}`; \
+	@builddir=`cd ..; ${PWD_COMMAND}`; \
 	  ${SHELL} ${doxygen_script} \
-	  --host_alias=${host_alias} --mode=xml $${srcdir} $${builddir} NO)
+	  --host_alias=${host_alias} --mode=xml \
+	  "${top_srcdir}" "$${builddir}" NO || true
 	$(STAMP) stamp-xml-doxygen
 
 stamp-xml-single-doxygen: stamp-xml-doxygen
@@ -930,29 +930,29 @@ stamp-xml-single-doxygen: stamp-xml-doxygen
 	$(STAMP) stamp-xml-single-doxygen
 
 stamp-html-doxygen: ${doxygen_outdir}/html
-	-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
-	  builddir=`cd ..; ${PWD_COMMAND}`; \
+	@builddir=`cd ..; ${PWD_COMMAND}`; \
 	  ${SHELL} ${doxygen_script} \
-	  --host_alias=${host_alias} --mode=html $${srcdir} $${builddir} YES)
+	  --host_alias=${host_alias} --mode=html \
+	  "${top_srcdir}" "$${builddir}" YES || true
 	$(STAMP) stamp-html-doxygen
 
 stamp-latex-doxygen: ${doxygen_outdir}/latex
-	-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
-	  builddir=`cd ..; ${PWD_COMMAND}`; \
+	@builddir=`cd ..; ${PWD_COMMAND}`; \
 	  ${SHELL} ${doxygen_script} \
-	  --host_alias=${host_alias} --mode=latex $${srcdir} $${builddir} NO)
+	  --host_alias=${host_alias} --mode=latex --latex_cmd=$(LATEX_CMD) \
+	  "${top_srcdir}" "$${builddir}" NO || true
 	$(STAMP) stamp-latex-doxygen
 
 # Chance of loooooonnggg creation time on this rule.  Iff this fails,
 # look at refman.log and see if TeX's memory is exhausted. Symptoms
 # include asking a wizard to enlarge capacity. If this is the case,
 # find texmf.cnf and add a zero for pool_size, string_vacancies,
-# max_strings, and pool_free values. A much simpler workaround is to install
-# lualatex and set LATEX_CMD_NAME = lualatex in the doxygen user.cfg file.
+# max_strings, and pool_free values. A much simpler workaround is to
+# install lualatex and set LATEX_CMD=lualatex when running make.
 # Errors like "File `foo.sty' not found" mean a TeX package is missing.
 stamp-pdf-doxygen: stamp-latex-doxygen ${doxygen_outdir}/pdf
-	-(cd ${doxygen_outdir}/latex && $(MAKE) -i pdf;)
 	@echo "Generating doxygen pdf file...";
+	-$(MAKE) -C ${doxygen_outdir}/latex -i pdf
 	@if [ -f ${doxygen_pdf} ]; then \
 	  mv ${doxygen_pdf} ${api_pdf} ; \
 	  echo ":: PDF file is ${api_pdf}"; \
@@ -965,10 +965,10 @@ stamp-pdf-doxygen: stamp-latex-doxygen ${doxygen_outdir}/pdf
 	$(STAMP) stamp-pdf-doxygen
 
 stamp-man-doxygen: ${doxygen_outdir}/man
-	-(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
-	  builddir=`cd ..; ${PWD_COMMAND}`; \
+	@builddir=`cd ..; ${PWD_COMMAND}`; \
 	  ${SHELL} ${doxygen_script} \
-	  --host_alias=${host_alias} --mode=man $${srcdir} $${builddir} YES)
+	  --host_alias=${host_alias} --mode=man \
+	  "${top_srcdir}" "$${builddir}" YES || true
 	$(STAMP) stamp-man-doxygen
 
 doc-xml-doxygen: stamp-xml-doxygen
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 25f7e1ef33f..349b9ec9c36 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -1940,7 +1940,7 @@ LATEX_OUTPUT           = latex
 # the output language.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_CMD_NAME         =
+LATEX_CMD_NAME         = @latex_cmd@
 
 # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate
 # index for LaTeX.
diff --git a/libstdc++-v3/scripts/run_doxygen b/libstdc++-v3/scripts/run_doxygen
index 3a24a1f4242..a36772128ec 100644
--- a/libstdc++-v3/scripts/run_doxygen
+++ b/libstdc++-v3/scripts/run_doxygen
@@ -35,8 +35,7 @@ find_doxygen() {
       fi
     done
     if test -z "$doxygen"; then
-	echo run_doxygen error:  Could not find Doxygen $DOXYVER in path. 1>&2
-	print_usage
+	fail "Could not find Doxygen $DOXYVER in path."
     fi
     # We need to use other tools from the same package/version.
     echo :: Using Doxygen tools from ${dir}.
@@ -45,8 +44,8 @@ find_doxygen() {
 }
 
 print_usage() {
-    cat 1>&2 <<EOF
-Usage:  run_doxygen --mode=MODE --host_alias=BUILD_ALIAS [<options>]
+    cat <<EOF
+Usage:  run_doxygen --mode=MODE --host_alias=HOST_ALIAS [<options>]
 		    <v3-src-dir> <v3-build-dir> <shortnamesp>
       MODE is one of:
 	  html           Generate user-level HTML library documentation.
@@ -54,48 +53,67 @@ Usage:  run_doxygen --mode=MODE --host_alias=BUILD_ALIAS [<options>]
 	  xml            Generate user-level XML pages.
 	  latex          Generate user-level LaTeX pages.
 
-      BUILD_ALIAS is the GCC build alias set at configure time.
+      HOST_ALIAS is the GCC host alias triplet set at configure time.
+
+      shortnamesp is one of YES or NO and is used as the SHORT_NAMES value
+      in the Doxygen config file.
+
+      Supported options:
+
+      --help | -h      Print this message and exit.
+      --latex_cmd=CMD  Set LATEX_CMD_NAME=CMD in the Doxygen config file.
 
 Note:  Requires Doxygen ${DOXYVER} or later; get it at
        ftp://ftp.stack.nl/pub/users/dimitri/doxygen-${DOXYVER}.src.tar.gz
 
 EOF
-    exit 1
+}
+
+# Print an error message followed by usage to stderr, then exit.
+fail() {
+  echo "$0: error: $*" 1>&2
+  echo 1>&2
+  print_usage 1>&2
+  exit 1
 }
 
 parse_options() {
-  for o
+  while [ $# -ne 0 ]
   do
     # Blatantly ripped from autoconf, er, I mean, "gratefully standing
     # on the shoulders of those giants who have gone before us."
-    case "$o" in
-      -*=*) arg=`echo "$o" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
+    case "$1" in
+      -*=*) arg=`echo "$1" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
       *) arg= ;;
     esac
 
-    case "$o" in
+    case "$1" in
       --mode=*)
 	mode=$arg ;;
       --host_alias=*)
 	host_alias=$arg ;;
-      --mode | --host_alias | --help | -h)
-	print_usage ;;
+      --help | -h)
+	print_usage ; exit ;;
+      --mode | --host_alias)
+	fail "missing argument: $1" ;;
+      --latex_cmd=*)
+	latex_cmd=$arg ;;
+      --*)
+	fail "invalid option: $1" ;;
       *)
-	# this turned out to be a mess, maybe change to --srcdir=, etc
-	if test $srcdir = unset; then
-	  srcdir=$o
-	elif test $outdir = unset; then
-	  builddir=${o}
-	  outdir=${o}/doc/doxygen
-	elif test $shortname = unset; then
-	  shortname=$o
-	else
-	  echo run_doxygen error:  Too many arguments 1>&2
-	  exit 1
-	fi
-	;;
-      esac
+	break ;;
+    esac
+    shift
   done
+
+  if [ $# -ne 3 ]
+  then
+    fail "wrong number of arguments"
+  fi
+  srcdir="$1"
+  builddir="$2"
+  outdir="$2/doc/doxygen"
+  shortname="$3"
 }
 
 
@@ -109,6 +127,7 @@ do_html=false
 do_man=false
 do_xml=false
 do_latex=false
+latex_cmd=
 enabled_sections=
 generate_tagfile=
 DATEtext=`date '+%Y-%m-%d'`
@@ -121,8 +140,7 @@ find_doxygen
 
 if test $srcdir = unset || test $outdir = unset || test $mode = unset || test $shortname = unset || test $host_alias = unset; then
     # this could be better
-    echo run_doxygen error:  You have not given enough information...! 1>&2
-    print_usage
+    fail "You have not given enough information...!  $srcdir - "
 fi
 
 case x"$mode" in
@@ -173,6 +191,7 @@ chmod u+w $outdir
 	-e "s=@enabled_sections@=${enabled_sections}=" \
 	-e "s=@do_html@=${do_html}=" \
 	-e "s=@do_latex@=${do_latex}=" \
+	-e "s=@latex_cmd@=${latex_cmd}=" \
 	-e "s=@do_man@=${do_man}=" \
 	-e "s=@do_xml@=${do_xml}=" \
 	-e "s=@generate_tagfile@=${generate_tagfile}=" \