[PATCH] libgloss: doc: generate single page & split html manuals

[PATCH] libgloss: doc: generate single page & split html manuals

[Mike Frysinger]

By default, only split node html manuals are generated.  Change the
default to single page, and add an extra rule to also generate the
split page manual.
---
 libgloss/Makefile.in      | 11 +++++++++--
 libgloss/doc/Makefile.inc |  7 +++++++
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/libgloss/Makefile.in b/libgloss/Makefile.in
index 6c5a12256c40..7c7ad68dc411 100644
--- a/libgloss/Makefile.in
+++ b/libgloss/Makefile.in
@@ -937,6 +937,7 @@ MULTISUBDIR =
 MULTIDO = true
 MULTICLEAN = true
 TEXINFO_TEX = ../texinfo/texinfo.tex
+@HAVE_DOC_TRUE@AM_MAKEINFOFLAGS = --no-split
 @CONFIG_AARCH64_TRUE@aarch64_librdimon_a_SOURCES = \
 @CONFIG_AARCH64_TRUE@	aarch64/_exit.c \
 @CONFIG_AARCH64_TRUE@	aarch64/_kill.c \
@@ -5097,6 +5098,7 @@ distclean-generic:
 maintainer-clean-generic:
 	@echo "This command is intended for maintainers to use"
 	@echo "it deletes files that may require special tools to rebuild."
+@HAVE_DOC_FALSE@html-local:
 clean: clean-recursive
 
 clean-am: clean-aminfo clean-binPROGRAMS clean-checkPROGRAMS \
@@ -5116,7 +5118,7 @@ dvi-am: $(DVIS)
 
 html: html-recursive
 
-html-am: $(HTMLS)
+html-am: $(HTMLS) html-local
 
 info: info-recursive
 
@@ -5283,7 +5285,7 @@ uninstall-am: uninstall-aarch64_cpu_initcpuinitDATA \
 	clean-noinstLIBRARIES cscope cscopelist-am ctags ctags-am \
 	dist-info distclean distclean-compile distclean-generic \
 	distclean-hdr distclean-local distclean-tags dvi dvi-am html \
-	html-am info info-am install \
+	html-am html-local info info-am install \
 	install-aarch64_cpu_initcpuinitDATA install-am \
 	install-arm_cpu_initcpuinitDATA install-binPROGRAMS \
 	install-data install-data-am install-dvi install-dvi-am \
@@ -5336,6 +5338,11 @@ clean-local: clean-multi
 distclean-local: distclean-multi
 maintainer-clean-local: maintainer-clean-multi
 
+@HAVE_DOC_TRUE@html-local: doc/porting/index.html
+@HAVE_DOC_TRUE@doc/porting/index.html: doc/porting.texi doc/$(am__dirstamp)
+@HAVE_DOC_TRUE@	$(AM_V_GEN)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \
+@HAVE_DOC_TRUE@		--split=node $< -o $(@D)
+
 @CONFIG_AARCH64_TRUE@aarch64/crt0.$(OBJEXT): aarch64/crt0.S
 @CONFIG_AARCH64_TRUE@	$(AM_V_CPPAS)$(CPPASCOMPILE) -DSEMIHOST_V2 -o $@ -c $<
 @CONFIG_AARCH64_TRUE@aarch64/rdimon-crt0.$(OBJEXT): aarch64/crt0.S
diff --git a/libgloss/doc/Makefile.inc b/libgloss/doc/Makefile.inc
index fa5e30fbf2bc..6f9050fc87f8 100644
--- a/libgloss/doc/Makefile.inc
+++ b/libgloss/doc/Makefile.inc
@@ -1 +1,8 @@
+AM_MAKEINFOFLAGS = --no-split
+
 info_TEXINFOS += %D%/porting.texi
+
+html-local: %D%/porting/index.html
+%D%/porting/index.html: %D%/porting.texi %D%/$(am__dirstamp)
+	$(AM_V_GEN)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \
+		--split=node $< -o $(@D)
-- 
2.42.0

Re: [PATCH] libgloss: doc: generate single page & split html manuals

[R. Diez]

> By default, only split node html manuals are generated.  Change the
> default to single page, and add an extra rule to also generate the
> split page manual.

I am a little confused about this patch, and I would like to learn more anyhow about the way Newlib generates its documentation.


> libgloss/Makefile.in      | 11 +++++++++--
> libgloss/doc/Makefile.inc |  7 +++++++

Does this mean that only libgloss is affected? Or does the libc part also have the concept of split / single HTML manuals?


> +@HAVE_DOC_TRUE@html-local: doc/porting/index.html

Is 'html-local' the new target? If so, why not call it 'html-split' or 'html-split-node'? I am guessing that the default target is called 'html'.

On the other hand, if the old behaviour was to generate "split node html", why not just add a new target called 'html-single' or 'html-single-node'?


> +@HAVE_DOC_TRUE@AM_MAKEINFOFLAGS = --no-split
> [...]
> +@HAVE_DOC_TRUE@doc/porting/index.html: doc/porting.texi doc/$(am__dirstamp)
> +@HAVE_DOC_TRUE@    $(AM_V_GEN)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \
> +@HAVE_DOC_TRUE@        --split=node $< -o $(@D)
> [...]
> +AM_MAKEINFOFLAGS = --no-split
> [...]
> +html-local: %D%/porting/index.html
> +%D%/porting/index.html: %D%/porting.texi %D%/$(am__dirstamp)
> +    $(AM_V_GEN)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \
> +        --split=node $< -o $(@D)


I do not actually know what @HAVE_DOC_TRUE@ means. All I can see above next to AM_MAKEINFOFLAGS is "--no-split", but then the command-line arguments are both "--split=node". Is that not a contradiction?

Thanks in advance for your help,
  rdiez

Re: [PATCH] libgloss: doc: generate single page & split html manuals

[Mike Frysinger]

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

On 16 Oct 2023 09:31, R. Diez wrote:
> > libgloss/Makefile.in      | 11 +++++++++--
> > libgloss/doc/Makefile.inc |  7 +++++++
> 
> Does this mean that only libgloss is affected? Or does the libc part also have the concept of split / single HTML manuals?

i'll update newlib (libc+libm) once people are happy with this direction.

> > +@HAVE_DOC_TRUE@html-local: doc/porting/index.html
> 
> Is 'html-local' the new target?

this is an internal Automake hook point.  people still run `make html` and
they'll get both forms of the manual.
https://www.gnu.org/software/automake/manual/1.16.5/automake.html#index-html_002dlocal

> > +@HAVE_DOC_TRUE@AM_MAKEINFOFLAGS = --no-split
> > [...]
> > +@HAVE_DOC_TRUE@doc/porting/index.html: doc/porting.texi doc/$(am__dirstamp)
> > +@HAVE_DOC_TRUE@    $(AM_V_GEN)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \
> > +@HAVE_DOC_TRUE@        --split=node $< -o $(@D)
> > [...]
> > +AM_MAKEINFOFLAGS = --no-split
> > [...]
> > +html-local: %D%/porting/index.html
> > +%D%/porting/index.html: %D%/porting.texi %D%/$(am__dirstamp)
> > +    $(AM_V_GEN)$(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) \
> > +        --split=node $< -o $(@D)
> 
> 
> I do not actually know what @HAVE_DOC_TRUE@ means.

Makefile.in is generated code that isn't meant to be read by most people.

> All I can see above next to AM_MAKEINFOFLAGS is "--no-split", but then the command-line arguments are both "--split=node". Is that not a contradiction?

standard CLI behavior: later options override earlier one.
-mike

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

Re: [PATCH] libgloss: doc: generate single page & split html manuals

[R. Diez]

>> Does this mean that only libgloss is affected? Or does
>> the libc part also have the concept of split / single HTML manuals?

> i'll update newlib (libc+libm) once people are happy with this direction.

OK, thanks.


> Makefile.in is generated code that isn't meant to be read by most people.

You are right. I forgot that Newlib is still checking into the repository machine-generated files.


>>> [...]
>>> add an extra rule to also generate the split page manual.

>> Is 'html-local' the new target?

> this is an internal Automake hook point.  people still run `make html` and
> they'll get both forms of the manual.

If I understood it correctly, you are not actually adding an extra rule, but injecting an extra step in the standard 'html' rule.

The makefile will then be generating both 'single' and 'split' HTML documentation variants at once. This will usually be a waste of CPU time and disk space, will it not? I guess most people would normally want one version or the other, but not both.

The 'html' target, and the notion single/split, seems like a standard Automake concept, but I am not familiar with it yet. Is the Automake user supposed to specify via MAKEINFOFLAGS whether to generate a single or split variant? What happens if the user specifies MAKEINFOFLAGS=--no-split or MAKEINFOFLAGS=--split=chapter ?

Regards,
  rdiez

Re: [PATCH] libgloss: doc: generate single page & split html manuals

[Mike Frysinger]

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

On 16 Oct 2023 13:44, R. Diez wrote:
> >>> [...]
> >>> add an extra rule to also generate the split page manual.
> 
> >> Is 'html-local' the new target?
> 
> > this is an internal Automake hook point.  people still run `make html` and
> > they'll get both forms of the manual.
> 
> If I understood it correctly, you are not actually adding an extra rule, but injecting an extra step in the standard 'html' rule.

i don't know if you're trying to understand the internals, or just form a mental
model of how this comes together.  from a makefile perspective, it is a new rule
that you can `make html-local` if you really want.  automake will add a dep on
the new rule to the standard html rule iff the rule exists so that people don't
have to run the explicit xxx-local rules.

> The makefile will then be generating both 'single' and 'split' HTML documentation variants at once. This will usually be a waste of CPU time and disk space, will it not? I guess most people would normally want one version or the other, but not both.

currently, the html manual isn't built by default.  it's only generated if the
user runs `make html` explicitly.

but sure, if the user only wants one version and not the other, it's technically
a waste of time.  considering the manual generation takes <150ms on my system
per variant, i don't think it's worth the time debating this.  running configure
takes significantly longer.

other projects haven't really provided a choice to people -- they generate both.

> The 'html' target, and the notion single/split, seems like a standard Automake concept, but I am not familiar with it yet. Is the Automake user supposed to specify via MAKEINFOFLAGS whether to generate a single or split variant? What happens if the user specifies MAKEINFOFLAGS=--no-split or MAKEINFOFLAGS=--split=chapter ?

the single/split is a texinfo thing, not automake.  the point of generating both
of them is to make it easier for people to have access to whichever version they
want, and to make it easier for us producing the release docs for the website.
-mike

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