| From: | Vinay Manikanda <vinay(dot)manikanda(at)gmail(dot)com> |
|---|---|
| To: | Daniel Gustafsson <daniel(at)yesql(dot)se> |
| Cc: | Xavier Fischer <xavier_fischer(at)hotmail(dot)fr>, "David G(dot) Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com>, "pgsql-docs(at)lists(dot)postgresql(dot)org" <pgsql-docs(at)lists(dot)postgresql(dot)org>, Matemática A3K <matematica(dot)a3k(at)gmail(dot)com> |
| Subject: | Re: Introductory docs-hacking task: Example markup |
| Date: | 2026-11-17 03:44:57 |
| Message-ID: | CAAMO2zK+8UXA=1OJaD5ymn3Cq1BX8qojp7jynTDGkfRtTz3QEw@mail.gmail.com |
| Views: | Whole Thread | Raw Message | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-docs |
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 <matematica(dot)a3k(at)gmail(dot)com>
wrote:
> On Thu, Nov 12, 2026 at 9:33 AM Daniel Gustafsson <daniel(at)yesql(dot)se> wrote:
> >
> > > On 12 Nov 2026, at 08:33, Xavier Fischer <xavier_fischer(at)hotmail(dot)fr>
> wrote:
> > >
> > > 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.
> >
> > 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 | Content-Type | Size |
|---|---|---|
| fix-example-redundancy.patch | application/octet-stream | 2.9 KB |
| From | Date | Subject | |
|---|---|---|---|
| Next Message | David G. Johnston | 2026-11-17 05:20:25 | Re: Introductory docs-hacking task: Example markup |
| Previous Message | Matemática A3K | 2026-11-17 03:00:37 | Re: Introductory docs-hacking task: Example markup |