Added documentation for export options

diff --git a/CHANGELOG b/CHANGELOG
index eab81590134acf7795493939d162d4de469791e5..eb2f957fb0ca079d61adaef3c8ef218732f9286f 100644 (file)
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,8 @@
+0.3 (2016-02-02)
+================
+
+* Add support for on-demand page export in several formats: pdf, beamer, latex, docx, odt and epub.
+
 0.2.1 (2016-01-31)
 ==================
 

diff --git a/README.md b/README.md
index be0b89905216bcd1cda4117dbc3d44d3d531be7a..3afe52cd5e2a04b97ebe77ffc90984a27813e767 100644 (file)
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ Pandoc <http://johnmacfarlane.net/pandoc/> has a richer syntax and more flexible
 
 
 Install
-=======
+-------
 
     # (1) Install the library.
     # Alternatively, can be installed in /usr/share/perl5 or similar.
@@ -34,14 +34,15 @@ Install
     #     add 'pandoc' to `add_plugins` list in your *.setup file
 
     # (5) Refresh your *.setup file and rebuild your wiki:
-    # Between those two commands, you may want to tweek some options.
+    # Between those two commands, you may want to tweak some options.
     #
     ikiwiki --changesetup *.setup
     ikiwiki --rebuild --setup *.setup
 
 **Note:** If you want to put mathematics markup into your pages or blog entries, you are likely to run into problems with the `smiley` plugin, so you should probably disable it by adding it to the `disable_plugins` list in your `*.setup` file.
 
-## Options
+Options
+-------
 
 The following options are available in the `*.setup` file. Some of them are also available in the web settings.
 
@@ -105,8 +106,49 @@ These settings have no effect unless you have activated the `page.tmpl` file whi
 
 * `pandoc_codeclasses` (string): CSS classes to add to indented code blocks. One may also specify CSS classes individually for each block.
 
+### Extra output formats
+
+It is sometimes useful to use pandoc to export the content of a wiki page to non-html formats, e.g. pdf or docx. This can be triggered by setting certain attributes in the YAML meta block of the page. The currently supported formats are `pdf`, `docx`, `odt`, `latex`, `beamer`, and `epub`. The corresponding meta attributes are the boolean values `generate_pdf`, `generate_docx`, `generate_odt`, `generate_latex`, `generate_beamer`, and `generate_epub`. As a shortcut, `generate_all_formats` will turn on all the generation of all six formats. For instance,
+
+```yaml
+generate_all_formats: true
+generate_beamer: false
+```
+
+will export files of all formats except Beamer.
+
+When such extra formats have been generated for a page, links to the exported files will be appended to the action links (e.g. "Edit"). These are at the top of the page in the default theme.
+
+There are several configuration options related to the export functionality:
+
+* `pandoc_latex_template`: Path to pandoc template for LaTeX and PDF output. Since PDF files are created by way of LaTeX, there is no separate PDF template. (Obviously, PDF generation requires a working LaTeX installation).
+
+* `pandoc_latex_extra_options`: List of extra pandoc options of LaTeX and PDF generation. (Note that this, like other `*_extra_options`, is a *list*, not simply a string).
+
+* `pandoc_beamer_template`: Path to pandoc template for Beamer PDF output. (Beamer is a presentations package for LaTeX).
+
+* `pandoc_beamer_extra_options`: List of extra pandoc options for Beamer PDF generation.
 
-## Details
+* `pandoc_docx_template`: Path to pandoc template for MS Word (`docx`) output.
+
+* `pandoc_docx_extra_options`: List of extra pandoc options for `docx` generation.
+
+* `pandoc_odt_template`: Path to pandoc template for OpenDocument (`odt`) output for LibreOffice, OpenOffice, etc..
+
+* `pandoc_odt_extra_options`: List of extra pandoc options for `odt` generation.
+
+* `pandoc_epub_template`: Path to pandoc template for epub output. (Note that the this will actually generate EPUB3 files rather than the more familiar EPUB2. The reason is that EPUB3 has better native math support).
+
+* `pandoc_epub_extra_options`: List of extra pandoc options for epub generation.
+
+Notable **limitations** with regard to the export suppport:
+
+* There is currently no way of overriding template or option settings for a specific format on a per-page basis.
+
+* There is currently no option for turning some list of export formats on by default for all pandoc-processed pages. The reason is that some plugins which insert content into the page, notably the [template plugin](https://ikiwiki.info/plugins/template/), call pandoc in such a way that the pandoc plugin apparently has no certain way of distinguishing between these calls and the processing of an entire page. A global option might thus lead to much wasted work and conceivably even to the overwriting of export files by incorrect content.
+
+Details
+-------
 
 ### Syntax Coloring
 
@@ -222,4 +264,3 @@ License
 =======
 
 GPLv2. See `LICENSE` for more details.
-

diff --git a/pandoc.pm b/pandoc.pm
index b5e201970d43e67599dbdff2a5406b9bc951f31e..239832553dccdcbdc43441b908259d2db17083d3 100755 (executable)
--- a/pandoc.pm
+++ b/pandoc.pm
@@ -15,7 +15,7 @@ my %extra_formats = (
     pdf    => { ext=>'pdf', label=>'PDF', format=>'latex', extra=>[], order=>1 },
     docx   => { ext=>'docx', label=>'DOCX', format=>'docx', extra=>[], order=>2 },
     odt    => { ext=>'odt', label=>'ODT', format=>'odt', extra=>[], order=>3 },
-    beamer => { ext=>'beamer.pdf', label=>'Slides', format=>'beamer', extra=>[], order=>4 },
+    beamer => { ext=>'beamer.pdf', label=>'Beamer', format=>'beamer', extra=>[], order=>4 },
     epub   => { ext=>'epub', label=>'EPUB', format=>'epub3', extra=>[], order=>5 },
     latex  => { ext=>'tex', label=>'LaTeX', format=>'latex', extra=>['--standalone'], order=>6 },
 );
@@ -573,9 +573,10 @@ sub export_file {
     my ($export_path, $export_url) = _export_file_path_and_url($page, $ext);
     my $subdir = $1 if $export_path =~ /(.*)\//;
     my @extra_args = @{ $extra_formats{$ext}->{extra} };
-    my $template = $config{"pandoc_".$ext."_template"} || '';
+    my $eopt = $ext eq 'pdf' ? 'latex' : $ext;
+    my $template = $config{"pandoc_".$eopt."_template"} || '';
     push @extra_args, "--template=$template" if $template;
-    my $conf_extra = $config{"pandoc_".$ext."_extra_options"};
+    my $conf_extra = $config{"pandoc_".$eopt."_extra_options"};
     if (ref $conf_extra eq 'ARRAY' && @$conf_extra) {
         push @extra_args, @$conf_extra;
     }