[PATCH 0/5] Various improvements to newlib manpages build

[PATCH 0/5] Various improvements to newlib manpages build

[Jon Turney]

Jon Turney (5):
  Simplify rules for creating man pages
  Add build avoidance for 'make man'
  Silence xsltproc when writing manpages
  Fix warning about duplicate id in docbook XML
  Generate manpages for functions in chapter sys.tex

 newlib/Makefile.am                 |  3 +++
 newlib/doc/chapter-texi2docbook.py |  2 +-
 newlib/libc/Makefile.inc           | 17 ++++++++---------
 newlib/libc/libc.in.xml            |  4 +++-
 newlib/libm/Makefile.inc           | 17 ++++++++---------
 5 files changed, 23 insertions(+), 20 deletions(-)

-- 
2.36.0

[PATCH 1/5] Simplify rules for creating man pages

[Jon Turney]

Simplify rules for creating docbook XML used to create manpages:
Updating the output using move-if-change and then unconditionally
touching the .stamp file doesn't make much sense.
---

Notes:
    See https://sourceware.org/pipermail/newlib/2022/019061.html

 newlib/libc/Makefile.inc | 8 +++-----
 newlib/libm/Makefile.inc | 8 +++-----
 2 files changed, 6 insertions(+), 10 deletions(-)

diff --git a/newlib/libc/Makefile.inc b/newlib/libc/Makefile.inc
index 61ae0d793..792b50f97 100644
--- a/newlib/libc/Makefile.inc
+++ b/newlib/libc/Makefile.inc
@@ -15,15 +15,13 @@ $(LIBC_CHEWOUT_FILES): $(MKDOC)
 	$(AM_V_at)touch $@
 %D%/targetdep.tex: %D%/targetdep.tex.stamp; @true
 
-%D%/libc.xml.stamp: %D%/libc.in.xml $(LIBC_CHAPTERS) $(LIBC_DOCBOOK_OUT_FILES)
+%D%/libc.xml: %D%/libc.in.xml $(LIBC_CHAPTERS) $(LIBC_DOCBOOK_OUT_FILES)
 	$(AM_V_at)\
 	for chapter in $(LIBC_CHAPTERS); do \
 	  $(TEXI2DOCBOOK) < $(srcdir)/$$chapter > %D%/`basename $${chapter%.tex}`.xml || exit 1; \
 	done
 	$(AM_V_GEN)xsltproc --xinclude --path $(builddir)/%D% --nonet $(srcdir)/refcontainers.xslt $< > $@.tmp
-	$(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change $@.tmp $(@:.stamp=)
-	$(AM_V_at)touch $@
-%D%/libc.xml: %D%/libc.xml.stamp; @true
+	$(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change $@.tmp $@
 
 %C%_man: %D%/libc.xml
 	$(AM_V_GEN)xmlto --skip-validation -o %D% --searchpath $(builddir)/%D% man -m $(srcdir)/man.xsl %D%/libc.xml
@@ -69,4 +67,4 @@ CLEANFILES += \
 	%D%/targetdep.tex.stamp \
 	$(LIBC_CHEWOUT_FILES) \
 	$(LIBC_DOCBOOK_OUT_FILES) \
-	%D%/*.xml %D%/*.xml.stamp %D%/*.3
+	%D%/*.xml %D%/*.3
diff --git a/newlib/libm/Makefile.inc b/newlib/libm/Makefile.inc
index de63b8674..e2b6b1371 100644
--- a/newlib/libm/Makefile.inc
+++ b/newlib/libm/Makefile.inc
@@ -15,15 +15,13 @@ $(LIBM_CHEWOUT_FILES): $(MKDOC)
 	$(AM_V_at)touch $@
 %D%/targetdep.tex: %D%/targetdep.tex.stamp; @true
 
-%D%/libm.xml.stamp: %D%/libm.in.xml $(LIBM_CHAPTERS) $(LIBM_DOCBOOK_OUT_FILES)
+%D%/libm.xml: %D%/libm.in.xml $(LIBM_CHAPTERS) $(LIBM_DOCBOOK_OUT_FILES)
 	$(AM_V_at)\
 	for chapter in $(LIBM_CHAPTERS); do \
 	  $(TEXI2DOCBOOK) < $(srcdir)/$$chapter > %D%/`basename $${chapter%.tex}`.xml || exit 1; \
 	done
 	$(AM_V_GEN)xsltproc --xinclude --path $(builddir)/%D% --nonet $(srcdir)/refcontainers.xslt $< > $@.tmp
-	$(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change $@.tmp $(@:.stamp=)
-	$(AM_V_at)touch $@
-%D%/libm.xml: %D%/libm.xml.stamp; @true
+	$(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change $@.tmp $@
 
 %C%_man: %D%/libm.xml
 	$(AM_V_GEN)xmlto --skip-validation -o %D% --searchpath $(builddir)/%D% man -m $(srcdir)/man.xsl %D%/libm.xml
@@ -88,4 +86,4 @@ CLEANFILES += \
 	%D%/targetdep.tex.stamp \
 	$(LIBM_CHEWOUT_FILES) \
 	$(LIBM_DOCBOOK_OUT_FILES) \
-	%D%/*.xml %D%/*.xml.stamp %D%/*.3
+	%D%/*.xml %D%/*.3
-- 
2.36.0

Re: [PATCH 1/5] Simplify rules for creating man pages

[Mike Frysinger]

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

On 02 May 2022 13:55, Jon Turney wrote:
> Simplify rules for creating docbook XML used to create manpages:
> Updating the output using move-if-change and then unconditionally
> touching the .stamp file doesn't make much sense.

it does make sense.  i explained the point of the stamp file in the
response to your message:
https://sourceware.org/pipermail/newlib/2022/019064.html

tl;dr: it's a common optimization pattern used in the tree.  it avoids
recreating all the docbook & man pages when there is no content change.
-mike

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

[PATCH 2/5] Add build avoidance for 'make man'

[Jon Turney]

This will generate multiple manpage files as an output, but we don't
know what they will be called, so use a timestamp for build avoidance.
---
 newlib/libc/Makefile.inc | 9 +++++----
 newlib/libm/Makefile.inc | 9 +++++----
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/newlib/libc/Makefile.inc b/newlib/libc/Makefile.inc
index 792b50f97..21f356664 100644
--- a/newlib/libc/Makefile.inc
+++ b/newlib/libc/Makefile.inc
@@ -23,11 +23,12 @@ $(LIBC_CHEWOUT_FILES): $(MKDOC)
 	$(AM_V_GEN)xsltproc --xinclude --path $(builddir)/%D% --nonet $(srcdir)/refcontainers.xslt $< > $@.tmp
 	$(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change $@.tmp $@
 
-%C%_man: %D%/libc.xml
+%C%_man.stamp: %D%/libc.xml
 	$(AM_V_GEN)xmlto --skip-validation -o %D% --searchpath $(builddir)/%D% man -m $(srcdir)/man.xsl %D%/libc.xml
-man: %C%_man
+	$(AM_V_at)touch $@
+man: %C%_man.stamp
 
-%C%_install-man: %C%_man
+%C%_install-man: %C%_man.stamp
 	$(MKDIR_P) $(DESTDIR)$(mandir)/man3
 	$(INSTALL_DATA) %D%/*.3 $(DESTDIR)$(mandir)/man3/
 install-man: %C%_install-man
@@ -67,4 +68,4 @@ CLEANFILES += \
 	%D%/targetdep.tex.stamp \
 	$(LIBC_CHEWOUT_FILES) \
 	$(LIBC_DOCBOOK_OUT_FILES) \
-	%D%/*.xml %D%/*.3
+	%D%/*.xml %C%_man.stamp %D%/*.3
diff --git a/newlib/libm/Makefile.inc b/newlib/libm/Makefile.inc
index e2b6b1371..699bc4caf 100644
--- a/newlib/libm/Makefile.inc
+++ b/newlib/libm/Makefile.inc
@@ -23,11 +23,12 @@ $(LIBM_CHEWOUT_FILES): $(MKDOC)
 	$(AM_V_GEN)xsltproc --xinclude --path $(builddir)/%D% --nonet $(srcdir)/refcontainers.xslt $< > $@.tmp
 	$(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change $@.tmp $@
 
-%C%_man: %D%/libm.xml
+%C%_man.stamp: %D%/libm.xml
 	$(AM_V_GEN)xmlto --skip-validation -o %D% --searchpath $(builddir)/%D% man -m $(srcdir)/man.xsl %D%/libm.xml
-man: %C%_man
+	$(AM_V_at)touch $@
+man: %C%_man.stamp
 
-%C%_install-man: %C%_man
+%C%_install-man: %C%_man.stamp
 	$(MKDIR_P) $(DESTDIR)$(mandir)/man3
 	$(INSTALL_DATA) %D%/*.3 $(DESTDIR)$(mandir)/man3/
 install-man: %C%_install-man
@@ -86,4 +87,4 @@ CLEANFILES += \
 	%D%/targetdep.tex.stamp \
 	$(LIBM_CHEWOUT_FILES) \
 	$(LIBM_DOCBOOK_OUT_FILES) \
-	%D%/*.xml %D%/*.3
+	%D%/*.xml %C%_man.stamp %D%/*.3
-- 
2.36.0

[PATCH 3/5] Silence xsltproc when writing manpages

[Jon Turney]

Unless make is invoked with V=1, have xmlto pass the parameter
'man.output.quietly=1' to xsltproc to suppress "Note: Writing foo.N"
output from the manpages stylesheet.

(This doesn't quite do what it says: The output is not silenced if V has
any value, including 0.  You could consider that either a bug or a
feature.)
---
 newlib/Makefile.am       | 3 +++
 newlib/libc/Makefile.inc | 2 +-
 newlib/libm/Makefile.inc | 2 +-
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/newlib/Makefile.am b/newlib/Makefile.am
index 16c10f4a0..0108d8576 100644
--- a/newlib/Makefile.am
+++ b/newlib/Makefile.am
@@ -442,6 +442,9 @@ TEXI2DVI = texi2dvi -E
 
 TEXINFO_TEX = ../texinfo/texinfo.tex
 
+XMLTO_MAN_QUIET_=--stringparam man.output.quietly=1
+XMLTO_MAN_QUIET=$(XMLTO_MAN_QUIET_$(V))
+
 if HAVE_DOC
 include doc/Makefile.inc
 endif
diff --git a/newlib/libc/Makefile.inc b/newlib/libc/Makefile.inc
index 21f356664..d07eed764 100644
--- a/newlib/libc/Makefile.inc
+++ b/newlib/libc/Makefile.inc
@@ -24,7 +24,7 @@ $(LIBC_CHEWOUT_FILES): $(MKDOC)
 	$(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change $@.tmp $@
 
 %C%_man.stamp: %D%/libc.xml
-	$(AM_V_GEN)xmlto --skip-validation -o %D% --searchpath $(builddir)/%D% man -m $(srcdir)/man.xsl %D%/libc.xml
+	$(AM_V_GEN)xmlto --skip-validation -o %D% --searchpath $(builddir)/%D% man -m $(srcdir)/man.xsl $(XMLTO_MAN_QUIET) %D%/libc.xml
 	$(AM_V_at)touch $@
 man: %C%_man.stamp
 
diff --git a/newlib/libm/Makefile.inc b/newlib/libm/Makefile.inc
index 699bc4caf..7fda120e5 100644
--- a/newlib/libm/Makefile.inc
+++ b/newlib/libm/Makefile.inc
@@ -24,7 +24,7 @@ $(LIBM_CHEWOUT_FILES): $(MKDOC)
 	$(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change $@.tmp $@
 
 %C%_man.stamp: %D%/libm.xml
-	$(AM_V_GEN)xmlto --skip-validation -o %D% --searchpath $(builddir)/%D% man -m $(srcdir)/man.xsl %D%/libm.xml
+	$(AM_V_GEN)xmlto --skip-validation -o %D% --searchpath $(builddir)/%D% man -m $(srcdir)/man.xsl $(XMLTO_MAN_QUIET) %D%/libm.xml
 	$(AM_V_at)touch $@
 man: %C%_man.stamp
 
-- 
2.36.0

[PATCH 4/5] Fix warning about duplicate id in docbook XML

[Jon Turney]

../newlib/libc/libc.xml:22242: element refentry: validity error : ID iconv already defined
    <refentry id="iconv">

Use a separate namespace for chaper ids, to avoid collision between the
ids for the chapter and function 'iconv', now that iconv documentation
is generated unconditionally.
---
 newlib/doc/chapter-texi2docbook.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/newlib/doc/chapter-texi2docbook.py b/newlib/doc/chapter-texi2docbook.py
index 1a7803091..834a14e7c 100755
--- a/newlib/doc/chapter-texi2docbook.py
+++ b/newlib/doc/chapter-texi2docbook.py
@@ -29,7 +29,7 @@ def main():
             l = l.strip()
             l = l.lower()
             if first_node:
-                print ('<chapter id="%s" xmlns:xi="http://www.w3.org/2001/XInclude">' % l.replace(' ', '_'))
+                print ('<chapter id="%s_chapter" xmlns:xi="http://www.w3.org/2001/XInclude">' % l.replace(' ', '_'))
                 first_node = False
         elif l.startswith("@chapter "):
             l = l.replace("@chapter ", "", 1)
-- 
2.36.0

[PATCH 5/5] Generate manpages for functions in chapter sys.tex

[Jon Turney]

Also generate manpages for functions in chapter sys.tex, omitted in
error.
---
 newlib/libc/libc.in.xml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/newlib/libc/libc.in.xml b/newlib/libc/libc.in.xml
index 6afae0d7b..7bdbb22e3 100644
--- a/newlib/libc/libc.in.xml
+++ b/newlib/libc/libc.in.xml
@@ -22,7 +22,7 @@
 
   <xi:include href="time.xml"/>
   <xi:include href="locale.xml"/>
-  <!-- reent.tex contains fixed content and nothing seems to include the .def made in reent/ -->
+  <!-- reent.tex contains fixed content -->
 
   <xi:include href="misc.xml"/>
   <!-- posix is optional -->
@@ -37,6 +37,8 @@
   </xi:include>
   <!-- ssp.tex contains fixed content -->
 
+  <xi:include href="sys.xml"/> <!-- sys.tex includes the .def files made in reent/ -->
+
   <!-- processing should insert index here -->
   <index/>
 
-- 
2.36.0

Re: [PATCH 0/5] Various improvements to newlib manpages build

[Jeff Johnston]

Thanks Jon.  Patches merged.

-- Jeff J.

On Mon, May 2, 2022 at 8:55 AM Jon Turney <jon.turney@dronecode.org.uk>
wrote:

> Jon Turney (5):
>   Simplify rules for creating man pages
>   Add build avoidance for 'make man'
>   Silence xsltproc when writing manpages
>   Fix warning about duplicate id in docbook XML
>   Generate manpages for functions in chapter sys.tex
>
>  newlib/Makefile.am                 |  3 +++
>  newlib/doc/chapter-texi2docbook.py |  2 +-
>  newlib/libc/Makefile.inc           | 17 ++++++++---------
>  newlib/libc/libc.in.xml            |  4 +++-
>  newlib/libm/Makefile.inc           | 17 ++++++++---------
>  5 files changed, 23 insertions(+), 20 deletions(-)
>
> --
> 2.36.0
>
>