[eeps] New EEP draft: -discontiguous declaration

[Raimo Niskanen]

On Tue, May 31, 2011 at 10:48:09AM +1200, Richard O'Keefe wrote:
> 
> On 30/05/2011, at 9:49 PM, Raimo Niskanen wrote:
> 
> > On Mon, May 30, 2011 at 01:55:11PM +1200, Richard O'Keefe wrote:
> >> 
> >> On 28/05/2011, at 2:00 AM, Raimo Niskanen wrote:
> >> 
> >>> I'm sorry, we have changed EEP format into Markdown.
> >>> See EEP 33: http://www.erlang.org/eeps/eep-0033.html
> >>> 
> >>> I am not sure if this has been communicated properly,
> >> 
> >> I wasn't aware of this at all, and am rather upset about
> >> it.  Why should I have to learn a new markup language?
> >> What the X is Markdown, anyway?
> > 
> > It is a markup language in roughly the same spirit as the
> > previous (Python's reStructuredText) of what you see is what
> > you get. This one is more like plaintext mail.
> 
> I have now read the Markdown documentation.
> It is truly appalling.

But practical. Not the documentation that is...

> 
> We want to talk about Erlang in the EEPs, right?
> So why pick a notation in which I have to backslash
> escape all the square brackets?

Not quite. I find only a sequence like [a][b] or [a](b)
would need escaping. And only in normal text. When you want
to mark something as code you should use either
    indented_code() -> [no][problem]
or code markup `[inline][like,this]`.

> 
> What's more, Markdown is STRICTLY MORE COMPLEX THAN HTML.
> Proof: you can include HTML markup directly in Markdown,
> plus it adds a whole lot of extra hair.

Yes. Unfortunately. In theory.

> 
> I suggest the following criteria for a notation to be
> accepted for EEPs:
> 
> (1) The documents should be viewable in a standard browser
> without any plugins.  This suggests plain text and (X)HTML
> as the leading candidates.

Why in a standard browser, and why without any plugins?
I think it is more important it is viewable in unprocessed
form, in a standard text editor. So I go for plaintext.

But even with pure plaintext you would want style guides.
You can regard Markdown as a plaintext style guide.

> 
> (2) It should be possible for an author to write an EEP
> without having to bother about any escaping rules.  In
> particular, it should be possible to paste an arbitrary
> chunk of Erlang into an EEP without manual correction.
> This again suggests plain text and (X)HTML -- using an
> HTML editor like Amaya -- as the leading candidates.

It is actually almost there. Markdown is more like
plaintext than you claim. Not entirely, but practically.

XHTML source would be another alternative, but require
some kind of HTML editor, as you say. I think that will
for most people create a higher threshold to write an EEP.

> 
> (3) It should be possible to scan and index these
> documents using pretty much off-the-shelf tools.
> This again brings plain text and (X)HTML to the top.

What is wrong with like now a supplied simple
in-the-repository tool?

> 
> > We wanted to get rid of the cumbersome Python toolchain
> > with its tweaked docutils of specific version. Now all that
> > is required is a non-ancient Perl.
> > 
> > Also, the unprocessed Markdown EEPs are practically readable
> > in their Github repository since Github does on-the-fly
> > converting of Markdown when browsing. The EEPs are now
> > version controlled in Git on Github:
> >  https://github.com/erlang/eep
> >  https://github.com/erlang/eep/blob/master/eeps/eep-0033.md
> 
> This adds requirement
> 
> (4) It should be straightforward to keep the EEPs under
> version control using *any* version control system.
> Once again, plain text and (X)HTML come to the top.

It is.

It is just a bonus that the unprocessed EEPs look nice at Github.

> 
> > We also wanted to migrate from Subversion to Git for the EEPs
> > when we went to Git for Erlang/OTP. Markdown was a better fit
> > also because of the on-the fly conversion.
> 
> (X)HTML is an even *better* fit because of the ZERO conversion
> required.

*But* more than zero conversion is required to read the
EEP in your editor, unless you get and learn a HTML editor.
I have never used one.

I have used text editors and simple markup, though, and find it
practical.

> 
> >> (I can use (La)TeX, (X)HTML, Lout, or troff, but surely
> >> enough is enough?)
> > 
> > I will convert your two EEPs, and you can see what they look
> > like afterwards. It is mainly references that look much different.
> > It is a very low learning threshold.
> 
> Now that I have looked at the Markdown documentation, I am
> very concerned.  Markdown is at best strongly context sensitive
> and from the description it appears to be ambiguous.  Add to
> this the fact that there are now several variants of Markdown
> around, all of them with extensions, and not all of them with
> the same extensions.
> 
> In all honesty, for *me* by far the easiest way to produce
> Markdown will be to write a program to convert XHTML to Markdown.
> It is certainly MUCH less effort for me to write HTML than Markdown.

Naah. Have you tried?

I do not doubt it is less effort for you if you can use your
nicely broken in trusted favourite HTML editor. But if it is
MUCH less effort than to produce the plaintext EEPs you have
in the past i doubt. This is more or less just another style
of plaintext.

> 
> If you are not going to accept plain text any more,
> can I at least be allowed to use XHTML?
> 

Please have a look at these and see for yourself how much plaintext
they actually are:
    http://www.erlang.org/eeps/eep-0037.md
    http://www.erlang.org/eeps/eep-0038.md

If you continue to submit plaintext EEPS i would appreciate if
you use the Markdown (email) style of headings and code quote.
Then it will be a minimal work for me to correct any Markdown
glitches. Why not pick up EEP 37 as a template, or even
EEP 33; the effort should be really small.

For XHTML EEPS, I have no tools.

-- 

/ Raimo Niskanen, Erlang/OTP, Ericsson AB