public inbox for cygwin-patches@cygwin.com
 help / color / mirror / Atom feed
* RE: [PATCH] Cygwin: Conditionally build documentation
@ 2022-01-14 20:18 Lavrentiev, Anton (NIH/NLM/NCBI) [C]
  2022-01-15  5:04 ` Brian Inglis
  2022-01-15 15:06 ` Jon Turney
  0 siblings, 2 replies; 10+ messages in thread
From: Lavrentiev, Anton (NIH/NLM/NCBI) [C] @ 2022-01-14 20:18 UTC (permalink / raw)
  To: Jon Turney, cygwin-patches

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

Can you please also add --disable-doc to "configure --help"?  It took me awhile to figure out which option I should use to skip the doc from building because it does no longer ignore doc build failure by default (unlike it used to do).  Also this fact is not reflected in the FAQ here:

https://cygwin.com/faq.html#faq.programming.building-cygwin

which still mentions the doc build errors ignored:

> Normally, building ignores any errors in building the documentation

Thanks!

Anton Lavrentiev
Contractor NIH/NLM/NCBI


^ permalink raw reply	[flat|nested] 10+ messages in thread
* [PATCH] Cygwin: Conditionally build documentation
@ 2021-12-18 17:47 Jon Turney
  2021-12-20  9:55 ` Corinna Vinschen
  0 siblings, 1 reply; 10+ messages in thread
From: Jon Turney @ 2021-12-18 17:47 UTC (permalink / raw)
  To: cygwin-patches; +Cc: Jon Turney

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

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

Even if building the documentation was diabled with '--disable-doc',
'make -C doc' at the top-level can still make the documentation, if the
documentation tools were found. If the tools were not found, 'missing'
is used to issue a warning about that.

Update instructions for building Cygwin appropriately.

(Building documentation remains the default to increase the chances of
noticing when building the documentation is broken.)
---
 winsup/Makefile.am             |  6 +++++-
 winsup/configure.ac            | 25 ++++++++++++++++++++++++-
 winsup/doc/Makefile.am         |  2 +-
 winsup/doc/faq-programming.xml | 14 +++++++++-----
 4 files changed, 39 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..4ae20509a 100644
--- a/winsup/configure.ac
+++ b/winsup/configure.ac
@@ -88,7 +88,30 @@ 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=yes)
+AM_CONDITIONAL(BUILD_DOC, [test $enable_doc != "no"])
+
+AC_CHECK_PROGS([DOCBOOK2XTEXI], [docbook2x-texi db2x_docbook2texi])
+if test -z "$DOCBOOK2XTEXI" ; then
+    if test "x$enable_doc" != "xno"; then
+        AC_MSG_ERROR([docbook2texi is required to build documentation])
+    else
+        unset DOCBOOK2XTEXI
+        AM_MISSING_PROG([DOCBOOK2XTEXI], [docbook2texi])
+    fi
+fi
+
+AC_CHECK_PROGS([XMLTO], [xmlto])
+if test -z "$XMLTO"; then
+    if test "x$enable_doc" != "xno"; then
+        AC_MSG_ERROR([xmlto is required to build documentation])
+    else
+        unset XMLTO
+        AM_MISSING_PROG([XMLTO], [xmlto])
+    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


^ permalink raw reply	[flat|nested] 10+ messages in thread

end of thread, other threads:[~2022-01-18 20:01 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-01-14 20:18 [PATCH] Cygwin: Conditionally build documentation Lavrentiev, Anton (NIH/NLM/NCBI) [C]
2022-01-15  5:04 ` Brian Inglis
2022-01-15 15:06 ` Jon Turney
2022-01-15 19:06   ` [EXTERNAL] " Lavrentiev, Anton (NIH/NLM/NCBI) [C]
2022-01-15 23:00     ` Brian Inglis
2022-01-18 20:01       ` Jon Turney
2022-01-17 19:39   ` Lavrentiev, Anton (NIH/NLM/NCBI) [C]
2022-01-18 19:57     ` Jon Turney
  -- strict thread matches above, loose matches on Subject: below --
2021-12-18 17:47 Jon Turney
2021-12-20  9:55 ` Corinna Vinschen

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).