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