Re: documentation structure

On 2024-07-18 Th 4:16 PM, Corey Huinker wrote:
>
>
> 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.

I'm opposed to having a separate file for every function. I think
breaking up func.sgml into one piece per sect1 is about right. If that
proves cumbersome still we can look at breaking it up further, but let's
start with that.

More concretely, sometimes the bits that relate to a particular function
are not contiguous. e.g. you might have an entry in a table for a
function and then at the end Notes relating to that function. That make
doing a file per function not very practical.

Also, being able to view the context for your function documentation is
useful when editing.

cheers

andrew

--
Andrew Dunstan
EDB:https://www.enterprisedb.com