Proposal for footnote GUID syntax

[A. Pagaltzis]

* 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/>