Re: Introductory docs-hacking task: Example markup

On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <daniel(at)yesql(dot)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.

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