[ANN] PHP Markdown Extra 1.1b1

[Michel Fortin]

Along with the new release of PHP Markdown 1.0.2b7 comes this new  
version of PHP Markdown Extra. It contains every improvements of PHP  
Markdown 1.0.2b7 plus some new fixes and two new features. You can  
download it here:

<http://www.michelf.com/docs/projets/php-markdown-extra-1.1b1.zip>

and you can test it on the PHP Markdown Dingus (select PHP Markdown  
Extra):

<http://www.michelf.com/projects/php-markdown/dingus/>


Footnotes
---------

Footnotes have been discussed a lot on this list back in [July 2005] 
[1]. A year has passed and I implemented nothing. I looked back at  
that old thread recently to rediscover the syntax and finally decided  
to add it to Extra.

   [1]: http://six.pairlist.net/pipermail/markdown-discuss/2005-July/ 
thread.html#1401

How do footnotes work? Mostly like reference-style links. There is a  
marker in the text which gets converted to a superscript number in  
the HTML rendering. There is a definition that can happen anywhere in  
the document and which is appended at the end inside a list of  
footnotes. A footnote looks like this:

     That's some text with a footnote.[^1]

     [^1]: And that's the footnote.

Footnote definitions can be found anywhere in the document, but  
footnotes will always be listed in the order they are linked to in  
the text. Note that you cannot make two links to the same footnotes:  
if you try the second footnote reference will be left as plain text.

Each footnote must have a distinct name. That name will be used for  
linking to and from footnote references, but has no effect on the  
numbering of the footnotes. Names can be anything which is valid  
within an id attribute in HTML.

Footnotes can contain block-level elements, which means that you can  
put multiple paragraphs, lists, blockquotes and so on in a footnote.  
It works the same as for list items: just indent the following  
paragraphs by four spaces in the footnote definition:

     That's some text with a footnote.[^1]

     [^1]: And that's the footnote.

         That's the second paragraph.

If you want things to align better, you can leave the first line of  
the footnote empty and put your first paragraph just below:

     [^1]:
         And that's the footnote.

         That's the second paragraph.


### Output

It has been said countless times in the discussions that one output  
format cannot satisfy everyone. So I'm not trying to make something  
which will work for everyone. I decided I'd follow what I've seen on  
Daring Fireball, as I think it's a pretty good default, but with some  
minor differences. Here is the default output from the first sample:

     <p>That's some text with a footnote.
        <sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup></p>

     <div class="footnotes">
     <hr />
     <ol>

     <li id="fn:1">
     <p>And that's the footnote.
        <a href="#fnref:1" rev="footnote">&#8617;</a></p>
     </li>

     </ol>
     </div>

A little cryptic, but in a browser it will look like this (minus  
links and superscript):

     That's some text with a footnote.1

     __________________

     1.  And that's the footnote. ↩

The "rel" and "rev" attributes on the links express the relation they  
have with the elements they link to, the reference links to the  
footnote and the backlink is a reverse reference from the footnote,  
hence rel= and rev="footnote". They can be used to style the elements  
with CSS rules such as:

     a[rel="footnote"]
     a[rev="footnote"]

So this is what PHP Markdown Extra 1.1b1 does. I'm thinking about  
adding some configuration variables to allow customized class and  
title attributes on the in-text reference and the backlink to make  
that even more usable.


### Limitations

*   You cannot make a footnote without having the content wrapped in  
a paragraph
     or another block-level construct. I've been wondering if it  
would be good to
     allow, somehow, span-level footnotes.

*   It's probably not the best way to add bibliographic references when
     a reference can appear many times in a document. I think a  
distinct syntax,
     using another special character instead of `^` would be better  
suited for
     that purpose.


Abbreviations
-------------

PHP Markdown Extra 1.1b1 adds supports for abbreviations (HTML  
`<abbr>` tag) as an experimental feature. How it works is pretty  
simple: create an abbreviation definition like this:

     [HTML]*: Hyper Text Markup Language
     [W3C]*:  World Wide Web Consortium

then write text such as:

     The HTML specification
     is maintained by the W3C.

and any instance of those words in the text will become:

     The <abbr title="Hyper Text Markup Language">HTML</abbr>
     is maintained by the <abbr title="World Wide Web  
Consortium">W3C</abbr>.

Abbreviation are case-sensitive, and can span on multiple words when  
required. An abbreviation may also have an empty definition, in which  
case the title attribute will be omitted.

     Operation Tigra Genesis is going well.

     [Tigra Genesis]*:

Abbreviation definition can be anywhere in the document. They won't  
appear in the final result other than within the text as `<abbr>`  
elements.

This syntax is a work in progress. I'm not sure the syntax is  
distinctive enough from standard link definition. I'm open to  
suggestions.


PHP Markdown Extra 1.1b1
------------------------

*   Added a syntax for footnotes.

*   Added an experimental syntax to define abbreviations.

*   Fixed a bug where Markdown Extra outputs invalid HTML when a  
horizontal
     rule isn't preceded *and* followed by a blank like.

*   Fixed a bug which would cause some block-level elements to appear  
inside a
     a tag with markdown="span", or markdown="1" defaulting to span  
content.




Michel Fortin
michel.fortin at michelf.com
http://www.michelf.com/