From cea84fa22c75fcf0d3adb684b2c4a0186cc76b65 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Fran=C3=A7ois=20Boulogne?= Date: Sat, 4 May 2013 22:05:55 +0200 Subject: [PATCH] add author --- README.md | 163 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 107 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 8a44316..1e43b92 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ -Ikiwiki plugin for the Pandoc markdown processor -================================================ +ikiwiki-pandoc +============== + +Pandoc plugin for ikiwiki. Pandoc has a richer syntax and more flexible configuration than Markdown, and is also able to parse a variety of @@ -10,129 +12,178 @@ inline TeX using a variety of methods. And, if Pandoc was compiled with the blocks and `inline code spans`. +License +======= + +GPLv2 + +Authors +======= +* Jason Blevin (Original author) +* Jim Pryor +* Beni Cherniavsky-Paskin +* Ryan Burgoyne +* Baldur Kristinsson +* François Boulogne + +Install +======= + + # Install the library + mkdir -p ~/.ikiwiki/IkiWiki/Plugin + cp pandoc.pm ~/.ikiwiki/IkiWiki/Plugin + # Alternatively, can be installed in /usr/share/perl5 + + # Install templates + cp *tmpl /usr/share/ikiwiki/templates + cd /usr/share/ikiwiki/templates + mv page.tmpl page.tmpl.ori + ln -s mathjax.tmpl page.tmpl + + # Install javascript + cp *js /usr/share/ikiwiki/javascript + + + ## Options ## ### Available in Ikiwiki's web preferences ### -#. File extension for Markdown files (defaults to mdwn) +1. File extension for Markdown files (defaults to mdwn) -#. Use smart quotes, dashes, and ellipses +1. Use smart quotes, dashes, and ellipses -#. Generate ASCII instead of UTF8. +1. Generate ASCII instead of UTF8. -#. Number section headings in generated pages +1. Number section headings in generated pages -#. Wrap sections in `
` tags (or `
` tags in HTML5), and +1. Wrap sections in `
` tags (or `
` tags in HTML5), and attach identifiers to the `
` rather than th header itself. This allows the section to be styled or manipulated via javascript. -#. Obfuscate emails using HTML character references +1. Obfuscate emails using HTML character references -#. Generate HTML5 (the Ikiwiki html5 setting should also be set) +1. Generate HTML5 (the Ikiwiki html5 setting should also be set) -#. Classes to use for all indented code blocks (these can also be +1. 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) +1. Path to pandoc executable (defaults to /usr/local/bin/pandoc) -#. Enable Pandoc processing of LaTeX documents +1. Enable Pandoc processing of LaTeX documents -#. Enable Pandoc processing of reStructuredText documents +1. Enable Pandoc processing of reStructuredText documents -#. Method for handling inline TeX (see below) +1. 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: +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); - } - ~~~ + ~~~ + 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: +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); - } - ~~~ + ~~~{.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: - 
-		
-		...
-		
-
+ 
+        
+        ...
+        
+
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"; - """]] + [[!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. +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 . 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.) +1. You can use MathJax . 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 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`. +1. 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 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 . 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`. +1. A different JavaScript solution is 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 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`. +1. Instead of using JavaScript, a different approach is to build and install a cgi on your server. MathTeX + 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 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`. +1. MimeTeX 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 . (Available since Pandoc 1.6.) +1. Or you could use a third-party cgi, such as Google Charts API . (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.) +1. 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. +1. 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 +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 has a plugin for using that tool together with Markdown. (A newer version is mentioned at .) -See also , which describes a number of other works-in-progress for rendering LaTeX in Ikiwiki.) +See also , 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 . - + \newcommand{\tuple}[1]{\langle #1 \rangle} + ... + $\tuple{a, b, c}$ - -- 2.39.2