From b82a74e650e5cdc24a9061a18b0594e1a3a1536a Mon Sep 17 00:00:00 2001 From: Baldur Kristinsson Date: Tue, 2 Feb 2016 10:03:34 +0000 Subject: [PATCH] Added documentation for export options --- CHANGELOG | 5 +++++ README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++----- pandoc.pm | 7 ++++--- 3 files changed, 55 insertions(+), 8 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index eab8159..eb2f957 100644 --- 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 be0b899..3afe52c 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ 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 b5e2019..2398325 100755 --- 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; } -- 2.39.2