Subject: [Emo-dir] quick-start guides

From: Alice Russo <[email-masked]>
Date: Thu, 27 Jan 2022 10:11:34 -0800

As discussed today. Outlines below as potential starting points.

Alice
--

A) Quick-start guide for editing in XML
   - Start with a file (an existing I-D or template [1]).
   - Edit it w/ the software of your choice.
     -> Tip: Rely on the citation library by using xi:include [2].
   - Convert it using https://author-tools.ietf.org.
   - Upload it to the I-D submission tool [3].
   - Share it and update it.

B) Quick-start guide for editing in markdown (specifically kramdown-rfc2629)
   - Start with a file (an existing I-D or template [4]).
   - Edit it w/ the software of your choice.
     -> Tip: Rely on the citation library by using a YAML header [5].
   - Convert it using https://author-tools.ietf.org.
   - Upload it to the I-D submission tool [3].
   - Share it and update it.

Note: If you prefer a GitHub workflow, see instructions on [6].

[1] https://github.com/ietf-authors/rfcxml-templates-and-schemas/blob/main/draft-rfcxml-general-template-standard-00.xml
[2] https://authors.ietf.org/references-in-rfcxml
[3] https://datatracker.ietf.org/submit/
[4] https://github.com/martinthomson/internet-draft-template/blob/main/draft-todo-yourname-protocol.md
[5] https://github.com/cabo/kramdown-rfc2629#references
[6] https://github.com/martinthomson/i-d-template/blob/main/doc/TEMPLATE.md

---

From: Mirja Kuehlewind <[email-masked]>
Date: Fri, 28 Jan 2022 11:38:16 +0100

Thanks. I think that’s exactly what is needed. And I also revise my own statement from yesterday: I guess providing both xml and md makes sense as this is easy enough. Now we only need to to layout it nicely and put it in as many places as possible :-)

> On 27. Jan 2022, at 19:11, Alice Russo <[email-masked]> wrote:
> 
> _______________________________________________
> Emo-dir mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/emo-dir
>

---

From: Lars Eggert <[email-masked]>
Date: Mon, 31 Jan 2022 10:45:20 +0200

Hi,

do we want to (strongly) recommend kramdown-rfc2629 esp. for new documents?

It has a significantly lower bar than editing directly in XML.

Thanks,
Lars

> On 2022-1-27, at 20:11, Alice Russo <[email-masked]> wrote:
>

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 31 Jan 2022 12:15:55 +0100

On 2022-01-27, at 19:11, Alice Russo <[email-masked]> wrote:
> Convert

I have a slight problem with this word.

Convert, to many, implies a one-time activity.
“Let’s convert this library to C++ so it is easier to maintain”…

What we mean here is something that is done after each round of editing.

Maybe we need a better term for formatting documents.
“Formatting” may be more familiar to people who have used LaTeX or similar at the university.
“Rendering” is another word, but maybe even more of an in-group term.
“Printing” is something a Word user would do, “Print to PDF”.

Grüße, Carsten

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 31 Jan 2022 16:23:49 +0100

I would strongly recommend kramdown-rfc2629, but...

I think we need some better documentation / tooling pieces first to avoid
users to maybe become frustrated:.

1. Instead of Matin Thomsons template, i would suggest a template that
has (ideally) an instance of every formatting option:
- a table, - figure, - an instance of every paragraph formatting etc. pp.
at least what the xml template has: https://github.com/ietf-authors/rfcxml-templates-and-schemas/blob/main/draft-rfcxml-general-template-standard-00.xml

2. If you want to start changing an existing I-D in MD and there is
no github, but only datatracker, you need to retrieve an existing MD via
the XML: Every XML on datatracker that was generated by kramdown-rfc2629
contains a compressed version of the MD source. I couldn't find a tool
to extract the MD from the XML though. it is  easy to write it yourself (base64
or the like, don't quite remember), but would strngly suggest to have a pointer
to such a tool. 

3. It might be helpful to have on authors.ietf.org a page also documenting
MD formatting. The doc on cabos github is kinda hmm... all over the place,
but not complete for the formatting pieces ?

4. aplicable to MD and XML: I would add to the templates also elements
that are not mandatory, but very useful: 
- a terminology section (references to a defined term in such a section
  are somewhat of a pain. Have not tried to see how good that works in MD).
- A changelog section (helps WG chairs and others a lot if these are done well).

Cheers
    Toerless

-- 
---
[email-masked]

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 1 Feb 2022 00:28:26 +0100

On 31. Jan 2022, at 16:23, Toerless Eckert <[email-masked]> wrote:
> 
> I couldn't find a tool
> to extract the MD from the XML though.

It’s called kramdown-rfc-extract-markdown 

   kramdown-rfc-extract-markdown myfile.xml >myfile.md

Documented at:

https://github.com/cabo/kramdown-rfc2629#upconversion

Grüße, Carsten

---

From: Jay Daley <[email-masked]>
Date: Tue, 1 Feb 2022 16:29:41 +1300

> On 1/02/2022, at 12:15 AM, Carsten Bormann <[email-masked]> wrote:
> 

The standard term used by the tools team is "rendering".  This predates me so I don’t the know origins but authors.ietf.org uses this term and "converting" where "rendering" would be hard to understand.  I agree that it has a one-time implication but some times we just need to pick a word.

Jay

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Jay Daley <[email-masked]>
Date: Tue, 1 Feb 2022 16:44:13 +1300

When I looked at quick start guides before the new year there were some unanswered questions getting in the way.

1. As below, do we recommend Markdown over XML or let people choose?  The authors site currently lets people choose but that can change.

2. Do we recommend kramdown-rfc over mmark or let people choose?  kramdown-rfc is used much more than mmark so that would be fair but it’s still odd that we should pick a winner.

3.  Do we recommend going straight in with Martin Thompson’s templates?  The recommendation from Ekr on another list was "I would think one with XML and one with Markdown and a separate one for how to use MT's ID tools, which means Github."

If we’re going to include all of those then that’s four quickstarts and they still need to choose between them.  Doable but not as snappy as perhaps we might hope.

Any thoughts?

Jay

> On 31/01/2022, at 9:45 PM, Lars Eggert <[email-masked]> wrote:
> 
> Signed PGP part
> Hi,
> 

--
Jay Daley
IETF Executive Director
[email-masked]

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 1 Feb 2022 06:16:25 +0100

> 1. As below, do we recommend Markdown over XML or let people choose?  The authors site currently lets people choose but that can change.

Afaik, XML was never designed for direkt human writing. Mardown is.
Arguably this means that we should have and recommend a markdown
language for writing.

As i said in my prior mail, if we recommend then this puts us in a bit
of a bind to document/tool-support the markdown as much as the XML (IMHO).
Aka: additional work for tools team (although i think it's not much work).

> 2. Do we recommend kramdown-rfc over mmark or let people choose?  kramdown-rfc is used much more than mmark so that would be fair but it’s still odd that we should pick a winner.

I would just put "recommend" into context. It just means that the recommended
choice is the one where tools team will spend resources on and where it
seems more members of the community can provide peer-2-peer support.

> 3.  Do we recommend going straight in with Martin Thompson’s templates?  The recommendation from Ekr on another list was "I would think one with XML and one with Markdown and a separate one for how…

Repeating: I would like to see a template that has an instance of all
important formatting options and all useful sections, and have it the
same for XML as for markdown. The XML template is already quite good,
the markdown one weak.

No opinions about the importance of the github piece.

> If we’re going to include all of those then that’s four quickstarts and they still need to choose between them.  Doable but not as snappy as perhaps we might hope.

I'd start with kramdown-rfc markdown and XML quickstarts.

Toerless

-- 
---
[email-masked]