Publications and publication types
This feature requires PageSeeder v5.96 or higher.
Background
A “publication” is a hierarchical collection of PSML component documents joined by “embed” or “transclude” type xrefs.
The core of the feature is a process that seamlessly resolves the publication component into a single document for presentation or numbering. The following documentation explains the options for processing a publication.
For additional background, we recommend completing this tutorial. The challenges of document numbering are widely recognized and the sample files of the tutorial help to explain how PageSeeder addresses this issue.
Concepts
Following are some key ideas that have a role in PageSeeder publications.
Block labels
Publications process the content of a <block>
element if the value of the @label
attribute corresponds to a declaration in the publication config. Use cases for block labels include numbering figures or tables.
Block labels and headings
In the publication-config
, the level of the <block>
element declarations is significant. Any values to be included with the counter must already be declared in the config.
For example, to prefix a figure caption with a chapter number, say – Chapter 4: Figure 7 – and chapter heading is @level="2"
, then block-label="figure-caption"
cannot be declared at @level="1"
. To create a prefix that includes a value from level 2, the declaration for the counter must be at least @level="3"
.
Components / Shared components
Component document is a term to describe a document that has been referenced from a publication root using an embed, or transclude xref. A shared component is part of multiple publications. How the document is numbered, or its position in the Table of Contents, depends on which publication root is current (open).
See also “current publication”.
embed
and transclude
These are the only two xref types that can be used to assemble component documents into a publication.
Current publication
The publication that determines the display of a component document. Where a component is shared, it is possible to select other publication root documents by clicking the box at the top of the Table of Contents.
See also “shared component”.
@level
vs @indent
In PSML, the <heading>
element has a @level
attribute and the <para>
element has an @indent
attribute. For the purposes of the publication configuration, unless the documentation is explicit, consider any references to level
to also mean indent
.
Microsoft Word
To reliably generate correctly numbered DOCX files, it is important to calibrate the Word template and the publication config. See DOCX support.
Numbered vs Unnumbered
Both <heading>
and <para>
elements support an attribute of @numbered
that is available through the number icon in the editing interface. Any object where this attribute has a value of true
is subject to processing by the publication config.
Publication config
Stores all configuration information for a given Publication Type in the following folder:
template/[project]/publication/[type]
Publication headings
The <heading>
element is a fundamental part of PSML, and in a publication, it is the primary structural and navigational object. Only the content of <headings>
elements are displayed in the ToC.
Publication ID
Adding a publication ID through the document properties makes any PSML document with embed or transclude xrefs into a publication. All documents with a publication ID are listed in the Group Publications. A document with a publication ID is known as the Publication Root.
While future releases might provide tools to help manage publication IDs, at present, as it is with the Doc ID, users must ensure that IDs are unique within a server. Preventing ID clashes can usually be achieved by prefixes that incorporate the project or group name.
Publication paragraphs
In publications, all the properties of a <heading>
element are available to the <para>
element, with one important distinction—<para>
elements are not display in the ToC by default and when displayed their content is always truncated.
References document type
Although it is not mandatory, the references document type is the logical choice for the document-type of a publication root.
Table of Contents (ToC)
The PageSeeder interface supports two approaches to the ToC:
- If all the headings are linked from a single references document, the entire ToC is displayed at once.
- If the publication root links to a references document, the ToC displays the high-level xref titles always, but only displays a complete list of headings for the current references document.
Versions
Publications add a new dimension to PageSeeder document versions, especially documents that are part of multiple publications. See Versioning a publication.
Xref config
These are project-level configurable templates that automatically format links such as references to numbered paragraphs, footnotes or citations.
<xref display="template" title="{parentnumber}{prefix}" config="paragraph" ...>
Best Practice
Getting the best results out of publications is easier under the following circumstances:
- Start every document with a heading level 1 then let the references document and publication process calculate the final level of heading. This is easier than trying to anticipate and adjust the position of the heading in the hierarchy.
- Do not put any paragraphs before the level 1 heading in a document.
- To include single fragments in a publication, use xref type of “transclude”, not “embed”.
- Whenever using an xref type of “embed”, the link cannot be one-way, it must reverse.
The in-built “best practice” schema validates for these issues.
Publication management
Following are the details for some routine tasks:
Create a publication
To create a publication requires a publication ID. These can consist of letters, numbers, hyphens or underscores up to 250 characters long. This value must be unique for the PageSeeder server (similar to Document ID).
To create a publication from an existing set of documents, follow these steps:
- Navigate to the root document and click the Properties tab.
- Enter an ID of your choice under Publication ID (usually less than 20 characters).
- Unless users have specific instructions to choose a Publication type, ignore this field and let the system assign the default type.
- Click Save.
Now click the View tab on the horizontal menu, then open the Table of contents block to the left of the document. This displays all the headings across the publication files—see following.
Delete a publication
To delete a publication, clear the value from the publication ID field on the Properties page.
This also deletes all the versions associated with the publication.
Change the publication root
To change the root document of a publication, navigate to the new root document and enter the publication ID on the Properties page. To do this, the user must also have contributor access to the old root document.
Publication configuration
Each publication has a type that specifies the levels and numbering. If no value has been selected through the Publication Type field on the Properties page of the root document, then the type is default.
To define a custom publication-type needs a publication-config.xml
file in the template/[project]/publication/[type]
folder. To create this file, do the following:
-
In the Developer perspective, go to Document config under the Dev tab on the horizontal menu.
-
Select Create publication type and enter a name using only letter, number and underscore characters.
-
Select the create icon next to
publication-config.xml
. -
Modify the publication (see options following).
-
Save the publication config file.
-
Navigate to the publication root and click the Properties tab.
-
In the Publication type field, select the new type.
-
Save the changes.
Select reload after any edits. This clears the cache and regenerates the tables of contents with the new settings.
publication-config.xml
Following is the default publication-config.xml
used by PageSeeder.
<publication-config> <toc title-collapse="always" /> <levels xref-relative-to="heading" para-relative-to="6" /> <numbering> <schemes> <scheme level="1" type="decimal" format="[1.]" /> <scheme level="2" type="decimal" format="[1.][2]" /> <scheme level="3" type="decimal" format="[1.][2.][3]" /> <scheme level="4" type="decimal" format="[1.][2.][3.][4]" /> <scheme level="5" type="decimal" format="[1.][2.][3.][4.][5]" /> <scheme level="6" type="decimal" format="[1.][2.][3.][4.][5.][6]" /> <scheme level="7" type="loweralpha" format="[(7)]" element="para" /> <scheme level="8" type="lowerroman" format="[(8)]" element="para" /> <scheme level="9" type="upperroman" format="[(9)]" element="para" /> <scheme level="10" type="upperalpha" format="[(10)]" element="para" /> </schemes> </numbering> </publication-config>
<toc> element
This element is optional and can have the following optional attributes:
Attribute | Description | Default value |
---|---|---|
title-collapse |
By default, PageSeeder documents are created with the same value in the document title and the first heading of the document. The reason to collapse the title is so that the default content doesn’t appear twice in the ToC. Allowed values for
| always |
para-indents |
The allowed value for this attribute is a comma-separated list of indent values. By default, only headings are included in the ToC. However, this attribute allows the content of autonumbered or prefixed paragraphs to be included (only the first 40 characters are displayed). Requires PageSeeder v5.9702 or higher. | |
block-labels |
The allowed value for this attribute is a comma-separated list of block labels values). By default, only headings are included in the ToC. However, this attribute allows the content of paragraphs wrapped by block labels to be included (only the first 100 characters). Requires PageSeeder v5.9702 or higher. |
<levels> element
When processing the publication components into a single instance, this element controls the resolution of the levels. This can affect the numbering and presentation of headings, paragraphs and xrefs. This element is optional and can have the following optional attributes:
Attribute | Description | Default value |
---|---|---|
xref-relative-to |
Calculates the link title by processing the heading levels of the target document. Allowed values are:
| heading |
para-relative-to |
Determines how paragraph indents are calculated when the documents in the publication are consolidated. Allowed values are:
| heading |
heading-adjust |
DEPRECATED as of v5.98. Indicates whether to adjust the
| numbering |
para-adjust |
DEPRECATED as of v5.98. Indicates whether to adjust the
| numbering |
<numbering> element
The <numbering>
element applies numbering schemes to a PSML document that has a specific document label. Without this element, there is no generation of numbers in the publication. The <numbering>
element supports the following optional attributes:
Attribute | Description | Default value |
---|---|---|
skipped-levels |
Non-consecutive, or “skipped” heading levels are for example when a
| 1 |
document-label | Numbering only applies to documents with the specified document label. When a document has multiple labels, the first <numbering> element in the config that matches is used. |
<scheme> element
Each <scheme>
represents a configuration of publication characteristics differentiated by a @level
attribute.
For the sake of consistency and clarity, the configuration for each @level
is explicit. Where the content of a publication does not conform with what has been declared in the scheme, a contingency must be declared (see the @skipped-levels
attribute on the <numbering>
element above).
The <scheme>
element can have the following attributes:
Attribute | Description | Default value |
---|---|---|
level |
Each scheme level must have a unique value (required). If the value of the For example, there might be a requirement to process the level 2 differently in an Appendix than the body of a Report. To do this, one of the numbering schemes must have a
| |
format |
The formatting characteristics of each level of the scheme (required). Defined by one or more patterns
| |
type |
The expression of numbering (optional). Allowed values are the following:
| decimal |
element |
The PSML element that each numbering level applies to (optional). Allowed values are the following:
| heading |
block-label |
Spawns a separate numbering stream when this value corresponds to the value of the Designed to support use cases such as numbering figures and tables separate to paragraphs or headings. For example, Table 1.1, Table 3.1. Requires PageSeeder v5.98 or higher. |
Example
<publication-config> <toc title-collapse="always" /> <levels xref-relative-to="heading" para-relative-to="heading" heading-adjust="content" para-adjust="content" /> <numbering> <schemes> <scheme level="1" type="decimal" format="[1.]" /> <scheme level="2" type="decimal" format="[1.][2]" /> <scheme level="3" type="decimal" format="[1.][2.][3]" /> <scheme level="4" type="decimal" format="[1.][2.][3.][4]" /> <scheme level="5" type="decimal" format="[1.][2.][3.][4.][5]" /> <scheme level="6" type="loweralpha" format="[(6)]" /> <scheme level="7" type="lowerroman" format="[(7)]" /> <scheme level="8" type="upperroman" format="[(8)]" /> <scheme level="9" type="upperalpha" format="[9]" /> </schemes> </numbering> <numbering skipped-levels="strip" document-label="detail"> <schemes> <scheme level="1" type="decimal" format="[1.]" /> <scheme level="2" type="decimal" format="[1.][2.]" /> <scheme level="2" type="decimal" format="[Table 1-][2]" block-label="table-caption" /> <scheme level="2" type="upperalpha" format="[Fig 1-][2]" block-label="figure-caption" /> <scheme level="3" type="decimal" format="[1.][2.][3.]" element="any"/> <scheme level="4" type="decimal" format="[1.][2.][3.][4.]" element="any"/> <scheme level="5" type="loweralpha" format="[(5)]" element="para"/> <scheme level="6" type="lowerroman" format="[(6)]" element="para" /> <scheme level="7" type="upperalpha" format="[(7)]" /> <scheme level="8" type="upperroman" format="[(8)]" /> <scheme level="9" type="loweralpha" format="[9]" /> </schemes> </numbering> </publication-config>
DOCX support
It is important to understand the consequences of the settings in the publication-config.xml
file and their effect on Microsoft Word or applications that can process DOCX
file format such as Adobe InDesign.
Getting the needed results from the PageSeeder publication requires coordinating the publication config and the docx
template to meet the objectives of the final output.
The intention of the publication is to deliver the wanted results. Sometimes the best way to do this is to capture the numbering logic but not necessarily to transfer these settings to DOCX or other formats. In many cases, the intention of these properties is to represent the same logic, so that the people editing have a representation that is closer to their final format. This might be something as straightforward as image numbers, so references are the same in the editing view as they are in the final format. For example, [Fig 1-2]
instead image-456.jpg
.
To calibrate the publication with a docx
template or an InDesign import might require some deep understanding of non-PageSeeder technologies. In addition to the publication-config
, users might need to configure the Default Numbering in the PageSeeder word-export-template.doc
. See How to configure auto-numbering for additional information.
As many people might know already, applications like Word and InDesign are powerful, but complex. The good news is that PageSeeder publications can support very demanding numbering, done properly. Users can expect the numbering in their Word documents to be correct every single time they export. Unfortunately, this needs Word skills, not only PageSeeder.
Contact Allette Systems to discuss your requirements.
Versioning a publication
All the component documents in a publication can be versioned by taking the following steps:
- Navigate to the publication root document and click the Version tab.
- Click Create publication version and enter the new version number.
- Click Submit.
Refresh the version page and mouse over the identifier for the new version. Something like Publication ID: [mypub1] is displayed in the pop-up box.
To create a publication version for a single document, do the following:
-
Navigate to a document in the publication and select the Version tab.
-
Select Create version and enter an identifier for the version.
-
Select a Publication from the drop-down menu.
-
Submit.
In the change history of a fragment, publication versions have the publication ID in [square brackets] after the version identifier.
Exporting a publication
To export a publication version, follow these steps:
- Select Developer perspective from the cube icon (top left).
- Navigate to the publication root (alternatively, where a publication is the content of a single folder, navigate to the location).
- For the root document, select the Export icon from the action block the upper left of the Document view. (for the Folder view, select Export from icon to the right of the folder).
- In the root document, select Export as PSML and enter an appropriate number under Maximum depth of forward xrefs.
- If applicable, select Version to export.
- Select the appropriate value under Publication ID for version. The publication ID must correspond to the publication version or compare version. A publication ID with no version or compare version exports the original uploaded version.
- Click Export.