Subject: [xml2rfc] Much repetition of "Paragraph 1" in references

From: Roger Price <[email-masked]>
Date: Sat, 19 Mar 2022 13:49:32 +0100 (CET)

Dear List, I am seeing automatic inclusion of the mention "Paragraph 1" in many 
references.  It seems to me that these mentions are not needed and clutter up 
the output.

The anchor is coded as

  <section>
  <name>Events</name>
  <t anchor="events">A bla bla bla ... etc

The reference is coded as

  the events are listed in <xref target="events"></xref>.

The HTML displays as

  the events are listed in Section 5.2, Paragraph 1.

Is there some way of eliminating these paragraph references, except when really 
needed?

Roger

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 19 Mar 2022 14:03:37 +0100

On 2022-03-19, at 13:49, Roger Price <[email-masked]> wrote:
> Is there some way of eliminating these paragraph references, except when really needed?

Yes.  If you don’t want to reference the paragraph but the section, put the anchor on the section and not the paragraph:

>>> <section anchor="events">
>>> <name>Events</name>
>>> <t>A bla bla bla … etc

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Sun, 20 Mar 2022 12:11:31 +0100

>>>> <section anchor="events">

Note that this is a change fron xml2rfc v2, where only the Section was
mentioned. For long sections, this might be useful, but it IMHO should
be an opt-in (for the format attribute).

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 20 Mar 2022 13:26:29 +0100

> be an opt-in (for the format attribute).

IMHO that would be a design mistake: The referencing site should not have to know what is being referenced — it is the job of the anchor site to provide this information.  (Yes, this principle is already being violated, but we should not pile up on this.)

Grüße, Carsten

---

From: Roger Price <[email-masked]>
Date: Sun, 20 Mar 2022 13:27:34 +0100 (CET)

On Sun, 20 Mar 2022, Julian Reschke wrote:
>> Yes.  If you don’t want to reference the paragraph but the section, put the 
> anchor on the section and not the paragraph:
>>

I have an HTML rendering of a link as

    See Section 6.4.5, Paragraph 4, Item 1.

which seems to me to be the most precise way of presenting that link. This 
currently happens automatically, without the need for an opt-in.  My "mistake" 
was to put the anchor on the <t> and not the <section>.  Perhaps a note in the 
documentation would be helpful.

Roger