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. Publications are at group level.

The core of the feature is a process that seamlessly resolves the publication components 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. Use xref type of “transclude” to include single fragments in a publication.

Current publication

The publication that determines the display of a component document. Where a component is shared, at the top of the Table of Contents panel, to the right of the publication title, you can click the angle-down icon to select other publications from the drop-down.

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’s 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 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 by default in the ToC, but you can configure the TOC to include numbered paragraphs.

Publication ID

Adding a publication ID through the document properties makes any PSML document with embed or transclude xrefs into a publication. A document with a publication ID is known as the Publication root.

All documents with a publication ID are listed in the Publications tab on the group homepage:

Navigation menu >  Group >  Group home 

Publication paragraphs

In publications, all the properties of a <heading> element are available to the <para> element, with one important distinction – <para> elements aren’t displayed in the ToC by default, and when displayed, their content is always truncated.

References document type

Although it’s 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:

1. 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.
2. Do not put any paragraphs before the level 1 heading in a document.
3. To include single fragments in a publication, use xref type of “transclude”, not “embed”.
4. Whenever using an xref type of “embed”, the link cannot be one-way, it must reverse.

Publication management

Following are the details for some routine tasks.

Create a publication

Publication ID

To create a publication requires a Publication ID on the publication root document. This value must be:

• Unique for the PageSeeder server domain (similar to Document ID).
• Up to 250 characters long (but usually less than 20 characters), and
• It can only contain the following characters: [a-z][A-Z][0-9][-_]

To create a publication from an existing set of documents, follow these steps:

1. Navigate to the document that is to be the publication root document, and click the  icon in the right sidebar to open the Document info & metadata panel to the default Properties tab.
2. Click the Make this document a publication button at the bottom of the panel.
3. Enter an ID of your choice in the ID field.
4. Unless users have specific instructions to choose a Publication type, ignore this field and let the system assign the default type.
5. Click Submit.

The Table of contents panel on the left displays all the headings that you have added to your root document, across the publication files – see the following image.

Delete a publication

To delete a publication, clear the value from the Publication ID field in the Document info & metadata panel.

Change the publication root

To do this, the user must have a role of contributor or higher, to edit the old root document to remove the Publication ID if they want to re-use it for the new root document.

Since Publication ID's must be unique server-wide, you must first delete the old publication. Then, navigate to the document you want to be the new root document and make it a publication, or if already a publication, edit the Publication ID – you can re-use the Publication ID you deleted, or you can use a different Publication ID.

Publication configuration

Each publication type has an associated publication-config.xml file that defines every aspect of the levels and numbering that you see when viewing the publication content in PageSeeder, including:

• Numbered headings.
• Paragraphs.
• Numbering for other objects such as images.
• How numbering restarts, and
• How numbering is inherited across documents in the publication.

If no value in the Publication type field, on the Document info & metadata panel of the publication root document, then the type is default.

If you won’t be using the default publication, first a new publication type needs to be created, then create its publication-config.xml file in the template/[project]/publication/[type] folder. To create this file, do the following:

1. Go to the Template configuration page:

1. Administration menu > [Project] > Template > Template configuration, OR

2. Click the Manage document types button in the Developer tools panel, OR

3. Click the Manage document types button at the top of the Navigation menu > Project > Document types page.

2. Under the Publication types tab, click Create publication type... and enter a name using only letter, number, and underscore characters:

1. Click the Cancel button to abandon creating the publication type, or

2. Click Create and the name displays in the table – to delete it, click the  icon beside the publication name in the table.

3. To create the publication-config.xml file, under the Config column, click Create.

4. Click edit to open and modify the publication config contents in the template file panel at the right (see options following).

5. Save the publication config file.

6. Navigate to the publication root document and click the  icon to open the Document info & metadata panel on the right.

7. In the Publication type field, select the new type from the drop-down.

8. Save the changes.

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="upperalpha"
              format="[(9)]"
              element="para" />
      <scheme level="10"
              type="upperroman"
              format="[(10)]"
              element="para" />
    </schemes>
  </numbering>
</publication-config>

<toc> element

This element is optional and can have the following optional attributes:

<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:

<numbering> element

The <numbering> element applies numbering schemes to a PSML document and can apply additional numbering schemes for documents that have a specific document label. See the example below. Without this element, there is no generation of numbers in the publication. The <numbering> element supports the following optional attributes:

<scheme> element

Each <scheme> represents a configuration of publication characteristics differentiated by a @level attribute. It must appear inside a <schemes> element that is inside a <numbering> element. See the example below.

For the sake of consistency and clarity, the configuration for each @level is explicit. Where the content of a publication doesn’t 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:

<scheme level="7"
        type="lowerroman"
        format="[(8)]"
        element="para" />
<scheme level="7"
        type="decimal"
        format="[Figure 7]" 
        element="para"
        block-label="Caption" />

<restart> element

Each <restart> represents a rule for when to restart the numbering. It must appear inside a <restarts> element after <schemas>. Requires PageSeeder v6.0012 or higher.

Without using this element, when a numbered heading or paragraph is encountered the publication numbering for all levels below it is restarted automatically, except for schemes with a @block-label that don’t include this level in their @format. This is so figures can be numbered independently, for example.

However, if a <restart> element is specified for a level, then a numbered OR unnumbered heading or section title at that level restarts the numbering for all levels below it, for ALL schemes (unless it has a @block-label which restricts it to those schemas). Paragraphs at the correct level will also trigger a restart in PageSeeder v6.1000 or higher.

The <restart> element can have the following attributes:

Example

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

  <numbering skipped-levels="strip" document-label="component">
    <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.]"
              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="7"
              type="decimal"
              format="[Table 1-][7]"
              block-label="table-caption" />
      <scheme level="7"
              type="upperalpha"
              format="[Fig 1-][7]"
              block-label="figure-caption" />
      <scheme level="8"
              type="upperroman"
              format="[(8)]" />
      <scheme level="9"
              type="loweralpha"
              format="[9]" />
    </schemes>
    <restart>
      <restart level="2" />
      <restart level="4"
               block-label="table-caption" />
    </restart>
  </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.docx. 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

Only approvers can create document versions.

By default, the Apply this version to all the documents in the current publication [publication ID]. is selected.

All the component documents in a publication can be versioned by taking the following steps:

1. View the publication root document, or any document in the publication, and click the icon in the right sidebar. The Document versions panel displays on the right.
2. Click Create version... and in the Version dialog, enter the new version name:
1. Maximum length 250 characters, or click one of the following buttons:
1. Minor – default value is 0.1.
2. Major – default value is 1.0.
3. Date – select date, click the calendar.
3. If needed, enter a note, add labels or change message settings.
4. Click Create version.

The new version displays in the Document versions panel. When you hold the cursor over the icon beside the new version name, the publication ID (something like Publication: mypub1) is displayed in the tool tip. When component documents are shared, the icons for the different publications show as different colours, eg mypub1 might be blue and mypub2 might be red.

In the Document history panel for a document, any version changes to a document are grouped together for a given date. When you click the Show versions option, the Document versions panel opens on the right.

Exporting a publication

To export a publication version, follow these steps:

1. When viewing a publication root document, click the icon in the right sidebar. If in Folder view, click the icon to the right of the root document, then click the icon.
2. Choose an export action from the drop-down:
1. For example, select Export as PSML and click the Show more details option. Enter an appropriate number under Maximum depth of forward xrefs.
2. If applicable, select a Version to export from the drop-down.
3. Select the appropriate value under Publication ID for version. The publication ID must correspond to the publication version or compare version. Selecting a publication ID with no version or compare version exports the current version.
4. If applicable, select a Log level from the drop-down.
3.  Click Run.