From 60fc7cce2494416a224da2e93d3a41c4d8bad5ba Mon Sep 17 00:00:00 2001 From: P. J. McDermott Date: Tue, 05 Jun 2012 21:38:57 -0400 Subject: Document why MMD doesn't help with in-book links. --- diff --git a/markdown-vs-multimarkdown.txt b/markdown-vs-multimarkdown.txt new file mode 100644 index 0000000..1d71d57 --- /dev/null +++ b/markdown-vs-multimarkdown.txt @@ -0,0 +1,23 @@ +Markdown: +MultiMarkdown: + +MultiMarkdown seems to provide much of what we currently need and may want in +the future: cross references, footnotes, tables, and PDF rendering (though this +can be done with Markdown as well using Pandoc). Why don't we just use that to +do all our work for us? + +The cross references (hyperlinks to sections) only work within a single +document. We want policy manuals to have a chapter/appendix per document (e.g. +HTML file). MultiMarkdown doesn't really support hyperlinks to sections in +other documents. So while MMD might be nice for its other features, it looks +like we should still handle in-book hyperlinks with our own pre-processing. + +Then why don't we just use normal hyperlinks to sections in different chapters? +This assumes we're outputting documents only in HTML. We would have source text +like this: + + See [Library Packages](binpkgs.html#librarypackages) for more information. + +Rendering a plain text file that refers to other plain text files with a ".html" +extension makes no sense. Additionally, this fails to work in the case of PDF +rendering. -- cgit v0.9.1