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

Mike Frysinger <[email protected]> Wed, 29 Nov 2023 03:45:06 -0500

Newsgroups	gmane.comp.lib.newlib
Message-ID	<ZWb6Eoh2dJrpkizl@vapier>

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

signature.asc (application/pgp-signature, 833 B)