Hi Daniel and others, > 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).
Thanks for pointing this out. I've removed all the instances of redundant xref paragraphs in the plpgsql-trigger documentation (Examples 41.3-41.8). The changes eliminate the "shows an example of..." text that appeared immediately before each `<example>` element, while keeping the examples properly linkable via their `id` attributes. Patch attached: fix-example-redundancy.patch Thanks, Vinay On Mon, Nov 16, 2026 at 10:00 PM Matemática A3K <[email protected]> wrote: > On Thu, Nov 12, 2026 at 9:33 AM Daniel Gustafsson <[email protected]> wrote: > > > > > On 12 Nov 2026, at 08:33, Xavier Fischer <[email protected]> > wrote: > > > > > > 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. > > > > This aligns with my thinking. There might be cases where the example > can be > > made part of the prose but in general I think technical documentation is > > improved by having separate and indexable examples. > > I think the problem is the lack of documentation guidelines, and it is > not clear how to set them. > > Once you define a guideline, then, you have a rule to make the doc > adhere. Different parts of the documentation follow different rules, > which one is the best? No answer, only that one should be chosen to > give shape. Consistency is defined through rules, without rules, there > cannot be defined "a deviation", or an inconsistency. > > Once there is mechanism of defining guidelines, then, which guidelines > to use can be discussed. > > The lack of defined guidelines makes any attempt to "move" the > documentation in some direction to "drown". Every argument makes sense > under some guideline, then, they get confronted, and then, nothing > happens. So, the documentation "doesn't move", it seems to be frozen. > > Defining such mechanism should be the priority. > > > One benefit to having proper markup is that the code in the examples can > be > > extracted and tested against the current codebase to ensure no example > code has > > become incorrect. > > In other threads, it has been stated that the examples do not > necessarily run, questions have been routed with that. That's another > guideline, which one should be followed? See the problem? > > > -- > > Daniel Gustafsson > > > > >
fix-example-redundancy.patch
Description: Binary data
