Subject: Re: [edu-team] [rfc-i] Kramdown lovers lunch today

From: Mirjam Kuehne <[email-masked]>
Date: Tue, 20 Jan 2015 14:02:55 +0100

Hi Carsten,

Would you be still available to give a tutorial in Dallas?

Kind regards,
Mirjam

On 13/11/14 21:47, Carsten Bormann wrote:
>> You're a bit late, since we are currently planning the Prague tutorials…
> 
> Count me in.
> (And I’ll happily take that Dallas slot.)
> 
>> Is there an I-D on using kramdown?
> 
> Right on the 22nd place of my to-do-list from this meeting.
> (It will mainly contain material from https://github.com/cabo/kramdown-rfc2629/blob/master/README.md, but probably in a more accessible way.)
> 
> Grüße, Carsten
> 
> _______________________________________________
> edu-team mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/edu-team
>

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 20 Jan 2015 15:17:27 +0100

> Would you be still available to give a tutorial in Dallas?

Absolutely!

(I haven't completed the travel planning for Dallas but do expect to be
there.)

Grüße, Carsten

---

From: Mirjam Kuehne <[email-masked]>
Date: Tue, 20 Jan 2015 15:43:42 +0100

Fantastic. Thanks, Carsten! Do you have a preferred time slot: 13:00 or
15:00 or would both times work?

Mirjam

---

From: Mirjam Kuehne <[email-masked]>
Date: Tue, 20 Jan 2015 21:24:59 +0100

Hi Carsten,

One more question: Will there be another speaker who will give the
tutorial together with you? And could you please send us a short
description of the tutorial that we can add to the announcement on the
web site.

Thanks,
Mirjam

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 21 Jan 2015 10:39:28 +0100

> 15:00 or would both times work?

Hi Mirjam,

15:00 might actually be better as it looks like there is going to be
something else going on in the morning.

I don't think we need to have multiple people to run this, but of course
I would be happy to add anyone if that comes up.

Below is a short intro (in markdown format :-), building on your
proposed text.

Grüße, Carsten

Writing RFCs in markdown and a bit of YAML
==========================================

Speaker: Carsten Bormann

Time: IETF 92, Sunday [13:00 or 15:00]

Writing RFCs has traditionally involved some finicky Word templating
or hard-to-use (and read!) XML.  Recently, it has become more popular
in many communities to write text in the plaintext-like markdown
format.  Tools have emerged that also allow RFC writing in markdown.
We'll look at what's available and then focus on the "kramdown" set
of tools, which enhances markdown with some structured YAML for the
management of references.  Bring a laptop with a current version of
Ruby (≥ 1.9) -- we'll do some exercises, and hands-on questions are
welcome!

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 23 Jan 2015 20:26:46 +0100

Hi Mirjam,

your recent message made me think maybe you didn't see this one...

Grüße, Carsten

Hi Mirjam,

Grüße, Carsten

Speaker: Carsten Bormann

---

From: Mirjam Kuehne <[email-masked]>
Date: Fri, 23 Jan 2015 21:17:33 +0100

Thanks, Carsten. No, I hadn't seen this message. I passed the info on to
secretariat.

Have a nice weekend,
Mirjam

---

From: Alice Russo <[email-masked]>
Date: Fri, 23 Jan 2015 13:23:20 -0800

Carsten,

A few questions about this description and a nit.

When using kramdown-rfc2629, is there an XML file created that runs with xml2rfc? If so, I suggest adding a sentence about that because it's a selling point. (Having an XML file is to the authors' advantage, especially in the future.) 

> Tools have emerged that also allow writing I-Ds in markdown.

> We'll look at what's available and then focus on the "kramdown" set

Specifically, does this tutorial cover using markdown as in Pandoc2rfc (RFC 7238)?  I suggest listing any specific tools that will be covered.

Nit: I suggest changing "RFC" to "I-D" in the title & description, as this is a tool to help authors write I-Ds.  (Only a portion of I-Ds are approved and become RFCs.) Updated text below.

Thanks,
Alice

Writing I-Ds in markdown and a bit of YAML
==========================================

Speaker: Carsten Bormann

Writing I-Ds has traditionally involved some finicky Word templating
or hard-to-use (and read!) XML.  Recently, it has become more popular
in many communities to write text in the plaintext-like markdown
format.  Tools have emerged that also allow writing I-Ds in markdown.
We'll look at what's available and then focus on the "kramdown" set
of tools, which enhances markdown with some structured YAML for the
management of references.  Bring a laptop with a current version of
Ruby (≥ 1.9) -- we'll do some exercises, and hands-on questions are
welcome!

---

From: Alice Russo <[email-masked]>
Date: Fri, 23 Jan 2015 13:27:06 -0800

I wrote:
> Pandoc2rfc (RFC 7238)

correction: RFC 7328

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 26 Jan 2015 21:18:52 +0100

Hi Alice,

thank you for these good suggestions.

> When using kramdown-rfc2629, is there an XML file created that runs
> with xml2rfc? If so, I suggest adding a sentence about that because
> it's a selling point. (Having an XML file is to the authors'
> advantage, especially in the future.)

Yes, kramdown-rfc2629 converts into RFCXML.
Indeed, this information should be added.
(What is today's correct, but reasonable short way to say RFCXML?
"XML file that runs with xml2rfc" is unambiguous, but long.)

> Specifically, does this tutorial cover using markdown as in Pandoc2rfc
> (RFC 7238)?  I suggest listing any specific tools that will be
> covered.

How long is this paragraph supposed to be?
Yes, the RFC 7328 solution will be covered in principle, but working
with it is not in focus.
I have updated the text below to make this clearer.

Mirjam: I'm no longer so sure 1 hour will be enough.
Can you schedule this for 15-16:30, so I still have a fighting chance to
see at least some of meet and greet?

> Nit: I suggest changing "RFC" to "I-D" in the title & description, as
> this is a tool to help authors write I-Ds.  (Only a portion of I-Ds
> are approved and become RFCs.) Updated text below.

While this is undoubtedly true, people do seem to think they are writing
I-Ds in order for them to become RFCs.  So from a tutorial marketing
point of view, I think it is better to say "writing RFCs".
RFC 7328 meets in the middle with "Writing I-Ds and RFCs"; I'll follow
that compromise for now.  So this updates the announcement as below.

Grüße, Carsten

Writing RFCs and I-Ds in markdown and a bit of YAML
===================================================

Speaker: Carsten Bormann

Time: IETF 92, Sunday 15:00..16:30

Writing I-Ds has traditionally involved some finicky Word templating or
typing up hard-to-use (and read!) XML.  Recently, it has become more
popular in a wide range of communities to write text in the
plaintext-like "markdown" format.  Tools have emerged in the IETF that
allow writing I-Ds in markdown, automatically converting into the XML
format accepted by the RFC editor (and performing a number of chores in
the process that used to be manual work).

We'll look at what's available and then focus on the "kramdown" set of
tools, which enhances markdown with a bit of structured YAML for the
management of references.  We'll also look at popular workflows that
minimize manual work while optimizing collaboration with co-editors and
contributors.  Bring a laptop with a current version of the programming
language Ruby (≥ 1.9) -- we'll do some exercises, and hands-on questions
are welcome!

---

From: Mirjam Kuehne <[email-masked]>
Date: Tue, 27 Jan 2015 09:31:02 +0000

Hi Carsten,

The tutorial slot is scheduled from 15:00 - 17:00, so you should have
enough time. Maybe clarify to the audience before you start that you
plan to end around 16:30, so people don't start running out at 15:00.

I'll pass the amended description on to the secretariat.

Cheers,
Mirjam

---

From: Alice Russo <[email-masked]>
Date: Tue, 27 Jan 2015 10:23:06 -0800

> "XML file that runs with xml2rfc" is unambiguous, but long.)

I've heard various ways, but unfortunately I don't think there's a better one.

> that compromise for now. 

OK; thanks for the compromise.

Alice