Making the PostgreSQL Documentation Even Better

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:    <title>Planning for High Availability</title>

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:

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:

       <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>

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.