On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <[email protected]> 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 > > >
