Configuration

Configuration manual for PageSeeder

Publications and publication types

This feature requires PageSeeder v5.96 or later.

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.

Publication ID

Adding a publication ID via the document properties will make any PSML document with embed or transclude XRefs into a publication. All documents with a publication ID are listed in the Group Publications block on the left side of the user interface. A document with a publication ID is known as the Publication Root.

Note: Future PageSeeder releases may have an interface to manage publication IDs. However, until then, it is the responsibility of users to ensure IDs are unique server-wide, like a Doc ID. To prevent ID clashes may require the use of group-level prefixes or some other mechanism to ensure uniqueness. 

Components / Shared components

Component documents are not a specific type of document, they are simply whatever documents are the target of embed, or transclude, XRefs from a publication root. A component can be the target of multiple publications with each one configured to number or present the component differently.

embed and transclude

These are the only two XRef types that can be used to assemble component documents into a publication. 

References document type

Although it is not mandatory, the references document type is the logical choice for the root document of a publication.

Publication config

Stores all configuration information for a given Publication Type in the following folder:

template/[project]/publication/[type]

Current publication

The publication controlling the current display of a component document. As opposed to another publication which may “share” the component. 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.

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 will be displayed at once,
  • if the publication root links to references document, the ToC will display the high-level XRef titles always, but only display a complete list of headings for the current references document.

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 paragraphs

In publications, all the properties of a <heading> element are available to the <para> element, with one important distinction – <para> elements do not display in the ToC.

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" will be subject to processing by the publication config.

Block Labels

Publications will 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.

Combined with headings

In the publication-config, the location of the <block> element declaration effects the numbering. If other counters are to be included with the block, the declarations must follow that sequence in the config.  

For example, to prefix a figure caption with a chapter number, say – Chapter 4: Figure 7 –and the chapter heading is @level="1" , then block-label="table-caption" must be at least @level="2".

@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

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

Versions

Publications add a new dimension to PageSeeder document versions, especially documents that are part of multiple publications. See Versioning a publication.

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

Note

The in-built “best practice” schema will validate 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:

  1. Navigate to the root document and click the Properties tab.
  2. Enter an ID of your choice under Publication ID (usually less than 20 characters).

  3. Unless users have specific instructions to choose a Publication type, ignore this field and let the system assign the default type.

  4. Click on Save.

create-publication.png

Now click the View tab on the horizontal menu, then open the Table of contents block to the left of the document. This will display all the heading across the publication files – see below.

publication-toc.png

Delete a publication

To delete a publication, clear the value from the publication ID field on the Properties page.

Note

This will also delete 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 will be 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:

  1. In the Developer perspective, go to Document config under the Dev tab on the horizontal menu.

  2. Select Create publication type and enter a name using only letter, number and underscore characters.

  3. Select the create icon next to publication-config.xml.

  4. Modify the publication (see options below).

  5. Save the publication config file.

  6. Navigate to the publication root and click the Properties tab.

  7. In the Publication type field, select the new type.

  8. Save the changes.

Note

Select reload after any edits. This will clear the cache and regenerate the tables of contents with the new settings.

publication-config.xml

Below is the default publication-config.xml used by PageSeeder.

<publication-config>
  <toc title-collapse="always" />
  <levels xref-relative-to="heading"
      para-relative-to="heading"
      heading-adjust="numbering"
      para-adjust="numbering" />
  <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)]"
                     element="para" />
      <scheme level="7" type="lowerroman"
                      format="[(7)]"
                     element="para" />
      <scheme level="8" type="upperroman"
                      format="[(8)]"
                     element="para" />
      <scheme level="9" type="upperalpha"
                      format="[9]"
                     element="para" />
    </schemes>
  </numbering>
</publication-config>

<toc> element

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

AttributeDescriptionDefault value
title-collapse

As a default, PageSeeder documents have the same value in the title and the first heading of the document. This option avoids that content appearing twice in the ToC. Allowed values are:

  • always – if the first heading in a document is above all other headings, then always collapse it;
  • auto – if the first heading in a document is above all other headings and it matches the document title, then collapse it;
  • never – never collapse the headings.
always

<levels> element

When processing the publication components into a single instance, this element controls the resolution of the levels. This can affect are the numbering and presentation of headings, paragraphs and XRefs. This element is optional and can have the following optional attributes:

AttributeDescriptionDefault value
xref-relative-to

Calculates the link title by processing the heading levels of the target document. Allowed values are:

  • heading – this option considers the XRefs target as a child of current heading in the source document. If the XRef is below a heading 3 in the source document, the content of the XRef will be promoted by three levels.
  • document – this option ignores the content of the document that hosts the XRef and simply adjust the content according to how the host document is handled by the References document. If the host is indented "+1", the headings and paragraphs in the target document are promoted one level.
heading
para-relative-to

Determines how paragraph indents are calculated when the documents in the publication are consolidated. Allowed values are:

  • heading – process according to the content in the source document,
  • document – process according to the ToC.
heading
heading-adjust

Indicates whether to adjust the @level attribute on the <heading> element. Allowed values are:

  • numbering – adjust for numbering only,
  • content – adjust for numbering and in document content.
numbering
para-adjust

Indicates whether to adjust the @indent attribute on the <para> element. Allowed values are:

  • numbering – adjust for numbering only,
  • content – adjust for numbering and in document content.
numbering

<numbering> element

The <numbering> element applies numbering schemes to PSML document-types or documents that have specific document labels. Without this element, there will be no generation of numbers in the publication. The <numbering> element supports the following optional attributes:

AttributeDescriptionDefault value
skipped-levels

Non-consecutive, or “skipped” heading levels are when a <heading level="3"> follows <heading level="1">. Processing options include the following:

  • 1 – the publication will make the missing levels a “1” – e.g. 2.1.3
  • 0 – the publication will make the missing levels a “0” – e.g. 2.0.3
  • strip – the publication will remove any reference to missing levels – e.g. 2.3
1
document-label

Numbering only applies to documents with the specified document-label and the document-label must exist on both the source and target documents.

<scheme> element

Each @level attribute on this element represents the intersection of content and the properties of the publication. All @level references are explicit. There is no way to imply headings or paragraph levels, so content with no declaration in the scheme becomes part of the “skipped-levels” processing. (see <numbering> element above).

This element can have the following attributes:

AttributeDescriptionDefault value
level

numbering level (required).

In a document this will not match the actual @level value for <heading> or @indent value for <para> in the document editing view but the post processed value of level or indent that corresponds to the position in the ToC.

format

Each level format (required).

Defined by one or more patterns [x(level)x] where:

  • (level) – defines the level of numbering from1 to 9;
  • x – is a string of static content to decorate the numbering. For example, “Figure –“ before each image number or “Chapter ” before each heading 1.

The value of a @level attribute can only be once per hierarchy. To use more than once requires each instance have a different block-label.

For example, a specification can process the level 2 numbering differently in the Appendix than the body, but one of the numbering schemes must have a block-label for disambiguation.

type

The expression of numbering (optional). Allowed values are:

  • decimal
  • upperalpha
  • loweralpha
  • upperroman
  • lowerroman.
decimal
element

The PSML element that each numbering level applies to (optional). Allowed values are:

  • heading
  • para
  • any

Note

DocX does not support "any".

heading
block-label

Spawns a separate numbering stream when this value corresponds to the value of the @label attribute on a <block> element.

Designed to support use cases such as numbering figures and tables separate to paragraphs or headings (optional). For example Table 1.1, Table 3.1 and so on.

When block label is defined the @level attribute on <format> will match the actual  @indent attribute on <para> in the document editing view. However it will not match the actual @level value for <heading> but the post processed value of level that corresponds to the position in the ToC.

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 setting in the publication-config.xml file and their effect on Microsoft Word or applications that can process docx file format such as Adobe InDesign.

In many cases, getting the desired results from a publication may require coordinating the publication config and the docx template in the context of a third-party application.

The intention of the publication properties is 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 may be something as simple as image numbers, so references are the same in the editing view as they will be 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 may require some deep understanding of non-PageSeeder technologies. In addition to the publication-config, users may 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 will know already, applications like Word and InDesign are powerful, but complex. The good news is that PageSeeder publications can support very demanding numbering and 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 just 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 these steps:

  1. Navigate to the publication root document and click the Version tab.
  2. Click on Create publication version and enter the new version number.
  3. Click Submit.

Refresh the version page and mouse over the identifier for the new version. It should display something like Publication ID: [mypub1] in the pop-up box.

To create a publication version for a single document, do the following:

  1. Navigate to a document in the publication and select the Version tab.

  2. Select Create version and enter an identifier for the version.

  3. Select a Publication from the drop-down menu.

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

  1. Select Developer perspective from the cube icon (top left).
  2. Navigate to the publication root (alternatively, where a publication is the content of a single folder, navigate to the location).
  3. 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)
  4. In the root document, select Export as PSML and enter an appropriate number under Maximum depth of forward xrefs.
  5. If applicable, select Version to export.
  6.  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 will export the original uploaded version.
  7.  Click Export.

Created on , last edited on