[PATCH] Cygwin: Conditionally build documentation

[PATCH] Cygwin: Conditionally build documentation

[Jon Turney]

Add a configure option '--disable-doc' to disable building of
documentation by 'all' target.

Check for the required tools at configure time, and require them if
building documentation is enabled.

'make doc' at top-level (or 'cd doc; make') can still make documentation
even if it was disabled, if the documentation tools were found.

Update instructions for building Cygwin appropriately.

(Building documentation remains the default to increase the chances of
noticing when building the documentation is broken.)
---

Notes:
    As discussed at [1]
    
    [1] https://cygwin.com/pipermail/cygwin-patches/2021q2/011358.html
    
    '--disable-doc' or '--disable-docs'... I just can't decide :)

 winsup/Makefile.am             |  6 +++++-
 winsup/configure.ac            | 15 ++++++++++++++-
 winsup/doc/Makefile.am         |  2 +-
 winsup/doc/faq-programming.xml | 14 +++++++++-----
 4 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/winsup/Makefile.am b/winsup/Makefile.am
index 067f74688..9efdd4cb1 100644
--- a/winsup/Makefile.am
+++ b/winsup/Makefile.am
@@ -14,6 +14,10 @@ cygdoc_DATA = \
 	CYGWIN_LICENSE \
 	COPYING
 
-SUBDIRS = cygwin cygserver doc utils testsuite
+SUBDIRS = cygwin cygserver utils testsuite
+
+if BUILD_DOC
+SUBDIRS += doc
+endif
 
 cygserver utils testsuite: cygwin
diff --git a/winsup/configure.ac b/winsup/configure.ac
index cf1128b37..694442008 100644
--- a/winsup/configure.ac
+++ b/winsup/configure.ac
@@ -88,7 +88,20 @@ AC_SUBST(TLSOFFSETS_H)
 
 AM_CONDITIONAL(TARGET_X86_64, [test $target_cpu = "x86_64"])
 
-AC_CHECK_PROGS([DOCBOOK2XTEXI], [docbook2x-texi db2x_docbook2texi], [true])
+AC_ARG_ENABLE(doc,
+	      [AS_HELP_STRING([--enable-doc], [Build documentation])],
+	      enable_doc=$enableval,
+	      enable_doc=yes)
+AM_CONDITIONAL(BUILD_DOC, [test $enable_doc != "no"])
+
+AC_CHECK_PROGS([DOCBOOK2XTEXI], [docbook2x-texi db2x_docbook2texi])
+AC_CHECK_PROGS([XMLTO], [xmlto])
+
+if test "x$enable_doc" != "xno"; then
+   if test -z "$DOCBOOK2XTEXI" || test -z "$XMLTO"; then
+       AC_MSG_ERROR([Required documentation tools not found])
+   fi
+fi
 
 if test "x$with_cross_bootstrap" != "xyes"; then
     AC_CHECK_PROGS(MINGW_CXX, ${target_cpu}-w64-mingw32-g++)
diff --git a/winsup/doc/Makefile.am b/winsup/doc/Makefile.am
index 534d67480..5164c6e0a 100644
--- a/winsup/doc/Makefile.am
+++ b/winsup/doc/Makefile.am
@@ -16,7 +16,7 @@ doc_DATA = \
 
 htmldir = $(datarootdir)/doc
 
-XMLTO=xmlto --skip-validation --with-dblatex
+XMLTO=@XMLTO@ --skip-validation --with-dblatex
 DOCBOOK2XTEXI=@DOCBOOK2XTEXI@ --xinclude --info --utf8trans-map=charmap
 
 -include Makefile.dep
diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml
index 26fcfe921..46dd23ab8 100644
--- a/winsup/doc/faq-programming.xml
+++ b/winsup/doc/faq-programming.xml
@@ -689,12 +689,16 @@ Building for 32-bit Cygwin also requires
 Building for 64-bit Cygwin also requires
 <literal>mingw64-x86_64-gcc-g++</literal> and
 <literal>mingw64-x86_64-zlib</literal>.
+</para>
+
 <!-- If you want to run the tests, <literal>dejagnu</literal> is also required. -->
-Normally, building ignores any errors in building the documentation,
-which requires the <literal>dblatex</literal>, <literal>docbook2X</literal>,
-<literal>docbook-xml45</literal>, <literal>docbook-xsl</literal>, and
-<literal>xmlto</literal> packages.  For more information on building the
-documentation, see the README included in the <literal>cygwin-doc</literal> package.
+
+<para>
+Building the documentation also requires the <literal>dblatex</literal>,
+<literal>docbook2X</literal>, <literal>docbook-xml45</literal>,
+<literal>docbook-xsl</literal>, and <literal>xmlto</literal> packages.  Building
+the documentation can be disabled with the <literal>--disable-doc</literal>
+option to <literal>configure</literal>.
 </para>
 
 <para>Next, check out the Cygwin sources from the
-- 
2.34.1

Re: [PATCH] Cygwin: Conditionally build documentation

[Jon Turney]

On 08/12/2021 15:03, Jon Turney wrote:
> Add a configure option '--disable-doc' to disable building of
> documentation by 'all' target.

Oops, wrong list.  Apologies for the noise.

Re: [PATCH] Cygwin: Conditionally build documentation

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 757 bytes --]

On 08 Dec 2021 15:03, Jon Turney wrote:
> +AC_ARG_ENABLE(doc,
> +	      [AS_HELP_STRING([--enable-doc], [Build documentation])],
> +	      enable_doc=$enableval,
> +	      enable_doc=yes)

the 3rd arg is redundant.  you can just write ,, to use the default iirc.

> +AC_CHECK_PROGS([DOCBOOK2XTEXI], [docbook2x-texi db2x_docbook2texi])
> +AC_CHECK_PROGS([XMLTO], [xmlto])
> +
> +if test "x$enable_doc" != "xno"; then
> +   if test -z "$DOCBOOK2XTEXI" || test -z "$XMLTO"; then
> +       AC_MSG_ERROR([Required documentation tools not found])
> +   fi
> +fi

i think AM_MISSING_PROG would be more appropriate.  then you don't need
the `test` logic.
https://www.gnu.org/software/automake/manual/html_node/Public-Macros.html#index-AM_005fMISSING_005fPROG
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]