Version dev

# How to configure the speedata publisher

The speedata publisher can be configured in several ways:

1. The file publisher.cfg in `/etc/speedata/`, in the home directory (with a leading dot) and in the current working directory (Linux, Mac)
2. The file `%APPDATA%\speedata\publisher.cfg` on Windows.
3. Parameters given on the command line
4. Options given in the layout file

## The file `publisher.cfg`

The file publisher.cfg (`/etc/speedata/publisher.cfg`, `$HOME/.publisher.cfg` and in the current working directory) is a text file that is read at the beginning of the publisher run. The default file looks like this:

    data      = data.xml
    layout    = layout.xml
    autoopen  = false
    # This is a comment
    # But this is not a comment
    # ^^^ of course the line above is also a comment
    #

    # section specific values
    [section]
    key = value

You can access the base directory of the project with `%(projectdir)s`. This is the directory with the file `publisher.cfg`.

All entries in the configuration file are optional. The configuration files are read in the following order: `/etc/speedata/publisher.cfg`, `~/.publisher.cfg` and in the current directory `publisher.cfg`. The current directory can be changed on the command line with the switch `--wd=....`.

The format of the file is important, otherwise it won’t be recognized. The following options are supported:

`autoopen` (command line: `--autoopen`)
  If true, the publisher opens the PDF file after the run. Default: false.
`addlocalpath` (command line: `--local`, `--no-local`)
  If true, the publisher adds the current working directory recursively to the search path. Default: true.
`cache` (command line: `--cache`)
  Caching-strategy for http(s) image requests and external image processors. Use `fast` for file system lookup only or `optimal` for checking on each request. Use `none` for no caching. `none` works also for SVG conversion. In this case, PDF is generated on each request. The default is `optimal`.
`data` (command line: `--data`)
  Name of the data file (XML). If not given, the system uses `data.xml`. Use `-` to read the data from standard input (STDIN, only one run possible). An external resource (`http://`) can be given as well.
`dummy` (command line: `--dummy`)
  If true, the system won’t read the data file, instead it uses the single element `<data />` as its input.
`extra-dir` (command line: `-x`, `--extra-dir`)
  A list of directories in the file system separated by `;` (Windows) or `:` (Mac, Linux). These directories contain the images, fonts, source files and other assets that are used during the publisher run. Example for windows: `extra-dir=c:\myfonts`. On the command line the parameter can be given multiple times.
`extensionhandler`
  Assignment of file extensions to converters defined in ‘imagehandler’. To convert graphics on-the-fly. Example: `extensionhandler="mmd:mermaid"`. Multiple entries are separated by semicolon. See also `imagehandler`. (Since version 3.9.1.)
`extraxml` (command line: `--extra-xml`)
  Add this XML file to the layout instructions. List of comma separated file names (`extraxml=file1.xml,file2.xml`). Not supported with the new XPath module. Use xinclude instead.
`fontloader`
  Set the fontloader to `fontforge` (default until version 4.16) or `harfbuzz` (default starting from version 4.18). The `fontforge` fontloader is deprecated and scheduled for removal in version 6.0.
`filter` (command line: `--filter`)
  Run the given file as a Lua filter. See the section Lua-Filter / Vorverarbeitung.
`fontpath`
  Set the path for system fonts. On Windows this is `%WINDIR%\Fonts`, on Mac OS X it defaults to `/Library/Fonts:/System/Library/Fonts`.
`grid` (command line: `--grid`, `--no-grid`)
  If true, the underlying grid is shown in the PDF file. For debugging purpose only. Can also be enabled in the layout with the `<Trace>` command.
`hidespinfo`
  If set to ’true’, the speedata Publisher does not add the `(Created with the speedata Publisher - www.speedata.de)` information. Needs a Pro plan.
`imagecache` (command line: `--imagecache`)
  Folder for cached images (`href="http://..."` and image processors). Defaults to `$TMPDIR/sp/images`. The directory is created if necessary.
`imagehandler`
  Assignments of image type to external converters, for example `imagehandler="mermaid:(/usr/bin/mmdc -i %%input%% -o %%output%%.pdf)"`. Multiple entries are separated by semicolons. How this works, the placeholders and further examples are described in the section External Conversion Tools.
`ignore-case` (command line: `--ignore-case`)
  Ignore case when accessing files (on a case-insensitive file system) in the recursive file lookup.
`inkscape` (command line: `--inkscape`)
  The path to the program inkscape when you need on the fly SVG to PDF conversion.
`inkscape-command`
  Command line for image conversion. Version 0.92 and before needs `--export-pdf` and since version 1 it is `--export-filename`.
`jardir`
  Directory containing the Java JAR files used for XSLT and RELAX-NG processing. Defaults to the bundled `lib` directory. Mainly relevant for OS package maintainers — see Using system-provided Java JARs.
`jobname` (command line: `--jobname`)
  Name of the output file (without extension). Default is `publisher`.
`layout` (command line: `--layout`)
  Name of the layout rule set (XML). The default name is `layout.xml`. An external resource (`http://`) can be given as well.
`loglevel` (command line: `--loglevel`)
  Set the log level to one of `debug`, `info`, `message`, `warn` and `error`. Messages from this level and above are written to the protocol file.
`luatex`
  Path to the LuaTeX binary. Experimental! This is provided for your experiments, not for production use.
`mode` (command line: `--mode`)
  Set the layout mode. See Control of the layout.
`opencommand`
  Command that will be run to open the documentation and the PDF file. For MacOS X this should be `open`, for Linux `xdg-open` or `exo-open` (xfce).
`pathrewrite`
  Comma separated list of entries of the form A=B which replace parts in `file:///media/XYZ` to `file:///path/to/project/myfiles/XYZ`. Useful when you have absolute paths in the data which must be changed during the publishing process.
`pdfversion` (command line: `--pdfversion`)
  The PDF version that gets written. Default is `1.7`.
`prependxml` (command line: `--prepend-xml`)
  Add this XML file in front of the layout instructions. List of comma separated file names (`prependxml=file1.xml,file2.xml`). Not supported with the new XPath module. Use xinclude instead.
`reportmissingglyphs`
  Should requested but missing glyphs be reported as an error or as a warning? The allowed values are `true`, `false`, or `warning`. `false` disables the reporting.
`resizehandler`
  Assignment of screen type to external converters that resize images to the desired DPI. For example, `resizehandler="jpegimage:(magick %%input%% -resize %%width%%x%%height%%! %%output%%)"`. See also the section Configuration of the Resize Handler. (Since version 5.1.23.)
`runs` (command line: `--runs`)
  Set the number of runs.
`startpage` (command line: `--startpage`)
  Number of the first page.
`systemfonts` (command line: `--systemfonts`)
  If set to `true`, then the publisher searches for fonts in the system directories. Does not work on Windows XP.
`tempdir` (command line: `--tempdir`)
  Name of the temporary directory. Default is the system’s temp.
`timeout` (command line: `--timeout`)
  Maximum time of the publishing run. If time is exceeded, the publisher exits with status 1.
`vars` (command line: `-v`, `--var`)
  Comma separated list of variables and values in the form `var=value` to set additional variables. On the command line each `--var variable=value` sets one variable and can be given multiple times, see also `--varsfile`. The variables can be used in the layout with `select="$variable"`.
`verbose` (command line: `--verbose`)
  `true` prints the messages from the protocol file to the standard output.
`wd` (command line: `--wd`)
  Change into this directory before the run starts, as if you had changed into it with `cd` beforehand.
`xpath` (command line: `--xpath`)
  Set the XML module. The current default is `lxpath`, and the old is called `luxor`. The old parser is deprecated and scheduled for removal in version 6.0.

### Section server (`server`)

`address` (command line: `--address`)
  IP address to which the server should open the port. Default is 127.0.0.1.
`extra-dir`
  Extra directories for the publishing runs to be included.
`filter`
  Lua script to run before processing the publishing runs (like a call to `sp --filter ...`).
`logfile` (command line: `--logfile`)
  File name for the log. `STDOUT` for standard output and `STDERR` for standard error.
`loglevel`
  Set the log level to one of `debug`, `info`, `message`, `warn` and `error`.
`port` (command line: `--port`)
  Port to which a connection can be established. Default is 5266.
`runs`
  Set the number of publishing runs for the client document.

### Section Hotfolder (`hotfolder`)

`hotfolder`
  Directory to be “watched”.
`events`
  Rules which programs to run on which files.

A detailed description can be found in the Starting the Publisher via the Hotfolder section.

## Command line parameters

The valid command line parameters are written on a separate page.

## Options given in the layout file

The XML layout file has a command called `<Options>` that allows to set some parameters (tracing, default language, …)

#### On this page