[eeps] New EEP draft: -discontiguous declaration

Thu Jun 2 05:56:48 CEST 2011

On 2/06/2011, at 3:26 AM, Raimo Niskanen wrote:
> If you submit EEPs in plaintext now, do in the "mail style"
> (Markdown), and add the mail like headers at the top.
> Then I will not have to reindent the whole document to
> make it Markdown.

I do not understand this.

There are *three* things mentioned here:
• plain text
• "mail style"
• Markdown

I understand what plain text is.
All the EEPs I ever submitted were in plain text format;
the same format, copied from the original template.
Line length limit, indentation as required, the lot.

I have no idea what "mail style" signifies.
(I _am_ aware of MIME's Rich Text Format, not to be
confused with Microsoft's.  Is that what this means?)

I have read the Markdown syntax document, and have a
vague idea of what it is, because that's all it gives
one.  But the grammar of the sentence uses apposition
in a way that suggests that "plaintext" and "(Markdown)"
are supposed to refer to the same thing, and they cannot.
Markdown is most emphatically NOT a plain text format.

Don't you just love little gotchas like

+       Tweaked the rules for link definitions so that they must occur
        within three spaces of the left margin. Thus if you indent a link
        definition by four spaces or a tab, it will now be a code block.

                   [a]: /url/  "Indented 3 spaces, this is a link def"

                    [b]: /url/  "Indented 4 spaces, this is a code block"

Something which might appear as text or might be taken as data and not
appear in the text depending on the number of preceding spaces is not
by any stretch of the imagination plain text.

Since code spans are delimited by `...` and backslash processing is not
done in them, how do you get a backquote into a code span?

The "Markdown Readme.text" file is scary...

> Or, check out the EEP repository; or from Github you can
> download it as a .tar.gz file.
> Edit eeps/eep-9999.md, ./build.pl, Browse eeps/eep-9999.html

Well, ever cooperative, I did just that.
Downloaded the .tar.gz (a little tricky because there is no
'git' on this machine: rcs cvs svn hg even darcs but no git).
Unpacked it, and are my eyes deceiving me?

There is no eeps/eep-9999.md

Markdown is supposed to produce XHTML, we are told.
However,

	perl md/Markdown.pl eeps/eep-0033.md > 33.htm

does not produce well-formed XML (the rock bottom entry level
requirement for something to count as XHTML), let alone valid
XHTML.

m% tidy 33.htm >/dev/null
line 1 column 1 - Warning: missing <!DOCTYPE> declaration
line 1 column 1 - Warning: inserting implicit <body>
line 1 column 1 - Warning: inserting missing 'title' element
Info: Document content looks like HTML 3.2

The headings are used wrongly in eep-0033.md,
at least according to Markdown.pl.  Looking in the output we
see

<h2>EEP 33: Sample Markdown EEP Template</h2>

<h1>Abstract</h1>

where the main title is <h2> instead of <h1> and
the section titles are <h1> instead of <h2>.
"There are six levels of headings in HTML with H1 as the
most important and H6 as the least." -- HTML 4.01; XHTML 1.0
is defined by reference to this.  ISO HTML makes it a hard
rule that you *must* have an H1 outside an H2 if you have an
H2 at all.  It looks extremely odd with small letters for
the title and huge letters for "abstract".

If <h1> is to be used for the section headings,
then the main title must also be <h1>.