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
# And 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

if true, the publisher opens the PDF file. Default: false. The same effect can be achieved if you run sp --autoopen.

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.

data

Name of the data file (XML). If not given, the system uses data.xml.

dummy

If true, the system won’t read the data file, instead it uses the single element <data /> as its input.

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.

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

Add this XML file to the layout instructions. List of comma separated file names (extraxml=file1.xml,file2.xml).

fontloader

Set the fontloader to fontforge (default until version 4) or harfbuzz (default starting from version 5).

prependxml

Add this XML file in front of the layout instructions. List of comma separated file names (prependxml=file1.xml,file2.xml).

filter

Run the given file as an Lua-Filter. See the section Lua-Filter / pre-processing.

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

If true, the underlying grid is shown in the PDF file. For debugging purpose only.

imagecache

Folder for cached images (href="http://…​" and image processors). Defaults to $TMPDIR/sp/images.

imagehandler

Assignments of screen type to external converters. For example, imagehandler="mermaid:(/usr/bin/mmdc -i %%input%% -o %%output%%%.pdf)". The image type mermaid is converted with the program /usr/bin/mmdc and receives as input parameter -i, the input file, -o and the output file with attached file extension .pdf. The file names are replaced at runtime and generated randomly. Multiple entries are separated by semicolons.

ignore-case

Ignore case when accessing files (on a case-insensitive file system).

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.

jobname

Name of the output file. Default is publisher.

layout

Name of the layout rule set (XML). The default name is layout.xml.

luatex

Path to the Lua(jit)TeX binary. Experimental! This is provided for your experiments, not for production use.

mode

Set the layout mode. See Control of the layout when calling the Publisher.

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.

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.

runs

Set the number of runs.

startpage

Number of the first page.

systemfonts

If set to 'true', then the publisher searches for fonts in the system directory.

tempdir

Name of the temporary directory. Default is the system’s temp.

timeout

Maximum time of the publishing run. If time is exceeded, the publisher exits with status 1.

vars

Comma separated list of variables and values in the form var=value to set additional variables.

wd

Set the current directory.

xmlparser

Sets the XML parser to use. Since version 4.5 the default is go, the old variant is lua. This option will be dropped in a future version of the Publisher in favor of the go variant and is currently included only for compatibility.

Section server (`server')

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 includes.

filter

Lua script to run before processing the publishing runs (like a call to sp --filter …​).

logfile

File name for the log. STDOUT for standard output and STDERR for standard error.

port

Port to which a connection can be established.

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, …)