On Wed, Nov 11, 2026 at 7:42 PM Matemática A3K 
<[email protected]<mailto:[email protected]>> wrote:
On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson 
<[email protected]<mailto:[email protected]>> 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 <[email protected]>
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).

Reply via email to