Re: documentation structure

>
>
> looking back.
> The patch is big. no convenient way to review/validate it.
>

Perhaps we can break up the patches as follows:

1. create the filelist.sgml entries, and create new files as you detailed,
empty with func.sgml still managing the sections, but each section now has
it's corresponding &func-something; The files are included, but they're
completely empty.

2 to 999+. one commit per function moved from func.sgml to it's
corresponding func-something.sgml.

It'll be a ton of commits, but each one will be very easy to review.

Alternately, if we put each function in its own file, there would be a
series of commits, one per function like such:

1. create the new func-my-function.sgml, copying the definition of the same
name
2. delete the definition in func.sgml, replaced with the &func-include;
3. new entry in the filelist.

This approach looks (and IS) tedious, but it has several key advantages:

1. Each one is very easy to review.
2. Big reduction in future merge conflicts on func.sgml.
3. location of a given functions docs is now trivial.
4. separation of concerns with regard to content of function def vs
placement of same.
5. Easy to ensure that all functions have an anchor.
6. The effort can stall and be resumed at our own pace.

Perhaps your python script can be adapted to this approach? I'm willing to
review, or collaborate, or both.