Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- Go to the postgresql mailing list, read all the threads and provide a list of threads which contain something about styling guidelines
- Qwen4-Max
- 23:46
- Deep Thinking
- 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."
- 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.
- Known facts:
- PostgreSQL source formatting: pgindent (src/tools/pgindent), pg_bsd_indent, typedefs.list, perltidy (src/tools/perltidyrc), pgperltidy.
- 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.
- 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.
- 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.
- Known mailing list threads about style (from memory, may be imprecise):
- "pgindent run for v12/v13/..." annual threads by Bruce Momjian / Tom Lane.
- "pg_bsd_indent" / "Update pg_bsd_indent to version 2.1" (Tom Lane,2019/2020).
- "C code formatting" / "Code style" discussions.
- "pgperltidy" / "perltidy run" threads.
- "Message style guidelines" / "error message style" threads on pgsql-hackers, e.g., "Error message style" discussions, "capitalization of error messages".
- "Documentation style" / "SGML vs XML" / "DocBook" threads.
- "pgindent and typedefs" threads.
- "Formatting of SQL examples in docs".
- "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.
- "pg_bsd_indent 2.1.1" etc.
- "pgindent run before PG 17 beta1" etc.
- "pgindent, and C99 / bool" etc.
- "Remove tabs"?
- "pgindent and C++ compatibility".
- "perltidy version" threads.
- "pgperlcritic" — Perl::Critic policies added by Peter Eisentraut around 2018-2020, threads "perlcritic" on pgsql-hackers.
- "pgindent for Perl" etc.
- "Code formatting rules" / "indentation of switch statements".
- "pgindent and pg_bsd_indent build".
- Also "pgindent" typedef list updates.
- "Message style: 'could not' vs 'failed to'".
- "Standardize error messages" / "Error message capitalization".
- "make our error messages more consistent".
- "pgindent" run threads yearly.
- "pgindent" and "pg_bsd_indent" for MSVC.
- "Style guide for documentation" maybe.
- "pgindent" and "// comments".
- "pgindent" and "pg_bsd_indent" for MSVC.
- 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.
- I should be concise but useful. Let me offer to help if they paste content or if browsing is enabled.
- 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.
- 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.
- Let me write it.
- 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.
- Here's what I can genuinely offer instead.
- Where to search
- 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).
- Full-text search: https://www.postgresql.org/search/?m=1&q=<terms> restricts to mailing lists.
- Mirrors that are sometimes easier to grep: marc.info/?l=pgsql-hackers, spinics.net/lists/pgsql/, mail-archive.com.
- Search terms that actually surface style threads
- Code formatting: pgindent, pg_bsd_indent, typedefs.list, clang-format, indentation, code style, coding conventions, perltidy, pgperltidy, perlcritic, pgperlcritic
- Messages/user-facing text: error message style, message style guidelines, capitalization, errmsg, wording, errhint
- Docs: documentation style, SGML style, DocBook, markup conventions, docguide
- Website/CSS (if that's what you meant by "styling"): pgsql-www, CSS, stylesheet, site redesign
- Recurring thread families you'll find
- These are patterns I'm confident exist, though I won't guess at exact subjects, dates, or message IDs:
- Annual pgindent runs before each release's beta — usually posted by Bruce Momjian or Tom Lane, one per major version.
- 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.
- perltidy / perlcritic introduction and version bumps — largely Peter Eisentraut, mid-to-late 2010s onward.
- Error-message wording and consistency patches, often with side debates about style rules.
- Occasional "should we switch to clang-format / a different formatter" discussions.
- The authoritative style rules (not mailing list, but likely what you want)
- src/tools/pgindent/README and src/tools/pgindent/pgindent in the source tree
- src/tools/perltidyrc, src/tools/pgperlcritic*
- doc/src/sgml/docguide.sgml — documentation markup and prose conventions
- 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
- 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.
- =========================
- Browser tool can't be enabled, I'm using the web UI for the agent, so it has to be other way
- =========================
- Do you have the discussions of the postgres documentation mailing list in your memory?
- Qwen4-Max
- 23:31
- Deep Thinking
- 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.
- Keep concise, honest, calibrated.
- Not in any reliable sense. Let me be precise about what I do and don't have:
- 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.
- 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.
- And since no browsing tool is attached here, I can't go check the archives either.
- Practical options:
- Paste the thread or message text and I'll analyze, summarize, or argue with it.
- 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.
- If you want the actual discussion, searching the archives directly for site:postgresql.org/message-id/ <your terms> tends to work well.
- What are you trying to find out? There may be a faster route than the list archives.
- Message Length: 310
- First Frame:
- 2,469ms
- Last Frame:
- 12,021ms
- Input tokens: 815
- Output tokens: 432
- 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?
- Qwen4-Max
- 23:36
- Deep Thinking
- 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.
- Let me actually construct a useful, accurate set of guidelines. What do I actually know about PostgreSQL documentation conventions?
- Sources of these conventions:
- doc/src/sgml/README in the source tree — has notes on DocBook usage.
- The PostgreSQL wiki "Documentation" page and "Editing the documentation" / "DocBook" guidance.
- Peter Eisentraut's work converting from SGML to XML (PG 10-ish, docs moved to DocBook XML, XSLT toolchain).
- The docs themselves demonstrate conventions consistently.
- Key technical facts I'm reasonably confident about:
- 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).
- 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.
- IDs: lowercase, hyphen-separated, e.g. id="sql-select", id="functions-string". Reference pages have id like sql-select.
- 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=""/>.
- <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.
- Indexing: <indexterm><primary>...</primary><secondary>...</secondary></indexterm>, significant terms indexed; there's a convention to index at the point of definition.
- 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.
- <synopsis> with <command>, <option choice="opt">, <replaceable class="parameter">, repeatable via ....
- 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.
- 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.
- American English spelling (e.g., "behavior", "initialize"). Yes, PG docs use US spelling.
- Serial comma? PG docs tend to use "a, b, and c" — I believe yes, Oxford comma is common. Hedge.
- 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.
- Present tense, indicative; avoid future tense ("will") — use present ("returns", "creates").
- Avoid "please", avoid marketing language, avoid "simply", "just", "easy", "obviously".
- 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".
- "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.
- "role" vs "user": prefer "role", use "user" when specifically about login roles.
- "superuser", "unprivileged user".
- GUC parameters referred to as "configuration parameter", marked <varname>, and linked to runtime-config sections.
- 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.
- Compatibility section: SQL standard conformance, note extensions.
- 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.
- Tables: prefer <table> with title for reference tables; <informaltable> for layout without title.
- Line wrapping: source wrapped at ~78 columns? I believe the SGML files wrap around 78-80 chars. Hedge slightly.
- 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.
- <sect1 id="...">
- <title>...</title>
- <para>
- ...
- </para>
- </sect1>
- That's a real PG convention. Good detail but flag moderate confidence.
- No tabs; trailing whitespace avoided.
- <para> wrapping, <literal> for values, <quote> for quoted text.
- Whitespace inside inline elements matters — avoid stray spaces inside tags because it produces bad output spacing.
- Comments <!-- ... -->.
- Patches: submit as unified diff to [email protected], or via Commitfest; docs patches welcome, "documentation patches are a great way to start contributing".
- 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".
- Toolchain: xsltproc, docbook-xsl, docbook-xml (4.5? DocBook XML 4.5), fop for PDF.
- Since PG 10 the docs are XML with .sgml extension retained.
- 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.
- <systemitem class="username">, <systemitem class="osname">, <systemitem class="library">, <systemitem class="resource">.
- <envar> for environment variables, <errorcode>/<errortext> for SQLSTATE, <returnvalue>.
- <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.
- <email>, <author>.
- Bibliography <bibliolist>? There's a "Bibliography" appendix with <biblioentry>.
- Style: "e.g." and "i.e." usage; docs prefer spelled-out? Not sure, skip.
- 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."
- Avoid contractions.
- Numbers: spell out small numbers? Skip.
- "cannot" vs "can not": prefer cannot.
- Use of <note> for ancillary info, <caution>/<warning> for data-loss risks.
- 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.
- Mailing list recurring themes (I should present as "recurring themes I recall, not verifiable quotes"):
- Debates over "should docs say 'we recommend'" / tone.
- Tom Lane's insistence on precision and avoiding overpromising behavior.
- Preference for describing behavior rather than implementation internals in user docs.
- Arguments about whether to document undocumented behavior (if it's not guaranteed, don't imply it is).
- Peter Eisentraut's markup consistency cleanups, and the SGML→XML migration.
- Alvaro Herrera, Bruce Momjian doing docs commits.
- "Don't document it as a guarantee unless we're willing to keep it" — backward-compat concerns.
- Requests to avoid version-specific "new" markers that rot.
- Discussion about whether examples should use \d output etc.
- The "docs are not the place for tutorials on SQL itself" boundary.
- Debates about "cluster" terminology confusing users vs cloud "cluster".
- 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.
- Also "whitelist/blacklist" → "allowlist/blocklist"? Less sure. Skip or hedge.
- 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.
- 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.
- 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.
- 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.
- Let me write it.
- I should be careful about a few specifics I'm shaky on and either omit or explicitly flag:
- exact indentation (1 space) — fairly confident, include with note
- manvolnum — include lightly
- <function> parens convention — flag as uncertain
- SQL keyword case — note inconsistency
- DocBook version 4.5 — fairly confident
- make check in doc dir — reasonably confident there's a validation target
- I'll put genuinely uncertain items in a short list at the end rather than sprinkling hedges everywhere, but hedge inline where it matters.
- 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.
- Happy to — with one important caveat about provenance.
- 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.
- 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.
- Source format and toolchain
- DocBook XML since PG 10 (SGML before that). Files keep the .sgml extension in doc/src/sgml/ despite being XML — don't "fix" this.
- DocBook 4.5 vocabulary, transformed with xsltproc + DocBook XSL stylesheets; PDF via Apache FOP.
- There's an XML-validation target in the doc directory; run it before submitting. Broken nesting or stray & will fail the build.
- Source is hard-wrapped (~78 cols), no tabs. Indentation is the distinctive one space per level:
- <sect1 id="sql-select">
- <title>SELECT</title>
- <para>
- ...
- </para>
- </sect1>
- IDs are lowercase and hyphenated, prefixed by area: sql-select, functions-string, runtime-config-query.
- Markup: use semantic tags, not visual ones
- The core habit is tagging what a thing is, never how it should look.
- Table
- Thing Element
- SQL command / shell command
- <command>
- Function
- <function>
- Literal value, keyword in prose
- <literal>
- Config parameter, variable
- <varname>
- Command-line flag
- <option>
- Placeholder the user replaces
- <replaceable>
- Data type
- <type>
- Table/column identifier
- <structname>, <structfield>
- File, directory
- <filename>
- Environment variable
- <envar>
- Error code / text
- <errorcode>, <errortext>
- Program output block
- <screen> / <programlisting>
- First use of a defined term
- <firstterm>
- Acronym
- <acronym>
- Other conventions:
- <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".
- Index significant terms with <indexterm><primary>…</primary><secondary>…</secondary></indexterm> at the point where the term is actually explained, not every mention.
- 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.
- <variablelist> for parameter/option descriptions; <table> (with title) for reference tables, <informaltable> for untitled ones.
- Watch whitespace inside inline elements — a stray space or newline inside <literal> shows up in rendered output.
- Prose style
- American English spelling: behavior, initialize, catalog.
- Present tense, indicative. "The function returns…", not "will return".
- Impersonal voice preferred. Avoid "we"; "you" is used but sparingly. Avoid "please".
- No contractions. No marketing or editorialising: cut simply, just, easily, obviously, powerful, seamless.
- 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.
- 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".
- User-facing docs describe behaviour, not internals. Internals belong in the source READMEs or the internals part of the docs.
- The docs are not an SQL tutorial. Assume SQL literacy; explain PostgreSQL's specifics.
- Terminology
- PostgreSQL in the docs, always — not "Postgres", not "PostGreSQL".
- database cluster for the collection of databases served by one instance; avoid bare "instance" and "installation" for this, since they're ambiguous.
- role generally; user only when specifically meaning a role with LOGIN.
- primary / standby, not master/slave.
- configuration parameter for GUCs, linked to the relevant runtime-config section.
- Be consistent with the term already used in the surrounding chapter rather than introducing a synonym.
- Reference page structure
- SQL commands (refentry, man section 7):
- Name → Synopsis → Description → Parameters → Notes → Examples → Compatibility → See Also
- Client/server applications (man section 1):
- Name → Synopsis → Description → Options → Environment → Files → Diagnostics → Notes → Examples → See Also
- Synopsis uses <synopsis> with <option choice="opt"> for optional parts and ... for repeatable ones.
- Compatibility documents conformance to the SQL standard and names PostgreSQL extensions as such. Don't leave it out for a standard command.
- Keep refentry structure valid — it's what generates the man pages.
- Examples
- Runnable and self-contained: create the table, insert the data, then show the query.
- Show realistic output, including psql transcripts in <screen> where the output format matters.
- Simple and minimal — illustrate one point, not five.
- SQL keywords are predominantly uppercase in examples, though the corpus is genuinely inconsistent here; match the file you're in.
- Submitting
- 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.
- Small, single-purpose patches review far faster than sweeping rewrites.
- Docs patches are explicitly welcomed as an entry point for new contributors.
- Things I'm genuinely unsure about
- 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.
- 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