Re: Markdown Extra Specification (First Draft)

[Michel Fortin]

Le 2008-05-06 à 18:18, Sherwood Botsford a écrit :

As a suggestion for the next pass at this, add an example of each,  
and how it should be rendered.

I found fireball's web site fairly lucid for this.


The content model section currently includes a basic description of  
each syntax element, but its primary goal is to explain the structure  
of a Markdown Extra document. The parsing section is intended to  
define without ambiguity the syntax for each element.


Nothing is set in stone though. I could, for instance, remove entirely  
the syntax description part from the document model and leave that  
entirely to the parsing section. I'll see what fits when I write the  
parsing section.




E.g.
Example abbreviation definition
*[TLA] :Three Letter Acronym

Note, If I'm reading this correctly then
* [TLA]: Three Letter Acronym

would be incorrect, as there is a space after the asterisk and after  
the colon.

It's also not clear if this critter has to appear on a line by itself.


This will be defined in more precise terms in due time. I'm not there  
just yet.


That said, I think the first one should be allowed, but not the second  
one. Putting a space before a colon is common in the French-speaking  
world, and don't think it causes a problem to allow it; whereas the  
second one is ambiguous with a list item and I'd rather have the user  
see a list item where he doesn't expect one than seeing a list item  
disappear because it looks like an abbreviation definition.


In fact, the first one is allowed by PHP Markdown Extra, but not the  
second one which becomes a list item.



If the abbreviation is long enough that it spans line ends, is that  
ok?


* [ODITLOID]: A Day in the Life of Ivan
Denisovich (Alexander Solzhenitsyn)


Currently, PHP Markdown Extra doesn't handle that very well. I'm not  
sure what will the final specification should say about this. I'll  
look at it when doing the parsing section.




***
A lot of the critters that appear as references aren't clear about  
how they

appear in the text, and how they appear when resolved. The footnote
dfinition starts with [^ but does the footnote in the text also  
start that way?


I'm not sure I understand your concern here. The spec may not be clear  
about that currently, but the spec's extra features are coming from  
PHP Markdown Extra, and so will follow PHP Markdown Extra's syntax.  
Please take a look at this document:





2.2.1 Link Reference

Quote:
A link reference is alone on a line. It begins with the reference  
name inside square brackets, optionally followed by a space or a no- 
break-space, a colon, a URI (either enclosed in angle brackets or  
not), and an optional title enclosed in single or double quotes, or  
in parenthesis (which can be preceded by a newline).



four things:
1. Sometimes the link is *(@*&^(^ long. So if I'm editing with vi, I  
have everything else in 60-70 column
lines, then this great bloody honker. I'd like an optional syntax  
for breaking a long URI into chunks.


Eg. the usual unix convention of \ with optional trailing whitespace
means continued on next line, with the \ and whitespace going to the  
bit bucket.


I'm not sure that's useful enough to justify the added complexity for  
parsers. But still, please remind me of this problem after I've done  
the part of the parsing section that deals with URLs.



2. I'd like some way to hook references to an external file, or  
database lookup instead of doing them internally.


That can be a parser feature; it's out of the scope of the  
specification.




3. Why three versions of quoting characters for the title?

4. Why the <> around the URI?


Because that's what Markdown.pl supports, alongside other  
implementations based on it such as PHP Markdown. I think that's the  
exact kind of detail that is under-documented right now and that is  
making life difficult for other implementers who want to be compatible  
with existing documents.




5. Only if you put the title in () can you start on a newline?


No idea. I haven't looked at the implications of this yet, but perhaps  
it could be done.




2.2.2 Abbreviation
Again, I'd like a hook so that I can put these in an external file.  
In my tree farm web page I'd like to use botanical descriptions, but  
be able to let users see the definition on mouse over or click. But  
the word 'glabrous' may appear on 40 pages. Be nice if I only had to  
define it once. If someone is creating an annotated Shakespeare they  
would want to use an Elizabethan English dictionary as their  
external file, style it so that defined words are barely different  
from the text, and let the confused reader click for enlightenment.


That should be an implementation-specific feature; perhaps we should  
make sure the spec doesn't disallow that.




2.2.2 footnotes

Note possible numbering error both abbreviation and footnotes are  
2.2.2


Oops... should

Re: Markdown Extra Specification (First Draft)

[Waylan Limberg]

Sherwood,

First of all, realize that Michel is currently documenting existing
behavior. I like some of our suggestions, but they should have
happened years ago when the discussion happened here on the list.
Various other implementations have copied the existing behavior and
there are countless documents already using them, so I doubt we'll see
any changes, unless we move to Markdown 2.0 or something. I get the
impression that's not likely any time soon.

Anyway, there were a few things I'll comment on individually:

On Tue, May 6, 2008 at 6:18 PM, Sherwood Botsford <[EMAIL PROTECTED]> wrote:
> As a suggestion for the next pass at this, add an example of each, and how
> it should be rendered.

I agree. I was going to make the same suggestion. This would be helpful.

[snip]
>  2.2.2 Abbreviation
>  Again, I'd like a hook so that I can put these in an external file. In my
> tree farm web page I'd like to use botanical descriptions, but be able to
> let users see the definition on mouse over or click. But the word 'glabrous'
> may appear on 40 pages. Be nice if I only had to define it once. If someone
> is creating an annotated Shakespeare they would want to use an Elizabethan
> English dictionary as their external file, style it so that defined words
> are barely different from the text, and let the confused reader click for
> enlightenment.

An excellent idea! After all, I had the same idea some time ago and
implemented it in the Abbreviation Extension [1] for Python-Markdown.
However, I'm not sure this should be a requirement of a syntax
specification.

[1]: http://achinghead.com/markdown/abbr/


As I noted above, the rest I'll leave to existing behavior, even if I
like your suggestion better. We don't want to forget J.G.'s motivation
and goals for creating markdown to start with. A review of that will
answer some of your questions about current behavior. And, we must
also never forget the (even as implementors) we should not care so
much about how hard it is to implement if it makes if easier (and more
permisive/relaxed) for the document author.



-- 

Waylan Limberg
[EMAIL PROTECTED]
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Markdown Extra Specification (First Draft)

[Sherwood Botsford]

As a suggestion for the next pass at this, add an example of each, and 
how it should be rendered.

I found fireball's web site fairly lucid for this.

E.g.
Example abbreviation definition
*[TLA] :Three Letter Acronym

Note, If I'm reading this correctly then
* [TLA]: Three Letter Acronym

would be incorrect, as there is a space after the asterisk and after the 
colon.

It's also not clear if this critter has to appear on a line by itself.

If the abbreviation is long enough that it spans line ends, is that ok?

* [ODITLOID]: A Day in the Life of Ivan
Denisovich (Alexander Solzhenitsyn)



***
A lot of the critters that appear as references aren't clear about how they
appear in the text, and how they appear when resolved. The footnote
dfinition starts with [^ but does the footnote in the text also start 
that way?


2.2.1 Link Reference

Quote:
A link reference is alone on a line. It begins with the reference name 
inside square brackets, optionally followed by a space or a 
no-break-space, a colon, a URI (either enclosed in angle brackets or 
not), and an optional title enclosed in single or double quotes, or in 
parenthesis (which can be preceded by a newline).




four things:
1. Sometimes the link is *(@*&^(^ long. So if I'm editing with vi, I 
have everything else in 60-70 column
lines, then this great bloody honker. I'd like an optional syntax for 
breaking a long URI into chunks.


Eg. the usual unix convention of \ with optional trailing whitespace
means continued on next line, with the \ and whitespace going to the bit 
bucket.


2. I'd like some way to hook references to an external file, or database 
lookup instead of doing them internally.


3. Why three versions of quoting characters for the title?

4. Why the <> around the URI?

5. Only if you put the title in () can you start on a newline?

2.2.2 Abbreviation
Again, I'd like a hook so that I can put these in an external file. In 
my tree farm web page I'd like to use botanical descriptions, but be 
able to let users see the definition on mouse over or click. But the 
word 'glabrous' may appear on 40 pages. Be nice if I only had to define 
it once. If someone is creating an annotated Shakespeare they would want 
to use an Elizabethan English dictionary as their external file, style 
it so that defined words are barely different from the text, and let the 
confused reader click for enlightenment.


2.2.2 footnotes

Note possible numbering error both abbreviation and footnotes are 2.2.2

How does the footnote appear in the text? For clarity in reading, all 
the things that refer to something else

should be visible different. E.g. In markdown we presently have
[link text ][LINKREF]
![Image alt text][IMGREF]
so
^[FOOTNOTE] (although I'd prefer _[FOOTNOTE] as it tells me it's below 
the ruler line at the bottom of the page)
Except from your text it appears it should be [^FOOTNOTE] which is at 
odds with the image and abbreviation

syntax.
How are footnotes numbered?

I think you could make a case for a footnote being the child of the 
block element that the reference appears in.
This may potentially allow clever people with CSS to have the footnote 
appear as a sidebar div, adjacent to the reference.


2.3.7 Table syntax

Suggested syntax
[TT] Table title
|[TH] elements | separated by pipes | with white space | on either side |
| anything | that | appears | with | leading and trailing |
| is | formated | as a | table row|

|> This cell spans two columns | and | so forth|
| This cell also spans two columns <| and | so forth|
|>> This cell spans three columns | in the | table |
| This cell spans two rows | in the | table|
| " " | because it has ditto marks | in the cell below |

Since many tables are done without a title or header, the pipe syntax is 
the usual.

You can spent some time pretty printing it.
Suggested implementation would have warnings when the number of cells 
per row is inconsistent.


2.4.2 and 2.4.3 Emphasis and strong emphasis.
The current markdown uses either _ or * for emphasis and any combination 
of the two
doubled for strong emphasis. I suggested that * be used for strong 
(default bold) and _ be used for emphasis.
(default italic) This gives three combinations possible with the same 
set of symbols, and fits the general

intuitive nature of markdown.

2.4.6 Hard line break
This one bites me regularly, as I learned to touch type in high school 
and to end a sentence with
a period followed by two spaces. This means that every time I end a 
sentence on a line end, I
get an involuntary break. Lots of head scratching over this one. I don't 
like markup that depends on invisible

trailing characters.

I would favour ending a line with a forward slash. You sometimes see 
this in poetry where line length exceeds
the column width. And it has an easy mnuemonic: If a back slash means 
concatenate the next line onto this one

then forward slash means, force the line break here.

Thus my address would appear

Sherwood Botsford /
RR 1 S