Allow tweaking the order of chapters, sections and mansections

[fingolfin]

Right now, everything is output in the order we encounter it. This is sometimes annoying, but especially on the level of chapters. So we need to add a way that allows users to easily set the correct order.

Steve suggests the following: Provide a "skeleton file" which just lists the chapter labels (and possible more labels) in the order things should appear.

This is then parsed. If it mentions a chapter or section that contains no data, issue a warning (the user may have made a typo). If on the other hand something is missing from it, also issue a warning.

Finally, this could even allow inserting text and other stuff... I.e. it could basically use the same (or at least a similar) syntax as AutoDoc doc comments. Indeed, a very simple implementation for this could just be to tell users to add autodoc := rec( files := [ order_info.g ], ...) to their AutoDoc() invocation, and then put content like this into that file:

#! @Chapter First AutoDoc chapter
#! @Chapter Second AutoDoc chapter

Since scanning subdirs adds other files to the end of autodoc.files, it is ensured that this file is read first.

Anyway: The above is just one way to go about this. Others are conceivable, e.g. one could allow the user to add a numerical "priority" to each chapter declaration or so, and then we sort chapters by their "priority". But the skeleton approach sounds nicer to me.

[sebasguts]

The sceleton approach is a good idea. It allows, more than just order, a place to store some introductions to chapters and sections.

[stevelinton]

Did this ever get resolved? I'm using AutoDoc for the manual of the meataxe64 package, and I'd like to alter the chapter order.

[sebasguts]

The sceleton approach works, see for example https://github.com/homalg-project/CAP_project/blob/master/CAP/doc/Intros.autodoc.

We could also in principle add optional numeric values to the chapters that can be used for ordering them.

[stevelinton]

Thanks. That looks fine.