Introductory docs-hacking task: Example markup
Here is another doc hacking task pulled from my ever growing TODO which I think
would be suitable for someone keen to get started in hacking on the docs.
There is an element of research here in order to propose a fix, since the best
course of action is unknown (there are many possible options).
We have quite the variety in how we write examples in the docs, both within the
reference manpages and in the main documentation. A few examples (pun
intended) follow:
* https://www.postgresql.org/docs/devel/plpgsql-trigger.html
Here we use <example id=foo> to mark up the example and refer to the id
attribute in the text (sometimes just right before the example itself which
seems of questionable use).
* https://www.postgresql.org/docs/devel/typeconv-oper.html
This is similarly using <example> but no id for referencing it. There might
not be much need for referencing it in text of course, in which case omitting
the id is fine, but there seems to be little difference in "Some examples
follow" used here and "Example XX.YY below does blah" used elsewhere.
* https://www.postgresql.org/docs/devel/bloom.html#BLOOM-EXAMPLES
Here the example is a <sect2> which in turn creates a TOC entry for the example.
* https://www.postgresql.org/docs/devel/datatype-xml.html#DATATYPE-XML-CREATING
Another variant, here we just have a plain string "Examples:" with no markup at
all.
* https://www.postgresql.org/docs/devel/intagg.html
We only have one of this, but here we called it "Sample Uses" and made it a
<sect2>. Maybe that's fine, but there are similar sections elsewhere where we
use Examples so..
I'm sure there are more that I didn't see with a quick grep and skim. On top
of these there are also various combinations of Example(s) vs Exmaples, Example
Uses vs plain Examples etc.
Standardizing how we mark up examples would improve documentation consistency
and ideally make it easier to navigate and search. I have not done more than
collect the variants listed above so I don't know if the correct answer is "do
nothing" (which I doubt it is), but even reaching that conclusion would be a
step forward.
Anyone interested?
--
Daniel Gustafsson
On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <daniel@yesql.se> wrote:
Here is another doc hacking task pulled from my ever growing TODO which I think
would be suitable for someone keen to get started in hacking on the docs.
There is an element of research here in order to propose a fix, since the best
course of action is unknown (there are many possible options).We have quite the variety in how we write examples in the docs, both within the
reference manpages and in the main documentation. A few examples (pun
intended) follow:* https://www.postgresql.org/docs/devel/plpgsql-trigger.html
Here we use <example id=foo> to mark up the example and refer to the id
attribute in the text (sometimes just right before the example itself which
seems of questionable use).* https://www.postgresql.org/docs/devel/typeconv-oper.html
This is similarly using <example> but no id for referencing it. There might
not be much need for referencing it in text of course, in which case omitting
the id is fine, but there seems to be little difference in "Some examples
follow" used here and "Example XX.YY below does blah" used elsewhere.* https://www.postgresql.org/docs/devel/bloom.html#BLOOM-EXAMPLES
Here the example is a <sect2> which in turn creates a TOC entry for the example.* https://www.postgresql.org/docs/devel/datatype-xml.html#DATATYPE-XML-CREATING
Another variant, here we just have a plain string "Examples:" with no markup at
all.* https://www.postgresql.org/docs/devel/intagg.html
We only have one of this, but here we called it "Sample Uses" and made it a
<sect2>. Maybe that's fine, but there are similar sections elsewhere where we
use Examples so..I'm sure there are more that I didn't see with a quick grep and skim. On top
of these there are also various combinations of Example(s) vs Exmaples, Example
Uses vs plain Examples etc.Standardizing how we mark up examples would improve documentation consistency
and ideally make it easier to navigate and search.
I will argue that no markup should be used for examples. The goal of
an example is to help readers understand a general functioning by
seeing a particular one. As such, they should be part of the prose
that explains the functioning, not an independent element to be
indexed. The only value I currently see in having a delimited or
encapsulated example is the ability to skip it if you already got it
from the explanation prose.
I propose to add "Remove example markup and blend the encapsulated
content into the prose of the belonging element" to the options being
considered.
Show quoted text
I have not done more than
collect the variants listed above so I don't know if the correct answer is "do
nothing" (which I doubt it is), but even reaching that conclusion would be a
step forward.Anyone interested?
--
Daniel Gustafsson
On Wed, Nov 11, 2026 at 7:42 PM Matemática A3K <matematica.a3k@gmail.com>
wrote:
On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <daniel@yesql.se> wrote:
Standardizing how we mark up examples would improve documentation
consistency
and ideally make it easier to navigate and search.
Makes sense to me.
I propose to add "Remove example markup and blend the encapsulated
content into the prose of the belonging element" to the options being
considered.
This seems unlikely to be accepted and is definitely not 'newcomer
friendly'. I'd suggest you, or anyone who does think this is needed,
provide at least three or four patch-quality examples of what you are
thinking on another thread first.
David J.
On Wed, Nov 11, 2026 at 7:42 PM Matemática A3K <matematica.a3k@gmail.com<mailto:matematica.a3k@gmail.com>> wrote:
On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <daniel@yesql.se<mailto:daniel@yesql.se>> wrote:
I will argue that no markup should be used for examples. The goal of
an example is to help readers understand a general functioning by
seeing a particular one. As such, they should be part of the prose
that explains the functioning, not an independent element to be
indexed. The only value I currently see in having a delimited or
encapsulated example is the ability to skip it if you already got it
from the explanation prose.
I disagree with this: sometimes you want to search for examples of a construct, and having it indexed can avoid scrolling and makes clear that there's a dedicated section. I tend to do that when programming and it's useful to have a dedicated section to jump in directly.
There are some short examples in the middle of the main prose, not worth a section on their own.
Here are some examples :
Missing index: https://www.postgresql.org/docs/19/sql-altertable.html
Index not needed: examples are within the prose: https://www.postgresql.org/docs/19/functions-matching.html#FUNCTIONS-POSIX-REGEXP
Example without index for any section at all: https://www.postgresql.org/docs/current/sql-merge.html
I'll look for more examples
De : David G. Johnston <david.g.johnston@gmail.com>
Envoyé : jeudi 12 novembre 2026 03:56
This seems unlikely to be accepted and is definitely not 'newcomer friendly'. I'd suggest you, or
anyone who does think this is needed, provide at least three or four patch-quality examples of what
you are thinking on another thread first.
Noted. Still it's a good way to learn the docs in my opinion. I agree that this should be splitted as separate work (current examples markup, missing index examples, sections where examples lack).
On 12 Nov 2026, at 08:33, Xavier Fischer <xavier_fischer@hotmail.fr> wrote:
On Wed, Nov 11, 2026 at 7:42 PM Matemática A3K <matematica.a3k@gmail.com<mailto:matematica.a3k@gmail.com>> wrote:
On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <daniel@yesql.se<mailto:daniel@yesql.se>> wrote:I will argue that no markup should be used for examples. The goal of
an example is to help readers understand a general functioning by
seeing a particular one. As such, they should be part of the prose
that explains the functioning, not an independent element to be
indexed. The only value I currently see in having a delimited or
encapsulated example is the ability to skip it if you already got it
from the explanation prose.I disagree with this: sometimes you want to search for examples of a construct, and having it indexed can avoid scrolling and makes clear that there's a dedicated section. I tend to do that when programming and it's useful to have a dedicated section to jump in directly.
There are some short examples in the middle of the main prose, not worth a section on their own.
This aligns with my thinking. There might be cases where the example can be
made part of the prose but in general I think technical documentation is
improved by having separate and indexable examples.
One benefit to having proper markup is that the code in the examples can be
extracted and tested against the current codebase to ensure no example code has
become incorrect.
--
Daniel Gustafsson
Import Notes
Reply to msg id not found: AMBP193MB27424C3347F03DBD3CC4498094702@AMBP193MB2742.EURP193.PROD.OUTLOOK.COMReference msg id not found: AMBP193MB27424C3347F03DBD3CC4498094702@AMBP193MB2742.EURP193.PROD.OUTLOOK.COM
On Thu, Nov 12, 2026 at 9:33 AM Daniel Gustafsson <daniel@yesql.se> wrote:
On 12 Nov 2026, at 08:33, Xavier Fischer <xavier_fischer@hotmail.fr> wrote:
On Wed, Nov 11, 2026 at 7:42 PM Matemática A3K <matematica.a3k@gmail.com<mailto:matematica.a3k@gmail.com>> wrote:
On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <daniel@yesql.se<mailto:daniel@yesql.se>> wrote:I will argue that no markup should be used for examples. The goal of
an example is to help readers understand a general functioning by
seeing a particular one. As such, they should be part of the prose
that explains the functioning, not an independent element to be
indexed. The only value I currently see in having a delimited or
encapsulated example is the ability to skip it if you already got it
from the explanation prose.I disagree with this: sometimes you want to search for examples of a construct, and having it indexed can avoid scrolling and makes clear that there's a dedicated section. I tend to do that when programming and it's useful to have a dedicated section to jump in directly.
There are some short examples in the middle of the main prose, not worth a section on their own.This aligns with my thinking. There might be cases where the example can be
made part of the prose but in general I think technical documentation is
improved by having separate and indexable examples.
I think the problem is the lack of documentation guidelines, and it is
not clear how to set them.
Once you define a guideline, then, you have a rule to make the doc
adhere. Different parts of the documentation follow different rules,
which one is the best? No answer, only that one should be chosen to
give shape. Consistency is defined through rules, without rules, there
cannot be defined "a deviation", or an inconsistency.
Once there is mechanism of defining guidelines, then, which guidelines
to use can be discussed.
The lack of defined guidelines makes any attempt to "move" the
documentation in some direction to "drown". Every argument makes sense
under some guideline, then, they get confronted, and then, nothing
happens. So, the documentation "doesn't move", it seems to be frozen.
Defining such mechanism should be the priority.
One benefit to having proper markup is that the code in the examples can be
extracted and tested against the current codebase to ensure no example code has
become incorrect.
In other threads, it has been stated that the examples do not
necessarily run, questions have been routed with that. That's another
guideline, which one should be followed? See the problem?
Show quoted text
--
Daniel Gustafsson
Hi Daniel and others,
Here we use <example id=foo> to mark up the example and refer to the id
attribute in the text (sometimes just right before the example itself
which
seems of questionable use).
Thanks for pointing this out. I've removed all the instances of redundant
xref
paragraphs in the plpgsql-trigger documentation (Examples 41.3-41.8).
The changes eliminate the "shows an example of..." text that appeared
immediately before each `<example>` element, while keeping the examples
properly linkable via their `id` attributes.
Patch attached: fix-example-redundancy.patch
Thanks,
Vinay
On Mon, Nov 16, 2026 at 10:00 PM Matemática A3K <matematica.a3k@gmail.com>
wrote:
Show quoted text
On Thu, Nov 12, 2026 at 9:33 AM Daniel Gustafsson <daniel@yesql.se> wrote:
On 12 Nov 2026, at 08:33, Xavier Fischer <xavier_fischer@hotmail.fr>
wrote:
On Wed, Nov 11, 2026 at 7:42 PM Matemática A3K <
matematica.a3k@gmail.com<mailto:matematica.a3k@gmail.com>> wrote:
On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <daniel@yesql.se
<mailto:daniel@yesql.se>> wrote:
I will argue that no markup should be used for examples. The goal of
an example is to help readers understand a general functioning by
seeing a particular one. As such, they should be part of the prose
that explains the functioning, not an independent element to be
indexed. The only value I currently see in having a delimited or
encapsulated example is the ability to skip it if you already got it
from the explanation prose.I disagree with this: sometimes you want to search for examples of a
construct, and having it indexed can avoid scrolling and makes clear that
there's a dedicated section. I tend to do that when programming and it's
useful to have a dedicated section to jump in directly.There are some short examples in the middle of the main prose, not
worth a section on their own.
This aligns with my thinking. There might be cases where the example
can be
made part of the prose but in general I think technical documentation is
improved by having separate and indexable examples.I think the problem is the lack of documentation guidelines, and it is
not clear how to set them.Once you define a guideline, then, you have a rule to make the doc
adhere. Different parts of the documentation follow different rules,
which one is the best? No answer, only that one should be chosen to
give shape. Consistency is defined through rules, without rules, there
cannot be defined "a deviation", or an inconsistency.Once there is mechanism of defining guidelines, then, which guidelines
to use can be discussed.The lack of defined guidelines makes any attempt to "move" the
documentation in some direction to "drown". Every argument makes sense
under some guideline, then, they get confronted, and then, nothing
happens. So, the documentation "doesn't move", it seems to be frozen.Defining such mechanism should be the priority.
One benefit to having proper markup is that the code in the examples can
be
extracted and tested against the current codebase to ensure no example
code has
become incorrect.
In other threads, it has been stated that the examples do not
necessarily run, questions have been routed with that. That's another
guideline, which one should be followed? See the problem?--
Daniel Gustafsson
On Mon, Nov 16, 2026 at 8:00 PM Matemática A3K <matematica.a3k@gmail.com>
wrote:
Defining such mechanism should be the priority.
I agree that the lack of these guidelines adds a decent amount of friction.
But the project itself has basically zero priorities and this one item
isn't going to make such a list come into existence.
To a large extent what the docs do today is the guideline, if you want
evidence to back a position that is where it will be found.
A decent number of such potential guidelines have been mentioned in the
past, but getting them actually committed right now hasn't been attempted
by anyone, for whatever their personal reasons. Sticking an agent on the
mailing list archives looking for such - my participation in a thread
should narrow the surface area quite a bit though I don't know how big the
false negative set would be - would be a fruitful way to start such an
endeavor. Its on my own todo list but down quite a ways in priority.
David J.
On 17 Nov 2026, at 06:20, David G. Johnston <david.g.johnston@gmail.com> wrote:
But the project itself has basically zero priorities
I respectfully disagree with this statement, but that's beside the discussion
at hand.
and this one item isn't going to make such a list come into existence.
To a large extent what the docs do today is the guideline, if you want evidence to back a position that is where it will be found.
If anyone is interested in pursuing a set of guidelines for the documentation
(which for sure would be useful) I would argue that a good place to start would
be to document the consistent markup we have, and go from there. An excercise
like that will serve to identify where we are consistent and where we can
improve. The current Style Guide covers a pretty slim portion of the docs.
--
Daniel Gustafsson
On 17 Nov 2026, at 04:00, Matemática A3K <matematica.a3k@gmail.com> wrote:
In other threads, it has been stated that the examples do not
necessarily run, questions have been routed with that.
They will typically run (though I'm sure we have those that don't), but they
are not guaranteed to be complete examples. That's an important distinction
IMO, the syntax should be correct but an example might not list every partition
for a partition hierarchy for example. In such cases we could add what's
missing as a comment.
That's another guideline, which one should be followed? See the problem?
I don't see a problem. I was merely trying to point out one potential upside
of rich markup, though perhaps this was an ill-chosen example.
--
Daniel Gustafsson
A decent number of such potential guidelines have been mentioned in the past, but getting them actually committed right now hasn't been attempted by anyone, for whatever their personal reasons. Sticking an agent on the mailing list archives looking for such - my participation in a thread should narrow the surface area quite a bit though I don't know how big the false negative set would be - would be a fruitful way to start such an endeavor. Its on my own todo list but down quite a ways in priority.
TADA! https://pastebin.com/FTQ7jXj0
I think that from it, something can be extracted. Then a page
"Documentation Guidelines" can be constructed. Something like:
Conventions are largely oral tradition and enforced in review. To
streamline the process, have the following criteria in mind when
writing new documentation and submitting changes for it:
- ..
- The documentation source uses a distinctive style with single-space
indentation, with lines wrapping around 80 characters.
- American English spelling (e.g., "behavior", "initialize")
- Examples should be runnable
- ...
I was thinking in opening a wiki page where this can be worked on, I
see there are some pages related that require login to access, and
once logged in, I don't have permissions to create it.
Can you (or anyone) create a "Documentation_Guidelines" page - or
similar - for this?
David J.
Also, it provides "reflections" on the markup being used - which is in
the direction of what Daniel was talking about
On Thu, 2026-11-19 at 01:04 -0300, Matemática A3K wrote:
Can you (or anyone) create a "Documentation_Guidelines" page - or
similar - for this?
Here you are: https://wiki.postgresql.org/wiki/Documentation_Guidelines
I added links to all the information out there that I am aware of.
Yours,
Laurenz Albe