possible bug in PHP Markdown implementation of footnotes,
as well as request for standardized XHTML output
Fletcher T. Penney
fletcher at alumni.duke.edu
Wed Sep 20 17:58:15 EDT 2006
I am glad to see support for footnotes working its way into other
implementations of Markdown!
However, I have a couple of issues.
Issue # 1. There appears to be a bug in the footnote parser that
causes material following the footnote to be included as part of the
footnote. For example:
< Example Section >
## Metadata ##
First, take a look at the overall structure of the document. At the
very beginning is metadata, including a title, author, keywords,
copyright information, etc. Where possible, this metadata is put to
appropriate use, otherwise it is stored in a format designed to be
easily read and minimally distracting:
* In plain text and XHTML snippets[^snippets], it is located at the
top of the document.
* In a full XHTML document, is located in the `<head>` section, and
the title and CSS metadata, if present, are used appropriately.
* In a PDF generated from my XSLT files, metadata is used to generate
the appropriate fields (title, author, keywords) in the PDF itself.
Some PDF readers will let you examine this data. Additionally, the
title, subtitle, author, and copyright are placed at the beginning of
the document.
There are a lot of standard metadata keys that can be used, or you
can create your own and use them as you see fit. Definitely a
powerful feature.
[^snippets]: An XHTML snippet is my terminology for XHTML code that
does not include the `<html>`, `<head>`, and `<body>` tags. Most
browsers will display it properly, but it is not a complete XHTML
document. Without a `<head>` section there is nowhere to put metadata
(e.g. there is no `<title>`).
## Structure ##
The next thing to look at is the overall structure of the document.
You can visualize a Markdown document as an outline, with different
sections and different levels within those sections. Based on your
output format, these can be used to generate headers, or sections, or
even chapters. It's all based on what tools you use to process the
XHTML output.
Even within the XHTML document, however, you can make use of this
structure to allow easy navigation within the document. You can link
directly to the [Introduction][], for instance. And if you are
creating a PDF, it will contain a hierarchy of section names that you
can use to allow easy navigation, if your PDF reader supports this
function.
Link to [bob][].
</End Example Section>
When I try this, the footnote contains the expected portion through
the first paragraph of the following section of text (i.e. the first
paragraph of `Structure`.
Issue # 2. I would like to work towards a single consensus output
format for the footnote syntax as well --- MultiMarkdown and PHP
Markdown should have the same output format for compatibility reasons.
The current PHP output for the above (after it gets fixed) will be:
<div class="footnotes">
<hr />
<ol>
<li id="fn:snippets">
<p>An XHTML snippet is my terminology for XHTML code that does not
include the <code><html></code>, <code><head></code>, and
<code><body></code> tags. Most browsers will display it
properly, but it is not a complete XHTML document. Without a
<code><head></code> section there is nowhere to put metadata
(e.g. there is no <code><title></code>). <a
href="#fnref:snippets" rev="footnote">↩</a></p>
</li>
</ol>
</div>
The current MultiMarkdown output is:
<div class="footnotes">
<hr />
<p>Footnotes:</p>
<div id="snippets"><p><a href="#fsnippets"
class="reversefootnote">1.</a> An XHTML snippet is my terminology for
XHTML code that does not include the <code><html></code>,
<code><head></code>, and <code><body></code> tags. Most
browsers will display it properly, but it is not a complete XHTML
document. Without a <code><head></code> section there is
nowhere to put metadata(e.g. there is no <code><title></
code>).</p></div>
<div id="parties"><p><a href="#fparties" class="reversefootnote">2.</
a> I guess it depends on what kind of parties you go to…</p></div>
</div>
I would like to get feedback for a consensus standard (or at least
until John decides to implement footnotes in the official Markdown
syntax). These are the issues that I see:
1. MultiMarkdown used div's, PHP Markdown uses an ordered list. It
doesn't much matter, as long as there is a way for an XSLT parser to
reliable identify what constitutes each footnote. I suppose one
potential problem with the ordered list would be the inability to set
an arbitrary number for the first footnote, but in actuality neither
system could take advantage of it at the moment. It's worth
considering, but I am not sure there is an overwhelming reason to
choose one over the other. Any thoughts from others?
2. Reverse links should be from the footnote number, or from the
↩ symbol, in both syntaxes. Again, I don't see an overwhelming
reason to choose one over the other. I can easily modify
MultiMarkdown to use the ↩ symbol if that is the consensus
opinion.
3. Same thing goes for the syntax to choose footnote related id
tags. They can be whatever, but should be consistent.
To reiterate, I am ok with choosing to go with PHP format,
MultiMarkdown format, or a mixture of both. Just want to make sure
that the best output model arises, and would strongly suggest that
there be a consistent approach between all flavors of Markdown.
Looking forward to input...
Fletcher
--
Fletcher T. Penney
fletcher at alumni.duke.edu
Drugs have taught an entire generation of American kids the metric
system.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 2431 bytes
Desc: not available
Url : http://six.pairlist.net/pipermail/markdown-discuss/attachments/20060920/e55e1ca0/smime.bin
More information about the Markdown-Discuss
mailing list