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

# Using fonts

Embedding fonts in the common formats is very easy. The formats Type1 (files .pfb and .afm) as well as TrueType and OpenType (files .ttf and .otf) are supported.

To make fonts known and used by the publisher, two steps are necessary. The first step is to load a font file:

    <LoadFontfile name="MinionRegular" filename="MinionPro-Regular.otf" />

This assigns the file name MinionPro-Regular.otf the internal name MinionRegular. In the second step, these internal names are then used to define families:

    <DefineFontfamily name="textfont" fontsize="9" leading="11">
      <Regular fontface="MinionRegular"/>
      <Bold fontface="MinionBold"/>
      <Italic fontface="MinionItalic"/>
      <BoldItalic fontface="MinionBoldItalic"/>
    </DefineFontfamily>

The last three cuts (bold, italic and bold italic) do not have to be specified if they are not used in the layout. fontsize is the font height in points, leading is the distance between two baselines.

Font size and line spacing

The font is used in different ways: in the commands `<Textblock>`, `<Text>`, `<Paragraph>`, `<Table>`, `<NoBreak>` and `<Barcode>`, a font can be specified with the attribute fontfamily, e.g. `<Paragraph fontfamily="text font">`. Temporarily you can switch to another family with the command `<Fontface fontfamily="…​">`:

    <Paragraph>
      <Fontface fontfamily="title">
        <Value>Preface</Value>
      </Fontface>
      <Value> more text</Value>
    </Paragraph>

## Text labeling in the layout rules

There are several ways to switch to the cuts fat, italic and fat-italic. The most direct one is to switch with the commands `<B>` and `<I>`, these can also be nested within each other:

    <PlaceObject>
      <Textblock fontfamily="textfont">
        <Paragraph>
          <Value>A wonderful </Value>
          <B><Value>serenity</Value></B>
          <Value> has taken possession </Value>
          <I><Value>of my</Value>
            <Value> </Value>
            <B><Value>entire soul,</Value></B>
          </I>
          <Value> like these sweet mornings.</Value>
        </Paragraph>
      </Textblock>
    </PlaceObject>

Text markup in layout. Underline (not shown) is possible with the command `<U>`.

## Text markup in the data

If there are markups in the data (e.g. as HTML tags), then this works in principle in exactly the same way:

    <PlaceObject>
      <Textblock fontfamily="textfont">
        <Paragraph>
          <Value select="."/>
        </Paragraph>
      </Textblock>
    </PlaceObject>

with the corresponding data:

    <data>A wonderful <b>serenity</b> has taken possession
      <i>of my <b>entire soul,</b></i> like these sweet
      mornings.</data>

The result is the same as above. The tags can also be written in capital letters in the data: `<B>` instead of `<b>. Nesting is also allowed and again `<u>` is underlined.

| If the data is not in well-formed XML but in HTML format for example, you can use the layout function `sd:decode-html()` to interpret it.

## OpenType Features

The OpenType format knows so-called OpenType features, such as old style figures or small caps. Some of these features can be activated at `<LoadFontfile>`.

    <Layout
      xmlns="urn:speedata.de:2009/publisher/en"
      xmlns:sd="urn:speedata:2009/publisher/functions/en">

      <!-- Oldstyle figures / text figures -->
      <LoadFontfile
        name="MinionRegular-osf"
        filename="MinionPro-Regular.otf"
        oldstylefigures="yes" />

      <!-- Small caps -->
      <LoadFontfile
        name="MinionRegular-smcp"
        filename="MinionPro-Regular.otf"
        smallcaps="yes" />

      <DefineFontfamily name="osftext" fontsize="10" leading="12">
        <Regular fontface="MinionRegular-osf"/>
      </DefineFontfamily>

      <DefineFontfamily name="smcptext" fontsize="10" leading="12">
        <Regular fontface="MinionRegular-smcp"/>
      </DefineFontfamily>

      <Record element="data">
        <PlaceObject>
          <Textblock>
            <Paragraph fontfamily="osftext">
              <Value>Text with oldstyle figures 1234567890</Value>
            </Paragraph>
            <Paragraph fontfamily="smcptext">
              <Value>Text with small caps 1234567890</Value>
            </Paragraph>
          </Textblock>
        </PlaceObject>
      </Record>
    </Layout>

Text figures (above) often make reading the numbers more pleasant. Real small caps (below) differ significantly from mathematically reduced capital letters. The line width and proportions must be adjusted. Depending on the font used, smallcaps also switches to "old style figures".

## Harfbuzz

Since version 4 of speedata Publisher there is a new mode for loading font files: harfbuzz. It activates the library of the same name, which not only loads the font files, but is also responsible for the arrangement of characters in a word (text shaping). This is not as important for western writing systems as for e.g. Arabic. A side effect of the harfbuzz library is the extensive support for OpenType features.

Using the harfbuzz mode is as follows:

    <LoadFontfile
      name="..."
      filename="..."
      mode="harfbuzz" />

The OpenType features can be set with the `features` attribute, for example

    <Layout xmlns="urn:speedata.de:2009/publisher/en"
        xmlns:sd="urn:speedata:2009/publisher/functions/en"
        >

        <LoadFontfile name="CrimsonPro-Regular"
          filename="CrimsonPro-Regular.ttf"
          mode="harfbuzz" />
        <LoadFontfile name="CrimsonPro-Regular-frac"
          filename="CrimsonPro-Regular.ttf"
          mode="harfbuzz"
          features="+frac" />

        <DefineFontfamily fontsize="10" leading="12" name="regular">
            <Regular fontface="CrimsonPro-Regular" />
        </DefineFontfamily>
        <DefineFontfamily fontsize="10" leading="12" name="frac">
            <Regular fontface="CrimsonPro-Regular-frac" />
        </DefineFontfamily>

        <Record element="data">
            <PlaceObject>
                <Textblock>
                    <Paragraph fontfamily="regular">
                        <Value>Use 1/4 cup of milk.</Value>
                    </Paragraph>
                    <Paragraph fontfamily="frac">
                        <Value>Use 1/4 cup of milk.</Value>
                    </Paragraph>
                </Textblock>
            </PlaceObject>
        </Record>
    </Layout>

Upper text without the `frac` feature, lower text with the feature.

A complete description of the OpenType features can be found on https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist

## Optical margin alignment

With the parameter marginprotrusion (percentage) at the command `<LoadFontfile>` you can determine how far certain characters (comma, dot and hyphen) protrude into the right margin. This can be used to achieve an optically smoother margin in justified text:

    <Layout
      xmlns="urn:speedata.de:2009/publisher/en"
      xmlns:sd="urn:speedata:2009/publisher/functions/en">

      <Options mainlanguage="German" />
      <LoadFontfile name="main"
                    filename="MinionPro-Regular.otf"
                    marginprotrusion="100" />

      <DefineFontfamily name="text" fontsize="10" leading="12">
        <Regular fontface="main"/>
      </DefineFontfamily>

      <Record element="data">
        <PlaceObject>
          <Textblock width="4">
            <Paragraph>
              <Value select="."/>
            </Paragraph>
          </Textblock>
        </PlaceObject>
      </Record>
    </Layout>

The associated data file (`data.xml`) is as follows:

    <data>A wonderful serenity has taken possession of my entire
      soul, like these sweet mornings of spring which I enjoy
      with my whole heart. I am alone, and feel the charm of
      existence in this spot, which was created for the bliss of
      souls like mine. I am so happy, my dear friend, so
      absorbed in the exquisite sense of mere tranquil
      existence, that I neglect my talents.</data>

Left: Comma, period and hyphen protrude into the right margin. Right: without optical margin alignment.

## In which directory must the font files be located?

The organization of the files, and thus the fonts, is described in the directory File Organization. With `sp --systemfonts` when calling the publisher, you can access the system-wide font files.

## Tips and tricks

In order to save yourself work in defining fonts, you can use the command

    $ sp list-fonts --xml

use. This will then list all font files found, together with a line that can be used directly in the layout.

    $ sp list-fonts --xml
    <LoadFontfile name="DejaVuSans-Bold"
                  filename="DejaVuSans-Bold.ttf" />
    <LoadFontfile name="DejaVuSans-BoldOblique"
                  filename="DejaVuSans-BoldOblique.ttf" />
    <LoadFontfile name="DejaVuSans-ExtraLight"
                  filename="DejaVuSans-ExtraLight.ttf" />
    ...

| If no font is specified for a paragraph or text block (etc.), the system uses the text font family, which is also predefined in the Publisher and can be overwritten. See the Preferences in the Publisher appendix.

## Missing characters and replacement fonts

The character sets in the font files are usually very limited. For example, the speedata Publisher is delivered with the free font "TeXGyreHeros" (a very good Helvetica clone). However, the font file only contains characters that cover western languages, but not, for example, Greek, Arabic, Chinese etc. Also the whole Unicode special characters like U+2685 DIE FACE-6 (⚅) are not included. If a character is requested that is not contained in the font, an error message is displayed.

    Error: Glyph f1c7 (hex) is missing from the font "TeXGyreHeros-Regular"

This error can be suppressed with the command <Options>:

    <Options reportmissingglyphs="no"/>

Alternatively, you can also specify a replacement font at `<LoadFontfile>`, which will be searched as soon as a character is not found:

    <LoadFontfile name="helvetica" filename="texgyreheros-regular.otf">
      <Fallback filename="fontawesome-webfont.ttf" />
      <Fallback filename="line-awesome.ttf" />
    </LoadFontfile>

First the font `texgyreheros-regular.otf` is searched, then `fontawesome-webfont.ttf` and finally `line-awesome.ttf`.

## Aliases

There is a command to add an alternate name for an existing font name to the list of known font names:

    <DefineFontalias existing="..." alias="..."/>

The commands

    <LoadFontfile name="DejaVuSerif"
            filename="DejaVuSerif.ttf" />
    <LoadFontfile name="DejaVuSerif-Bold"
            filename="DejaVuSerif-Bold.ttf" />
    <LoadFontfile name="DejaVuSerif-BoldItalic"
            filename="DejaVuSerif-BoldItalic.ttf" />
    <LoadFontfile name="DejaVuSerif-Italic"
            filename="DejaVuSerif-Italic.ttf" />

    <DefineFontalias existing="DejaVuSerif" alias="serif"/>
    <DefineFontalias existing="DejaVuSerif-Bold" alias="serif-bold"/>
    <DefineFontalias existing="DejaVuSerif-Italic" alias="serif-italic"/>
    <DefineFontalias existing="DejaVuSerif-BoldItalic"
             alias="serif-bolditalic"/>

now allow to define font families in general as follows:

    <DefineFontfamily name="title" fontsize="15" leading="17">
      <Regular fontface="serif"/>
      <Bold fontface="serif-bold"/>
      <BoldItalic fontface="serif-bolditalic"/>
      <Italic fontface="serif-italic"/>
    </DefineFontfamily>

i.e. independent of the font actually used. With the options described in the section Splitting layout sets of rules into individual files, you can now swap the font definition into a separate file and, if necessary, quickly choose between different fonts by including the desired files.

- Hyphenation / language settings
- Text formats