RE: Introductory docs-hacking task: Example markup

On Wed, Nov 11, 2026 at 7:42 PM Matemática A3K <matematica(dot)a3k(at)gmail(dot)com<mailto:matematica(dot)a3k(at)gmail(dot)com>> wrote:
On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <daniel(at)yesql(dot)se<mailto:daniel(at)yesql(dot)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(dot)g(dot)johnston(at)gmail(dot)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).