[eeps] New EEP draft: -discontiguous declaration

[Raimo Niskanen]

This is getting too lengthly. I'll be brief and top-post.

Our requirements:
* The EEPs 'sources' should be plaintextish
* They should be convertable to nice looking HTML
  without having to install a complex tool chain.
* The markup language should preferably be something that
  is commonly used.
* We do not regard writing XHTML in a text editor as feasible
  and regard having to use a XHTML editor as too odd.

Markdown delivers this. If you check out the EEP repository
and have Perl you have the toolchain. A browser is needed
to view the result, and a code / plaintext editor of course.

Oh, and the generated HTML supports horizontal resizing.
It is both sites www.erlang.org and www.github.com that
does strange things. I'll have to take a look at the former.

What is missing:
* A complete syntax and documentation. Markdown lacks here.
* Formal verification tools. I did not know that was missing.
  I write, process, check the result. More tools than that
  I have never needed for these small text documents. Even
  if there was a formal verification tool I'd have to view
  the result.

If someone would write a Markdown dialect syntax definition,
and an accompaning maybe Erlang tool for conversion to XHTML,
that would be an option. Preferably narrowing down what
Markdown allows to make the new dialect good looking when
assumed to be original Markdown.

When you say we allowed plaintext before, that was not
entirely true. That plaintext was processed by docutils
to produce links to other EEPs, I think to find other
http://.../ links and reference list, etc. So if that
plaintext was not properly written I had to fix it.

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.

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

Best regards
/ Raimo Niskanen



On Wed, Jun 01, 2011 at 12:48:35PM +1200, Richard O'Keefe wrote:
> 
> 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...

-- 

/ Raimo Niskanen, Erlang/OTP, Ericsson AB