Getting Started with Paligo

Table of Contents

PDF Layout Editor Options

The tree of items you can choose to style in the Layout Editor is divided into a number of sections. Each section is described below, with the items you can style and the options available for them.

The Layout Editor will get more features continually, based on customer feedback for desired styling.

Note

Many of the items and options are self-explanatory, and have explanations right in the Layout Editor. So only the items that may not be immediately transparent are explained below.

General

Category/Element

Styling parameters

Description

Document

Double-sided

Select this option if you plan to print the publication as a book, with binding on the inside.

Languages

Specify if and how you want language names for a multilingual publication to appear.

Page

Here you can set the number of columns for your output, as well as header and footer settings.

Page margins

Page margin widths for top, bottom, outer, and inner margins.

Please note that the value of 0in does not have any effect until you change the value and save. Until then a default page margin will be used.

Fonts

  • Default font for titles

  • Default font for document body text

  • Font size for body text

Here you can set the default font for all titles. This will then be used unless you specify another value for certain level titles (Section 1, 2 etc).

Images

Default width for images

If you set a default width for images, any images that have no specific width set on them in the topic itself will get this width.

Default height for inline images

If you use inline images (the inlinemediaobject element), e.g for icons inline with the text, it defaults to fit the image in the normal line height. If you want to change this, you can do so here.

Border and border radius- set this if you want all images to have a border by default. 

You set it as a compound value: 0.25pt solid silver, e.g, setting border width, style, and color.

You can also set a border radius if you want rounded corners. Either use padding to get it as a frame, or if you want to cut the corners of the image itself, experiment with values and a white color to match the page color. Usually a ratio of 3 gets a good result. Eg., border = 3pt solid white and border-radius = 9pt.

You can override the default setting here on individual images by setting the role attribute to a value like  border: 0.25pt solid silver; border-radius: 3pt; padding: 15pt;. Of course if you just want the border, just use the first part. Each part is delimited by a semicolon.

The attribute should be set on the imagedata element.

Note

Note that there is one condition for this to work properly: every image that you set borders on must have a width attribute. Otherwise the border will be as wide as the page, which the image might not be. So if you set borders on images globally in the Layout Editor, you need to set the image "width" attribute on all images.

TOC

Styling properties for the Table of Contents

Misc

Miscellaneous other properties, such as hyphenation, text alignment, and specialized PDF output options: tagged or linearized.

You can also choose to set to use xml:lang as a profiling attribute here (for filtering content), if needed.

Bookmarks

Choose whether to generate PDF bookmarks

Prepress

Various prepress options

If you need to set crop marks, bleed, etc, sometimes required for printing purposes, you can set them here.

Draft

You can create a specific layout that you use for draft output only, to mark it up as such by e.g header text and a watermark.

To have your regular styling, create a new layout based on your custom style, and then just add these parameters.

Front Page

Category/Element

Styling parameters

Description

Logotype

Upload logotype for front cover, set alignment, margins, height, and width.

Set the alignment to select where the logotype will be placed on the page.

The margins you can select has a default value that may look a bit peculiar, e.g {$page.margin.inner}. This is a reference notation that will set it to the same as the page margin. If you set the value directly, e.g 1in, you can choose to give the logo a different margin.

Product image

Upload product image

This allows you to select and upload a default product image. If you do so, it will be placed on all publications using this style.

If you use a specific product image in the publication itself (opening the project/publication and adding an image in the cover element), that image will take precedence.

Background image

Upload background image and set background color

One use for this is if you have a complete background image that in itself represents the entire front cover.

Languages

Display language list

If you choose to publish multiple languages in one publication, checking this box will display those languages on the front cover.

Display language name on sidebar

If you check this, each language section of the publication will have a language bar on the outside of the page, showing the current language.

Language format

This dropdown allows you to select the format for displaying the language on the front cover and in the language bar, either as the full local name of the language, e.g "Italiano", or in English, e.g "Italian", or as a language code, e.g "it".

Header and Footer

Category/Element

Styling parameters

Description

Page header

Width for each area, and height of the entire area. For each area, set none, text, image, page number, title as the content.

The header area consists of three areas for content, like the cells of a table.

You can set how wide each area should be.

Then for each area/cell, select what content to place there using the dropdown list.

If you choose image or text, use the corresponding fields to upload the image or type the text.

Note

If you need the text field to be translatable, that can be done too, but please contact support for that.

Page footer

Width for each area, and height of the entire area. For each area, set none, text, image, page number, title as the content.

Same as for the header.

Note

You can also use Dynamic Text for text fields. There is some complexity to this, but it gives you a lot of flexibility for your content:

This means you can fetch data from your publication, such as the content of an edition element, publication date, publication name, and so on.

You can even use Dynamic Text to output things like the current date.

To do this, you use a special syntax. The dynamic text syntax at its most basic is: ${dynamictexthere}$

To output dynamic content from your publication, you use something called Xpath. For instance, if you want to output the edition element from your publication, you can use this:

${/d:article/d:info/d:edition}$

What this says is: Get the edition element content from the info element in the article (the XML element for a "publication"). And you don't really have to bother with this, but the "d:" part is just something that is needed for the XML to work. Just use it like this and it will work.

As another example, if you want to output the current date, you use this:

${date:date-time()}$

This means, output the current date. You can use these variables anywhere within a text field, making it very dynamic. So for instance you could have a text field saying: "Published on ${date:date-time()}$ by ${/d:article/d:info/d:author/d:orgname}$.

This would output a so-called time stamp. You can also use metadata already in the content, so if you just want the date for the time modified for instance, and no time zone info, you can use this:

${@xinfo:time-modified}$

There are also certain parameters you can use in dynamic text: the name of the current day or month for example. This is especially useful if you need greater control when you want to output the current date. In order to format the date, use the function date:format-usertime.

${date:format-usertime('EEE, MMM d, yyyy')}$

This would output something like Wed, Jul 4, 2017. You can find more examples and a technical specification on SimpleDateFormat (Java 2 Platform SE 5.0).

If you want to use this Dynamic Text and need help, contact support.

Section Titles

Category/Element

Styling parameters

Description

All sections

Default font size, font weight, section numbering, and color for all titles.

The font size uses a reference notation so that you can set the size relative to the body font size. This can be useful to get a consistency in your styling. Only change the value of the factor number if you want to do this.

If you want to hard code the value (e.g 15pt) you can do this too.

This is also the category to use if you want to set numbering for sections (topics). For instance if you want your section titles to have numbering like 1.2, 1.3.1 etc.

Level 1

Same parameters as all sections, and all other levels, and in addition background color.

Level 1 titles (topics on the highest level in a project/publication nesting structure) normally represents chapters or the equivalent.

In the default style for PDF top-level topic titles ("chapters") get a blue banner background. You can change this color, or just use white to remove the banner. Then change the font color to fit this background.

Level 2, 3, 4, 5

Same settings, but setting it separately for all lower levels.

Bridgehead

Same common properties as for section titles.

A bridgehead is an "intermediate" title that can be inserted in the middle of a topic. Can often act as a subtitle, when a separate topic or internal section is not suitable.

Formal objects

The term Formal objects comes from the content model. It basically is an umbrella term for elements like lists, figures, tables, equations, examples. In this section you can make general settings applying to all such elements consistently if desired.

Note that any settings you make on a higher level (General) can be overridden if you set another value on a lower level (like "informalexample")

Lists

Category/Element

Styling parameters

Description

General

Margin before/after lists.

Default value is used if the value here is "auto". Specify a value such as 15p, or 2em e.g t if you want a specific margin.

Unordered Lists

Various options for the bullet formatting.

You can specify what symbol you want for bullets depending on their nesting level.

Ordered Lists

The width of the label (number).

Set this if you want to control how much space there is between the label and the text of the list item.

Procedures

Font and color options

Use these styling options to make your procedures stand out from regular ordered lists.

Tables

Category/Element

Styling parameters

Description

General

Default width, font settings and padding for table cells, as well as the option to use alternate rows or not.

Most options are self-explanatory, alternate rows is the option to use a styling with every other row having a grey background or not.

Header

Header background color and font settings.

Footer

Footer background color and font settings.

Admonitions

Category/Element

Styling parameters

Description

General

Graphics and font settings

Select whether your admonitions (warnings and the like) should use icons or not by setting the graphics option. By default the standard admonition icons in Paligo will be used, but this can be changed to use custom icons.

Graphical

Various options for styling admonitions with icons, including the possibility to upload your own icons to replace the default ones.

Nongraphical

Various options for admonitions if you don't use icons.

Verbatim

Verbatim is a term for different kinds of elements that are to be output exactly as they are typed, i.e preserving white space and line breaks, such as elements for code samples, like programlisting.

Such elements can be particularly tricky in PDF output, because they can take up more space than the page allows. This section allows you to make a number of settings to deal with that problem:

  • Font-size: Set the default font-size for verbatim elements. You can override this on individual elements by using the role attribute, setting it to a value like font-size:8pt. You can also use the common size designators similar to CSS: small, smaller, etc.

  • Line-wrap: You can enable line wrapping by default for all verbatim elements. And if you do, you can choose to indicate that the line is really meant to continue from the previous line, as is a common convention when exemplifying code. You can choose which character to use as an indicator for this ("hyphenation character"). Note that your font must support the character you choose. This default setting can also be overriden by using the attribute role, set to a value of either wrap-option:wrap or wrap-option:no-wrap.

  • Color and border: You can also select whether you want your programlisting to have a background color and/or border.

  • Syntax highlighting: you can turn syntax highlighting on for code snippets (programlisting, etc), choose a theme and also the default programming language. If you set the language attribute on a particular element, that will override the default setting here.

    Note

    Note that syntax highlighting for PDF and HTML uses different highlighting mechanisms, so while both offer a number of themes, some similar, the exact look and feel will not be quite identical for each of these outputs.

Keep-together options

The keep-together options provide the possibility to control how elements are kept together on the same page or column, by default.

It is available for many of the most common elements, and each one has a dropdown where you select one of three values:

The default values often work very well, and usually you don't have to change these default settings, but if you do these are the options:

  1. no - means the element will not be kept together by default.

  2. yes - means the PDF processor will attempt to keep the element together. But the processor may in certain cases run into cases where it is not appropriate, and will then attempt to select the best keep option. This is usually the best choice if you want to keep a certain element together.

  3. always - means the element will be kept together no matter what. This is the strictest rule, and may be ok, but could also cause some undesired keeps.

Note

Note that you can always override the default values for a particular element in a topic, using the xinfo:keep-together and xinfo:keep-with-next attributes.