Markdown Discuss - Jul 2007 - Proposal for footnote GUID syntax

While we're talking about new syntax, I thought that I'd throw out an 
idea I had to extend the footnote syntax as it currently exists in 
PHP Markdown Extra.

I'm not sure that it's the best way to solve this particular problem, 
but I figured I'd throw it out there to get any comments on it.

It relates to the problem of specifying a document's GUID.  A few 
months back, I wrote:
>  Actually, I do have one feature suggestion for the PHP
>  Markdown Extra syntax.  If you're posting to a CMS system
>  where multiple articles may appear on the same HTML page,
>  you need to assign each article a GUID so that the footnote
>  links make sense (i.e., you can't have two articles that
>  both use "fnref" as the anchor name for the footnotes, since
>  you would end up with two anchors with the same name if two
>  articles are published on the same page).  It's of course
>  possible to do this with a search and replace of "fnref" to
>  something like "2007-01-23-1" prior to publishing.  But, it
>  would be nice if you could specify a document GUID and have
>  the Markdown processor do that substitution for you.
Michel Fortin was kind enough to respond with the following:
>  It's already possible if you instantiate the parser yourself
>  instead of calling the simplified Markdown function:
>
>       $parser = new Markdown_Parser;
>       $parser->fn_id_prefix = $entry_guid;
>       $text = $parser->transform($text);
So far so good.  However, we're still left with the problem of 
deciding on a GUID when we instantiate the parser.  This complicates 
our workflow, since we can't just pass a block of Markdown text to 
the parser and let it do its processing.  (We could do something like 
taking a hash of the document text and using that as the GUID, but 
that generates lengthy and ugly anchor names.  It also causes the 
anchor names to change if minor corrections are made to the document.)

Ideally, it should be possible to provide some metadata in the 
Markdown document itself to provide the parser with a GUID of our 
choosing.

There are two possibilities that come to mind.  The first would be to 
add in some form of generic metadata syntax, which could then be used 
for a variety of other things.  However, I think that adding that 
sort of syntax goes against the spirit of Markdown (as John puts it, 
"[t]he idea is that a Markdown-formatted document should be 
publishable as-is, as plain text, without looking like it's been 
marked up with tags or formatting instructions"), and leads down a 
slippery slope.

The second idea is to add the GUID to our footnote definitions.  It 
doesn't require adding any new sections to the document, and I think 
that it has a minimal impact on the readability of the non-processed 
document.  It's also easy to parse (and to specify in a formal 
grammar, if that ever happens).

Basically, rather than:
>  This is some text[^1].  And here's some more[^2].
>
>  [^1]: Which has an interesting footnote.
>  [^2]: Which has a less interesting footnote.
you'd have:
>  This is some text[^1].  And here's some more[^2].
>
>  [^1 guid="foo"]: Which has an interesting footnote.
>  [^2]: Which has a less interesting footnote.
You could also do something like [^1 documentID="foo"], which might 
be more readable.  Note that we only need to specify the GUID a 
single time, probably in our first footnote.

Anyway, as I mentioned, I'm not sure that this is the best choice of 
syntax to solve this problem, but it is one option.

I'd appreciate any thoughts.

(As a side note, it occurs to me that "GUID" is the wrong term to be 
using, since the ids in question aren't necessarily globally unique. 
Perhaps we should use "UID"?  Or something else?)

Cheers,
Jonathan


-- 
Jonathan Deber
jonathan.deber at utoronto.ca
jdeber.blogspot.com

* Jonathan Deber <jonathan.deber at utoronto.ca> [2007-07-12
22:05]:
> The second idea is to add the GUID to our footnote definitions.
> It doesn't require adding any new sections to the document, and
> I think that it has a minimal impact on the readability of the
> non-processed document. It's also easy to parse (and to
> specify in a formal grammar, if that ever happens).
> 
> Basically, rather than:
> 
> > This is some text[^1].  And here's some more[^2].
> >
> > [^1]: Which has an interesting footnote.
> > [^2]: Which has a less interesting footnote.
> 
> you'd have:
> 
> > This is some text[^1].  And here's some more[^2].
> >
> > [^1 guid="foo"]: Which has an interesting footnote.
> > [^2]: Which has a less interesting footnote.
How is that more natural than a footer with a simple metadata
format? At least the metadata in the footer is down at the end of
the document where a human can ignore it at will.

> Michel Fortin was kind enough to respond with the following:
> 
> > It's already possible if you instantiate the parser yourself
> > instead of calling the simplified Markdown function:
> >
> >      $parser = new Markdown_Parser;
> >      $parser->fn_id_prefix = $entry_guid;
> >      $text = $parser->transform($text);
> 
> So far so good. However, we're still left with the problem of
> deciding on a GUID when we instantiate the parser. This
> complicates our workflow, since we can't just pass a block of
> Markdown text to the parser and let it do its processing. (We
> could do something like taking a hash of the document text and
> using that as the GUID, but that generates lengthy and ugly
> anchor names. It also causes the anchor names to change if
> minor corrections are made to the document.)
>
> Ideally, it should be possible to provide some metadata in the
> Markdown document itself to provide the parser with a GUID of
> our choosing.
The `Markdown` function is very simple:

    function Markdown($text) {
        static $parser;
        if (!isset($parser)) {
            $parser_class = MARKDOWN_PARSER_CLASS;
            $parser = new $parser_class;
        }
        return $parser->transform($text);
    }

So just write your own wrapper function that has some extra code
before the `return`, to extract metadata from the end of $text if
there is any, and temporarily changes `$parser->fn_id_prefix` for
this particular parse if a footnote prefix was defined in the
metadata.

(I actually started writing such a function before I discovered
that PHP does not directly allow capturing parts of the input
string with a regex at the same as performing a substitution. In
Perl it would have been a four line addition, but PHP requires
much more effort and I lost patience after a while. Sorry.)

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>