Subject: [xml2rfc-dev] v3 XML template feature request

From: Tom Pusateri <[email-masked]>
Date: Wed, 23 Jan 2019 13:35:00 -0500

When I start a new draft, I always look for the most recent templates to start from in order to minimize pain.

Usually, I look here:

https://tools.ietf.org/tools/templates/

Currently, there is a v2 template that is not obviously the best starting place:

https://tools.ietf.org/tools/templates/davies-template-bare-06.xml

But since I’m starting fresh, I thought I would try to exercise the new v3 tools and I don’t see a template for that.

I think it would be nice if xml2rfc would add a - - template option that would grab the latest known good template from somewhere and place it in the current directory for you (or a —v2_template/—v3_template)

Thanks,
Tom

---

From: "Andrew G. Malis" <[email-masked]>
Date: Mon, 28 Jan 2019 10:06:54 -0500

Tom,

Seeing as you're starting fresh, why not give kramdown a try? I like it a
lot better than xml (v2 or v3), it's much easier to focus on the writing
rather than the coding.

I use the online converter at
https://xml2rfc.tools.ietf.org/experimental.html , but you can run it
locally as well if you want (see https://github.com/cabo/kramdown-rfc2629 ).

Cheers,
Andy

On Wed, Jan 23, 2019 at 1:54 PM Tom Pusateri <[email-masked]> wrote:

> But since I’m starting fresh, I thought I would try to exercise the new v3
> tools and I don’t see a template for that.
>
> I think it would be nice if xml2rfc would add a - - template option that
> would grab the latest known good template from somewhere and place it in
> the current directory for you (or a —v2_template/—v3_template)
>
> Thanks,
> Tom
>
>
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev
>

---

From: Tom Pusateri <[email-masked]>
Date: Mon, 28 Jan 2019 10:31:00 -0500

Thanks. I did and found I needed a bit more visual structure than it provided. XML is too much visual structure but in this case preferable. 

Maybe someday I’ll have time to create something in the middle of these two options using JSON or TOML...

Thanks,
Tom

> On Jan 28, 2019, at 10:06 AM, Andrew G. Malis <[email-masked]> wrote:
> 
> Tom,
> 
> Seeing as you're starting fresh, why not give kramdown a try? I like it a lot better than xml (v2 or v3), it's much easier to focus on the writing rather than the coding.
> 
> I use the online converter at https://xml2rfc.tools.ietf.org/experimental.html , but you can run it locally as well if you want (see https://github.com/cabo/kramdown-rfc2629 ).
> 
> Cheers,
> Andy
> 
>

---

From: Ronald Tse <[email-masked]>
Date: Mon, 28 Jan 2019 17:30:09 +0000

Hi Tom,

Or you could try out Metanorma (https://www.metanorma.com), which is based on AsciiDoc syntax.

The specific syntax called AsciiRFC it uses (and numerous examples of it) is specified in an I-D here (https://datatracker.ietf.org/doc/draft-ribose-asciirfc/).

The minimal template is provided here: https://github.com/riboseinc/rfc-asciirfc-minimal

Hope this helps!

Ron

_____________________________________

Ronald Tse
Ribose Inc.

+=========================================================+
This message may contain confidential and/or privileged
information.  If you are not the addressee or authorized to
receive this for the addressee, you must not use, copy,
disclose or take any action based on this message or any
information herein.  If you have received this message in
error, please advise the sender immediately by reply e-mail
and delete this message.  Thank you for your cooperation.
+=========================================================+

On Jan 28, 2019, at 11:31 PM, Tom Pusateri <[email-masked]<mailto:[email-masked]>> wrote:

Maybe someday I’ll have time to create something in the middle of these two options using JSON or TOML....

Thanks,
Tom

On Jan 28, 2019, at 10:06 AM, Andrew G. Malis <[email-masked]<mailto:[email-masked]>> wrote:

Tom,

Cheers,
Andy

On Wed, Jan 23, 2019 at 1:54 PM Tom Pusateri <[email-masked]<mailto:[email-masked]>> wrote:
When I start a new draft, I always look for the most recent templates to start from in order to minimize pain.

Usually, I look here:

Thanks,
Tom

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

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 28 Jan 2019 18:45:47 +0100

On Jan 28, 2019, at 16:31, Tom Pusateri <[email-masked]> wrote:
> 
> Thanks. I did and found I needed a bit more visual structure than it provided.

That’s interesting.  
What kind of structure were you looking for?
Section structure?

Of course, it helps to use a markdown-aware source editor (such as markdown-mode in Emacs) to better visualize the structure.

What is the editor you made this experience with?

> XML is too much visual structure but in this case preferable. 

More importantly, XML is too much noise.
(You still occasionally need to fall back into XML when using kramdown-rfc, though.)

> Maybe someday I’ll have time to create something in the middle of these two options using JSON or TOML….

Seriously, I hope not.  

HUMANS SHOULD NOT BE WRITING JSON [1].  TOML is actually designed for that, but still, both TOML and JSON would make exceedingly bad authoring formats for documents.

(We also have a nice collection of quite good humane authoring formats already, one each based on org-mode and asciidoc, and several based on markdown.  Maybe time to dial down invention a bit.)

Grüße, Carsten

[1]: https://duckduckgo.com/?q=%22HUMANS+SHOULD+NOT+BE+WRITING+JSON%22
(Use YAML or TOML if you have to.)

---

From: Tom Pusateri <[email-masked]>
Date: Mon, 28 Jan 2019 18:12:27 -0500

Carsten,

I’ve tried TextMate 2 on macOS, vim, and Sublime Text. All have Markdown modes but the distinctions between sections, subsections,  and paragraphs just aren’t enough for me.

Yes, agree that XML is too much noise but the whitespace distinctions in Markdown and the terse separators are not sufficient separators for me. Collapsing would also be nice but that’s not an option for Markdown in any editor I’ve seen.

AsciiDoc doesn’t seem any better in this sense.

Yes, JSON is probably not the right thing but whitespace based formatting is not either.

Thanks,
Tom

> On Jan 28, 2019, at 12:45 PM, Carsten Bormann <[email-masked]> wrote:
>

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 29 Jan 2019 07:44:35 +0100

> I’ve tried TextMate 2 on macOS, vim, and Sublime Text. All have Markdown modes but the distinctions between sections, subsections,  and paragraphs just aren’t enough for me.

I’m not working daily with these but some of these may have parameters for making the distinction stand out more.

> Yes, agree that XML is too much noise but the whitespace distinctions in Markdown and the terse separators are not sufficient separators for me. Collapsing would also be nice but that’s not an opti…

Markdown-mode in Emacs certainly does collapsing (TAB key).
(Unfortunately, that does not tolerate the way kramdown usually takes anchors on sections.)

> Yes, JSON is probably not the right thing but whitespace based formatting is not either.

Clearly, a lot of people think the markdown syntax works well…
Maybe it also helps to use “setext” style headers, as in

Introduction
============

As opposed to the terser “atx” style:

# Introduction

Grüße, Carsten

---

From: Ronald Tse <[email-masked]>
Date: Tue, 29 Jan 2019 08:36:10 +0000

Hi Tom,

Perhaps if you don’t mind would you mind showing a sample on what kind of separators seem sufficient? Are you looking for text editor support, or actual deliminators in text?

I think a lot of people here are interested in how that looks like. :-)

Ron

Ronald Tse
Ribose Inc.

On Jan 29, 2019, at 2:44 PM, Carsten Bormann <[email-masked]<mailto:[email-masked]>> wrote:

On Jan 29, 2019, at 00:12, Tom Pusateri <[email-masked]<mailto:[email-masked]>> wrote:

Carsten,

Introduction
============

# Introduction

Grüße, Carsten

---

From: Tom Pusateri <[email-masked]>
Date: Tue, 29 Jan 2019 13:51:38 -0500

> On Jan 29, 2019, at 3:36 AM, Ronald Tse <[email-masked]> wrote:
> 
> Hi Tom,
> 

I realize I am being set up here but I’ll play along. :-)

Here’s a rudimentary TOML example based on the davies template. I’m not suggesting this is the correct way to do it in TOML or that TOML is the correct choice for file format. But it gets the point across. It’s lighter handed than XML but a bit more visual reference points than Markdown with explicit section, subsection, paragraph boundaries.

Tom

---

From: Ronald Tse <[email-masked]>
Date: Wed, 30 Jan 2019 01:01:24 +0000

Hi Tom,

Absolutely not a setup — we’re all looking to improve authoring methods using plaintext!

Here’s an example of AsciiRFC of the https://github.com/riboseinc/rfc-asciirfc-minimal template (with minor modifications for readability).

It looks quite similar to the setup in TOML, except:

1. Whitespace delimited paragraphs ("it’s a feature not a bug" ;-))
2. The “author” attributes aren’t hierarchical, I admit the “_2” syntax is ugly.

Are there any other particular parts that aren’t good for you?

Ron

Ronald Tse
Ribose Inc.

On Jan 30, 2019, at 2:51 AM, Tom Pusateri <[email-masked]<mailto:[email-masked]>> wrote:

On Jan 29, 2019, at 3:36 AM, Ronald Tse <[email-masked]<mailto:[email-masked]>> wrote:

Hi Tom,

Ron

Tom

<Screen Shot 2019-01-29 at 1.48.32 PM.png>

---

From: Miek Gieben <[email-masked]>
Date: Wed, 30 Jan 2019 09:01:46 +0000

There is also mmark, see mmark.nl, in similar vein as kramdown. You use
markdown, the header is in TOML though.

Using TOML throughout is an interesting idea.

On Wed, 30 Jan 2019, 01:01 Ronald Tse <[email-masked] wrote:

> Here’s an example of AsciiRFC of the
> https://github.com/riboseinc/rfc-asciirfc-minimal template (with minor
> modifications for readability).
>
> On Jan 30, 2019, at 2:51 AM, Tom Pusateri <[email-masked]> wrote:
>
>
> Perhaps if you don’t mind would you mind showing a sample on what kind of
> separators seem sufficient? Are you looking for text editor support, or
> actual deliminators in text?
>
> Here’s a rudimentary TOML example based on the davies template. I’m not
> suggesting this is the correct way to do it in TOML or that TOML is the
> correct choice for file format. But it gets the point across. It’s lighter
> handed than XML but a bit more visual reference points than Markdown with
> explicit section, subsection, paragraph boundaries.
>
> Tom
>