Re: Patch to document base64 encoding - Mailing list pgsql-hackers

On Thu, 16 Jan 2020 14:41:33 +0100 (CET)
Fabien COELHO <coelho@cri.ensmp.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@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein