Re: Optional features (was: Markdown Extra Specification (First Draft))

[Aristotle Pagaltzis]

* Yuri Takhteyev <[EMAIL PROTECTED]> [2008-05-24 21:35]:
> * Aristotle Pagaltzis <[EMAIL PROTECTED]> [2008-05-24 11:15]:
> > If your XHTML parser has a streaming input mode, you can
> > couple your Markdown converter directly to the XHTML parser
> > and feed the HTML output to it as you go. If the XHTML parser
> > throws a well-formedness error, you can then relate it to
> > the vicinity of the last Markdown chunk you converted to HTML
> > and passed into the XHTML parser.
> 
> I am not quite sure what you mean, but Markdown documents can't
> always be processed on a chunk by chunk basis. Consider:
> 
> Here is a [link][id].
> 
> ... 100KB of text...
> 
> [id]: http://example.com/  "Optional Title Here"
> 
> This document cannot be processed correctly unless it's
> considered all at the same time.

Good point, so streaming the Markdown input is not possible. But
that doesn’t mean you can’t generate the output piecemeal and
also feed it to the XHTML parser that way.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Optional features (was: Markdown Extra Specification (First Draft))

[Yuri Takhteyev]

> It seems to me that filtering is a red herring in your case. If
> you want to allow users to enter literal tags, you will have this
> problem whether you filter the ultimate output or not.

If I want to allow them, then yes, but this is not the case I was
considering.  Suppose I do _not_ want to allow them to enter HTML
tags.  This is easy to implement as an option in a Markdown converter.
 However, if the converter doesn't do that, then I have a much harder
task: user's tags are now mixed with Markdown's tags, and I have to
figure out how to sort them out.  There _is_ a difference between the
 inserted by markdown and the  inserted by the user.  I know
Markdown's em will be balanced.  I am not sure that the user's will
be.  At this point the only way to be sure that the HTML is valid is
to parse it.

> If your XHTML parser has a streaming input mode, you can couple
> your Markdown converter directly to the XHTML parser and feed the
> HTML output to it as you go. If the XHTML parser throws a well-
> formedness error, you can then relate it to the vicinity of the
> last Markdown chunk you converted to HTML and passed into the
> XHTML parser.

I am not quite sure what you mean, but Markdown documents can't always
be processed on a chunk by chunk basis. Consider:

Here is a [link][id].

... 100KB of text...

[id]: http://example.com/  "Optional Title Here"

This document cannot be processed correctly unless it's considered all
at the same time.

> If you don't want to couple the Markdown converter with an XHTML
> parser that closely, it's still possible to do this, but the
> Markdown converter will have to be able to accept streaming input
> itself and will need to generate output sufficiently frequently
> that you can track the correlation of input and output with a
> useful amount of precision.

Sure, if you want to drop support for references, footnotes, etc.  But
it's much simpler to implement a "safe mode" that escapes or validates
all HTML submitted by the user.

  - yuri

-- 
http://sputnik.freewisdom.org/
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Optional features (was: Markdown Extra Specification (First Draft))

[Aristotle Pagaltzis]

* Yuri Takhteyev <[EMAIL PROTECTED]> [2008-05-23 08:35]:
> * Aristotle Pagaltzis <[EMAIL PROTECTED]> [2008-05-23 05:40]:
> > I also agree with your opposition to them; if anything, one
> > should filter the *output* of a Markdown-to-HTML conversion
> > so that it won't matter whether people write literal ``
> > tags or use asterisks.
> 
> This is true in theory... I actually just recently write
> something along those lines in Lua [1] to use with my Lua wiki.
> The idea is to do as you suggest: Convert from MD to HTML
> first, then filter the HTML. To make it safe, I parse HTML as
> XHTML and complain if it doesn't parse. Hence a problem: if the
> user screws up with their HTML (and my filter is pretty
> unforgiving), it becomes hard to communicate to them what went
> wrong. I can tell them where there is a problem in the overall
> HTML, but this doesn't help much, since the user didn't know
> there was all of this HTML to begin with.

It seems to me that filtering is a red herring in your case. If
you want to allow users to enter literal tags, you will have this
problem whether you filter the ultimate output or not.

> There is no easy way to show them where the problem occurred
> relative to the input that they provided, or to show them the
> content with just _their_ HTML escaped. So, a good solution in
> Markdown itself actually would be a good thing.

If your XHTML parser has a streaming input mode, you can couple
your Markdown converter directly to the XHTML parser and feed the
HTML output to it as you go. If the XHTML parser throws a well-
formedness error, you can then relate it to the vicinity of the
last Markdown chunk you converted to HTML and passed into the
XHTML parser.

It will sometimes be an earlier chunk; eg. if the user writes
` ` (notice the missing semicolon) and this is exacly at end
of string in the HTML chunk you pass to the XHTML parser, then
the XHTML parser will have to wait until the next chunk before
it can decide that that entity is broken.

If you don’t want to couple the Markdown converter with an XHTML
parser that closely, it’s still possible to do this, but the
Markdown converter will have to be able to accept streaming input
itself and will need to generate output sufficiently frequently
that you can track the correlation of input and output with a
useful amount of precision. The glue code that combines the
Markdown converter with the XHTML parser will have to do some
relatively hairy (tho not very complex) bookkeeping in that case.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Optional features (was: Markdown Extra Specification (First Draft))

[Yuri Takhteyev]

> I also agree with your opposition to them; if anything, one
> should filter the *output* of a Markdown-to-HTML conversion
> so that it won't matter whether people write literal ``
> tags or use asterisks.

This is true in theory...  I actually just recently write something
along those lines in Lua [1] to use with my Lua wiki.  The idea is to
do as you suggest: Convert from MD to HTML first, then filter the
HTML.  To make it safe, I parse HTML as XHTML and complain if it
doesn't parse.  Hence a problem: if the user screws up with their HTML
(and my filter is pretty unforgiving), it becomes hard to communicate
to them what went wrong.  I can tell them where there is a problem in
the overall HTML, but this doesn't help much, since the user didn't
know there was all of this HTML to begin with.  There is no easy way
to show them where the problem occurred relative to the input that
they provided, or to show them the content with just _their_ HTML
escaped.  So, a good solution in Markdown itself actually would be a
good thing.

  - yuri

[1]: http://sputnik.freewisdom.org/lib/xssfilter/

-- 
http://sputnik.freewisdom.org/
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Optional features (was: Markdown Extra Specification (First Draft))

[Aristotle Pagaltzis]

* Michel Fortin <[EMAIL PROTECTED]> [2008-05-23 04:35]:
> I'm not sure those "features" should be formally part of the
> spec. I believe however that if the spec is well written it
> should be pretty trivial to see what must be changed to achieve
> them.

Yeah, I don’t think they belong in the spec itself either.

I also agree with your opposition to them; if anything, one
should filter the *output* of a Markdown-to-HTML conversion
so that it won’t matter whether people write literal ``
tags or use asterisks. In both cases the resulting HTML is
benign, so why disallow those tags? OTOH disallowing literal
tags in the input means you cannot write a ``
with a `cite` attribute, since Markdown provides no syntax
for that. Scrubbing the input indiscriminately therefore
removes functionality for no benefit at all.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Optional features (was: Markdown Extra Specification (First Draft))

[Michel Fortin]

Le 2008-05-22 à 2:10, Aristotle Pagaltzis a écrit :


It is, mind, perfectly fine to have two (or maybe three?) specs
of which one is a superset of the other, as seems to be Michel’s
current thrust with Markdown vs Markdown Extra. Assuming that no
feature in either spec is optional, that means you would be able
to expect Markdown Extra documents to work in all Markdown Extra
processors, and all Markdown documents to work in all Markdown
and Markdown Extra processors. The scope of the problem is much
smaller in such a scenario, enough so to be perfectly tractable.


I perfectly agree with this by the way: optional features should be  
kept to a minimum. It may be interesting to note there are currently  
two configurable parsing-related[^1] in PHP Markdown:


Tab width (default = 4)

:   This one comes from a similar configuration option in
Markdown.pl and is essentially the size in spaces for one
indent through a Markdown document. When John Gruber says
"four spaces or one tab" in his syntax description document,
he really means " spaces or one tab", where
tab-width is a configurable parameter defaulting to 4.

I'm not aware of anyone changing this parameter, and I'm not
even sure of how well it works, but it is clear that changing
this will break many documents written with a different tab
width in mind.

No markup (default = false)
No entities (default = false)

:   This one prevents the parser from skipping over HTML tags
and/or HTML character entities. I was originally opposed to
it, and in some way I still am. I decided to add it because
there was too much people attempting to disable HTML by
preprocessing the input with strip_tags or a substitution
regular expression without realizing they were breaking
automatic links, code spans and code blocks with HTML in
them, and sometimes blockquotes.

I'm no fan of this mode, but I feel it was the best way to
avoid people breaking the syntax by accident, so I've added
it in.

I'm not sure those "features" should be formally part of the spec. I  
believe however that if the spec is well written it should be pretty  
trivial to see what must be changed to achieve them.


[^1]:
A "parsing-related setting" is a setting that changes the
interpretation of the document given in output. The oposite
is an "output-related setting", which changes the HTML
output but does not affect the interpretation the parser
makes of the document.


Michel Fortin
[EMAIL PROTECTED]
http://michelf.com/


___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Optional features (was: Markdown Extra Specification (First Draft))

[Allan Odgaard]

On 22 May 2008, at 08:10, Aristotle Pagaltzis wrote:


[...]
Optional features are dangerous and impede interoperability.

Everyone who ever thinks about chipping in on the design of
a spec should read [section 5 of RFC 3339][1]. [...]


I love how it says:

[...] A format which includes rarely used options is
likely to cause interoperability problems [...] The
format defined below includes only one rarely used
option: fractions of a second. [...]

Which reminds me of when svn started to report fractions of seconds in  
their ‘svn log --xml’ output, causing a few log visualizers to break :)


___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Optional features (was: Markdown Extra Specification (First Draft))

[Aristotle Pagaltzis]

* Sherwood Botsford <[EMAIL PROTECTED]> [2008-05-07 22:10]:
> THAT said, however, maintaining perfect backward compatibility
> slows down progress.

I don’t know. It seems to me perfect backward compatibility is
not even possible, considering that Markdown.pl is not set in
stone (John takes bug reports and writes fixes, every so often)
and yet is not formally defined anywhere. As such, there is no
way to say what is backward compatible and what isn’t. I think
at most, backcompat for the purposes of a spec for Markdown can
only be defined as targetting a particular feature set, but not
an exact implementation of it.

That is, after all, the entire reason for the spec effort in the
first place.

> Can markdown extra have a configuration file:
> The default behaviour is to emulate markdown.
> The configuration file allows for new features that don't fit
> well into the old set.

Optional features are dangerous and impede interoperability.

Everyone who ever thinks about chipping in on the design of
a spec should read [section 5 of RFC 3339][1]. That RFC is
a spec for a particular datetime format, but section 5 is
largely agnostic of the nature of the format, and lays down
the principles according to which the design decisions for
this format were made. [Section 5.3][2] is the part with
direct relevance to your stipulation, but the entire section
is readworthy.

[1]: http://tools.ietf.org/html/rfc3339#section-5
[2]: http://tools.ietf.org/html/rfc3339#section-5.3

One problem is that every new option leads to a geometric
increase in the number of feature combinations that have to be
tested.

Another issue is that Markdown is a document format. If it has
many optional features, what are the chances that if I send you
a document ostensibly written in Markdown that will work in your
implementation of Markdown exactly as it did in mine? You really
really don’t want to have to wonder.

This was a major reason why SGML mostly failed, f.ex., and only
gained traction when it was restandardised as XML. SGML had
legions of optional author-friendly features that it made it an
extreme amount of work to implement a parser that correctly
implemented the entire spec. The XML working group sat down and
basically chucked out 95% of the optional features and made the
rest mandatory. The rest is history.

Optional features in a document format are an invitation for
interoperability problems. Since the entire point of the Markdown
spec effort was to reduce existing interoperability problems,
I strongly advise that as little as possible in the spec be made
optional. Ideally, nothing would be.

It is, mind, perfectly fine to have two (or maybe three?) specs
of which one is a superset of the other, as seems to be Michel’s
current thrust with Markdown vs Markdown Extra. Assuming that no
feature in either spec is optional, that means you would be able
to expect Markdown Extra documents to work in all Markdown Extra
processors, and all Markdown documents to work in all Markdown
and Markdown Extra processors. The scope of the problem is much
smaller in such a scenario, enough so to be perfectly tractable.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Markdown Extra Specification (First Draft)

[Jacob Rus]

Sherwood Botsford wrote:

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.


Vi can't handle line wrap?  Why do you need to look at the end of the URL?


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


There's an RFC which recommends wrapping URIs in plain text in `<>`s.  I 
suggest if you are bothered by long lines, you use that format.



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


Just make a tool which concatenates your files first, then runs markdown 
on it.



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


Presumably either in case you want to use the others in the title, or 
just so you don't have to think about what the quoting character is when 
you're writing.  I think it's unnecessary.



4. Why the <> around the URI?


There is as mentioned an RFC which recommends this.  It has been the 
accepted format in plain-text emails for decades.


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.


Go back and look through this list's archives.  3-4 years ago there was 
a long and fruitful discussion of table syntax.



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


I would favour ending a line with a forward slash. You sometimes see 


I put your chances of selling John on these at about zero.

-Jacob

___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Markdown Extra Specification (First Draft)

[Jacob Rus]

Sherwood Botsford wrote:
Not to worry.  I wasn't expecting backward compatibility, so that [...] 
THAT said, however, maintaining perfect backward compatibility slows 
down progress.


If this is your view, you shouldn't put "markdown" in the name.


Implementation specs:  The program should have a compiled in
set of locations to look for the config file, a command line option, and 
an environment option.


Wait, compiled?  Environment options?  This is getting way more complex 
than necessary.  Keep it simple, on general principle.



Consider too, if it is truly an improvement, it can be given a


Yes, I'd guess that's unlikely.  There have been a half dozen attempts 
to "improve" markdown; I don't particularly like any of them. (no 
offense intended to those implementors)


I agree that you need a way for people to gracefully make the 
transition.  The best approach is a method that allows old
and new systems to co-exist in the same environment.  If you call it 
with a new name, there shouldn't be a problem.


The new one is unlikely to gain much mindshare unless it is a) 
unquestionably better, and b) gets used by some prominent system/tool/etc.


Good luck.
Jacob

(not trying to rain on parades here :)

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

ns what, and the span element 2.4.7 is "Abbreviation",
representing an instance of an abbreviation in the text (deduced 
automatically by the parser). I'm not sure what is the problem there. 
It's pretty much alike 2.2.1 Link Reference and 2.4.4 Link: one is the 
definition of the URL and title of a link; the other is the actual link.


 * * *

I'm sorry to ditch most of your suggestions like that, but I can't 
really do any breaking change to the syntax, or that syntax wouldn't be 
Markdown anymore. The idea behind the spec is to give implementors an 
unambiguous reference about how to implement Markdown (and Markdown 
Extra), allowing documents tested with one parser to work with any 
other, unchanged.




Not to worry.  I wasn't expecting backward compatibility, so that 
flavoured much of what I said. I was not aware of PHP Markdown 
extra.  I will read further before commenting again.


THAT said, however, maintaining perfect backward compatibility 
slows down progress.


Can markdown extra have a configuration file:
The default behaviour is to emulate markdown.
The configuration file allows for new features that don't fit
well into the old set.

Implementation specs:  The program should have a compiled in
set of locations to look for the config file, a command line 
option, and an environment option.


Consider too, if it is truly an improvement, it can be given a
new name, and a new calling convention, "MarkdownX"  This allows
both systems to be in use while a system is in transition.

Couple this with a program that scans old markdown files for 
'gotchas' that have changed in the new one.


Given the current situation, it may be a little utopian to believe no 
current document will be broken as implementations adjust themselves to 
the spec, but we should try to minimize that.





I agree that you need a way for people to gracefully make the 
transition.  The best approach is a method that allows old
and new systems to co-exist in the same environment.  If you call 
it with a new name, there shouldn't be a problem.





___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

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

Markdown Extra Specification (First Draft)

[Michel Fortin]

It took much more time than I expected, and it is currently less  
complete than I have hoped, but I've finaly made a first draft of the  
Markdown Extra spec. You can find it at 


Currently, the specification defines its goals and a document model  
for Markdown Extra. It lacks the most important part though: the  
parsing section, which I'm going to write next. As I update the  
document locally on my computer, I'll update the public specification  
page to always reflect the latest version.


I'm working on this on my free time, alongside a full-time job, a few  
other projects, and other duties. I'm hoping to have a draft of the  
parsing section covering all parts of the syntax by July, and to have  
completed the whole specification by 2009. I'm not sure of how  
realistic this timetable is, but we'll see.


To take part in this work, simply leave your comments, suggestions,  
and potential issues on this list, or send them to me by private email  
if you don't want your comment to be public for some reason.



Michel Fortin
[EMAIL PROTECTED]
http://michelf.com/


___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss