Guest User

Qwen4 reflections on PostgreSQL documentation guidelines

a guest
Nov 18th, 2026
34
0
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 29.23 KB | Software | 0 0
  1. Go to the postgresql mailing list, read all the threads and provide a list of threads which contain something about styling guidelines
  2.  
  3.  
  4. Qwen4-Max
  5. 23:46
  6.  
  7. Deep Thinking
  8.  
  9. The user is asking me to go to the PostgreSQL mailing list, read all threads, and provide a list of threads about styling guidelines. I don't have browsing/tool access here — there are no tools available in this conversation. So I cannot actually browse the web. I should be honest that I can't access the internet or browse the mailing list archives, and I can't read "all the threads."
  10.  
  11. I should explain the limitation and offer helpful alternatives: point them to the archives (postgresql.org/list/, pgsql-hackers), suggest search terms, mention known relevant threads/topics from memory (with caveats about accuracy), and mention the actual style-related resources: the PostgreSQL source code formatting conventions (pgindent, perltidy, pg_bsd_indent), the documentation style guidelines in the docs (doc/src/sgml/docguide.sgml), the "Message style guidelines" / error message style guidelines in the backend (src/backend/utils/error/elog.c comments? Actually there's "Error message style guidelines" in the docs — src/backend/nls.mk? Let me recall: PostgreSQL documentation has "Error Message Style Guide" in the... Actually there's a section in the source: src/backend/utils/errcodes.txt, and the error message style guidelines are in the PostgreSQL wiki? There's "Error Messages" style guidance in the documentation "Appendix"? Hmm.
  12.  
  13. Known facts:
  14.  
  15. PostgreSQL source formatting: pgindent (src/tools/pgindent), pg_bsd_indent, typedefs.list, perltidy (src/tools/perltidyrc), pgperltidy.
  16. Documentation: doc/src/sgml/docguide.sgml contains documentation style guidance; there's also the PostgreSQL wiki "Documentation Style Guide"? There's a wiki page "Editing documentation"? Not sure.
  17. Error message style guidelines: there's a section in the PostgreSQL docs? I recall "src/backend/utils/error/README"? Hmm, actually the error message style guidelines are in the PostgreSQL source at src/backend/utils/errcodes.txt and there's a comment block in elog.c. Also the wiki page "Error Message Guidelines"? I believe there IS a documented "Error message style guidelines" in the PostgreSQL documentation... Let me think. In PostgreSQL docs, there's "Appendix J. Error Codes"? That's the error codes appendix. There's also a message style guide in the source tree: src/backend/po/... no.
  18. Actually I recall: PostgreSQL has a file src/backend/utils/error/elog.c with comments about message style, and there's a documented guideline in the wiki: "Message Style Guidelines" — hmm. There's also the "NLS" translator guidelines. I should be careful and hedge.
  19.  
  20. Known mailing list threads about style (from memory, may be imprecise):
  21.  
  22. "pgindent run for v12/v13/..." annual threads by Bruce Momjian / Tom Lane.
  23. "pg_bsd_indent" / "Update pg_bsd_indent to version 2.1" (Tom Lane,2019/2020).
  24. "C code formatting" / "Code style" discussions.
  25. "pgperltidy" / "perltidy run" threads.
  26. "Message style guidelines" / "error message style" threads on pgsql-hackers, e.g., "Error message style" discussions, "capitalization of error messages".
  27. "Documentation style" / "SGML vs XML" / "DocBook" threads.
  28. "pgindent and typedefs" threads.
  29. "Formatting of SQL examples in docs".
  30. "pgindent vs clang-format" — there was a thread about using clang-format instead of pgindent (around 2019-2023?). I recall discussions "Use clang-format?" Hmm, there was a thread "pgindent alternative" maybe.
  31. "pg_bsd_indent 2.1.1" etc.
  32. "pgindent run before PG 17 beta1" etc.
  33. "pgindent, and C99 / bool" etc.
  34. "Remove tabs"?
  35. "pgindent and C++ compatibility".
  36. "perltidy version" threads.
  37. "pgperlcritic" — Perl::Critic policies added by Peter Eisentraut around 2018-2020, threads "perlcritic" on pgsql-hackers.
  38. "pgindent for Perl" etc.
  39. "Code formatting rules" / "indentation of switch statements".
  40. "pgindent and pg_bsd_indent build".
  41. Also "pgindent" typedef list updates.
  42. "Message style: 'could not' vs 'failed to'".
  43. "Standardize error messages" / "Error message capitalization".
  44. "make our error messages more consistent".
  45. "pgindent" run threads yearly.
  46. "pgindent" and "pg_bsd_indent" for MSVC.
  47. "Style guide for documentation" maybe.
  48. "pgindent" and "// comments".
  49. "pgindent" and "pg_bsd_indent" for MSVC.
  50. Given I can't verify, I should be honest and not fabricate specific thread titles/URLs/dates. Better approach: explain I can't browse, then give a practical method (search queries on postgresql.org/list/ and archives, marc.info, spinics), plus list known recurring thread topics with hedging, plus point to canonical style docs.
  51.  
  52. I should be concise but useful. Let me offer to help if they paste content or if browsing is enabled.
  53.  
  54. Format: short explanation, then "How to find them yourself" with concrete search terms and archive URLs, then "Known style-related topics/resources" with hedges. Keep moderate length.
  55.  
  56. Note: postgresql.org/list/ is the official archive (uses a web interface powered by... it's "postgresql.org/list/" with search). Also "https://www.postgresql.org/search/?m=1&q=..." for mailing list search. marc.info/?l=pgsql-hackers, spinics.net/lists/pgsql/, mail-archive.com. Also the git repo for style tools.
  57.  
  58. Let me write it.
  59.  
  60. I can't do that in this conversation — I have no browsing or tool access here, so I can't open the PostgreSQL list archives, and I certainly can't read "all the threads" (pgsql-hackers alone has hundreds of thousands of messages across ~30 years). Anything I produced as a "list of threads" would be invented titles and links, which is worse than useless for you.
  61.  
  62. Here's what I can genuinely offer instead.
  63.  
  64. Where to search
  65. Official archives: https://www.postgresql.org/list/pgsql-hackers/ (also pgsql-general, pgsql-docs, pgsql-www — style discussions land in different lists depending on whether it's C code, docs, or website).
  66. Full-text search: https://www.postgresql.org/search/?m=1&q=<terms> restricts to mailing lists.
  67. Mirrors that are sometimes easier to grep: marc.info/?l=pgsql-hackers, spinics.net/lists/pgsql/, mail-archive.com.
  68. Search terms that actually surface style threads
  69. Code formatting: pgindent, pg_bsd_indent, typedefs.list, clang-format, indentation, code style, coding conventions, perltidy, pgperltidy, perlcritic, pgperlcritic
  70.  
  71. Messages/user-facing text: error message style, message style guidelines, capitalization, errmsg, wording, errhint
  72.  
  73. Docs: documentation style, SGML style, DocBook, markup conventions, docguide
  74.  
  75. Website/CSS (if that's what you meant by "styling"): pgsql-www, CSS, stylesheet, site redesign
  76.  
  77. Recurring thread families you'll find
  78. These are patterns I'm confident exist, though I won't guess at exact subjects, dates, or message IDs:
  79.  
  80. Annual pgindent runs before each release's beta — usually posted by Bruce Momjian or Tom Lane, one per major version.
  81. pg_bsd_indent updates — Tom Lane's work on the forked BSD indent, including the 2.x updates and the changes to comment/typedef handling.
  82. perltidy / perlcritic introduction and version bumps — largely Peter Eisentraut, mid-to-late 2010s onward.
  83. Error-message wording and consistency patches, often with side debates about style rules.
  84. Occasional "should we switch to clang-format / a different formatter" discussions.
  85. The authoritative style rules (not mailing list, but likely what you want)
  86. src/tools/pgindent/README and src/tools/pgindent/pgindent in the source tree
  87. src/tools/perltidyrc, src/tools/pgperlcritic*
  88. doc/src/sgml/docguide.sgml — documentation markup and prose conventions
  89. Error-message style guidance lives in comments in src/backend/utils/error/elog.c and in the SGML docs; the wiki has historically carried a message-style page too
  90. If you paste in archive search results, a thread dump, or a month's index, I'll happily read through it and pull out the style-related threads with summaries. And if you can enable a browsing tool, I can do the searching directly.
  91.  
  92. =========================
  93. Browser tool can't be enabled, I'm using the web UI for the agent, so it has to be other way
  94. =========================
  95.  
  96. Do you have the discussions of the postgres documentation mailing list in your memory?
  97.  
  98.  
  99. Qwen4-Max
  100. 23:31
  101.  
  102. Deep Thinking
  103.  
  104. The user asks whether I have the PostgreSQL documentation mailing list discussions in memory. Honest answer: no verbatim archive; training data may include some publicly archived pgsql-docs / pgsql-hackers content, but I can't recall reliably, can't quote verbatim, and could confabulate. Also no browsing tool available here. Offer alternatives: paste archives, or I can help with docs questions from general knowledge with caveats.
  105.  
  106. Keep concise, honest, calibrated.
  107.  
  108. Not in any reliable sense. Let me be precise about what I do and don't have:
  109.  
  110. What I might have: the pgsql-docs and pgsql-hackers lists are publicly archived (postgresql.org/list/, plus mirrors like postgresql.org/message-id/ and marc.info), so some of that text was likely in my training data. That can leave me with a vague sense of recurring themes — e.g. long-running debates about wording in the docs, or how a particular feature's description got reworked.
  111.  
  112. What I don't have: a searchable archive. I can't look up a thread by date, subject, or message-ID, can't tell you who said what, and can't quote a message verbatim with any confidence. If I tried, I'd be reconstructing plausible-sounding text rather than recalling actual posts — which is exactly the failure mode you don't want for something as citable as a mailing list discussion. I also have a training cutoff, so anything recent is simply absent.
  113.  
  114. And since no browsing tool is attached here, I can't go check the archives either.
  115.  
  116. Practical options:
  117.  
  118. Paste the thread or message text and I'll analyze, summarize, or argue with it.
  119. Tell me the documentation question underneath, and I'll answer from general PostgreSQL knowledge — flagging where I'm unsure and where the answer is version-dependent.
  120. If you want the actual discussion, searching the archives directly for site:postgresql.org/message-id/ <your terms> tends to work well.
  121. What are you trying to find out? There may be a faster route than the list archives.
  122.  
  123.  
  124.  
  125.  
  126.  
  127. Message Length: 310
  128. First Frame:
  129. 2,469ms
  130. Last Frame:
  131. 12,021ms
  132. Input tokens: 815
  133. Output tokens: 432
  134. I'm trying to find a summary of documentation formatting and writing guidelines for postgres. From your memory about the postgres documentation and discussions in the documentation mailing list, can you construct thos guidelines?
  135.  
  136.  
  137. Qwen4-Max
  138. 23:36
  139.  
  140. Deep Thinking
  141.  
  142. The user wants a summary of PostgreSQL documentation formatting and writing guidelines, reconstructed from memory. I should be honest about provenance: much of this is genuinely observable from the docs themselves (which are heavily represented in training data), plus the doc/src/sgml/README and the "Documentation" section of the wiki, and recurring pgsql-docs themes. But I should not fabricate specific mailing list quotes or attribute rules to specific threads.
  143.  
  144. Let me actually construct a useful, accurate set of guidelines. What do I actually know about PostgreSQL documentation conventions?
  145.  
  146. Sources of these conventions:
  147.  
  148. doc/src/sgml/README in the source tree — has notes on DocBook usage.
  149. The PostgreSQL wiki "Documentation" page and "Editing the documentation" / "DocBook" guidance.
  150. Peter Eisentraut's work converting from SGML to XML (PG 10-ish, docs moved to DocBook XML, XSLT toolchain).
  151. The docs themselves demonstrate conventions consistently.
  152. Key technical facts I'm reasonably confident about:
  153.  
  154. Docs are written in DocBook XML (since PG 10; before that SGML). Source in doc/src/sgml/*.sgml (file extension retained .sgml even after XML conversion).
  155. Build requires xsltproc, DocBook XSL stylesheets, and for PDF: FOP (Apache FOP) — historically JadeTeX/OpenJade, then switched to FOP. HTML build: make html, and there's a "docs" target. Actually in the meson build (PG 16+) there's docs support too.
  156. IDs: lowercase, hyphen-separated, e.g. id="sql-select", id="functions-string". Reference pages have id like sql-select.
  157. Element usage: <command>, <function>, <literal>, <varname>, <option>, <parameter>, <filename>, <structname>, <type>, <classname>, <symbol>, <token>, <replaceable>, <productname>, <application>, <quote>, <firstterm>, <acronym>, <prompt>, <computeroutput>, <userinput>, <programlisting>, <screen>, <informaltable>/<table>, <variablelist>, <itemizedlist>, <orderedlist>, <note>, <tip>, <caution>, <warning>, <important>, <sect1>/<sect2>, <refentry>, <refnamediv>, <refsynopsisdiv>, <refsect1>, <indexterm>, <xref linkend=""/>, <link linkend=""/>.
  158. <xref> vs <link>: xref generates the target's title/label automatically; link lets you supply text. Convention: prefer xref when referring to a whole section; use link with explicit text when needed. Avoid "see here" style.
  159. Indexing: <indexterm><primary>...</primary><secondary>...</secondary></indexterm>, significant terms indexed; there's a convention to index at the point of definition.
  160. Reference page structure for SQL commands: Name, Synopsis (<refsynopsisdiv>), Description, Parameters, Notes, Examples, Compatibility, See Also. Some have "Outputs", "Bugs" (historical). For client apps: Synopsis, Description, Options, Environment, Files, Diagnostics, Notes, Examples, See Also.
  161. <synopsis> with <command>, <option choice="opt">, <replaceable class="parameter">, repeatable via ....
  162. SQL keywords uppercase in synopsis and in prose? Actually PostgreSQL docs convention: SQL keywords are uppercase in synopses; in examples, keywords are typically uppercase... Hmm. Let me think. In the PG docs, examples often use uppercase SELECT, FROM, WHERE. Yes, e.g. SELECT * FROM pg_class;. But newer docs sometimes lowercase. The convention historically: keywords uppercase in examples. Actually there's a mix. I recall the docs use uppercase SQL keywords in most examples. I should flag this as "predominantly uppercase, though inconsistent" — honest.
  163. Function names in prose written as foo() with parentheses, marked up <function>foo()</function> — actually convention is <function>foo</function> with parentheses outside? I recall <function>lower</function> and text like <function>lower(string)</function>. Hmm. There's a known convention: use <function>name</function> and put arguments in <parameter> or <replaceable>. I'm not certain enough; I should hedge or omit fine detail.
  164. American English spelling (e.g., "behavior", "initialize"). Yes, PG docs use US spelling.
  165. Serial comma? PG docs tend to use "a, b, and c" — I believe yes, Oxford comma is common. Hedge.
  166. Avoid first person ("we"), avoid "you" in some contexts? Actually PG docs do use "you" occasionally but prefer impersonal constructions. Historically the docs avoided "you" heavily; Tom Lane and others have pushed toward more direct style. I recall guidance "avoid the use of the first person" and prefer present tense.
  167. Present tense, indicative; avoid future tense ("will") — use present ("returns", "creates").
  168. Avoid "please", avoid marketing language, avoid "simply", "just", "easy", "obviously".
  169. Terminology consistency: "PostgreSQL" never "Postgres" in docs (though Postgres is acceptable informally / the project rebranded to allow "Postgres"). In docs, always PostgreSQL. Version references: "PostgreSQL 16" not "v16"? Docs use e.g. "PostgreSQL 9.6 and later".
  170. "server" vs "postmaster"; "database cluster" not "database installation"/"instance" — there's a known convention to use "database cluster" for the collection of databases managed by one server instance, and to avoid "instance" ambiguity.
  171. "role" vs "user": prefer "role", use "user" when specifically about login roles.
  172. "superuser", "unprivileged user".
  173. GUC parameters referred to as "configuration parameter", marked <varname>, and linked to runtime-config sections.
  174. Notes about version: use "Before PostgreSQL X" / "In PostgreSQL X and later" rather than "currently"/"now"/"new in this release" — because docs live on. This is a real convention: avoid time-relative wording.
  175. Compatibility section: SQL standard conformance, note extensions.
  176. Cross-reference to SQL standard: "SQL:2016" etc.- Examples should be runnable, self-contained, use realistic but simple data; psql transcripts in <screen> with prompt.
  177. Tables: prefer <table> with title for reference tables; <informaltable> for layout without title.
  178. Line wrapping: source wrapped at ~78 columns? I believe the SGML files wrap around 78-80 chars. Hedge slightly.
  179. Indentation: one space per level in SGML? I recall PG SGML uses one-space indentation increments. Yes! The doc source uses a distinctive style with single-space indentation. I'm fairly confident: e.g.
  180. <sect1 id="...">
  181. <title>...</title>
  182. <para>
  183. ...
  184. </para>
  185. </sect1>
  186. That's a real PG convention. Good detail but flag moderate confidence.
  187.  
  188. No tabs; trailing whitespace avoided.
  189. <para> wrapping, <literal> for values, <quote> for quoted text.
  190. Whitespace inside inline elements matters — avoid stray spaces inside tags because it produces bad output spacing.
  191. Comments <!-- ... -->.
  192. Patches: submit as unified diff to [email protected], or via Commitfest; docs patches welcome, "documentation patches are a great way to start contributing".
  193. Build validation: make check in doc/src/sgml? There is make check for docs that validates XML. Yes — doc/src/sgml has a check target that runs xmllint validation. Also make docs builds HTML+PDF? Historically make html, make postgres.pdf... Let me hedge: "there's a validation target (xmllint-based) and HTML build".
  194. Toolchain: xsltproc, docbook-xsl, docbook-xml (4.5? DocBook XML 4.5), fop for PDF.
  195. Since PG 10 the docs are XML with .sgml extension retained.
  196. Also: the docs use <productname>PostgreSQL</productname> and <acronym>SQL</acronym>? Hmm, <acronym> used for e.g. MVCC, WAL. And <firstterm> for first use of a term.
  197. <systemitem class="username">, <systemitem class="osname">, <systemitem class="library">, <systemitem class="resource">.
  198. <envar> for environment variables, <errorcode>/<errortext> for SQLSTATE, <returnvalue>.
  199. <citetitle> for external references, <ulink url=""> (DocBook 4) — after XML conversion still <ulink>? DocBook 5 uses <link xlink:href>. PG uses DocBook 4.5 XML I believe, so <ulink url="..."> remains. Hedge.
  200. <email>, <author>.
  201. Bibliography <bibliolist>? There's a "Bibliography" appendix with <biblioentry>.
  202. Style: "e.g." and "i.e." usage; docs prefer spelled-out? Not sure, skip.
  203. Titles: sentence case? PG section titles use title case mostly ("Query Planning", "Populating a Database", "Continuous Archiving and Point-in-Time Recovery (PITR)"). Mixed. Reference page titles are the command name. Chapter titles often title case. Hedge: "chapter/section titles are generally title-ish case; be consistent with neighbors."
  204. Avoid contractions.
  205. Numbers: spell out small numbers? Skip.
  206. "cannot" vs "can not": prefer cannot.
  207. Use of <note> for ancillary info, <caution>/<warning> for data-loss risks.
  208. Man page output: refentry generates man pages, so keep refentry structure valid; <refmiscinfo class="manual"> etc. Actually PG refentries include <refmiscinfo class="source">PostgreSQL</refmiscinfo> and <refmiscinfo class="manual">PostgreSQL Documentation</refmiscinfo>. Hmm, I think there's <refmeta><refentrytitle><application>psql</application></refentrytitle><manvolnum>1</manvolnum><refmiscinfo class="source">PostgreSQL</refmiscinfo><refmiscinfo class="version">17</refmiscinfo><refmiscinfo class="manual">PostgreSQL Documentation</refmiscinfo></refmeta>. Reasonably confident about manvolnum 1 for apps, 7 for SQL commands? SQL commands are man section... I think SQL commands use <manvolnum>7</manvolnum>? Hmm, actually PG SQL command man pages are in section 7? Let me think: man SELECT — I believe PostgreSQL installs SQL command man pages in section 7 (e.g., SELECT(7)). Yes, I'm fairly confident: psql(1), SELECT(7). Good but hedge lightly.
  209. Mailing list recurring themes (I should present as "recurring themes I recall, not verifiable quotes"):
  210.  
  211. Debates over "should docs say 'we recommend'" / tone.
  212. Tom Lane's insistence on precision and avoiding overpromising behavior.
  213. Preference for describing behavior rather than implementation internals in user docs.
  214. Arguments about whether to document undocumented behavior (if it's not guaranteed, don't imply it is).
  215. Peter Eisentraut's markup consistency cleanups, and the SGML→XML migration.
  216. Alvaro Herrera, Bruce Momjian doing docs commits.
  217. "Don't document it as a guarantee unless we're willing to keep it" — backward-compat concerns.
  218. Requests to avoid version-specific "new" markers that rot.
  219. Discussion about whether examples should use \d output etc.
  220. The "docs are not the place for tutorials on SQL itself" boundary.
  221. Debates about "cluster" terminology confusing users vs cloud "cluster".
  222. Whether to use "master"/"slave" → replaced with "primary"/"standby" (PG 14-ish? Actually the change from "master" to "primary" in docs happened around PG 14/15; also "slave" → "standby"). There was a real effort. Also master in wal_level etc. Hmm, synchronous_standby_names always used standby. The "master/slave" → "primary/standby" doc change: yes, there was a commit by... I think it happened. Flag moderate.
  223. Also "whitelist/blacklist" → "allowlist/blocklist"? Less sure. Skip or hedge.
  224. I should be honest that I can't verify these against the archives and that the authoritative sources are doc/src/sgml/README, the wiki, and the docs themselves. And I should mark confidence levels rather than presenting everything as canon.
  225.  
  226. Format: This warrants a decent-length structured answer with headers, since it's a reference-style request. But I should keep it tight and useful, not bloated. Use a confidence framing up front, then sections: sources of truth, toolchain/structure, markup conventions, prose style, terminology, reference page structure, examples, process, and a short "uncertain" list. Maybe combine.
  227.  
  228. Let me aim for something thorough but scannable — maybe 700-1000 words equivalent with code snippets. Actually given it's a guidelines summary, moderately long is appropriate. Let me not overdo it.
  229.  
  230. I'll add a clear caveat at top: this is reconstructed from the docs' observable conventions + general knowledge of the project's practices, NOT from retrieved list archives; treat as a working checklist to verify against doc/src/sgml/README and the wiki.
  231.  
  232. Let me write it.
  233.  
  234. I should be careful about a few specifics I'm shaky on and either omit or explicitly flag:
  235.  
  236. exact indentation (1 space) — fairly confident, include with note
  237. manvolnum — include lightly
  238. <function> parens convention — flag as uncertain
  239. SQL keyword case — note inconsistency
  240. DocBook version 4.5 — fairly confident
  241. make check in doc dir — reasonably confident there's a validation target
  242. I'll put genuinely uncertain items in a short list at the end rather than sprinkling hedges everywhere, but hedge inline where it matters.
  243.  
  244. Also worth noting: no formal style guide document exists in the tree as far as I know — conventions are largely oral tradition / enforced in review. That's an important honest point and matches the user's interest in list discussions.
  245.  
  246. Happy to — with one important caveat about provenance.
  247.  
  248. What this is: a reconstruction from the observable conventions of the PostgreSQL docs themselves (which are heavily represented in my training data), plus general knowledge of the project's practices. What it isn't: a summary of actual pgsql-docs threads. I can't cite messages, and I'd be inventing them if I tried. Notably, I don't believe there's a single canonical style-guide file in the tree — much of this is oral tradition enforced in review, which is probably why you went looking for list discussions in the first place.
  249.  
  250. Treat the below as a working checklist to verify against doc/src/sgml/README, the PostgreSQL wiki's documentation pages, and neighbouring sections of whatever file you're editing. The last of those is the most reliable guide by far.
  251.  
  252. Source format and toolchain
  253. DocBook XML since PG 10 (SGML before that). Files keep the .sgml extension in doc/src/sgml/ despite being XML — don't "fix" this.
  254. DocBook 4.5 vocabulary, transformed with xsltproc + DocBook XSL stylesheets; PDF via Apache FOP.
  255. There's an XML-validation target in the doc directory; run it before submitting. Broken nesting or stray & will fail the build.
  256. Source is hard-wrapped (~78 cols), no tabs. Indentation is the distinctive one space per level:
  257. <sect1 id="sql-select">
  258. <title>SELECT</title>
  259. <para>
  260. ...
  261. </para>
  262. </sect1>
  263. IDs are lowercase and hyphenated, prefixed by area: sql-select, functions-string, runtime-config-query.
  264. Markup: use semantic tags, not visual ones
  265. The core habit is tagging what a thing is, never how it should look.
  266.  
  267. Table
  268. Thing Element
  269. SQL command / shell command
  270. <command>
  271. Function
  272. <function>
  273. Literal value, keyword in prose
  274. <literal>
  275. Config parameter, variable
  276. <varname>
  277. Command-line flag
  278. <option>
  279. Placeholder the user replaces
  280. <replaceable>
  281. Data type
  282. <type>
  283. Table/column identifier
  284. <structname>, <structfield>
  285. File, directory
  286. <filename>
  287. Environment variable
  288. <envar>
  289. Error code / text
  290. <errorcode>, <errortext>
  291. Program output block
  292. <screen> / <programlisting>
  293. First use of a defined term
  294. <firstterm>
  295. Acronym
  296. <acronym>
  297. Other conventions:
  298.  
  299. <xref linkend="..."/> when referring to a section as a whole (it auto-generates the title); <link linkend="...">text</link> when you need your own wording. Never "click here".
  300. Index significant terms with <indexterm><primary>…</primary><secondary>…</secondary></indexterm> at the point where the term is actually explained, not every mention.
  301. Admonitions have distinct meanings: <note> for ancillary info, <tip> for advice, <caution>/<warning> for risk of data loss or breakage. Don't use <note> as a generic emphasis box.
  302. <variablelist> for parameter/option descriptions; <table> (with title) for reference tables, <informaltable> for untitled ones.
  303. Watch whitespace inside inline elements — a stray space or newline inside <literal> shows up in rendered output.
  304. Prose style
  305. American English spelling: behavior, initialize, catalog.
  306. Present tense, indicative. "The function returns…", not "will return".
  307. Impersonal voice preferred. Avoid "we"; "you" is used but sparingly. Avoid "please".
  308. No contractions. No marketing or editorialising: cut simply, just, easily, obviously, powerful, seamless.
  309. Precision over reassurance. Don't imply a guarantee the project isn't prepared to keep — describe observed behaviour, and say explicitly when something is unspecified or implementation-dependent. This is the theme I'd most expect to find dominating pgsql-docs review, and it's the one worth internalising.
  310. Avoid time-relative wording. Not "currently", "now", "new in this release" — the docs outlive the release. Write "In PostgreSQL 16 and later" / "Before PostgreSQL 16".
  311. User-facing docs describe behaviour, not internals. Internals belong in the source READMEs or the internals part of the docs.
  312. The docs are not an SQL tutorial. Assume SQL literacy; explain PostgreSQL's specifics.
  313. Terminology
  314. PostgreSQL in the docs, always — not "Postgres", not "PostGreSQL".
  315. database cluster for the collection of databases served by one instance; avoid bare "instance" and "installation" for this, since they're ambiguous.
  316. role generally; user only when specifically meaning a role with LOGIN.
  317. primary / standby, not master/slave.
  318. configuration parameter for GUCs, linked to the relevant runtime-config section.
  319. Be consistent with the term already used in the surrounding chapter rather than introducing a synonym.
  320. Reference page structure
  321. SQL commands (refentry, man section 7):
  322.  
  323. Name → Synopsis → Description → Parameters → Notes → Examples → Compatibility → See Also
  324.  
  325. Client/server applications (man section 1):
  326.  
  327. Name → Synopsis → Description → Options → Environment → Files → Diagnostics → Notes → Examples → See Also
  328.  
  329. Synopsis uses <synopsis> with <option choice="opt"> for optional parts and ... for repeatable ones.
  330. Compatibility documents conformance to the SQL standard and names PostgreSQL extensions as such. Don't leave it out for a standard command.
  331. Keep refentry structure valid — it's what generates the man pages.
  332. Examples
  333. Runnable and self-contained: create the table, insert the data, then show the query.
  334. Show realistic output, including psql transcripts in <screen> where the output format matters.
  335. Simple and minimal — illustrate one point, not five.
  336. SQL keywords are predominantly uppercase in examples, though the corpus is genuinely inconsistent here; match the file you're in.
  337. Submitting
  338. Unified diff against git master, to [email protected] (or pgsql-hackers for substantive/structural changes), and register it in the Commitfest so it isn't lost.
  339. Small, single-purpose patches review far faster than sweeping rewrites.
  340. Docs patches are explicitly welcomed as an entry point for new contributors.
  341. Things I'm genuinely unsure about
  342. Flagging rather than guessing: whether <function> should enclose the parentheses or just the name; the exact <refmiscinfo> fields expected in refmeta; whether Oxford commas are house style; the precise wrap column; and the current state of PDF-build requirements. Check these against existing files.
  343.  
  344. If you paste doc/src/sgml/README or a representative .sgml file, I can turn this into something verified rather than reconstructed — and tighten it to the conventions actually in force.
Advertisement
Add Comment
Please, Sign In to add comment