Re: Patch to document base64 encoding

On Thu, 16 Jan 2020 14:41:33 +0100 (CET)
Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> wrote:

> The "Binary String Functions and Operators" 9.5 section has only one
> subsection, "9.5.1", which is about at two thirds of the page. This
> structure looks weird. ISTM that a subsection is missing for the
> beginning of the page, or that the subsection should just be dropped,
> because it is somehow redundant with the table title.
>
> The "9.4" section has the same structural weirdness. Either remove
> the subsection, or add some for the other parts?

Hi Fabien,

cc-ing the folks who did the work on format(), who added a sub-section
9.4.1. The whole thread for that is here:
https://www.postgresql.org/message-id/flat/CAFj8pRBjMdAjybSZkczyez0x%3DFhC8WXvgR2wOYGuhrk1TUkraA%40mail.gmail.com

I'm going to dis-agree with you on this. Yes, it's a little odd
to have only a single sub-section but it does not really bother me.

If there's a big/important enough chunk of information to present I like
seeing something in the table of contents. That's the "big thing"
to my mind.

I don't see a good way to get rid of "9.4.1. format". Adding
another sub-section heading above it just to have 2 seems
pointless.

I really want the "9.5.1 String to Binary and Binary to String
Conversion" to show up in the table of contents. Because it
is not at all obvious that "9.5. Binary String Functions and
Operators" is the place to look for conversions between
string and binary. Tom thought that merely having a separate
table for string<->binary functions "could be overkill"
so my impression right now is that having an entirely
separate section for these would be rejected.
(See: https://www.postgresql.org/message-id/22540.1564501203@sss.pgh.pa.us)

Otherwise an entirely separate section might be the right approach.

The following *.1 sections
in the (devel version) documentation are "single sub-sections":

(Er, this is too much but once I started I figured I'd finish.)

5.10. Inheritance
5.10.1. Caveats
9.4. String Functions and Operators
9.4.1. format
9.30. Statistics Information Functions
9.30.1. Inspecting MCV Lists
15.4. Parallel Safety
15.4.1. Parallel Labeling for Functions and Aggregates
17. Installation from Source Code on Windows
17.1. Building with Visual C++ or the Microsoft Windows SDK
18.10. Secure TCP/IP Connections with GSSAPI Encryption
18.10.1. Basic Setup
30.2. Subscription
30.2.1. Replication Slot Management
30.5. Architecture
30.5.1. Initial Snapshot
37.13. User-Defined Types
37.13.1. TOAST Considerations
41. Procedural Languages
41.1. Installing Procedural Languages
50.5. Planner/Optimizer
50.5.1. Generating Possible Plans
52.3. SASL Authentication
52.3.1. SCRAM-SHA-256 Authentication
57. Writing a Table Sampling Method
57.1. Sampling Method Support Functions
58.1. Creating Custom Scan Paths
58.1.1. Custom Scan Path Callbacks
58.2. Creating Custom Scan Plans
58.2.1. Custom Scan Plan Callbacks
58.3. Executing Custom Scans
58.3.1. Custom Scan Execution Callbacks
64.4. Implementation
64.4.1. GiST Buffering Build
67.1. Introduction
67.1.1. Index Maintenance
68.6. Database Page Layout
68.6.1. Table Row Layout
G.2. Server Applications
pg_standby — supports the creation of a PostgreSQL warm standby server
I. The Source Code Repository
I.1. Getting the Source via Git
J.4. Documentation Authoring
J.4.1. Emacs
J.5. Style Guide
J.5.1. Reference Pages

I like that I can see these in the documentation.

FYI, the format sub-section, 9.4.1, was first mentioned
by Dean Rasheed in this email:
https://www.postgresql.org/message-id/CAEZATCWLtRi-Vbh5k_2fYkOAPxas0wZh6a0brOohHtVOtHiddA%40mail.gmail.com

"I'm thinking perhaps
format() should now have its own separate sub-section in the manual,
rather than trying to cram it's docs into a single table row."

There was never really any further discussion or objection to
having a separate sub-section.

Attaching a new patch to my next email, leaving off the
folks cc-ed regarding "9.4.1 format".

Regards,

Karl <kop(at)karlpinc(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein