doc: fast access to server parameters

Started by Euler Taveira7 days ago1 messageshackers
Jump to latest
#1Euler Taveira
euler@eulerto.com

Hi,

If you want to check a GUC description, you access the "Server Configuration"
chapter and then need to figure out what is the exact section. Sometimes you
need a back-and-forth until find the exact GUC. You can click on the section
19.X and then browse to find the GUC. I was wondering if there is a better (and
fast) way to find a GUC. I experimented 2 approaches (see screenshots): (a) add
the GUCs to the "Reference" part and (b) add an appendix with all GUCs. The
idea is a page that list all GUCs in alphabetic order with a link that points
to the detailed description into "Server Configuration" chapter.

The natural choice is "Reference" part because it is more-or-less the proposal:
list of GUCs with links. However, the structure of it requires one HTML/man
page per GUC (even if you suppress the man generation, it would add 424 chunked
HTML files, each containing a single link to the detailed description). That's
an unavoidable cost of putting the GUC in the "Reference" ToC and that's why I
tried the option (b) whose approach is a list in a single page.

I thought about converting the "Server Configuration" chapter into a
"Reference" part. The 2 main cons are (a) increase the number of HTML/man files
(+400) and (b) each section may contain additional contents (before and after
the detailed GUC description) that apply to a set of GUCs.

I'm attaching option (b) that adds a new Appendix page ("PostgreSQL
Parameters"). It serves as a list of all GUCs with link directly to the
detailed description into "Server Configuration" chapter. The list is generated
at build time using a Perl script that avoids maintenance cost. I added this
new page as the first item in the Appendix mainly because of its importance.

--
Euler Taveira
EDB https://www.enterprisedb.com/

Attachments:

reference-1.pngimage/png; name=reference-1.pngDownload
reference-2.pngimage/png; name=reference-2.pngDownload
appendix.pngimage/png; name=appendix.pngDownload+1-0
v1-0001-Add-an-appendix-listing-the-configuration-paramet.patchtext/x-patch; name="=?UTF-8?Q?v1-0001-Add-an-appendix-listing-the-configuration-paramet.patc?= =?UTF-8?Q?h?="Download+79-2