Subject: [xml2rfc-dev] RFC 7991: issue #41: Target audience for writing XML

From: Miek Gieben <[email-masked]>
Date: Thu, 4 Oct 2018 07:29:59 +0100

Hi all,

Forwarded from issue #41:

Do we target humans writing XML directly, or it this spec mean to for other 
languages (i.e. markdown) to compile to?

If "humans" would should aim (IMO) for a consistent spec where attribute names 
are consistent and not that numerous and there aren't a lot of exceptions on 
where what elements can be used.

If we let something compile to XML we could relax this is bit. Although my 
experience with using markdown is that a lot of the details carry over to the 
markdown as well; making it easy to generate an illegal document.

/Miek

--
Miek Gieben

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 4 Oct 2018 14:35:11 +0000

On 3 Oct 2018, at 23:29, Miek Gieben wrote:

> Do we target humans writing XML directly, or it this spec mean to for other languages (i.e. markdown) to compile to?

Definitely both. In particular, some humans will want to start with a template in XML, or with the XML that was generated from an old RFC. Other humans will want to work just in Markdown or similar formats.

> If "humans" would should aim (IMO) for a consistent spec where attribute names are consistent and not that numerous and there aren't a lot of 
> exceptions on where what elements can be used.

Consistent: that seems like a fine goal. It is stymied by the fact that v3 is a version of v2, which had its own consistency issues. It is also stymied by the fact that v3 was developed over time and different parts had more focus. Still, if we can make it more consistent without making it harder to covert from v2, that's probably worth doing.

Not that numerous: As long as the numerous ones are optional, I would disagree. In probably >90% of the cases that were added, this was for added functionality that will make the resulting documents have more useful metadata, display better, or both.

Not lots of exceptions: I guess I'm inured to XML attributes having lots of exceptions, and that probably leads to specs that are more complicated.

> If we let something compile to XML we could relax this is bit. Although my experience with using markdown is that a lot of the details carry over to 
> the markdown as well; making it easy to generate an illegal document.

Conversion from Markdown and similar formats has always been a mixed bag. FWIW, I normally start new documents in Markdown. When the v3 spec is finished and usable as a publication format, I will certainly look at my Markdown-to-XML output for a particular draft and see if the extras that I might get from sprinkling in my own XML is worth the pain of then living in XML only.

--Paul Hoffman