doc/plugins/contrib/compile.mdwn

   1 [[!meta author="spalax"]]
   2 [[!template id=plugin name=compile author="[[Louis|spalax]]"]]
   3
   4 # Compile
   5
   6 The compile plugin provides the `compile` directive, used to on-the-fly compile
   7 and publish documents.
   8
   9 For instance, if you want to publish files together with their sources (like
  10 `.tex` and `.pdf` files), you can have the `.tex` file in your source wiki
  11 directory, and command `\[[!compile files="foo.tex"]]` (or wikilink
  12 `\[[foo.tex]]`, if the right option is set) will compile file and render as a
  13 link to the `.pdf` file.
  14
  15 [[!toc startlevel=2]]
  16
  17 ## Warning
  18
  19 Some important security notice.
  20
  21 - This plugins allows user to execute arbitrary commands when compiling the
  22   wiki.  Use at your own risk. If you use Ikiwiki as a static web site compiler
  23   (and not a wiki), and you are the only one to compile the wiki, there is no
  24   risk. If you *do* allow untrusted users to edit or comment on the wiki, they
  25   can use the `compile` directives to execute completely arbitrary code, regardless
  26   of configuration safeguards you may put.
  27
  28 - Source files are published, wheter option `source` is true or not. If
  29   `source` is false, source may not be *advertised*, but it is still available
  30   somewhere on your website (most likely by replacing in the compiled file URL
  31   the extension of the compiled file by the extension of the source file). So,
  32   do not use this plugin if you do not want to publish your source files
  33     (sorry: I designed this plugin to publish free stuff).
  34
  35 The plugin could be modified to only allow commands to be modified from the
  36 configuration and it would be safer to use. However, it would still be vulnerable
  37 to command injection attacks because it uses `qx()` command expansion, which
  38 runs commands through `/bin/sh -c`. A thorough security review would be in order
  39 before this should be considered secure running on untrusted input.
  40
  41 A simpler implementation, that only runs a predefined set of commands, may be
  42 simpler to implement than auditing this whole plugin. For example, the
  43 [[bibtex2html]] module performs a similar task than the compile module, but
  44 hardcodes the command used and doesn't call it with `/bin/sh -c`. It could be
  45 expanded to cover more commands.
  46
  47 ## Rationale
  48
  49 I want to publish some latex files, both source (`.tex`) and compiled (`.pdf`)
  50 version, but I do not want to maintain two versions of the same file.
  51
  52 Using this plugin, I only have to maintain the `.tex` files, and thoses files
  53 are compiled on the fly, so that the `pdf` is published.
  54
  55 ## String formatting
  56
  57 Strings (destination name, template name and build command) accept python-like
  58 syntax ``%{name}s``, which is replaced by the value of variable ``name``. The
  59 following variables are abailable.
  60
  61 - `srcname`: Source name.
  62 - `srcextension`: Extension of the source name.
  63 - `filetype`: File type (extension of the source name, otherwise specified by directive).
  64 - `dirname`: Directory of the source file.
  65 - `wikiname`: Name of source file, relative to source wiki directory.
  66 - `srcfullname`: Name of source file, relative to file system root.
  67 - `basename`: Source name, without directory nor extension.
  68 - `destname`: Destination name (without directory).
  69 - `destextension`: Extension of the destination name.
  70 - `targetname`: Destination name, relative to the destination directory.
  71 - `destfullname`: Destination name, relative to file system root.
  72
  73 ## Directive
  74
  75 ### Usage
  76
  77 Basic usage of this plugin is:
  78
  79     \[[!compile files="foo.ext"]]
  80
  81 It renders file `foo.ext` according to rules defined in the setup file, and
  82 publish the compiled version.
  83
  84 ### Arguments
  85
  86 All the arguments (but `source` and `filetype`) are string which are processed
  87 using python-like string formatting, and described in the setup options section.
  88
  89 - `files`: List of files used in compilation, as space separated string. For
  90   instance, to compile some tex file including a png image, you will have:
  91   `files="foo.tex image.png"`. It is not possible to have filenames containing
  92   spaces (unless you provide me a patch to recognize escaped spaces).
  93 - `filetype`: By default, the source file extension is used to determine build
  94   command and other configuration. If the same extension refer to different
  95   type of files, you can enforce the filetype using this argument. For
  96   instance, if some your LaTeX files have to be compiled with `pdflatex`, while
  97   the other require `latex`, your `compile_filetypes` can contains two keys
  98   `tex` and `texdvi`. By default, LaTeX files will be compiled using
  99   configuration associated to `tex`, unless directive has argument
 100   `filetype=texdvi`, in which case the latter configuration is used.
 101 - `destname`: Name of the compiled file name.
 102 - `build`: Build command.
 103 - `source`: Boolean to choose whether to publish source file or not. The only
 104   effect is the template choice: source is always published (but not always
 105   advertised).
 106 - `template`: Name of the template to use (if set, the `source` option is
 107   irrelevant).
 108 - `var_*`: Any argument with a name starting with ``var_`` is transmitted to the template. For instance, if directive has argument ``var_foo=bar``, then the template will have a variable named ``foo``, and ``<TMPL_VAR FOO>`` will be replaced by ``bar``.
 109
 110 ### Extensions
 111
 112 Note: This directive does not work if source file name does not have an
 113 extension (i.e. does not contain a dot). This should not be too hard to
 114 implement, but I do not need it. Patches welcome.
 115
 116 ## Configuration
 117
 118 Here are the setup options (most of them can be overloaded on a per-extension
 119 basis by setup option `compile_filetypes`, or by directive arguments):
 120
 121 - `compile_source` (boolean): should sources be published with compiled file
 122   (this only affect template choice; see warning)? Default is true.
 123 - `compile_template_source` (string): name of the template to use for compiled
 124   files when option `source` is true. Default is `compile_source.tmpl`.
 125 - `compile_template_nosource` (string): name of the template to use for
 126   compiled files when option `source` is false. Default is
 127   `compile_nosource.tmpl`.
 128 - `compile_filetypes` (string): Per extension configuration (see paragraph
 129   below).
 130 - `compile_tmpdir` (string): Path of a directory to use to compile files:
 131   source file (and dependency) are copied to this directory before being
 132   compiled (to avoid messing the ikiwiki directory with compiled version or
 133   auxiliary files). Default is `SOURCE_WIKI/.ikwiki/tmp/compile`.
 134 - `compile_bindir` (string): Directory containing binaries to use to compile
 135   files. Default is undefined.
 136 - `compile_depends` (string): List of files all compiled files will depend on
 137   (see *Compilation* section below).
 138 - `compile_build` (string): Command to use to compile files. Default
 139   is undefined.
 140 - `compile_inline` (boolean): If true, wikilinks pointing to files with an
 141   extension specified in `compile_filetypes` are treated as a directive
 142   \[[!compile files="LINK"]]. For instance, if this is set globally (or just
 143   for tex), a wikilink \[[foo.tex]] will compile file `foo.tex`, and publish
 144   the compiled `foo.pdf` file.
 145
 146 ### The `compile_filetypes` option
 147
 148 This variable is a json string, representing a dictionary. Keys are source file
 149 extensions, values are dictionary of options applying only to files with this
 150 extension.
 151
 152 Keys of these new directory are `source`, `template_nosource`,
 153 `template_source`, `build`, `depends`, `inline`, and overrides generic options
 154 defined above. They are themselves overriden by directive arguments (excepted
 155 `inline`).
 156
 157 Example:
 158
 159     compile_filetypes => '{
 160       "tex": {
 161         "build": "pdflatex %{basename}s",
 162         "destname": "%{basename}s.pdf",
 163         "depends": ["logo.png"],
 164         "inline": "1"
 165       },
 166       "texdvi": {
 167         "build": "latex %{basename}s",
 168         "destname": "%{basename}s.pdf",
 169         "depends": ["logo.eps"]
 170       }
 171     }'
 172
 173 ## Compilation
 174
 175 ### Dependencies
 176
 177 Before compilation, the source file and all dependencies are copied to the
 178 temporary directory defined by option `compile_tmpdir`. For instance, if all
 179 you LaTeX files are compiled using a custom class `foo.sty`, and a particular
 180 file `bar.tex` uses the `logo.png` file, your setup option will contain
 181 `foo.sty` as `depends`, and `compile` directive will be called using
 182 `\[[!compile files="bar.tex logo.png"]]`. Then, before compilation, files
 183 `foo.sty`, `bar.tex` and `logo.png` will be copied in the same temporary
 184 directory.
 185
 186 Note that path are *flattened* when copied: before performing compilation of
 187 directive `\[[!compile files="sub1/foo sub2/bar"]]`, files `foo` and `bar` will
 188 be copied in the same directory: this temporary directory will contain failes
 189 `foo` and `bar`, but not `sub1/foo` and `sub2/bar`.
 190
 191 ### Build command
 192
 193 The build command used is (if defined, by priority order):
 194
 195 - defined by argument `build` of directive;
 196 - setup command ``compile_filetypes{TYPE}{build}``;
 197 - setup command ``compile_build`` (if you have a generic build command);
 198 - command ``$config{compile_bindir}/${extension}s %{srcname}s`` (if setup variable ``compile_bindir``is defined, is a directory, and contains an executable file matching the extension, it will be used);
 199 - command ``make -f $config{compile_bindir}/make.${extension}s %{destname}s`` (if setup variable ``compile_bindir`` is defined, is a directory, and contains a readable makefile ``make.EXTENSION``, it will be used).
 200
 201 ## Template
 202
 203 The way links are rendered is defined in a template, which is (by order of
 204 priority, some of them depends on whether ``source`` is true):
 205
 206 - argument `template` of directive;
 207 - setup variable ``compile_filetypes{TYPE}{template_source}`` or ``compile_filetypes{TYPE}{template_nosource}``;
 208 - setup variable ``compile_source`` or ``compile_nosource``;
 209 - `compile_source.mdwn` or `compile_nosource.mdwn`.
 210
 211 It is passed the following variables:
 212
 213 - `DESTURL`: URL to the compiled file.
 214 - `DESTNAME`: Name of the compiled file.
 215 - `SRCURL`: URL to the source file.
 216 - `SRCNAME`: Name of the source file (without directory).
 217 - `ORIGNAME`: Name of the source file (with directory).
 218
 219 Note that templates can be used to display images (instead of a link to them).
 220 For instance, if you have a `.tiff` file you want to convert to png before
 221 displaying it on your website, you can use as a template:
 222
 223     <img src="<TMPL_VAR DESTURL>">
 224
 225 # Download
 226
 227 Code and documentation can be found here : [[https://atelier.gresille.org/projects/gresille-ikiwiki/wiki/Compile]].