Subject: [xml2rfc] Inline use of <sourcecode>

From: Roger Price <[email-masked]>
Date: Mon, 18 Jan 2021 13:58:29 +0100 (CET)

I'm trying to work out how to markup a protocol token in running text since 
there seems be no inline version of <sourcecode> in the way that HTML has 
<code>.

It looks as if <sourcecode> is the correct element since RFC 7991 clause 2.48 
https://tools.ietf.org/html/rfc7991#page-59 says:

  « ...  When <sourcecode> is a child of <figure> or <section>, it provides
    full control of horizontal whitespace and line breaks...
    (When <sourcecode> is a child of other elements, it flows with the text
    that surrounds it.) »

I tried the markup:

  <t>(a) Protocol token <sourcecode>LB</sourcecode> <t>indicates a low battery.
  <t>(b) Protocol token <tt>LB</tt> indicates a low battery.

In the .txt file it produces

    (a) Protocol token

    LB

    indicates a low battery.

    (b) Protocol token "LB" indicates a low battery.

and in the .html file it produces

   (a) Protocol token

       LB

   indicates a low battery.

   (b) Protocol token LB indicates a low battery.

Comments:

1. Correct: The LB's are correctly formatted in the HTML in a monospaced font.

2. Bug: In both outputs (a), although <sourcecode> is a child of <t> it does not 
flow with the text as stated in the RFC.

3. Ugly: In the txt file, (b) sees the token OB adorned with quote characters 
which are not part of the protocol.  The txt and html files do not agree.

4. Ugly: A <t> element is needed after <sourcecode> since <sourcecode> is not 
behaving as a true inline element.

What is the recommended way of marking up inline source code?

Roger

---

From: Anders Rundgren <[email-masked]>
Date: Mon, 18 Jan 2021 14:09:40 +0100

> there seems be no inline version of <sourcecode> in the way that HTML has

Hi Roger,
I have used <tt> successfully:

https://www.ietf.org/archive/id/draft-jordan-jws-ct-01.html#name-canonicalize-the-json-objec
https://tools.ietf.org/html/draft-jordan-jws-ct-01#section-3.1.2

Are you using the on-line version?
The "" around <tt> objects for RfcMarkup appears to have been removed; 8 months ago they were there...

Thanx,
Anders

> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc
>

---

From: Anders Rundgren <[email-masked]>
Date: Mon, 18 Jan 2021 14:13:21 +0100

Pardon me, the "ugly" is still there for RfcMarkup..

Anders

---

From: Julian Reschke <[email-masked]>
Date: Mon, 18 Jan 2021 14:20:44 +0100

Am 18.01.2021 um 13:58 schrieb Roger Price:
> I'm trying to work out how to markup a protocol token in running text
> since there seems be no inline version of <sourcecode> in the way that
> HTML has <code>.
>
> It looks as if <sourcecode> is the correct element since RFC 7991 clause
> 2.48 https://tools.ietf.org/html/rfc7991#page-59 says:
>
> 2. Bug: In both outputs (a), although <sourcecode> is a child of <t> it
> does not flow with the text as stated in the RFC.
>
> 3. Ugly: In the txt file, (b) sees the token OB adorned with quote
> characters which are not part of the protocol.  The txt and html files
> do not agree.
>
> 4. Ugly: A <t> element is needed after <sourcecode> since <sourcecode>
> is not behaving as a true inline element.
>

There currently is no provision for inline source code. The statement

>    [RFC5234] or the RNC notation used in this document).  (When
>    <sourcecode> is a child of other elements, it flows with the text
>    that surrounds it.)  Tab characters (U+0009) inside of this element
>    are prohibited.

is misleading because <sourcecode> is a true block-level element, see
<https://greenbytes.de/tech/webdav/rfc7991.html#rfc.section.2.48.p.6>.

If xml2rfc "accepts" it as a child element of <t>, that's a bug.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 18 Jan 2021 14:35:21 +0100

> If xml2rfc "accepts" it as a child element of <t>, that's a bug.

The v2v3 converter does, and it splits the <t> and places the sourcecode outside the <t> as a block element.

The examples given are missing the </t> end tags that are needed to make the examples work.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Mon, 18 Jan 2021 14:37:50 +0100

> The examples given are missing the </t> end tags that are needed to make the examples work.

Interesting. Why does the conversion step touch elements that are not v2?

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 18 Jan 2021 14:43:32 +0100

> Interesting. Why does the conversion step touch elements that are not v2?

The conversion is meant to help with the transition and therefore allows mixtures of v2 and v3 elements.  Apparently, it tries to generate valid v3 in all cases.

Grüße, Carsten

---

From: Roger Price <[email-masked]>
Date: Mon, 18 Jan 2021 16:12:24 +0100 (CET)

> The examples given are missing the </t> end tags that are needed to make the examples work.

My apologies, I mark up in SGML with lots of tag omission and then use an SGML 
parser to produce fully tagged XML.  I wrongly showed the example in SGML, the 
corresponding XML is

<t>(a) Protocol token </t>
<sourcecode>LB</sourcecode>
<t>indicates a low battery.
</t>
<t>(b) Protocol token <tt>LB</tt> indicates a low battery.
</t>

which shows that <sourcecode> is indeed a child of a previous <section>. 
My mistake, sorry.

I shall follow Anders: <tt> is the best choice.

Roger