Subject: Re: [xml2rfc] xml to markdown?

From: Robert Moskowitz <[email-masked]>
Date: Thu, 1 Aug 2019 21:34:11 -0400

Report on my first real experience reading a kramdown draft (what is the 
difference between kramdown and markdown?).

The .md file of my .xml is cryptic.  There is a lot of assumed 
knowledge.  Stuff you have to remember to format right.

Well xml has to be formatted right, but it is a rigorous structure that 
your editor can pretty much tell you have it right, even before you run 
xml2rfc.

Perhaps there is a plugin for Geany, but with xml, it is easy to close 
the sections I am not working on and be able to focus on the work at 
hand.  My time writing and moving around in the draft is thus more 
focused and better spent.

I suppose things grow on us.  I will continue to look at this new stuff, 
but for now will stay with xml.

On 7/31/19 2:33 PM, Andrew G. Malis wrote:
> Bob,
>
> While I don't have such a tool (although Carsten may), I do have a 
> draft that uses a lot of kramdown features, please feel free to use it 
> as a template. I use the tools at 
> https://xml2rfc.tools.ietf.org/experimental.html for converting 
> kramdown to text. In the top dialog box, "Convert Your XML Source", 
> choose kramdown rather than xml2rfc as the input type. I go straight 
> to text rather than generating xml as an intermediate step, although 
> that option is available further down on that same page.
>
> I've attached my draft source and output so that you can compare them 
> side by side.
>
> Cheers,
> Andy
>
>
> On Wed, Jul 31, 2019 at 2:10 PM Robert Moskowitz <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     I am having to work with people that prefer markdown for creating
>     their
>     IDs.  They go the md -> xml -> ID route.
>
>     I have yet to figure out how to read markdown drafts let alone
>     work with
>     that format.
>
>     Is there a tool I can use to convert my xml to markdown so that I can
>     see what I have been doing looks like in markdown and see if all
>     the xml
>     features I use (like hangtext in defs) are mapped to markdown?
>
>     thanks
>
>     _______________________________________________
>     xml2rfc mailing list
>     [email-masked] <mailto:[email-masked]>
>     https://www.ietf.org/mailman/listinfo/xml2rfc
>

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 2 Aug 2019 08:17:40 +0200

On Aug 2, 2019, at 03:34, Robert Moskowitz <[email-masked]> wrote:
> 
> Report on my first real experience reading a kramdown draft (what is the difference between kramdown and markdown?).

kramdown is an implementation of a markdown processor.
kramdown-rfc2629 (or kramdown-rfc for short) is a tool that uses kramdown as its markdown implementation and generates RFCXML.

> The .md file of my .xml is cryptic.  There is a lot of assumed knowledge.  Stuff you have to remember to format right.

Right, there is the markdown syntax (which many of us use daily anyway), and then there is some syntax to support referencing and other RFC-specific things.  Syntax that gets in the way much less than XML does.

> Well xml has to be formatted right, but it is a rigorous structure that your editor can pretty much tell you have it right, even before you run xml2rfc.

Markdown syntax is supported by many editors.  But there is little need for that, as markdown syntax is intuitive (*).

(*) intuitive is another word for familiar.  If you don’t encounter markdown in your daily life a lot, there is some learning involved for it to become familiar…

More importantly, markdown lends itself to a slightly different style of working than XML:

Just write.  You can always worry about syntax later.

XML-supporting editors tend to provide this straightjacket that you have to work in, so you are concerned with the syntax before you actually can lay down text.  (And then, there are things like PIs where they don’t help at all.)

(Interestingly, I’m a zero tolerance guy when it comes to the actual writing, but I don’t care about tool syntax very much while doing so — the focus is on the text.)

> Perhaps there is a plugin for Geany,

Geany plugins don’t seem to be able to support code folding.

> but with xml, it is easy to close the sections I am not working on and be able to focus on the work at hand.  

It seems the code folding built in to Geany doesn’t support markdown (tried with 1.33).

I don’t run surveys on things like this but it seems most editors these days do support markdown, including code folding where that is a standard feature of the editor (e.g., use the TAB key in emacs markdown-mode).  Too bad that Geany doesn’t.

> My time writing and moving around in the draft is thus more focused and better spent.

An editor that supports code folding is indeed a useful tool to have.

> I suppose things grow on us.  I will continue to look at this new stuff, but for now will stay with xml.

So no need to convert the other XML file?

Grüße, Carsten

---

From: Robert Moskowitz <[email-masked]>
Date: Fri, 2 Aug 2019 12:51:31 -0400

> kramdown-rfc2629 (or kramdown-rfc for short) is a tool that uses kramdown as its markdown implementation and generates RFCXML.

Only kramdown rpm is rubygem-kramdown.  I doubt if that will help me.

> Right, there is the markdown syntax (which many of us use daily anyway), and then there is some syntax to support referencing and other RFC-specific things.  Syntax that gets in the way much less t…

Is there a manual for the syntax and special content like how the 
address structure works and things like the BCP14 boilerplate?

To me, the xml syntax helps me visualize the data structure of the 
document.  But then I am dyslexic.

> More importantly, markdown lends itself to a slightly different style of working than XML:

That last point is putting it mildly.  I have NO other encounters with 
markdown in my daily life let alone monthly life!  Whereas xml is like 
html and I do hand coding of my web pages (see www.htt-consult.com, 
particularly the 'new' stuff).

And there is nothing intuitive about markdown.  It is all rout 
learning.  IMHO.

> XML-supporting editors tend to provide this straightjacket that you have to work in, so you are concerned with the syntax before you actually can lay down text.  (And then, there are things like PI…

I find it easy.  Create a section with anchor, make a text block, and 
start writing.    And much of that is copy and paste.

What is PIs?

> (Interestingly, I’m a zero tolerance guy when it comes to the actual writing, but I don’t care about tool syntax very much while doing so — the focus is on the text.)

The focus is not just the text but the flow of the document.  As I 
write, I want to work at seeing that one part flows into another.

> Geany plugins don’t seem to be able to support code folding.

I installed the geany-markdown plugin.  All it seems to do is colorize 
some command text and does not get all that kramdown uses. And no 
'folding' (I assume this is the term for collapsing a block of text)

> It seems the code folding built in to Geany doesn’t support markdown (tried with 1.33).

And the markdown pluging does not help.

> I don’t run surveys on things like this but it seems most editors these days do support markdown, including code folding where that is a standard feature of the editor (e.g., use the TAB key in ema…

Can you provide names of a couple?  I will also ask on the  Fedora user 
list.

> So no need to convert the other XML file?

I did send you a 2nd one last night.

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 2 Aug 2019 20:01:01 +0200

Hi Bob,

> On Aug 2, 2019, at 18:51, Robert Moskowitz <[email-masked]> wrote:
> 

The recommended way to install kramdown-rfc2629 is

gem install kramdown-rfc2629

(Some platforms need a sudo here; you’ll notice if it doesn’t work without.)

Of course, there is also the web service, but given that the tool is so easy to install, I would recommend trying that first.
(A little more work for Windows users…)

> Is there a manual for the syntax and special content like how the address structure works and things like the BCP14 boilerplate?

Writing a manual is on my backlog.
Up to then, try http://rfc.space

> What is PIs?

Processing instructions, things like  <?rfc subcompact="no" ?>  and 	<?rfc include=“reference.RFC.7401.xml"?>  (the second one is not the usual way to write these, BTW).

> The focus is not just the text but the flow of the document.  As I write, I want to work at seeing that one part flows into another.

Which is easy to see in the unobliterated view that markdown provides…

But, yeah, folding helps.

> Can you provide names of a couple?  I will also ask on the  Fedora user list.

Since I’ve been pretty much wed to emacs for the last 31 years, I don’t analyze the scene a lot.
Atom (and sublime) are the tools that my students like, if they don’t go all the way to emacs (or vim, but that is a different story).

> I did send you a 2nd one last night.

Will do, then.

Grüße, Carsten

---

From: "Andrew G. Malis" <[email-masked]>
Date: Fri, 2 Aug 2019 17:44:42 -0400

Bob,

Did you try reading the markdown source that I sent you? It's "native"
source written from scratch rather than converted from XML. You might find
it easier as a semi-tutorial. I find it extremely straightforward to write
in markdown.

Cheers,
Andy

On Fri, Aug 2, 2019 at 12:51 PM Robert Moskowitz <[email-masked]>
wrote:

> >> Report on my first real experience reading a kramdown draft (what is
> the difference between kramdown and markdown?).
> > kramdown-rfc2629 (or kramdown-rfc for short) is a tool that uses
> kramdown as its markdown implementation and generates RFCXML.
>
> > Right, there is the markdown syntax (which many of us use daily anyway),
> and then there is some syntax to support referencing and other RFC-specific
> things.  Syntax that gets in the way much less than XML does.
>
> > Markdown syntax is supported by many editors.  But there is little need
> for that, as markdown syntax is intuitive (*).
> >
> > (*) intuitive is another word for familiar.  If you don’t encounter
> markdown in your daily life a lot, there is some learning involved for it
> to become familiar…
> >
> > XML-supporting editors tend to provide this straightjacket that you have
> to work in, so you are concerned with the syntax before you actually can
> lay down text.  (And then, there are things like PIs where they don’t help
> at all.)
>
> > (Interestingly, I’m a zero tolerance guy when it comes to the actual
> writing, but I don’t care about tool syntax very much while doing so — the
> focus is on the text.)
>
> > I don’t run surveys on things like this but it seems most editors these
> days do support markdown, including code folding where that is a standard
> feature of the editor (e.g., use the TAB key in emacs markdown-mode).  Too
> bad that Geany doesn’t.
>