public inbox for newlib@sourceware.org
 help / color / mirror / Atom feed
* [PATCH 0/5] Various improvements to newlib manpages build
@ 2022-05-02 12:55 Jon Turney
  2022-05-02 12:55 ` [PATCH 1/5] Simplify rules for creating man pages Jon Turney
                   ` (5 more replies)
  0 siblings, 6 replies; 8+ messages in thread
From: Jon Turney @ 2022-05-02 12:55 UTC (permalink / raw)
  To: newlib; +Cc: 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


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

* [PATCH 1/5] Simplify rules for creating man pages
  2022-05-02 12:55 [PATCH 0/5] Various improvements to newlib manpages build Jon Turney
@ 2022-05-02 12:55 ` Jon Turney
  2022-05-08 19:42   ` Mike Frysinger
  2022-05-02 12:55 ` [PATCH 2/5] Add build avoidance for 'make man' Jon Turney
                   ` (4 subsequent siblings)
  5 siblings, 1 reply; 8+ messages in thread
From: Jon Turney @ 2022-05-02 12:55 UTC (permalink / raw)
  To: newlib; +Cc: 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


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

* [PATCH 2/5] Add build avoidance for 'make man'
  2022-05-02 12:55 [PATCH 0/5] Various improvements to newlib manpages build Jon Turney
  2022-05-02 12:55 ` [PATCH 1/5] Simplify rules for creating man pages Jon Turney
@ 2022-05-02 12:55 ` Jon Turney
  2022-05-02 12:55 ` [PATCH 3/5] Silence xsltproc when writing manpages Jon Turney
                   ` (3 subsequent siblings)
  5 siblings, 0 replies; 8+ messages in thread
From: Jon Turney @ 2022-05-02 12:55 UTC (permalink / raw)
  To: newlib; +Cc: 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


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

* [PATCH 3/5] Silence xsltproc when writing manpages
  2022-05-02 12:55 [PATCH 0/5] Various improvements to newlib manpages build Jon Turney
  2022-05-02 12:55 ` [PATCH 1/5] Simplify rules for creating man pages Jon Turney
  2022-05-02 12:55 ` [PATCH 2/5] Add build avoidance for 'make man' Jon Turney
@ 2022-05-02 12:55 ` Jon Turney
  2022-05-02 12:55 ` [PATCH 4/5] Fix warning about duplicate id in docbook XML Jon Turney
                   ` (2 subsequent siblings)
  5 siblings, 0 replies; 8+ messages in thread
From: Jon Turney @ 2022-05-02 12:55 UTC (permalink / raw)
  To: newlib; +Cc: 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


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

* [PATCH 4/5] Fix warning about duplicate id in docbook XML
  2022-05-02 12:55 [PATCH 0/5] Various improvements to newlib manpages build Jon Turney
                   ` (2 preceding siblings ...)
  2022-05-02 12:55 ` [PATCH 3/5] Silence xsltproc when writing manpages Jon Turney
@ 2022-05-02 12:55 ` Jon Turney
  2022-05-02 12:55 ` [PATCH 5/5] Generate manpages for functions in chapter sys.tex Jon Turney
  2022-05-05  0:37 ` [PATCH 0/5] Various improvements to newlib manpages build Jeff Johnston
  5 siblings, 0 replies; 8+ messages in thread
From: Jon Turney @ 2022-05-02 12:55 UTC (permalink / raw)
  To: newlib; +Cc: 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


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

* [PATCH 5/5] Generate manpages for functions in chapter sys.tex
  2022-05-02 12:55 [PATCH 0/5] Various improvements to newlib manpages build Jon Turney
                   ` (3 preceding siblings ...)
  2022-05-02 12:55 ` [PATCH 4/5] Fix warning about duplicate id in docbook XML Jon Turney
@ 2022-05-02 12:55 ` Jon Turney
  2022-05-05  0:37 ` [PATCH 0/5] Various improvements to newlib manpages build Jeff Johnston
  5 siblings, 0 replies; 8+ messages in thread
From: Jon Turney @ 2022-05-02 12:55 UTC (permalink / raw)
  To: newlib; +Cc: 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


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

* Re: [PATCH 0/5] Various improvements to newlib manpages build
  2022-05-02 12:55 [PATCH 0/5] Various improvements to newlib manpages build Jon Turney
                   ` (4 preceding siblings ...)
  2022-05-02 12:55 ` [PATCH 5/5] Generate manpages for functions in chapter sys.tex Jon Turney
@ 2022-05-05  0:37 ` Jeff Johnston
  5 siblings, 0 replies; 8+ messages in thread
From: Jeff Johnston @ 2022-05-05  0:37 UTC (permalink / raw)
  To: Jon Turney; +Cc: Newlib

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
>
>

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

* Re: [PATCH 1/5] Simplify rules for creating man pages
  2022-05-02 12:55 ` [PATCH 1/5] Simplify rules for creating man pages Jon Turney
@ 2022-05-08 19:42   ` Mike Frysinger
  0 siblings, 0 replies; 8+ messages in thread
From: Mike Frysinger @ 2022-05-08 19:42 UTC (permalink / raw)
  To: Jon Turney; +Cc: newlib

[-- 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 --]

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

end of thread, other threads:[~2022-05-08 19:41 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-05-02 12:55 [PATCH 0/5] Various improvements to newlib manpages build Jon Turney
2022-05-02 12:55 ` [PATCH 1/5] Simplify rules for creating man pages Jon Turney
2022-05-08 19:42   ` Mike Frysinger
2022-05-02 12:55 ` [PATCH 2/5] Add build avoidance for 'make man' Jon Turney
2022-05-02 12:55 ` [PATCH 3/5] Silence xsltproc when writing manpages Jon Turney
2022-05-02 12:55 ` [PATCH 4/5] Fix warning about duplicate id in docbook XML Jon Turney
2022-05-02 12:55 ` [PATCH 5/5] Generate manpages for functions in chapter sys.tex Jon Turney
2022-05-05  0:37 ` [PATCH 0/5] Various improvements to newlib manpages build Jeff Johnston

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).