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
  - Create and use images with MetaPost
- 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
- Compatibility with other software
- Command reference
  - A
  - Action
  - AddSearchpath
  - AtPageCreation
  - AtPageShipout
  - AttachFile
  - Attribute
  - B
  - Barcode
  - Bold
  - BoldItalic
  - Bookmark
  - Box
  - Br
  - Case
  - Circle
  - ClearPage
  - Color
  - Column
  - Columns
  - Compatibility
  - Contents
  - Copy-of
  - DefineColor
  - DefineColorprofile
  - DefineFontalias
  - DefineFontfamily
  - DefineGraphic
  - DefineMatter
  - 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.6.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
  - Create and use images with MetaPost
- 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
- Compatibility with other software
- Command reference
  - A
  - Action
  - AddSearchpath
  - AtPageCreation
  - AtPageShipout
  - AttachFile
  - Attribute
  - B
  - Barcode
  - Bold
  - BoldItalic
  - Bookmark
  - Box
  - Br
  - Case
  - Circle
  - ClearPage
  - Color
  - Column
  - Columns
  - Compatibility
  - Contents
  - Copy-of
  - DefineColor
  - DefineColorprofile
  - DefineFontalias
  - DefineFontfamily
  - DefineGraphic
  - DefineMatter
  - 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

# Troubleshooting / Debugging

The output does not always work as it should. Sometimes objects are too wide, sometimes the wrong text format is used and sometimes the table does not look as it should. In order to prevent troubleshooting from becoming too difficult, the speedata Publisher provides various aids. For this there is the command <Trace>, which offers different switches. These are (by default):

    <Trace
        assignments="no"
        objects="no"
        verbose="no"
        grid="no"
        gridallocation="no"
        hyphenation="no"
        kerning="no"
        textformat="no"
        />

`assignments`

  Displays the value of the assignment (<SetVariable>) on the console.

`objects`

  Draws a line around individual objects.

`verbose`

  Increases the output on the console (log file).

`grid`

  Draws the grid. See section Grid.

`gridallocation`

  Draws the grid allocation. See section Grid.

`hyphenation`

  Marks the places where the words may be hyphenated.

`kerning`

  Mark the place where the font inserts a kerning (harfbuzz mode).

`text format`

  Creates a tooltip above each line of text, showing the text format used. See the example in the Text Formats section.

## Messages

Besides the possibilities provided by the command `<Trace>`, there is also the possibility to output messages in the log file:

    <Message select="'Hello, world!'"/>
    <Message select="sd:current-page()"/>

The output appears in the log file (`publisher.protocol`)

    Message: "Hello, world!"
    Message: "1"

The command `<Message>` can be instructed with `error="yes"` to output an error message (instead of a message). You can also specify the error code that will be returned when you exit the Publisher. See the command `<Message>` in the reference command in the reference.

## Status File and Log File

At the end of the run, two files are written to the hard disk that can be helpful for troubleshooting. The publisher.status file is an XML file that contains the error messages and other messages (via the <Message> command). The example above with the two messages results in the following file:

    <Status>
      <Errors>0</Errors>
      <Message>Hello, world!</Message>
      <Message>1</Message>
      <DurationSeconds>1</DurationSeconds>
    </Status>

A more detailed log file (publisher.protocol) is also written, which contains various information.

    Protocol file for speedata Publisher (2.9.2)
    Time: Mon Feb 20 11:03:25 2017
    ---------------------------------------------
    Start processing
    Talking to server on port 56486
    LuaTeX version 79.1
    Loading hyphenation patterns "hyph-en-gb.pat.txt".
    Language id: 0
    Loading layout instructions "/tmp/layout.xml"
    DefineFontfamily, family=2, name="Überschrift"
    Loading aux file "/tmp/publisher-aux.xml"
    Loading data file "/tmp/data.xml"
    Page of type "Default Page" created (1)
    Number of rows: 28, number of columns = 19
    PlaceObject: Textblock in row 1 and column 1, width=19, height=1 (page 1)
    Message: "Hello, world!"
    Message: "1"
    Stop processing data
    0 errors occurred
    Duration: 0.223866 seconds

## How to get help

If all troubleshooting fails or if you have questions or comments that you want to share with others, you can use the following resources:

- Chat on gitter: https://gitter.im/speedata/publisher
- Discussions on Github: https://github.com/speedata/publisher/discussions
- Issues on Github: https://github.com/speedata/publisher/issues
- Stackoverflow with tag `speedatapublisher`: https://stackoverflow.com/questions/tagged/speedatapublisher

Any feedback is welcome and helpful. Notice however: Paid support is always prioritized over unpaid support. So if you have a feature request or the need of a bug-fix, please consider buying a support plan or sponsor this project on Github to get into the fast lane.

Feature requests on Github will all be seen and written down on a non-public list but closed from Github eventually, to keep the issue list clean.

If you have a bug report: please follow the simple guideline: Make an example that is as small as possible but shows the error. Otherwise I can’t see what is going wrong.

- Quality assurance and PDF comparison
- Server mode (REST API)