Fletcher T. Penney
2006-Sep-20 17:58 UTC
possible bug in PHP Markdown implementation of footnotes, as well as request for standardized XHTML output
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@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
Michel Fortin
2006-Sep-20 22:41 UTC
possible bug in PHP Markdown implementation of footnotes, as well as request for standardized XHTML output
Le 20 sept. 2006 ? 17:58, Fletcher T. Penney a ?crit :> I am glad to see support for footnotes working its way into other > implementations of Markdown!And I'm glad to see there is interest in footnotes. :-)> 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:Adam McMaster already signaled this bug at the start of this thread and has found a clever workaround until I fix it which is to put a comment just after the footnote, before the new content.> 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.I agree. But I think the scope for that problem goes a lot further than Markdown and its implementations. Maybe it'd be a good idea to make a microformat for footnotes, and try to standardise it through microformats.org. I'm not convinced there is a real need to have the exact same resulting markup however. As long as the output is in a format you can parse easily to extract footnote content and find reference markers in the text, it'd be fine by me. That doesn't mean we should make things different just for the sake of it either. But I have no problem with different implementations, with different goals, doing different things. There is value in variety.> 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?About arbitrary footnote numbers, I don't think many people need that. Those that do will probably want something integrated with a pagination system, which is way beyond what we should care at the moment. But I think it proves my previous point: no single markup is going to satisfy everyone's needs.> 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.As you said, they're both fine output. I'm following what John's doing because that's what I've always done with PHP Markdown. But I don't see a necessity for all implementations to have the same output. As long as the markup allows the identification of footnotes and of their reference markers -- so that it can be changed to another format for instance -- it's fine by me.> 3. Same thing goes for the syntax to choose footnote related id > tags. They can be whatever, but should be consistent.It could be a good idea if there was some sort of convention between Markdown implementations about how to generate the id. The reason being that if someone switches implementation, it would be preferable that it does not break any external bookmark to a footnote. That said, it probably wouldn't be a good idea to rely on the id attribute staying the same too much either. There are good reasons to change the generated id, adding an entry-specific prefix for a blog which may display more than one entry per page for instance. Michel Fortin michel.fortin@michelf.com http://www.michelf.com/