Subject: [rfc-i] t with indent

From: Eric Rescorla <[email-masked]>
Date: Tue, 29 Dec 2020 11:08:42 -0800

Hi folks,

In doing Auth48 for RFC8844 I noticed that each <t> block in the final
XML seems too contain an "indent" attribute, as in:

   <t indent="0" pn="section-2-5">

While I see that the current v3 grammar seems to allow "indent" under
<t>, this doesn't seem to be in draft-iab-rfc7991bis, so it's not
quite clear what purpose it's intended for. This seems to raise two
questions:

First, do we really want this kind of layout-specific markup rather
than semantic markup? Searching for <t> with indent != 0 in the
published RFCs, I see the following cases:

- RFC 8907, S. 6.2 -- a definition list nested in another definition list

- RFC 8916, S. 5 -- a definition list indented under a hed (arguably
                    another nested definition list)

- RFC 8919 S 7.3 -- a set of Note: values introduced by a sentence
                    ending in a colon

- RFC 8934 S 4.2.2 -- an equation

- RFC 8949 S 8 -- an equation

It seems like we might be better served here by introducing some new
semantic constructs. Both nested definition lists and equations are
natural structures that would benefit from consistent layout (note:
it's possible that nested definition lists already exist; it wasn't
quite clear to me from the grammar). RFC 8919 is kind of an edge:
one could probably model it as a definition list or one could just
live with the Notes not being indented.

Second, even assuming that <t indent=...> is a good thing, it seems
suboptimal to have it attached to every paragraph in the XML. Is
there a reason why it can't simply be omitted when it is set to
the modal value of "0"?

-Ekr
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Julian Reschke <[email-masked]>
Date: Tue, 29 Dec 2020 20:39:24 +0100

> quite clear what purpose it's intended for. This seems to raise two

FWIW, it seems to be a fairly recent addition
(<https://github.com/mnot/v3grammar/commit/20ccb12dc9d4b308f025c17aa3c8dcf8dbfb0ab2>).

> quite clear to me from the grammar). RFC 8919 is kind of an edge:

<dt> can contain <dl>, so yes, a definition inside a definition list can
contain another definition list.

AFAIC, the desire to tune horizonal whitespace likely comes from people
trying to optimize the text output. Something we explicitly should *not*
encourage (IMHO).

> live with the Notes not being indented.

The example IMHO clearly should be a <blockquote> (which will get
indentation), as it cites text from the IANA registry:

>   IANA has also added the following notes to this registry:
>
>       Note: For future codepoints, in cases where the document that
>       defines the encoding is different from the document that assigns
>       the codepoint, the encoding reference MUST be to the document that
>       defines the encoding.
>
>       Note: If a link attribute can be advertised both as a sub-TLV of
>       TLVs 22, 23, 25, 141, 222, and 223 and as a sub-sub-TLV of the
>       Application-Specific Link Attributes sub-TLV defined in RFC 8919,
>       then the same numerical code should be assigned to the link
>       attribute whenever possible.

It's frustrating that the RPC did not get this right. But, IMHO, a very
good example why we should be open to fix the XML even after publication.

> ...

That's a requirement for the preptool, see
<https://greenbytes.de/tech/webdav/rfc7998.html#attribute-default-value-insertion>:

"Fill in any default values for attributes on elements, except
"keepWithNext" and "keepWithPrevious" of <t>, and "toc" of <section>.
Some default values can be found in the RELAX NG schema, while others
can be found in the prose describing the elements in [RFC7991]."

(FWIW, I disagreed with that requirement)

Best regards, Julian

---

From: Eric Rescorla <[email-masked]>
Date: Tue, 29 Dec 2020 12:39:08 -0800

On Tue, Dec 29, 2020 at 11:39 AM Julian Reschke <[email-masked]>
wrote:

> (<
> https://github.com/mnot/v3grammar/commit/20ccb12dc9d4b308f025c17aa3c8dcf8dbfb0ab2
> >).
>

Great.

> indentation), as it cites text from the IANA registry:

Good point

> <
> https://greenbytes.de/tech/webdav/rfc7998.html#attribute-default-value-insertion
> >:
>

Ugh. What's the process to reconsider that requirement? It just seems like
clutter.

-Ekr

---

From: Eric Rescorla <[email-masked]>
Date: Tue, 29 Dec 2020 13:04:28 -0800

On Tue, Dec 29, 2020 at 12:47 PM John Levine <[email-masked]> wrote:

> In article <
> [email-masked]> you
> write:
> It was added quite recently. Before that the RPC was faking indented
> paragraphs with single element unnumbered lists which was silly.
> You'll find over a thousand of those.
>
> >natural structures that would benefit from consistent layout ...
>
> Perhaps, but I find one fairly quickly hits the point of diminishing
> returns when trying to assign semantics to every typographic feature.
> If someone can find consistent semantics in the thousand fake indents
> I wouldn't be opposed to adding semantic tags (even retroactively) but
> I'm not holding my breath.
>

Well, I certainly don't think all of them will have the same semantics.
Rather,
what I would expect is that the majority fall into a relatively small number
of buckets. We'd then need to go and look to see whether it was worth
having a typographical feature like this for the remainder or whether
we could just live with suboptimal typesetting in those cases -- it's not
like
it would be the first time our typesetting was suboptimal!

> The default is zero so I agree that there's no need to indicate zero
> indents.
>

That seems like a good start. What's the process for doing that? Based on
Julian's
note it sounds like this is a requirement documented somewhere.

-Ekr

R's,
> John

---

From: "John R Levine" <[email-masked]>
Date: 29 Dec 2020 16:35:50 -0500

On Tue, 29 Dec 2020, Eric Rescorla wrote:
> like it would be the first time our typesetting was suboptimal!

Sounds like a good project for someone, but I'm not volunteering at this 
point.

> Julian's note it sounds like this is a requirement documented somewhere.

It's in RFC 7998:

5.2.  Defaults

    These steps will ensure that all default values have been filled in
    to the XML, in case the defaults change at a later date.  Steps in
    this section will not overwrite existing values in the input file.

In retrospect, we should have flipped it around and said that the XML 
default values aren't going to change.  There's a lot of stuff in RFCs 
7991 to 7998 that has turned out to be a poor match for practice.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
Please consider the environment before reading this e-mail. https://jl.ly
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Julian Reschke <[email-masked]>
Date: Tue, 29 Dec 2020 22:48:34 +0100

Am 29.12.2020 um 21:39 schrieb Eric Rescorla:
> ...
>
> Ugh. What's the process to reconsider that requirement? It just seems
> like clutter.
>
> -Ekr

There's <https://github.com/rfc-format/draft-iab-rfcv3-preptool-bis> to
raise issues, but you can tell from that repo that nobody is working on it.

Best regards, Julian

---

From: Eric Rescorla <[email-masked]>
Date: Tue, 29 Dec 2020 14:02:04 -0800

> Sounds like a good project for someone, but I'm not volunteering at this

Do we have a list of the cases where this has happened? If so, I'd be
willing to sample and do a survey.

-Ekr

---

From: "John R Levine" <[email-masked]>
Date: 29 Dec 2020 17:47:03 -0500

> willing to sample and do a survey.

This comes pretty close:

$ egrep '<ul.*empty="true"' rfc8*.xml|egrep -v 'section-toc|section-boilerplate'

There's also about 1500 empty tag lists used to indent TOC lines to follow 
section nesting with pn="section-toc-something".  I suppose that's one 
that could be replaced with a more complex <toc> tag.

R's,
John

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 30 Dec 2020 00:03:28 +0100

> indentation), as it cites text from the IANA registry:

In RFCXMLv2, the equivalent of an HTML blockquote was done using a <list style=“empty”>, i.e., no bullets.

This idiom somehow continues into RFCXMLv3, with <ul empty=“true”>.

There now *additionally* is a <blockquote> element, but in xml2rfc that generates a lot of chrome, so it is *not* equivalent.  (It also has “cite” and “quotedFrom”(*) attributes.)

So kramdown-rfc translates a markdown blockquote into <list style=“empty”>, which is then translated into <ul empty=“true”> by xml2frc for RFCXMLv3.

You can still manually enter the new RFCXMLv3 blockquotes:

<blockquote>
Never argue with stupid people, they will drag you down to their level and then beat you with experience.
</blockquote>

And will get (xml2rfc TXT version):

   |  Never argue with stupid people, they will drag you down to their
   |  level and then beat you with experience.

(or an “inlay” style rendering in HTML), way more heavy than the normal blockquote style.

Grüße, Carsten

(*) due to its HTML-based roots, kramdown-rfc doesn’t support studLyCaps attributes yet.  Ouch.

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 30 Dec 2020 10:29:07 +1100

> On 30 Dec 2020, at 8:35 am, John R Levine <[email-masked]> wrote:
> 
> In retrospect, we should have flipped it around and said that the XML default values aren't going to change.  There's a lot of stuff in RFCs 7991 to 7998 that has turned out to be a poor match for practice.

+1 - this is a very strange approach.

I note that 7998 says:

> The details (particularly any vocabularies) described in this
>    document are expected to change based on experience gained in
>    implementing the new publication toolsets.  Revised documents will be
>    published capturing those changes as the toolsets are completed.

--
Mark Nottingham   https://www.mnot.net/

---

From: Julian Reschke <[email-masked]>
Date: Wed, 30 Dec 2020 06:22:53 +0100

Am 29.12.2020 um 23:47 schrieb John R Levine:
> There's also about 1500 empty tag lists used to indent TOC lines to
> follow section nesting with pn="section-toc-something".  I suppose
> that's one that could be replaced with a more complex <toc> tag.

Yes, but those should never have made it into the prepped XML. xml2rfc
inlines the generated ToC (and also expanded "authors" sections). This
is because it internally uses them in an intermediate step before
rendering (which is fine), but they never should leak into the canonical
XML and also not affect the user-visible XML grammar.

A bug (or if you want debatable design decision) leading to more confusion.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 30 Dec 2020 06:29:48 +0100

> (or an “inlay” style rendering in HTML), way more heavy than the normal blockquote style.

For completeness: there's also <aside>, which can be used to format
indented Notes. Unfortunately, the generated TXT is very similar to the
one generated for <blockquote> - the HTML is fine.

Best regards, Julian