Search manual:

- Main page
- Introduction
- Hello, world!
- Basics
  - How to write the layout
  - Structure of the data file and the layout rules
  - Outputting objects
  - Grid
  - Areas on the page (PositioningArea)
  - File organization
  - Hyphenation / language settings
  - Using fonts
  - Text formats
  - Text formatting
  - Colors
- Programming
- Image inclusion
- Tables
- Advanced topics
  - Bookmarks
  - Creation of XML structures
  - Print output / crop marks
  - Using CSS with the speedata Publisher
  - Groups (virtual objects)
  - Virtual pages
  - Rotation of contents
  - Sorting data
  - Wrap around images
  - Page types
  - Starting the Publisher via the Hotfolder
  - Lua-Filter / pre-processing
  - Schema validation
  - Quality assurance and PDF comparison
  - Troubleshooting / Debugging
  - Server mode (REST API)
  - Control of the layout when calling the Publisher
- Cookbook
  - Thumb index
  - Embed multipage PDF files
  - Layout optimization using groups
  - Imitate bulleted lists
  - Automatically generated directories
  - Create table of contents in one go
  - Page numbers: Page x of y
- Installation instructions
- File name in the Publisher
- speedata Publisher defaults
- Running the speedata publisher on the command line
- How to configure the speedata publisher
- Lenghts and units
- XPath- and Layoutfunctions
- Internal variables
- Associate XML editor with schema
  - Visual Studio Code
  - OxygenXML
  - Atom
- Changelog
- Glossary
- Command reference
  - A
  - Action
  - AddSearchpath
  - AtPageCreation
  - AtPageShipout
  - AttachFile
  - Attribute
  - B
  - Barcode
  - Bold
  - BoldItalic
  - Bookmark
  - Box
  - Br
  - Case
  - Circle
  - Color
  - Column
  - Columns
  - Compatibility
  - Contents
  - Copy-of
  - DefineColor
  - DefineColorprofile
  - DefineFontalias
  - DefineFontfamily
  - DefineTextformat
  - Element
  - Fallback
  - Fontface
  - ForAll
  - Frame
  - Grid
  - Group
  - Groupcontents
  - HSpace
  - Hyphenation
  - I
  - Image
  - Include
  - Initial
  - InsertPages
  - Italic
  - Layout
  - Li
  - LoadDataset
  - LoadFontfile
  - Loop
  - Makeindex
  - Margin
  - Mark
  - Message
  - NewPage
  - NextFrame
  - NextRow
  - NoBreak
  - Ol
  - Options
  - Otherwise
  - Output
  - Overlay
  - Pageformat
  - Pagetype
  - Paragraph
  - PDFOptions
  - PlaceObject
  - Position
  - PositioningArea
  - PositioningFrame
  - ProcessNode
  - Record
  - Regular
  - Rule
  - SaveDataset
  - SavePages
  - SetGrid
  - SetVariable
  - SortSequence
  - Stylesheet
  - Span
  - Sub
  - Sup
  - Switch
  - Table
  - TableNewPage
  - Tablefoot
  - Tablehead
  - Tablerule
  - Td
  - Text
  - Textblock
  - Tr
  - Trace
  - Transformation
  - U
  - Ul
  - Until
  - URL
  - Value
  - VSpace
  - While

Version 4.2.0
Search manual

- Main page
- Introduction
- Hello, world!
- Basics
  - How to write the layout
  - Structure of the data file and the layout rules
  - Outputting objects
  - Grid
  - Areas on the page (PositioningArea)
  - File organization
  - Hyphenation / language settings
  - Using fonts
  - Text formats
  - Text formatting
  - Colors
- Programming
- Image inclusion
- Tables
- Advanced topics
  - Bookmarks
  - Creation of XML structures
  - Print output / crop marks
  - Using CSS with the speedata Publisher
  - Groups (virtual objects)
  - Virtual pages
  - Rotation of contents
  - Sorting data
  - Wrap around images
  - Page types
  - Starting the Publisher via the Hotfolder
  - Lua-Filter / pre-processing
  - Schema validation
  - Quality assurance and PDF comparison
  - Troubleshooting / Debugging
  - Server mode (REST API)
  - Control of the layout when calling the Publisher
- Cookbook
  - Thumb index
  - Embed multipage PDF files
  - Layout optimization using groups
  - Imitate bulleted lists
  - Automatically generated directories
  - Create table of contents in one go
  - Page numbers: Page x of y
- Installation instructions
- File name in the Publisher
- speedata Publisher defaults
- Running the speedata publisher on the command line
- How to configure the speedata publisher
- Lenghts and units
- XPath- and Layoutfunctions
- Internal variables
- Associate XML editor with schema
  - Visual Studio Code
  - OxygenXML
  - Atom
- Changelog
- Glossary
- Command reference
  - A
  - Action
  - AddSearchpath
  - AtPageCreation
  - AtPageShipout
  - AttachFile
  - Attribute
  - B
  - Barcode
  - Bold
  - BoldItalic
  - Bookmark
  - Box
  - Br
  - Case
  - Circle
  - Color
  - Column
  - Columns
  - Compatibility
  - Contents
  - Copy-of
  - DefineColor
  - DefineColorprofile
  - DefineFontalias
  - DefineFontfamily
  - DefineTextformat
  - Element
  - Fallback
  - Fontface
  - ForAll
  - Frame
  - Grid
  - Group
  - Groupcontents
  - HSpace
  - Hyphenation
  - I
  - Image
  - Include
  - Initial
  - InsertPages
  - Italic
  - Layout
  - Li
  - LoadDataset
  - LoadFontfile
  - Loop
  - Makeindex
  - Margin
  - Mark
  - Message
  - NewPage
  - NextFrame
  - NextRow
  - NoBreak
  - Ol
  - Options
  - Otherwise
  - Output
  - Overlay
  - Pageformat
  - Pagetype
  - Paragraph
  - PDFOptions
  - PlaceObject
  - Position
  - PositioningArea
  - PositioningFrame
  - ProcessNode
  - Record
  - Regular
  - Rule
  - SaveDataset
  - SavePages
  - SetGrid
  - SetVariable
  - SortSequence
  - Stylesheet
  - Span
  - Sub
  - Sup
  - Switch
  - Table
  - TableNewPage
  - Tablefoot
  - Tablehead
  - Tablerule
  - Td
  - Text
  - Textblock
  - Tr
  - Trace
  - Transformation
  - U
  - Ul
  - Until
  - URL
  - Value
  - VSpace
  - While

- Dieses Handbuch auf Deutsch

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

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

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

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

- Running the speedata publisher on the command line
- Lenghts and units