Re: [Emo-dir] quick-start guides

[Toerless Eckert <[e-mail]>]

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

On Mon, Jan 31, 2022 at 10:45:20AM +0200, Lars Eggert wrote:
> 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 <[e-mail]> wrote:
> > 
> > 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
> > _______________________________________________
> > Emo-dir mailing list
> > [e-mail]
> > https://www.ietf.org/mailman/listinfo/emo-dir
> 



> _______________________________________________
> Emo-dir mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/emo-dir


-- 
---
[e-mail]