Take account of splitting option in gendocs.sh

Take account of splitting option in gendocs.sh

[Gavin Smith]

The patch at the bottom of this mail makes gendocs.sh take account
of the --split option.  Texinfo uses this as one of its manuals
(texi2any_internals) uses --split=chapter for the HTML output.  Up to
this point we have been getting around this problem by using a custom
gendocs template.

It appears that the existing gendocs template was written to support
different splitting possibilities but that gendocs.sh didn't use this
fully.

Please let me know if any further work needs to be done on this patch.

I notice that this script also still supports texi2html, which is no
longer developed.  I could produce a patch to remove this support if
it was very likely that nobody was relying on it.

diff --git a/ChangeLog b/ChangeLog
index 9477335e75..d67b9b2f0a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2023-02-26  Gavin Smith <gavinsmith0123@gmail.com>
+
+	gendocs: support chapter- and section-level split
+	* build-aux/gendocs.sh:
+	Strip out parts of the template depending on --split.
+	* doc/gendocs_template: Add lines to mark parts of file to output
+	only when splitting HTML by node.
+
 2023-02-26  Bruno Haible  <bruno@clisp.org>
 
 	dfa: Avoid warnings with some Apple clang versions.
diff --git a/build-aux/gendocs.sh b/build-aux/gendocs.sh
index 1ad5cf4f5d..ca813bffe3 100755
--- a/build-aux/gendocs.sh
+++ b/build-aux/gendocs.sh
@@ -465,12 +465,20 @@ fi
 
 # \f
 printf "\nMaking index.html for %s...\n" "$PACKAGE"
-if test -z "$use_texi2html"; then
-  CONDS="/%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
-         /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d"
+if test x$split = xnode; then
+  CONDS="/%%IF  *HTML_NODE%%/d;/%%ENDIF  *HTML_NODE%%/d;\
+         /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d;\
+         /%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;"
+elif test x$split = xchapter; then
+  CONDS="/%%IF  *HTML_CHAPTER%%/d;/%%ENDIF  *HTML_CHAPTER%%/d;\
+         /%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
+         /%%IF  *HTML_NODE%%/,/%%ENDIF  *HTML_NODE%%/d;"
+elif test x$split = xsection; then
+  CONDS="/%%IF  *HTML_SECTION%%/d;/%%ENDIF  *HTML_SECTION%%/d;\
+         /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d;\
+         /%%IF  *HTML_NODE%%/,/%%ENDIF  *HTML_NODE%%/d;"
 else
-  # should take account of --split here.
-  CONDS="/%%ENDIF.*%%/d;/%%IF  *HTML_SECTION%%/d;/%%IF  *HTML_CHAPTER%%/d"
+  CONDS="/%%IF.*%%/d;/%%ENDIF.*%%/d;" # invalid split argument
 fi
 
 curdate=`$SETLANG date '+%B %d, %Y'`
diff --git a/doc/gendocs_template b/doc/gendocs_template
index a101977dfc..0b959f0379 100644
--- a/doc/gendocs_template
+++ b/doc/gendocs_template
@@ -22,8 +22,10 @@ without any warranty.
 <ul>
 <li><a href="%%PACKAGE%%.html">HTML
     (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
+%%IF HTML_NODE%%
 <li><a href="html_node/index.html">HTML</a> - with one web page per
     node.</li>
+%%ENDIF HTML_NODE%%
 %%IF HTML_SECTION%%
 <li><a href="html_section/index.html">HTML</a> - with one web page per
     section.</li>
@@ -35,9 +37,11 @@ without any warranty.
 <li><a href="%%PACKAGE%%.html.gz">HTML compressed
     (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
     one web page.</li>
+%%IF HTML_NODE%%
 <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
     (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
     with one web page per node.</li>
+%%ENDIF HTML_NODE%%
 %%IF HTML_SECTION%%
 <li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
     (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -

Re: Take account of splitting option in gendocs.sh

[Bruno Haible]

Gavin Smith wrote:
> I notice that this script also still supports texi2html, which is no
> longer developed.  I could produce a patch to remove this support if
> it was very likely that nobody was relying on it.

A web search on www.gnu.org shows that the manuals of at least the following
packages still were generated using texi2html:
  anubis, auctex, autogen, cfengine, cflow, classpath, combine, complexity,
  cpio, freeimpi, freetalk, gama, gnats, gnu-pw-mgr, gnugo, gnuit, gnupod,
  hurd, indent, libcdio, libjit, oleo, plotutils, radius, sqltutor, tar.

That's definitely more than nobody.

Bruno

Re: Take account of splitting option in gendocs.sh

[Gavin Smith]

On Sun, Feb 26, 2023 at 09:52:08PM +0100, Bruno Haible wrote:
> Gavin Smith wrote:
> > I notice that this script also still supports texi2html, which is no
> > longer developed.  I could produce a patch to remove this support if
> > it was very likely that nobody was relying on it.
> 
> A web search on www.gnu.org shows that the manuals of at least the following
> packages still were generated using texi2html:
>   anubis, auctex, autogen, cfengine, cflow, classpath, combine, complexity,
>   cpio, freeimpi, freetalk, gama, gnats, gnu-pw-mgr, gnugo, gnuit, gnupod,
>   hurd, indent, libcdio, libjit, oleo, plotutils, radius, sqltutor, tar.
> 
> That's definitely more than nobody.
> 
> Bruno

OK it doesn't do any harm to keep the texi2html support in.

The patch I sent applied for both texi2html and texi2any, although I
hadn't tested it with texi2html.

Re: Take account of splitting option in gendocs.sh

[Gavin Smith]

On Mon, Feb 27, 2023 at 07:30:37AM +0000, Gavin Smith wrote:
> OK it doesn't do any harm to keep the texi2html support in.
> 
> The patch I sent applied for both texi2html and texi2any, although I
> hadn't tested it with texi2html.

Is there any progress on applying this patch?

This would allow us to eliminate the custom gendocs template we use
in the Texinfo project for chapter-level splitting for one of our
manuals.

Re: Take account of splitting option in gendocs.sh

[Bruno Haible]

Gavin Smith wrote, re
<https://lists.gnu.org/archive/html/bug-gnulib/2023-02/msg00183.html>:
> > OK it doesn't do any harm to keep the texi2html support in.
> > 
> > The patch I sent applied for both texi2html and texi2any, although I
> > hadn't tested it with texi2html.
> 
> Is there any progress on applying this patch?

I can't review it, because the interplay between the script and the template
is something I don't know about.

Also: What are the effects of the patch on the output, if no --split option
is being passed to gendocs.sh?

Can someone else please review it? Maybe Karl?

Bruno

Re: Take account of splitting option in gendocs.sh

[Gavin Smith]

On Sun, Mar 26, 2023 at 06:53:21PM +0200, Bruno Haible wrote:
> > Is there any progress on applying this patch?
> 
> I can't review it, because the interplay between the script and the template
> is something I don't know about.
> 
> Also: What are the effects of the patch on the output, if no --split option
> is being passed to gendocs.sh?

It should be the same as if --split=node was given, as 'node' is the
default value of $split in this script.

I see now that for texi2html, all three splitting options are used
("node", "chapter" and "section").  This can be seen at the GNU
Anubis manuals page (https://www.gnu.org/software/anubis/manual/),
where all three of these versions of the manual are available.

Here's an updated patch that does not affect the behaviour when
used with texi2html.

diff --git a/ChangeLog b/ChangeLog
index a0de338759..41a27c6710 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2023-03-26  Gavin Smith <gavinsmith0123@gmail.com>
+
+	gendocs: support chapter- and section-level split
+	* doc/gendocs_template: Add lines to mark parts of file to output
+	only when splitting HTML by node.
+	* build-aux/gendocs.sh
+	[!texi2html]: Strip out parts of the template depending on --split.
+	[texi2html] Include all of the template as before.
+
 2023-03-25  Bruno Haible  <bruno@clisp.org>
 
 	stdlib: ISO C 23: Document issue with once_flag and call_once.
diff --git a/build-aux/gendocs.sh b/build-aux/gendocs.sh
index 1ad5cf4f5d..c7c9e2826c 100755
--- a/build-aux/gendocs.sh
+++ b/build-aux/gendocs.sh
@@ -466,11 +466,24 @@ fi
 # \f
 printf "\nMaking index.html for %s...\n" "$PACKAGE"
 if test -z "$use_texi2html"; then
-  CONDS="/%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
-         /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d"
+  if test x$split = xnode; then
+    CONDS="/%%IF  *HTML_NODE%%/d;/%%ENDIF  *HTML_NODE%%/d;\
+           /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d;\
+           /%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;"
+  elif test x$split = xchapter; then
+    CONDS="/%%IF  *HTML_CHAPTER%%/d;/%%ENDIF  *HTML_CHAPTER%%/d;\
+           /%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
+           /%%IF  *HTML_NODE%%/,/%%ENDIF  *HTML_NODE%%/d;"
+  elif test x$split = xsection; then
+    CONDS="/%%IF  *HTML_SECTION%%/d;/%%ENDIF  *HTML_SECTION%%/d;\
+           /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d;\
+           /%%IF  *HTML_NODE%%/,/%%ENDIF  *HTML_NODE%%/d;"
+  else
+    CONDS="/%%IF.*%%/d;/%%ENDIF.*%%/d;" # invalid split argument
+  fi
 else
   # should take account of --split here.
-  CONDS="/%%ENDIF.*%%/d;/%%IF  *HTML_SECTION%%/d;/%%IF  *HTML_CHAPTER%%/d"
+  CONDS="/%%IF.*%%/d;/%%ENDIF.*%%/d;"
 fi
 
 curdate=`$SETLANG date '+%B %d, %Y'`
diff --git a/doc/gendocs_template b/doc/gendocs_template
index a101977dfc..0b959f0379 100644
--- a/doc/gendocs_template
+++ b/doc/gendocs_template
@@ -22,8 +22,10 @@ without any warranty.
 <ul>
 <li><a href="%%PACKAGE%%.html">HTML
     (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
+%%IF HTML_NODE%%
 <li><a href="html_node/index.html">HTML</a> - with one web page per
     node.</li>
+%%ENDIF HTML_NODE%%
 %%IF HTML_SECTION%%
 <li><a href="html_section/index.html">HTML</a> - with one web page per
     section.</li>
@@ -35,9 +37,11 @@ without any warranty.
 <li><a href="%%PACKAGE%%.html.gz">HTML compressed
     (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
     one web page.</li>
+%%IF HTML_NODE%%
 <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
     (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
     with one web page per node.</li>
+%%ENDIF HTML_NODE%%
 %%IF HTML_SECTION%%
 <li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
     (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -

Re: Take account of splitting option in gendocs.sh

[Karl Berry]

    +	gendocs: support chapter- and section-level split

Seems sensible to me. Basically making the html-by-node part of the
template conditional along with the other split options?

(Overall, it seems to me that several of these variants are pretty
pointless nowadays, but never mind.)

FWIW, in the past, only texi2html supported split=chapter. Hence the
hardwiring of various things.

     else
       # should take account of --split here.
    -  CONDS="/%%ENDIF.*%%/d;/%%IF  *HTML_SECTION%%/d;/%%IF  *HTML_CHAPTER%%/d"
    +  CONDS="/%%IF.*%%/d;/%%ENDIF.*%%/d;"

Should the comment now be something like
# No split output, so delete all conditionals.
?

--

    <p>Copyright &copy; 2022 Free Software Foundation, Inc.</p>

On the usual triviality front, the copyright year in gendocs_template
apparently didn't get updated along with everything else.

     Please make sure the copyright date is consistent with the document
     and that it is like this: "2001, 2002", not this: "2001-2002". -->

That comment has been obsolete for a couple for decades.
1) rms agreed to allow ranges; 2) only a single year is listed (which is
ok for web pages). It goes against the copyright listing at the top of
the file, so rather confusing.

That's what I see. I didn't actually try it, sorry. --thanks, karl.

Re: Take account of splitting option in gendocs.sh

[Bruno Haible]

Gavin Smith wrote:
> Here's an updated patch that does not affect the behaviour when
> used with texi2html.

Thanks for the improvement.

Bruno

Re: Take account of splitting option in gendocs.sh

[Gavin Smith]

On Sun, Mar 26, 2023 at 04:11:45PM -0600, Karl Berry wrote:
>     +	gendocs: support chapter- and section-level split
> 
> Seems sensible to me. Basically making the html-by-node part of the
> template conditional along with the other split options?
> 
> (Overall, it seems to me that several of these variants are pretty
> pointless nowadays, but never mind.)
> 
> FWIW, in the past, only texi2html supported split=chapter. Hence the
> hardwiring of various things.

I've made minor changes to the patch as specified in Karl's response below.
Please can this be applied?

The Texinfo package is still using a custom gendocs template for some of
its manuals and I would like to get rid of it to simplify our build process.


diff --git a/ChangeLog b/ChangeLog
index e55bfec8ed..9c8804f3f6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2023-07-12  Gavin Smith <gavinsmith0123@gmail.com>
+
+	gendocs: support chapter- and section-level split
+	* doc/gendocs_template: Add lines to mark parts of file to output
+	only when splitting HTML by node.
+	Remove obsolete comment about ranges of years in copyright notice
+	(as per Karl).
+	* build-aux/gendocs.sh
+	[!texi2html]: Strip out parts of the template depending on --split.
+	[texi2html] Include all of the template as before.
+
 2023-07-11  Bruno Haible  <bruno@clisp.org>
 
 	mbsrtoc32s, mbsnrtoc32s: Small optimization.
diff --git a/build-aux/gendocs.sh b/build-aux/gendocs.sh
index 1ad5cf4f5d..0e470bf7ce 100755
--- a/build-aux/gendocs.sh
+++ b/build-aux/gendocs.sh
@@ -2,7 +2,7 @@
 # gendocs.sh -- generate a GNU manual in many formats.  This script is
 #   mentioned in maintain.texi.  See the help message below for usage details.
 
-scriptversion=2023-01-21.00
+scriptversion=2023-07-12.10
 
 # Copyright 2003-2023 Free Software Foundation, Inc.
 #
@@ -466,11 +466,25 @@ fi
 # \f
 printf "\nMaking index.html for %s...\n" "$PACKAGE"
 if test -z "$use_texi2html"; then
-  CONDS="/%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
-         /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d"
+  if test x$split = xnode; then
+    CONDS="/%%IF  *HTML_NODE%%/d;/%%ENDIF  *HTML_NODE%%/d;\
+           /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d;\
+           /%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;"
+  elif test x$split = xchapter; then
+    CONDS="/%%IF  *HTML_CHAPTER%%/d;/%%ENDIF  *HTML_CHAPTER%%/d;\
+           /%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
+           /%%IF  *HTML_NODE%%/,/%%ENDIF  *HTML_NODE%%/d;"
+  elif test x$split = xsection; then
+    CONDS="/%%IF  *HTML_SECTION%%/d;/%%ENDIF  *HTML_SECTION%%/d;\
+           /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d;\
+           /%%IF  *HTML_NODE%%/,/%%ENDIF  *HTML_NODE%%/d;"
+  else
+    CONDS="/%%IF.*%%/d;/%%ENDIF.*%%/d;" # invalid split argument
+  fi
 else
-  # should take account of --split here.
-  CONDS="/%%ENDIF.*%%/d;/%%IF  *HTML_SECTION%%/d;/%%IF  *HTML_CHAPTER%%/d"
+  # for texi2html, we do not take account of --split and simply output
+  # all variants
+  CONDS="/%%IF.*%%/d;/%%ENDIF.*%%/d;"
 fi
 
 curdate=`$SETLANG date '+%B %d, %Y'`
diff --git a/doc/gendocs_template b/doc/gendocs_template
index a101977dfc..0e6e8e767b 100644
--- a/doc/gendocs_template
+++ b/doc/gendocs_template
@@ -22,8 +22,10 @@ without any warranty.
 <ul>
 <li><a href="%%PACKAGE%%.html">HTML
     (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
+%%IF HTML_NODE%%
 <li><a href="html_node/index.html">HTML</a> - with one web page per
     node.</li>
+%%ENDIF HTML_NODE%%
 %%IF HTML_SECTION%%
 <li><a href="html_section/index.html">HTML</a> - with one web page per
     section.</li>
@@ -35,9 +37,11 @@ without any warranty.
 <li><a href="%%PACKAGE%%.html.gz">HTML compressed
     (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
     one web page.</li>
+%%IF HTML_NODE%%
 <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
     (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
     with one web page per node.</li>
+%%ENDIF HTML_NODE%%
 %%IF HTML_SECTION%%
 <li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
     (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -
@@ -72,9 +76,7 @@ script</a>.)</p>
 <!-- If needed, change the copyright block at the bottom. In general,
      all pages on the GNU web server should have the section about
      verbatim copying.  Please do NOT remove this without talking
-     with the webmasters first.
-     Please make sure the copyright date is consistent with the document
-     and that it is like this: "2001, 2002", not this: "2001-2002". -->
+     with the webmasters first.  -->
 </div><!-- for id="content", starts in the include above -->
 <!--#include virtual="/server/footer.html" -->
 <div id="footer">
@@ -87,7 +89,7 @@ the FSF.  Broken links and other corrections or suggestions can be sent
 to <a href="mailto:%%EMAIL%%">&lt;%%EMAIL%%&gt;</a>.</p>
 </div>
 
-<p>Copyright &copy; 2022 Free Software Foundation, Inc.</p>
+<p>Copyright &copy; 2023 Free Software Foundation, Inc.</p>
 
 <p>This page is licensed under a <a rel="license"
 href="https://creativecommons.org/licenses/by-nd/3.0/us/">Creative




> 
>      else
>        # should take account of --split here.
>     -  CONDS="/%%ENDIF.*%%/d;/%%IF  *HTML_SECTION%%/d;/%%IF  *HTML_CHAPTER%%/d"
>     +  CONDS="/%%IF.*%%/d;/%%ENDIF.*%%/d;"
> 
> Should the comment now be something like
> # No split output, so delete all conditionals.
> ?
> 
> --
> 
>     <p>Copyright &copy; 2022 Free Software Foundation, Inc.</p>
> 
> On the usual triviality front, the copyright year in gendocs_template
> apparently didn't get updated along with everything else.
> 
>      Please make sure the copyright date is consistent with the document
>      and that it is like this: "2001, 2002", not this: "2001-2002". -->
> 
> That comment has been obsolete for a couple for decades.
> 1) rms agreed to allow ranges; 2) only a single year is listed (which is
> ok for web pages). It goes against the copyright listing at the top of
> the file, so rather confusing.
> 
> That's what I see. I didn't actually try it, sorry. --thanks, karl.

Re: Take account of splitting option in gendocs.sh

[Bruno Haible]

Gavin Smith wrote:
> I've made minor changes to the patch as specified in Karl's response below.
> Please can this be applied?

Thanks for having taken into account both my and Karl's comments. I have
applied your patch.

Bruno

Re: Take account of splitting option in gendocs.sh

[Gavin Smith]

On Wed, Jul 12, 2023 at 04:02:34PM +0200, Bruno Haible wrote:
> Gavin Smith wrote:
> > I've made minor changes to the patch as specified in Karl's response below.
> > Please can this be applied?
> 
> Thanks for having taken into account both my and Karl's comments. I have
> applied your patch.
> 
> Bruno

Thank you!