Дата публикации: 11-08-2026 06:40:00

While working on our project “PostgreSQL for Dolphins and Sea Lions,” I pored over the PostgreSQL documentation on replication.
Since I’m not quite up to speed on this topic yet, I like to look up certain terms (parameters, functions, etc.) every now and then to see exactly what they mean or how they work (RTFM!). That’s exactly why links were originally invented—the very thing that first made Gopher and later the Internet/WWW (http) so popular.
Unfortunately, however, these links are often missing from the documentation in question, which disrupts the flow of reading.
Fortunately, though, PostgreSQL is an open-source project, and contributions are highly encouraged! So instead of just grumbling about the documentation, I could add the missing links myself. But how exactly do I go about doing that in an ecosystem that’s new to me and therefore still a bit unfamiliar? An article by Elizabeth Christensen from Crunchy Data titled Contributing to Postgres 101: A Beginner’s Experience helped me get started.
Since I have absolutely no programming experience myself, I see improving the documentation as a great opportunity to actively contribute to the project and help out…
Improving the PostgreSQL Documentation
The PostgreSQL documentation is stored directly in the server repository. So, first, let’s download the Git repository from the PostgreSQL server:
$ git clone http://git.postgresql.org/git/postgresql.git
The next challenge is finding the right file:
$ cd postgresql/doc/src/sgml
The grep command, in all its forms, comes in handy here:
$ grep -r \'Planning for High Availability\' *.sgml
high-availability.sgml: Planning for High Availability
The correct document appears to be high-availability.sgml. The PostgreSQL documentation itself is written in SGML, which is similar to HTML and not particularly difficult to learn.
These SGML files can be easily read and edited using your editor of choice with appropriate code highlighting.
Next, we need to check the individual keywords to see if they’ve already been correctly marked up and, if so, add links to them:
Keyword
Markup
Links
synchronous_standby_names
synchronous_standby_names
archive_command
archive_command
archive_library
archive_library
synchronous_commit
synchronous_commit
pg_receivewal
pg_receivewal
pg_recvlogical
pg_recvlogical
pg_backup_stop
pg_backup_stop()
pg_backup_stop()
pg_backup_start
pg_backup_start()
pg_backup_start()
pg_switch_wal
pg_switch_wal()
pg_switch_wal()
Note: Keep in mind that keywords are written with an “_” (underscore) and links with a “-” (hyphen).
While building the documentation, it was also noticed that some link targets (id) hadn’t been set at all, so these had to be adjusted as well:
-
+
pg_backup_start
Quality Assurance
Once all changes have been made, it’s time for quality control. To do this, build the documentation locally:
$ cd postgresql
$ ./configure
$ cd doc
$ make
Exact details on how this works are described here.
If the build finds any errors, they will be displayed and the build will be aborted. If everything runs smoothly, you can now use your browser of choice to check whether everything actually works as intended:
$ firefox src/sgml/html/warm-standby.html
Something else I discovered later:
Building the documentation can take very long. But there is a method to just check the correct syntax of the documentation files, which only takes a few seconds: [ 5 ]
$ make check
make -C ../src/backend generated-headers
make[1]: Entering directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/backend\'
make -C ../include/catalog generated-headers
make[2]: Entering directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/include/catalog\'
make[2]: Nothing to be done for \'generated-headers\'.
make[2]: Leaving directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/include/catalog\'
make -C nodes generated-header-symlinks
make[2]: Entering directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/backend/nodes\'
make[2]: Nothing to be done for \'generated-header-symlinks\'.
make[2]: Leaving directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/backend/nodes\'
make -C utils generated-header-symlinks
make[2]: Entering directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils\'
make -C adt jsonpath_gram.h
make[3]: Entering directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils/adt\'
make[3]: \'jsonpath_gram.h\' is up to date.
make[3]: Leaving directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils/adt\'
make[2]: Leaving directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils\'
make[1]: Leaving directory \'/home/oli/fromdual/postgresql/docu/postgresql/src/backend\'
rm -rf \'/home/oli/fromdual/postgresql/docu/postgresql\'/tmp_install
/usr/bin/mkdir -p \'/home/oli/fromdual/postgresql/docu/postgresql\'/tmp_install/log
make -C \'..\' DESTDIR=\'/home/oli/fromdual/postgresql/docu/postgresql\'/tmp_install install >\'/home/oli/fromdual/postgresql/docu/postgresql\'/tmp_install/log/install.log 2 >&1
make -j1 checkprep > >\'/home/oli/fromdual/postgresql/docu/postgresql\'/tmp_install/log/install.log 2 >&1
PATH=\"/home/oli/fromdual/postgresql/docu/postgresql/tmp_install/usr/local/pgsql/bin:/home/oli/fromdual/postgresql/docu/postgresql/doc:$PATH\" LD_LIBRARY_PATH=\"/home/oli/fromdual/postgresql/docu/postgresql/tmp_install/usr/local/pgsql/lib:$LD_LIBRARY_PATH\" INITDB_TEMPLATE=\'/home/oli/fromdual/postgresql/docu/postgresql\'/tmp_install/initdb-template initdb --auth trust --no-sync --no-instructions --lc-messages=C --no-clean \'/home/oli/fromdual/postgresql/docu/postgresql\'/tmp_install/initdb-template > >\'/home/oli/fromdual/postgresql/docu/postgresql\'/tmp_install/log/initdb-template.log 2 >&1
Submitting the Patch
If everything works as intended and to your satisfaction, you can then proceed to create the patch and submit it:
$ git commit -m \'some references on variables and functions added\'
$ git format-patch -1 HEAD
This creates a file containing the commit comment: 0001-some-references-on-variables-and-functions-added.patch.
Apparently, in the PostgreSQL project, you don’t create a merge request to incorporate the patch back into the source code; instead, the patch must be sent to the appropriate mailing list and then merged into the main branch by a developer with merge/commit privileges. I’ve now agreed with “my” committer that we’ll hold the discussion about my patch on the pgsql-docs mailing list.
Let’s see how things go from here and how far I get with my patch…
This page was translated using deepl.com.
Making the PostgreSQL Documentation Even Better appeared first on MariaDB.org

Основное содержимое страницы с новостью.

$ git clone http://git.postgresql.org/git/postgresql.git

$ cd postgresql/doc/src/sgml

$ grep -r 'Planning for High Availability' *.sgml
high-availability.sgml:    <title>Planning for High Availability</title>

       <row>
-       <entry role="func_table_entry"><para role="func_signature">
+       <entry id="pg-backup-start" role="func_table_entry"><para role="func_signature">
         <indexterm>
          <primary>pg_backup_start</primary>

$ cd postgresql
$ ./configure
$ cd doc
$ make

$ firefox src/sgml/html/warm-standby.html

$ make check
make -C ../src/backend generated-headers
make[1]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend'
make -C ../include/catalog generated-headers
make[2]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/include/catalog'
make[2]: Nothing to be done for 'generated-headers'.
make[2]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/include/catalog'
make -C nodes generated-header-symlinks
make[2]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/nodes'
make[2]: Nothing to be done for 'generated-header-symlinks'.
make[2]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/nodes'
make -C utils generated-header-symlinks
make[2]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils'
make -C adt jsonpath_gram.h
make[3]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils/adt'
make[3]: 'jsonpath_gram.h' is up to date.
make[3]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils/adt'
make[2]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils'
make[1]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend'
rm -rf '/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install
/usr/bin/mkdir -p '/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/log
make -C '..' DESTDIR='/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install install >'/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/log/install.log 2>&1
make -j1  checkprep >>'/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/log/install.log 2>&1
PATH="/home/oli/fromdual/postgresql/docu/postgresql/tmp_install/usr/local/pgsql/bin:/home/oli/fromdual/postgresql/docu/postgresql/doc:$PATH" LD_LIBRARY_PATH="/home/oli/fromdual/postgresql/docu/postgresql/tmp_install/usr/local/pgsql/lib:$LD_LIBRARY_PATH" INITDB_TEMPLATE='/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/initdb-template  initdb --auth trust --no-sync --no-instructions --lc-messages=C --no-clean '/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/initdb-template >>'/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/log/initdb-template.log 2>&1

$ git commit -m 'some references on variables and functions added'
$ git format-patch -1 HEAD

Схожие новости