Merge branch 'markdown-book' of git://git.os.pehjota.net/users/pehjota/doc/policies

1 files changed, 23 insertions, 0 deletions

diff --git a/notes/markdown-vs-multimarkdown.txt b/notes/markdown-vs-multimarkdown.txt
new file mode 100644
index 0000000..1d71d57
--- /dev/null
+++ b/notes/markdown-vs-multimarkdown.txt
@@ -0,0 +1,23 @@
+Markdown: <http://daringfireball.net/projects/markdown/>
+MultiMarkdown: <http://fletcherpenney.net/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.