[eeps] New EEP draft: -discontiguous declaration

Tue Jun 7 12:00:35 CEST 2011

On Thu, Jun 02, 2011 at 03:56:48PM +1200, Richard O'Keefe wrote:
> 
> 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.

Yes, but use the new template.

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

From http://daringfireball.net/projects/markdown/ - Introduction:
> ... While Markdown's syntax has been influenced by several existing
> text-to-HTML filters, the single biggest source of inspiration for
> Markdown's syntax is the format of plain text email.

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

Yes that is an ugly one.

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

A Markdown document looks as plain text when you view it; plain text email.
That is another possible view of "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?

From http://daringfireball.net/projects/markdown/syntax#code:
> To include a literal backtick character within a code span, you can use
> multiple backticks as the opening and closing delimiters:
>     ``There is a literal backtick(`) here.``

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

./build.pl builds any file named eeps/eep-[0-9][0-9][0-9][0-9].md,
so if you copy the template eeps/eep-0033.md to e.g eeps/eep-9999.md
and edit it it will be built into eeps/eep-9999.html. You can of course
choose any number that is not occupied, but I thought 9999 was a nice
temporary number to use.

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

That it produces body content that can become valid XHTML when
included in an XHTML file did not surprise me that much when
thinking about how it normally is used, that is as a part
of a containing page.

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

My bad. I thought it looked nice to get a normally long title
into one line. But that should be a stylesheet issue. Anyway
I did it like this in the template and did not realize it was
a standard violation. Browsers handle it well.
I'll fix it when I get the time.

Is text before first <h1> allowed? I.e the <pre><code>...
</code></pre><hr /> section?

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

That sounds like the smallest fix.

> 
> 
> 

-- 

/ Raimo Niskanen, Erlang/OTP, Ericsson AB