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

Attachment: fix-example-redundancy.patch
Description: Binary data

Reply via email to