DOCS: Describe Missing Parameters on CREATE/ALTER PUBLICATION Pages

Core Problem

The PostgreSQL documentation for CREATE PUBLICATION and ALTER PUBLICATION SQL commands contains an inconsistency between the synopsis (the syntax definition at the top of each reference page) and the parameter descriptions (the <varlistentry> sections that explain each user-specified element).

Specifically:

• ALTER PUBLICATION synopsis uses column_name in the syntax but never defines it in the parameters section. It defines name, table_name, and schema_name but omits column_name.
• CREATE PUBLICATION synopsis uses table_name, schema_name, and column_name but only defines name in the parameters section.

This is a documentation quality issue where parameters appearing in the command syntax have no corresponding explanation on the same page. The assumption is that these terms are "self-explanatory," but this violates PostgreSQL's documentation standards where every synopsis parameter should have a formal definition.

Context: Why This Matters

The CREATE/ALTER PUBLICATION commands gained significant complexity in PostgreSQL 15 with the addition of column lists (allowing publication of specific columns rather than entire tables) and schema-level publication (publishing all tables in a schema). These features introduced column_name and schema_name parameters to the syntax, but the documentation parameter sections were apparently not fully updated to match.

This is a common documentation debt pattern: when features are added incrementally across releases, the synopsis gets updated to reflect new syntax, but the parameter description sections don't always keep pace—especially when the terms seem obvious.

Proposed Solution

The patch makes two changes:

1. Adds missing <varlistentry> parameter descriptions to both the CREATE PUBLICATION and ALTER PUBLICATION documentation pages, ensuring every parameter used in the synopsis has a corresponding definition. This brings consistency—both pages now define name, table_name, schema_name, and column_name.

2. Adds missing id attributes to <varlistentry> elements on the ALTER PUBLICATION page. These XML IDs are important for cross-referencing within the documentation system (SGML/DocBook), enabling other pages to link directly to specific parameter definitions.

Technical Assessment

This is a straightforward documentation-only patch with no code changes. The risk is essentially zero from a functional perspective. The main consideration is ensuring the parameter descriptions are accurate and consistent with how these terms are used in the actual SQL grammar and executor behavior:

• table_name: The name (optionally schema-qualified) of an existing table to add/remove from the publication
• schema_name: The name of an existing schema whose tables are published
• column_name: The name of a column in the table; when column lists are specified, only the named columns are replicated

Current Status

The patch has received no review feedback after approximately 5 weeks. The author pinged the thread on 2026-05-18 seeking attention. Documentation patches, particularly small ones like this, often struggle to attract reviewer attention on pgsql-hackers despite being low-risk and high-value for user experience.