[eeps] New EEP draft: -discontiguous declaration

[Richard O'Keefe]

On 31/05/2011, at 9:10 PM, Raimo Niskanen wrote:

>> I have now read the Markdown documentation.
>> It is truly appalling.
> 
> But practical. Not the documentation that is...

The question is whether it is *more* practical than (X)HTML.

> Not quite. I find only a sequence like [a][b] or [a](b)
> would need escaping. And only in normal text.

You *find*.  What a telling phrase that is.
The plain fact of the matter is that there is no precise
implementation-independent description of Markdown.
We *are* told that [a]  [b] and [a]    (b)  are legal
syntax.  We are *not* told that [a] without a following
[ or ( will be accepted, or, if accepted, what will
happen.  If I should write [A[i],j), will that be taken
as plain text, or will it start with "A[i" and go looking
for something more?

FROM THE DOCUMENTATION I CANNOT TELL.

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

If you *don't* want the documents to be viewed in a browser,
there isn't the slightest *point* in using Markdown.  It
does nothing that plain text cannot do better.

If you *do* want the documents to be viewed in a browser,
then plugins have two nasty problems:  they may not be
available for particular browsers at all (Amaya, Emacs-W3,
iCab) or may have version skew problems (when I upgraded
from FireFox 3 to FireFox 4 a lot of things went away and
have not come back yet).

> I think it is more important it is viewable in unprocessed
> form, in a standard text editor. So I go for plaintext.

BUT YOU DO NOT ACCEPT PLAIN TEXT ANY MORE!

> But even with pure plaintext you would want style guides.

We had one.  What was wrong with it?

> You can regard Markdown as a plaintext style guide.

And you can regard a visit to the dentist as a social
occasion.  That doesn't make it a _happy_ social occasion.

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

No, *PRACTICALLY* it is an underspecified mess of
special treatment for a host of punctuation marks.
I do not regard a notation that I cannot find a clear
definition of as *practical*.  I would have to type
up markdown text with vigilant trepidation, and would
have *no* grounds for believing that markdown text
acceptable to a tool chain I had installed was also
acceptable to yours, especially given that you are
requiring style rules that are not enforced by such
tool chains.

> XHTML source would be another alternative, but require
> some kind of HTML editor, as you say.

Well, no, I didn't quite say that.  I do _have_ HTML
editors (about 5 of them, come to think of it), but
when I personally write HTML, I find it quicker and
easier to use a text editor.  However, other people
may find it otherwise, and for *them* using an HTML
editor is as easy as using a word processor.

> I think that will
> for most people create a higher threshold to write an EEP.

Using say Amaya, the markup would be entirely invisible to
the author.  What a marked contrast to Markdown!
>> 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.

Let's be clear here.
I don't want to stop anyone else using Markdown (and never did
want to stop anyone using ReStructured Text).
What I want is to be allowed to use something
	SIMPLER
	MORE READABLE
	BETTER DEFINED
namely plain text.

OK.  Plain text has one problem when viewed in a browser window.
On reflection, I'm almost ready to grant that this is a
show-stopper.  Or _would_ be...  The problem is that when you
make your browser window narrower (so as to view several things
at once, perhaps), plain text is not re-flowed to fit.

BUT NEITHER IS THE HTML DELIVERED FOR THE EEPS NOW!

Is this an artefact of using Markdown?
It's certainly an inconvenience when using a browser.

I'm not all that good at CSS.  Could it be the fault of
#main_div{
	position:relative;
	width:979px;
	margin:auto;
	text-align:left;
	height: 100%;
} 
in style.css?  I've certainly learned that setting sizes
in terms of numbers of pixels is almost always a Bad Idea.
979px turns up a lot; why anyone thinks that has any
relevance to my screen resolution or browser window width
escapes me.

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

Netscape came with a built in HTML editor.
SeaMonkey has a descendant of that one.
There's BlueGriffon, which I am about to try.
OpenOffice/LibreOffice lets you edit HTML.
I have a fondness for Amaya.

All free, all easily usable by anyone who has used a
word processor.
>> 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?

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

The order of difficulty is
(1) Plain text.
    Dead simple.  What you see really is what you get.
(2) HTML, either typed in by hand or using an HTML editor.
    There are precisely two special characters to worry
    about in plain text (< and &) and my editor has a
    single key binding "convert region to HTML data".
    There are plenty of tools to deal with it.
(3) Markdown.  It *isn't* plain text.  It is complex
    and sadly underdocumented.  It is supposed to generate
    HTML but there are simple things to do in HTML that are
    (or seem to be) hard in Markdown.  I *don't* have any
    tools to convert in either direction between plain
    text and Markdown.

Markdown is NOT "just another style of plaintext".
Markdown is MARKUP.  Quirky, underdocumented, markup.

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

I clearly haven't communicated my discomfort.
It's not a question of how MUCH markup is needed when using
Markdown.  It's a question of NOT KNOWING what is going to
work and what is not.

I see that I shall have to write a 'downmarkit' tool...