DOCS - missing SGML markup in some ALTER PUBLICATION examples

First seen: 2026-06-02 02:10:23+00:00 · Messages: 3 · Participants: 2

Latest Update

2026-06-04 · claude-opus-4-6

DOCS - Missing SGML Markup in ALTER PUBLICATION Examples

Core Problem

This thread addresses a trivial documentation defect in the PostgreSQL documentation source files. Specifically, some examples in the ALTER PUBLICATION reference page are missing proper SGML/DocBook markup tags. In PostgreSQL's documentation system, all reference pages are written in SGML (DocBook format), where SQL keywords, literals, identifiers, and other syntactic elements must be wrapped in appropriate markup tags (e.g., <command>, <literal>, <replaceable>, etc.) to ensure correct rendering in HTML, PDF, and man page outputs.

Missing markup means the rendered documentation may display inconsistently—affected tokens would appear in plain text rather than with the expected formatting (monospace, bold, italic, etc.) that helps readers distinguish SQL keywords from user-supplied identifiers.

Architectural Context

PostgreSQL's documentation toolchain uses SGML/DocBook source files (located in doc/src/sgml/) that are processed by build tools to produce multiple output formats. Consistency in markup is important because:

  1. Semantic correctness: Markup conveys meaning (e.g., <command> indicates a SQL command name vs. <literal> for a literal value)
  2. Cross-reference integrity: Properly marked-up elements can be indexed and cross-referenced
  3. Accessibility: Screen readers and other assistive tools rely on semantic markup

Proposed Solution

Peter Smith submitted a trivial patch that adds the missing SGML markup tags to the ALTER PUBLICATION examples in the documentation. The fix is straightforward—wrapping untagged text in the appropriate DocBook elements to match the conventions used elsewhere in the same page and across the documentation corpus.

Key Technical Decision: Commit Timing

The most notable aspect of this thread is Amit Kapila's observation about commit timing. The fix targets HEAD (PG19 development branch), but cannot be pushed immediately because the beta1 release tag has not yet been created. PostgreSQL's release process requires that during the period between code freeze/feature freeze and the actual tagging of a beta release, commits to HEAD are restricted or coordinated carefully to avoid contaminating the release tag. Amit indicates he will push the fix after the beta1 tag appears, which is standard practice for non-critical changes during the release engineering window.

This is a minor but illustrative example of PostgreSQL's disciplined release management process, where even trivial documentation fixes respect the tagging/branching workflow.

Assessment

This is a minimal, uncontroversial documentation fix with no design tradeoffs or technical disagreements. It demonstrates the community's attention to documentation quality and the structured release process even for trivial patches.