Running the speedata publisher on the command line

The speedata Publisher is started via the command line (also: terminal, command window). On the one hand there are commands, on the other hand the commands can be controlled via parameters.

$ sp <Command> <Parameter> <Parameter> ...

The default command is run. So the call of

$ sp

the same as

$ sp run

Besides the command run there are other commands (see below).

With

$ sp --help

you can display a list of the allowed commands and parameters.

Description of the commands

clean

Deletes all generated intermediate files and keeps the PDF file.

checkupdate

Checks if a new version of the Publisher is available. Return code is 0 if the version is up to date. 1 if a new version is available.

clearcache

Removes files from the image cache.

compare

Recursively check a directory for layout changes. See the topic about quality assurance.

doc

Opens the reference manual in the browser (local HTML files).

list-fonts

Lists all font files found in the Publisher directories. Together with --xml this command allows you to copy and paste the output into the layout rules. See Using fonts.

new [DIRECTORY]

Create simple layout and data file to start. Provide optional directory.

run

Start publishing (default).

server

Run as http-api server on localhost port 5266 (configure with --address and --port). See the chapter Server-Modus (REST API).

watch

Start watchdog / hotfolder. See Starting the Publisher via the Hotfolder.

Description of the commandline parameters

-h, --help

Show this help

--address=IPADDRESS

Address to be used for the server mode. Defaults to 127.0.0.1.

--autoopen

Open the PDF file. Can be set in the How to configure the speedata publisher.

--cache=METHOD

Use cache method. One of none, fast or optimal. Default is optimal. See the description in the How to configure the speedata publisher.

-c, --config=NAME

Read the config file with the given NAME. Default: publisher.cfg

--credits

Show credits and exit

--[no-]cutmarks

Display cutmarks in the document

--data=NAME

Name of the XML data file. Defaults to data.xml. Use - for STDIN (only 1 run possible).

--dummy

Don’t read a data file, use <data /> as input

-x, --extra-dir=DIR

Additional directory for file search.

--extra-xml=NAME

Add this file to the layout file. Not supported with the new XPath module. Use xinclude instead.

--filter=FILTER

Run Lua filter before publishing starts

--generate-completion=SHELL

Print a shell completion script (bash, zsh or fish) to standard output and exit. See the section Shell completion below.

--grid

Display background grid. Disable with --no-grid

--ignore-case

Ignore case when accessing files (on a case-insensitive file system) in the recursive file lookup.

--imagecache=PATH

Set the image cache

--inkscape=PATH

Set the path to the inkscape program

--jobname=NAME

The name of the resulting PDF file (without extension), default is publisher

--[no-]local

Add local directory to the search path. Default is true

--layout=NAME

Name of the layout file. Defaults to layout.xml

--logfile=NAME

Logfile for server mode. Default publisher.protocol. Use STDOUT for standard output and STDERR for standard error.

--loglevel=LVL

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.

--mainlanguage=NAME

The document’s main language in locale format, for example en or en_US.

--mode=NAME

Set mode. Multiple modes given in a comma separated list. See advanced-controllayout.

--option=OPTION

Set a specific option that has no command line parameter.

--outputdir=DIR

Copy PDF and protocol to this directory.

--pdfversion=VERSION

Set the PDF version. Default is 1.7.

--prepend-xml=NAME

Add this file in front of the layout file. Not supported with the new XPath module. Use xinclude instead.

--port=PORT

Port to be used for the server mode. Defaults to 5266

--progress

Show progress information on standard output. Displays the current page number and elapsed time during a publishing run. If the publisher has been run before, it also shows the expected total number of pages (from the previous run) and the previous run duration. This option disables --verbose. Cannot be used together with --verbose.

--quiet

Run publisher in silent mode

--runs=NUM

Number of publishing runs

--startpage=NUM

The first page number

--show-gridallocation

Show the allocated grid cells

-s, --suppressinfo

Suppress optional information (timestamp) and use a fixed document ID

--systemfonts

Use system fonts (not Win XP)

--tempdir=DIR

Use this directory instead of the system temporary directory

--trace

Show debug messages and some tracing PDF output

--timeout=SEC

Exit after SEC seconds

-v, --var=VAR=VALUE

Set a variable for the publishing run

--varsfile=NAME

Set variables for the publishing run from a file with each line containing key=value pairs. Lines starting with a # are ignored.

--verbose

Print the messages from the log file to standard out.

--version

Show version information

--wd=DIR

Change working directory

--xpath

Set the XML and XPath parser. Valid values are luxor and lxpath. Default is ’lxpath’. The old luxor is less robust and has fewer capabilities.

--xml

Output as (pseudo-)XML (for list-fonts)

Shell completion

sp can produce tab-completion scripts for bash, zsh and fish. The script is written to standard output, so redirect it to wherever your shell expects completion files.

The completion knows all options and commands; for options that take a value it offers file completion as a generic default.

Bash

Per user (requires the bash-completion package):

$ sp --generate-completion=bash > ~/.local/share/bash-completion/completions/sp

System-wide (e.g. from a distribution package): /usr/share/bash-completion/completions/sp.

Zsh

Per user, one possible setup:

$ mkdir -p ~/.zsh/completions
$ sp --generate-completion=zsh > ~/.zsh/completions/_sp

Then add the following to ~/.zshrc before the compinit call:

fpath=(~/.zsh/completions $fpath)

System-wide locations are /usr/share/zsh/vendor-completions/_sp (Debian/Ubuntu) or /usr/share/zsh/site-functions/_sp.

Fish

Fish picks completions up automatically from the user configuration directory:

$ sp --generate-completion=fish > ~/.config/fish/completions/sp.fish

System-wide path: /usr/share/fish/vendor_completions.d/sp.fish.