+++ /dev/null
-Ikiwiki plugin for the Pandoc markdown processor
-================================================
-
-Pandoc <http://johnmacfarlane.net/pandoc/> has a richer syntax and more
-flexible configuration than Markdown, and is also able to parse a variety of
-other syntaxes. This plugin can be configured to generate wiki pages from LaTeX
-and reST sources, as well as markdown. It can also be configured to convert
-inline TeX using a variety of methods. And, if Pandoc was compiled with the
--fhighlighting, it can be configured to apply syntax highlighting to code
-blocks and `inline code spans`.
-
-
-
-
-## Options ##
-
-### Available in Ikiwiki's web preferences ###
-
-#. File extension for Markdown files (defaults to mdwn)
-
-#. Use smart quotes, dashes, and ellipses
-
-#. Generate ASCII instead of UTF8.
-
-#. Number section headings in generated pages
-
-#. Wrap sections in `<div>` tags (or `<section>` tags in HTML5), and
- attach identifiers to the `<div>` rather than th header itself. This
- allows the section to be styled or manipulated via javascript.
-
-#. Obfuscate emails using HTML character references
-
-#. Generate HTML5 (the Ikiwiki html5 setting should also be set)
-
-#. Classes to use for all indented code blocks (these can also be
- specified differently from block to block; see below)
-
-
-### Have to be configured manually in your wiki's *.setup file ###
-
-#. Path to pandoc executable (defaults to /usr/local/bin/pandoc)
-
-#. Enable Pandoc processing of LaTeX documents
-
-#. Enable Pandoc processing of reStructuredText documents
-
-#. Method for handling inline TeX (see below)
-
-
-## Details ##
-
-### Syntax Coloring ###
-
-Pandoc can be configured to apply classes globally to all its inline code blocks (for example, `numberLines` or `perl`). Alternatively, code blocks can be written in this style:
-
- ~~~
- if (a > 3) {
- moveShip(5 + gravity, DOWN);
- }
- ~~~
-
-The line of `~~~` can be longer than 3 characters, if you like. This manner of writing indented code blocks also permits us to specify the block's specific syntax, which might be different from other blocks:
-
-
- ~~~{.haskell .numberLines}
- if (a > 3) {
- moveShip(5 + gravity, DOWN);
- }
- ~~~
-
-If Pandoc wasn't compiled with syntax highlighting support, such a code block will be processed like this:
-
- <pre class="haskell">
- <code>
- ...
- </code>
- </pre>
-
-
-You can also specify the syntax for inline code spans: `` `some code`{.haskell} ``.
-
-This functionality overlaps somewhat with Ikiwiki's `highlight` plugin and `format` directive:
-
- [[!format perl """
- print "hello, world\n";
- """]]
-
-You'll have to decide which facility better suits your needs.
-
-### Tables ###
-
-Pandoc has a native [table-handling syntax](http://johnmacfarlane.net/pandoc/README.html#tables). This overlaps somewhat with Ikiwiki's `table` directive. Here too, you'll have to decide which facility better suits your needs.
-
-
-### Inline TeX processing ###
-
-Pandoc recognizes inline TeX and can be configured to display it on the web using a variety of tools.
-
-#. You can use MathJax <http://www.mathjax.org/>. This requires copying the `mathjax.tmpl` file that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`. (Available since Pandoc 1.8.)
-
-#. jsMath is the predecessor to MathJax. It doesn't give as nice results, and is harder to install, but it's also an option. Download jsMath and jsMath-fonts <http://www.math.union.edu/~dpvc/jsMath/> and install them so that they're served from the root of your server, that is, from `/jsMath/...` Also, copy the file `jsmath.tmpl` that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`.
-
-#. A different JavaScript solution is LatexMathML <http://math.etsu.edu/LaTeXMathML/>. Again, this gives less good results than MathJax, but it's easier to install than jsMath. Download the `LaTeXMathML.js` and `LaTeXMathML.standardarticle.css` files and install them so that they're served from the root of your server. Also, copy the file `latexmathml.tmpl` that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`.
-
-#. Instead of using JavaScript, a different approach is to build and install a cgi on your server. MathTeX <http://www.forkosh.com/mathtex.html> gives good results, but needs LaTeX to be available on the server. This plugin assumes that if you're using MathTeX, it will be served from `/cgi-bin/mathtex.cgi`.
-
-#. MimeTeX <http://www.forkosh.com/mimetex.html> is the predecessor to MathTeX. It doesn't give as nice results, but will work on less equipped servers. This plugin assumes that if you're using MimeTeX, it will be served from `/cgi-bin/mimetex.cgi`.
-
-#. Or you could use a third-party cgi, such as Google Charts API <http://code.google.com/apis/chart/>. (Available since Pandoc 1.6.)
-
-#. Another option is to directly render the TeX into MathML. Browser support for displaying MathML is coming slowly. Firefox supports it well, but WebKit/Chrome is only beginning to. To process inline TeX via this method, copy the file `mathml.tmpl` that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`. You should also arrange for the file `mathml.js` to be served from the root of your server; this file helps provide a better fallbacks for browsers that can't display the MathML. This method also requires htmlscrubber to be disabled, at least for pages containing MathML. (Available since Pandoc 1.5.)
-
-#. If none of the other options are enabled, Pandoc will attempt to render inline TeX using Unicode characters, in so far as that's possible.
-
-
-If none of these options work for you, you could check out the [teximg plugin](http://ikiwiki.info/plugins/teximg/); this works something like MathTex, above. You could also look into using
-`itex2MML`; Jason Blevins <http://jblevins.org/projects/ikiwiki/> has a plugin
-for using that tool together with Markdown. (A newer version is mentioned at <http://ikiwiki.info/todo/mdwn_itex/>.)
-
-See also <http://ikiwiki.info/todo/latex>, which describes a number of other works-in-progress for rendering LaTeX in Ikiwiki.)
-
-
-### TeX macros ###
-
-Another nice Pandoc feature is that it parses and uses `\newcommand` and `\renewcommand` macro definitions:
-
- \newcommand{\tuple}[1]{\langle #1 \rangle}
- ...
- $\tuple{a, b, c}$
-
-
-## Release Notes ##
-
- * v1.0 (1 June 2011) Initial release. Based on Jason Blevin's original <http://jblevins.org/projects/ikiwiki/>.
-
-
-<!-- vim: ft=pdc
--->
--- /dev/null
+Ikiwiki plugin for the Pandoc markdown processor
+================================================
+
+Pandoc <http://johnmacfarlane.net/pandoc/> has a richer syntax and more
+flexible configuration than Markdown, and is also able to parse a variety of
+other syntaxes. This plugin can be configured to generate wiki pages from LaTeX
+and reST sources, as well as markdown. It can also be configured to convert
+inline TeX using a variety of methods. And, if Pandoc was compiled with the
+-fhighlighting, it can be configured to apply syntax highlighting to code
+blocks and `inline code spans`.
+
+
+
+
+## Options ##
+
+### Available in Ikiwiki's web preferences ###
+
+#. File extension for Markdown files (defaults to mdwn)
+
+#. Use smart quotes, dashes, and ellipses
+
+#. Generate ASCII instead of UTF8.
+
+#. Number section headings in generated pages
+
+#. Wrap sections in `<div>` tags (or `<section>` tags in HTML5), and
+ attach identifiers to the `<div>` rather than th header itself. This
+ allows the section to be styled or manipulated via javascript.
+
+#. Obfuscate emails using HTML character references
+
+#. Generate HTML5 (the Ikiwiki html5 setting should also be set)
+
+#. Classes to use for all indented code blocks (these can also be
+ specified differently from block to block; see below)
+
+
+### Have to be configured manually in your wiki's *.setup file ###
+
+#. Path to pandoc executable (defaults to /usr/local/bin/pandoc)
+
+#. Enable Pandoc processing of LaTeX documents
+
+#. Enable Pandoc processing of reStructuredText documents
+
+#. Method for handling inline TeX (see below)
+
+
+## Details ##
+
+### Syntax Coloring ###
+
+Pandoc can be configured to apply classes globally to all its inline code blocks (for example, `numberLines` or `perl`). Alternatively, code blocks can be written in this style:
+
+ ~~~
+ if (a > 3) {
+ moveShip(5 + gravity, DOWN);
+ }
+ ~~~
+
+The line of `~~~` can be longer than 3 characters, if you like. This manner of writing indented code blocks also permits us to specify the block's specific syntax, which might be different from other blocks:
+
+
+ ~~~{.haskell .numberLines}
+ if (a > 3) {
+ moveShip(5 + gravity, DOWN);
+ }
+ ~~~
+
+If Pandoc wasn't compiled with syntax highlighting support, such a code block will be processed like this:
+
+ <pre class="haskell">
+ <code>
+ ...
+ </code>
+ </pre>
+
+
+You can also specify the syntax for inline code spans: `` `some code`{.haskell} ``.
+
+This functionality overlaps somewhat with Ikiwiki's `highlight` plugin and `format` directive:
+
+ [[!format perl """
+ print "hello, world\n";
+ """]]
+
+You'll have to decide which facility better suits your needs.
+
+### Tables ###
+
+Pandoc has a native [table-handling syntax](http://johnmacfarlane.net/pandoc/README.html#tables). This overlaps somewhat with Ikiwiki's `table` directive. Here too, you'll have to decide which facility better suits your needs.
+
+
+### Inline TeX processing ###
+
+Pandoc recognizes inline TeX and can be configured to display it on the web using a variety of tools.
+
+#. You can use MathJax <http://www.mathjax.org/>. This requires copying the `mathjax.tmpl` file that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`. (Available since Pandoc 1.8.)
+
+#. jsMath is the predecessor to MathJax. It doesn't give as nice results, and is harder to install, but it's also an option. Download jsMath and jsMath-fonts <http://www.math.union.edu/~dpvc/jsMath/> and install them so that they're served from the root of your server, that is, from `/jsMath/...` Also, copy the file `jsmath.tmpl` that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`.
+
+#. A different JavaScript solution is LatexMathML <http://math.etsu.edu/LaTeXMathML/>. Again, this gives less good results than MathJax, but it's easier to install than jsMath. Download the `LaTeXMathML.js` and `LaTeXMathML.standardarticle.css` files and install them so that they're served from the root of your server. Also, copy the file `latexmathml.tmpl` that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`.
+
+#. Instead of using JavaScript, a different approach is to build and install a cgi on your server. MathTeX <http://www.forkosh.com/mathtex.html> gives good results, but needs LaTeX to be available on the server. This plugin assumes that if you're using MathTeX, it will be served from `/cgi-bin/mathtex.cgi`.
+
+#. MimeTeX <http://www.forkosh.com/mimetex.html> is the predecessor to MathTeX. It doesn't give as nice results, but will work on less equipped servers. This plugin assumes that if you're using MimeTeX, it will be served from `/cgi-bin/mimetex.cgi`.
+
+#. Or you could use a third-party cgi, such as Google Charts API <http://code.google.com/apis/chart/>. (Available since Pandoc 1.6.)
+
+#. Another option is to directly render the TeX into MathML. Browser support for displaying MathML is coming slowly. Firefox supports it well, but WebKit/Chrome is only beginning to. To process inline TeX via this method, copy the file `mathml.tmpl` that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`. You should also arrange for the file `mathml.js` to be served from the root of your server; this file helps provide a better fallbacks for browsers that can't display the MathML. This method also requires htmlscrubber to be disabled, at least for pages containing MathML. (Available since Pandoc 1.5.)
+
+#. If none of the other options are enabled, Pandoc will attempt to render inline TeX using Unicode characters, in so far as that's possible.
+
+
+If none of these options work for you, you could check out the [teximg plugin](http://ikiwiki.info/plugins/teximg/); this works something like MathTex, above. You could also look into using
+`itex2MML`; Jason Blevins <http://jblevins.org/projects/ikiwiki/> has a plugin
+for using that tool together with Markdown. (A newer version is mentioned at <http://ikiwiki.info/todo/mdwn_itex/>.)
+
+See also <http://ikiwiki.info/todo/latex>, which describes a number of other works-in-progress for rendering LaTeX in Ikiwiki.)
+
+
+### TeX macros ###
+
+Another nice Pandoc feature is that it parses and uses `\newcommand` and `\renewcommand` macro definitions:
+
+ \newcommand{\tuple}[1]{\langle #1 \rangle}
+ ...
+ $\tuple{a, b, c}$
+
+
+## Release Notes ##
+
+ * v1.0 (1 June 2011) Initial release. Based on Jason Blevin's original <http://jblevins.org/projects/ikiwiki/>.
+
+
+<!-- vim: ft=pdc
+-->
projects / ikiwiki-pandoc.git / commitdiff