I had a look at your patch, starting from the end and up to "xfunc".
I looked at all the references in the documentation to see if I can spot
any oddities. I don't think I'll be able to look through the whole patch
at that level, but I wanted to get an idea.
Overall, I have the impression that the patch is an improvement.
Here are some general comments:
1. You seem to have taken the chapter heading as label automatically.
That leads to labels like "Author" and "Deprecation Notice" that are not
descriptive enough without a reference to the chapter.
These lables need going over.
2. I notice that you added labels to the sections, but not to the chapters, so
the references to the chapters still read like "Chapter 63". Is that deliberate,
an oversight, or are there problems adding labels to the chapters?
3. Similarly, you didn't add labels to subsections, so there are still references
like "Section 66.6.1". I understand that that might be too much code churn for
your patch, but the inconsistency is deplorable.
Comments for the individual changes I scrutinized:
- Chapter 36.3 now has:
PostgreSQL provides four kinds of functions:
• query language functions (functions written in SQL) (Query Language (SQL) Functions)
• procedural language functions (functions written in, for example, PL/pgSQL or PL/Tcl) (Procedural Language
Functions)
• internal functions (Internal Functions)
• C-language functions (C-Language Functions)
That is overly repetitive and should be simplified.
- "xtypes-toast":
The reference in the CREATE TYPE page becomes:
All storage values other than plain imply that the functions of the data type
can handle values that have been toasted, as described in Section 66.2 and
TOAST Considerations.
That sounds odd. Either do the magic for both references or for none of them.
- "xml2-author":
The label is "Author", see point #1 above.
Suggestions: xml2 Extension Author / Author of xml2
- "xml2-functions":
The label should be "Description of xml2 Functions".
- "xml2-deprecation":
"Deprecatoin Notice" is too little, see #1 above.
The label should be "xml2 Deprecation Notice".
- "xindex-example":
The label is "An Example"; see #1 above.
The label should be "Example for Creating an Operator Class".
- "xfunc-sql":
Perhaps the label should be "SQL-Language Functions".
But then the reference in chapter 5.16 becomes
(See SQL-Language Functions for an explanation of SQL-language functions.)
which is somewhat repetitive and could be improved.
Yours,
Laurenz Albe
