Re: documentation structure - Mailing list pgsql-hackers

From Corey Huinker
Subject Re: documentation structure
Date
Msg-id CADkLM=cXvybjLKQ+n3=kwFLyRp6AA9VPh_0QJvWBU2tZFmxN-g@mail.gmail.com
Whole thread Raw
In response to Re: documentation structure  (jian he <jian.universality@gmail.com>)
Responses Re: documentation structure
List pgsql-hackers

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.

pgsql-hackers by date:

Previous
From: Tom Lane
Date:
Subject: Re: Evaluate arguments of correlated SubPlans in the referencing ExprState
Next
From: Tom Lane
Date:
Subject: Re: Seq scan instead of index scan querying single row from primary key on large table