Doc: Add Table of Contents to psql Reference Page

Started by David G. Johnston10 months ago1 messages

david.g.johnston@gmail.com

10 months ago

1 attachment(s)

Hi!

IMO, the psql reference has too many non-standard subsections (and too much
material in each) to strictly conform to our guidelines for application
documentation. It needs a Table of Contents of its own to improve
usability.

Attached.

David J.

Attachments:

v1-0001-doc-add-local-TOC-to-psql-reference-page.patchtext/x-patch; charset=US-ASCII; name=v1-0001-doc-add-local-TOC-to-psql-reference-page.patchDownload

From c419cd7d32f0b60671cfa652c312c889875031bc Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <David.G.Johnston@Gmail.com>
Date: Tue, 25 Mar 2025 23:03:41 -0700
Subject: [PATCH] doc: add local TOC to psql reference page

---
 doc/src/sgml/ref/psql-ref.sgml | 63 ++++++++++++++++++++++++++++------
 1 file changed, 52 insertions(+), 11 deletions(-)

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index f083dba49a..60ba5c6ba7 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -45,7 +45,48 @@ PostgreSQL documentation
     </para>
  </refsect1>
 
- <refsect1 id="r1-app-psql-3">
+ <refsect1 id="app-psql-toc">
+  <title>Table of Contents</title>
+   <itemizedlist>
+    <listitem><para><xref linkend="r1-app-psql-3"/></para></listitem>
+    <listitem><para><xref linkend="app-psql-exitstatus"/></para></listitem>
+    <listitem>
+     <para><xref linkend="app-psql-usage"/></para>
+     <para>
+      <itemizedlist>
+       <listitem><para><xref linkend="r2-app-psql-connecting"/></para></listitem>
+       <listitem><para><xref linkend="r2-app-psql-4"/></para></listitem>
+       <listitem>
+        <para><xref linkend="app-psql-meta-commands"/></para>
+        <para>
+         <itemizedlist>
+          <listitem><para><xref linkend="app-psql-patterns"/></para></listitem>
+         </itemizedlist>
+        </para>
+       </listitem>
+       <listitem>
+        <para><xref linkend="app-psql-advanced"/></para>
+        <para>
+         <itemizedlist>
+          <listitem><para><xref linkend="app-psql-variables"/></para></listitem>
+          <listitem><para><xref linkend="app-psql-interpolation"/></para></listitem>
+          <listitem><para><xref linkend="app-psql-prompting"/></para></listitem>
+          <listitem><para><xref linkend="app-psql-readline"/></para></listitem>
+         </itemizedlist>
+        </para>
+       </listitem>
+      </itemizedlist>
+     </para>
+    </listitem>
+    <listitem><para><xref linkend="app-psql-environment"/></para></listitem>
+    <listitem><para><xref linkend="app-psql-files"/></para></listitem>
+    <listitem><para><xref linkend="app-psql-notes"/></para></listitem>
+    <listitem><para><xref linkend="app-psql-noteswindows"/></para></listitem>
+    <listitem><para><xref linkend="app-psql-examples"/></para></listitem>
+   </itemizedlist>
+ </refsect1>
+
+ <refsect1 id="r1-app-psql-3" xreflabel="Command-Line Options">
   <title>Options</title>
 
   <variablelist>
@@ -623,7 +664,7 @@ EOF
  </refsect1>
 
 
- <refsect1>
+ <refsect1 id="app-psql-exitstatus" xreflabel="Exit Status">
   <title>Exit Status</title>
 
   <para>
@@ -636,10 +677,10 @@ EOF
  </refsect1>
 
 
- <refsect1>
+ <refsect1 id="app-psql-usage" xreflabel="Usage">
   <title>Usage</title>
 
-  <refsect2 id="r2-app-psql-connecting">
+  <refsect2 id="r2-app-psql-connecting" xreflabel="Connecting to a Database">
     <title>Connecting to a Database</title>
 
     <para>
@@ -712,7 +753,7 @@ $ <userinput>psql postgresql://dbmaster:5433/mydb?sslmode=require</userinput>
     </para>
   </refsect2>
 
-  <refsect2 id="r2-app-psql-4">
+  <refsect2 id="r2-app-psql-4" xreflabel="Entering SQL Commands">
     <title>Entering SQL Commands</title>
 
     <para>
@@ -764,7 +805,7 @@ testdb=&gt;
     </para>
   </refsect2>
 
-  <refsect2 id="app-psql-meta-commands">
+  <refsect2 id="app-psql-meta-commands" xreflabel="Meta-Commands">
     <title>Meta-Commands</title>
 
     <para>
@@ -4080,7 +4121,7 @@ select 1\; select 2\; select 3;
   </refsect3>
  </refsect2>
 
- <refsect2>
+ <refsect2 id="app-psql-advanced" xreflabel="Advanced Features">
   <title>Advanced Features</title>
 
    <refsect3 id="app-psql-variables" xreflabel="Variables">
@@ -5076,7 +5117,7 @@ testdb=&gt; \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '
 
    </refsect3>
 
-   <refsect3 id="app-psql-readline">
+   <refsect3 id="app-psql-readline" xreflabel="Command-Line Editing">
     <title>Command-Line Editing</title>
 
    <indexterm>
@@ -5319,7 +5360,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
  </refsect1>
 
 
- <refsect1>
+ <refsect1 id="app-psql-files" xreflabel="Files">
   <title>Files</title>
 
  <variablelist>
@@ -5390,7 +5431,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
  </refsect1>
 
 
- <refsect1>
+ <refsect1 id="app-psql-notes" xreflabel="Notes">
   <title>Notes</title>
 
     <itemizedlist>
@@ -5437,7 +5478,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
  </refsect1>
 
 
- <refsect1>
+ <refsect1 id="app-psql-noteswindows" xreflabel="Notes for Windows Users">
   <title>Notes for Windows Users</title>
 
  <para>
-- 
2.34.1