Subject: [Rfc-markdown] Triple Parentheses vs. Triple Braces

From: Carsten Bormann <[email-masked]>
Date: Tue, 11 Aug 2020 16:55:07 +0200

For those who don’t know what the subject line is talking about, please have a quick look at:

https://en.wikipedia.org/wiki/Triple_parentheses

ASCIIDOC uses (((term))) as the notation to put “term” into the index at its point  (“concealed index term”), a convention that kramdown-rfc copies for its markdown dialect.  
(I’m not planning to fix anything about this until ASCIIDOC offers a replacement that would fit well with markdown; in any case, I’d only add another convention.
Fortunately, the index functionality of RFCXML is rarely used in RFCs.)

With the rise of RFCXMLv3, now I need a more friendly notation for the construct 

	<contact fullName=“Nguyễn Ái Quốc”/>

Am I a complete idiot to think that {{{Nguyễn Ái Quốc}}} is a good way to express this in kramdown-rfc’s markdown dialect, the above notwithstanding?  
It would never be visible as such in published material, only in the markdown source code.

[Searching RFCs, RFC 6386 contains the line
           union mv          chroma_mv[4] = {{{0}}};
in some source code; triple braces are not used anywhere else that I can find.
For another random example, note that Trac's wiki syntax uses {{{…}}} for monospace/code; but there are usually no names of people in those braces.
Since the slur was only invented in 2014, these notations predate that.]

Alternative notations that avoid the obvious trap, are still as easy to read and type, and don’t create new backwards compatibility nightmares, are expressly solicited.  

Sorry for the cross-posting to ietf@; we don’t have a mailing list for this kind of subject yet.  (In case it wasn’t clear, I’m looking for serious opinions here.)

Grüße, Carsten

---

From: Marc Petit-Huguenin <[email-masked]>
Date: Tue, 11 Aug 2020 08:18:28 -0700

Not directly answering, but in AsciiDoc I would suggest `[contact]#Nguyễn Ái Quốc#`, which is similar to the notation for <bcp14> (https://www.metanorma.com/author/ietf/topics/markup/#inline-formatting).

-- 
Marc Petit-Huguenin
Email: [email-masked]
Blog: https://marc.petit-huguenin.org
Profile: https://www.linkedin.com/in/petithug

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 11 Aug 2020 17:41:12 +0200

(Shortening to rfc-markdown:)

> On 2020-08-11, at 17:18, Marc Petit-Huguenin <[email-masked]> wrote:
> 
> [contact]#Nguyễn Ái Quốc#

If I do take this as a potential suggestion for kramdown-rfc, I have to say this is not much better than directly writing <contact fullName=“Nguyễn Ái Quốc”/>.

What I specifically do not like in the markdown context is that it inserts additional words into what would otherwise just be a slightly decorated, readable paragraph.  Brackets/braces/parentheses are also designed to invade less into their content than what the hash-mark does here.  Compare:

> [contact]#Nguyễn Ái Quốc#
> {{{Nguyễn Ái Quốc}}}

https://asciidoctor.org/docs/user-manual/#index-terms suggests something like 

> contact:[Nguyễn Ái Quốc]

which is a bit better, but still has the additional word that breaks the reading flow.

Grüße, Carsten

---

From: Marc Petit-Huguenin <[email-masked]>
Date: Wed, 12 Aug 2020 14:33:48 -0700

> which is a bit better, but still has the additional word that breaks the reading flow.

I now actually read the latest version of the schema, and I think that indeed `contact:[name]` (i.e. an inline macro) is the right way to encode a <contact>, because it also permits to encode the other attributes.

I also discover that <author> and <contact> can now be part of a <section>, so block macros should do the trick there:

contact::[name]

author::[name]

I agree that these do not blend in the text as well, but this is not unusual in AsciiDoc which is not, like Markdown, text with markings, but a translation of DocBook.

---

From: Julian Reschke <[email-masked]>
Date: Thu, 13 Aug 2020 05:57:56 +0200

Am 12.08.2020 um 23:33 schrieb Marc Petit-Huguenin:
> ...
> ...

No, <author> is not supposed to be allowed in <section>. If xml2rfc
accepts that, we should submit a bug report.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 14 Aug 2020 08:47:54 +0200

> accepts that, we should submit a bug report.

It is currently in v3.rnc:

   section =
     element section {
       attribute xml:base { text }?,
       attribute xml:lang { text }?,
       attribute anchor { xsd:ID }?,
       attribute pn { xsd:ID }?,
       attribute title { text }?,
       [ a:defaultValue = "true" ]
       attribute numbered { "true" | "false" }?,
       [ a:defaultValue = "default" ]
       attribute toc { "include" | "exclude" | "default" }?,
       [ a:defaultValue = "false" ]
       attribute removeInRFC { "true" | "false" }?,
       name?,
       (artset
        | artwork
        | aside
        | author
        | blockquote
        | contact
        | dl
        | figure
        | iref
        | ol
        | sourcecode
        | t
        | table
        | texttable
        | ul)*,
       section*
     }

Without consulting the source, it seems to be handled like a block-level contact.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Fri, 14 Aug 2020 11:26:17 +0200

> It is currently in v3.rnc:

It is, because the RNC regrettably reflects what xml2rfc uses internally
to pass the output of the "prep" stage to formatters. It's not supposed
to be used in user input, and it would be a bug if it did.

Best regards, Julian