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