[m-users.] Splitting up the documentation

[Volker Wysk]

Am Sonntag, dem 17.07.2022 um 00:47 +1000 schrieb 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.

Thanks, I'll look again.

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

I'm thinking about the library manual, first of all.

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

It just sends me to the beginning of the specific module. Do you mean the
navigation links at the end of a module? It doesn't give you one small part
at a time...

> What else
> are you looking for?

Hmm.. I'm browsing the documentation of a specific module and would like to
stay in that module. For instance, I want to be able to jump to the
beginning by pressing Pos1. (That's the name of the key on a German
keyboard. I think it's called "home" on English keyboards.) It's also
impossible to use the scroll bar, because the text is much too long. Also
when searching the text (with the browser), you easily leave the module and
get lost.

So most of the time I use the online documentation, which happens to be
split up nicely.

Having a all-in-one version might sometimes be handy, when you actually want
to search or browse the entire standard libraries. But this hasn't happened
to me yet. (Maybe I'm just not working efficiently... ;-) )

Cheers,
Volker
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part
URL: <http://lists.mercurylang.org/archives/users/attachments/20220716/aa68acf0/attachment.sig>