[m-users.] Splitting up the documentation

[Zoltan Somogyi]

2022-07-17 00:26 GMT+10:00 "Volker Wysk" <post at volker-wysk.de>: 
> How can the documentation be built such that one HTML page per chapter or
> per module is used? Right now, one single huge page for each documentation
> part (library reference manual, user manual, ...) is generated.
> 
> I'm working with a git MMC version, downloaded some one month ago. I've
> looked around a bit, but found no clues of how to accomplish it.

The commands that build the documentation are all listed in doc/Mmakefile.

For the library manual, creating one HTML page per module would be relatively easy,
for two reasons:

- each library module is independent of all the others, and
- the documenation of each module is derived from already-separate
  pieces (the initial parts of the modules themselves).

For the reference manual and the user guide, neither of these is true.
They both contain cross-references between chapters, and they are each built
from a single file (reference_manual.texi and user_guide.texi).

To get per-chapter HTML files for either the manual or the user guide,
you would have to either

- split up their .texi files, and try to process them separately, or
- convert them to a single big HTML file as we do currently, and then
  split up the HTML file.

Both could be done using e.g. an awk of python script, but handling
any cross-chapter references would be tricky.

Then there is the question of motivation: what purpose would a
set of per-chapter HTML files serve? The single large HTML file
can already be browsed in a way that gives you one small part
( a section or subsection) at a time; just click on one the chapter names
in the table of contents either at the start, or at the end. What else
are you looking for?

Zoltan.