Subject: Re: [xml2rfc] xml2rfc line break

From: Carsten Bormann <[email-masked]>
Date: Tue, 17 Aug 2021 11:07:56 +0200

Hi,

> On 2021-08-17, at 10:37, heasley <[email-masked]> wrote:
> 
> I appologize if there is a better forum for this question, I didnt find one.
> Cluebat welcome.

The answer to this question isn’t quite as clear-cut as it could; we don’t have an “rfcxml-authors” list, but typically these questions come up on the xml2rfc mailing list (or rfc-interest, or tools-discuss…).

> Is it possible to insert a line break in the contents of a list?
> 
> <ol>
> <li>
>  bunch of hooey
>  <line break>
>  more hoo-ah
> </li>
> 
> Everything that I have tried results in errors from xml2rfc.

First of all, I’m assuming you are using xml2rfc with --v3 flags (<ol/<li is new syntax for v3).  Even though there is older documentation that is supposedly more authoritative, the RFCXMLv3 we actually use is described in https://xml2rfc.tools.ietf.org/xml2rfc-doc.html  

https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#name-br-2
describes the <br element, which can do exactly what you want, and is in the content model for <li.
So the example becomes:

> <ol>
> <li>
>  bunch of hooey
>  <br/>
>  more hoo-ah
> </li>

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 18 Aug 2021 16:59:21 +0200

On 2021-08-18, at 16:43, Julian Reschke <[email-masked]> wrote:
> 
> Am 18.08.2021 um 01:08 schrieb heasley:
>> ...
>>> Or, if you actually want a list item containing two paragraphs:
>>> 
>>> <ol>
>>>    <li>
>>>      <t>bunch of hooey</t>
>>>      <t>more hoo-ah</t>
>>>    </li>
>>> </ol>
>> 
>> That works, but did not work for me originally and after your message I found
>> that I could not mix syntax like below.  Maybe using <t> throughout the <dl>
>> would work.
>> 
>> <ol>
>>    <li>
>>      bunch of hooey
>>      <t>more hoo-ah</t>
>>    </li>
>> </ol>
>> 
>> In all cases, the errors that it produced did not lead me to a solution.
> 
> Raise an issue (-> <https://trac.ietf.org/trac/xml2rfc>).
> 
> Best regards, Julian

As far as I can see, there is no support for mixed content between block-level elements (to which <t belongs) and text/span-level elements anywhere in the v3 grammar.

There are a few elements that can have sequences of text/span-level elements *or* sequences of block-level elements:

blockquote (but not aside!?)
li
dd (not dt!)
td/th

So while this may be confusing until one reads the grammar, this is at least somewhat consistent.

(It doesn’t help that there are elements like <contact that are allowed in both block-level and span-level contexts and change their semantics based on that context.)

A cleanup is clearly needed, but it would not help with this example.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Wed, 18 Aug 2021 17:01:12 +0200

> So while this may be confusing until one reads the grammar, this is at least somewhat consistent.

Absolutely. My suggestion was to raise a ticket for the non-helpful
diagnostics.

> (It doesn’t help that there are elements like <contact that are allowed in both block-level and span-level contexts and change their semantics based on that context.)

Indeed. (Guess what?)

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 18 Aug 2021 18:03:42 +0200

> Absolutely. My suggestion was to raise a ticket for the non-helpful

foo-broken.xml(623): Error: Element li has extra content: t, at /rfc/middle/section[2]/ul/li[1]/t
/.../foo-broken.xml(14): Error: Invalid document before running preptool.
Unable to complete processing foo-broken.xml

The line number turns out to be useful to me, as the XML editor is showing a validation error on the <t that follows text.

Creating useful error messages out of validation errors is generally impossible, as the grammar/schema has been abstracted of the information that could be used for a “why”/“what’s going on” part of the error message.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 19 Aug 2021 14:14:00 +0200

(You didn’t make your enlightened comment available to the xml2rfc list, which I’m doing herewith.)

Grüße, Carsten

> On 2021-08-19, at 09:05, Julian Reschke <[email-masked]> wrote:
> 
> Am 18.08.2021 um 18:03 schrieb Carsten Bormann:
> ...but of course that doesn't mean that the tool can't create better
> diagnostics. For instance, it could check certain things *before*
> validating.
> 
> Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 19 Aug 2021 14:21:12 +0200

> (You didn’t make your enlightened comment available to the xml2rfc list, which I’m doing herewith.)

Thanks.