[m-users.] Splitting up the documentation

Zoltan Somogyi zoltan.somogyi at runbox.com
Sun Jul 17 00:47:30 AEST 2022


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.


More information about the users mailing list