[eeps] New EEP draft: -discontiguous declaration

[Richard O'Keefe]

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.

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?

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.

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.

(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.

(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.

> 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.

> 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.

>> (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.

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