Re: split func.sgml to separated individual sgml files

On Wed, Nov 13, 2024 at 1:11 PM Corey Huinker <corey(dot)huinker(at)gmail(dot)com>
wrote:

> The following is step-by-step logic.
>>
>>
> The end result (one file per section) seems good to me.
>
> I suspect that reviewer burden may be the biggest barrier to going
> forward. Perhaps breaking up the changes so that each new sect1 file gets
> its own commit, allowing the reviewer to more easily (if not
> programmatically) verify that the text that moved out of func.sgml moved
> into func-sect-foo.sgml.
>
> Granted, the committer will likely squash all of those commits down into
> one big one, but by the the hard work of reviewing is done by then.
>
>
Validation is pretty trivial. I just built the before and after HTML files
and confirmed they are exactly the same size.

I suppose we might have lost some comments or something that wouldn't end
up visible in the HTML (seems unlikely) but this is basically one-and-done
so long as you don't let other commits happen (that touch this area) while
you extract and build HEAD and then compare it to the patched build
results. The git diff will let us know the script didn't affect any source
files it wasn't supposed to.

In short, ready to commit (see last paragraph below however), but the
committer will need to run the python script at the time of commit on the
then-current tree.

In my recent patch touching filelist.sgml I would be placing this new
%allfiles_func; line pairing at the top just beneath %allfiles; which is
the first child element. But the choice made here makes sense should this
go in first.

There is little downside, though, to renaming the existing %allfiles; to
%allfiles_ref; It's a local-only name.

David J.