Configuration

Configuration manual for PageSeeder

Publication types

This feature requires PageSeeder v5.96 or later.

A publication is a set of documents embedded or transcluded into the same hierarchy. A document can be in more than one publication allowing for re-use of content. Grouping documents in a publication enables the following features:

  • Display a table of contents (TOC) for a document and it's ancestors in a publication.
  • Configure heading and paragraph numbering for a publication.
  • Display numbering in the TOC based on the publication being viewed.
  • Resolve target numbering in XRef link text automatically (e.g. <xref display="template" title="{prefix}"> ).
  • Version all documents in a publication independent of other publications.
  • Export a version of a publication independent of other publication versions.

Note

Publications will work best if the recommendations below are followed:

  1. In a document have only one heading 1 at the top, with heading 2s below it.
  2. Do not use XRef type embed for single fragments, use transclude instead.
  3. All XRefs with type embed must be reverse links.

Doing a validation with the "best practice" schema should find these issues.

Creating a publication

Each publication has a root document which is the document at the top of the hierarchy. A publication must also have a user chosen publication ID which consists of letters, numbers, hyphens or underscores up to 250 characters long. It provides an easy, stable way to identify the publication and must be unique for the website domain on 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. Click on Save.

Now click on the View tab and open the Table of contents block (on the left) which should display the contents for the whole publication.

Deleting a publication

To delete a publication clear the publication ID from the root document Properties page.

Note

This will also delete all the versions associated with the publication.

Changing the publication root

To change the publication root document, 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.

Configuring a publication

Each publication has a type which can be used to customize the numbering and heading/paragraph levels for publications with that type. If no type is selected on the Document properties page of the root document then the type will be default.

A custom publication type is defined using a publication-config.xml file located in the template/[project]/publication/[type] folder on the server. The easiest way to create this file is as follows:

  1. Go to the Dev > Document config page in the Developer perspective.
  2. Click the Create publication type button and enter the name for the type which can contain letters, numbers or underscores.
  3. Click on the create icon next to publication-config.xml.
  4. Make modifications to customize the publication (see Publication config below).
  5. Click the Save button at the bottom.
  6. Navigate to the root document of the publication and click the Properties tab.
  7. Select the new type under Publication type.
  8. Click on Save.

Note

After editing an existing publication config the reload link next to it should be clicked to clear the cache for any related tables of contents so they will be reloaded with the new configuration.

Publication config

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

<toc> element

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

AttributeDescriptionDefault value
title-collapse

Specifies when document title headings should be collapsed (i.e. removed from the TOC) to avoid duplication with the parent link in the TOC. Allowed values are:

  • always: if the first heading in a document is a higher level than the other headings always collapse it;
  • auto: if the first heading in a document is a higher level than the other headings and it matches the document title then collapse it;
  • never: never collapse headings.
always

 

<levels> element

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

AttributeDescriptionDefault value
xref-relative-to

Indicates what XRef level is relative to. The XRef level is added to the headings of the target document during processing. Allowed values are:

  • heading: relative to previous heading (e.g. XRefs under a heading 3 will effectively have their @level increased by 3)
  • document: relative to containing document, i.e. XRefs take the level of their @level.
heading
para-relative-to

Indicates what paragraph indent is relative to. Allowed values are:

  • heading: relative to previous heading (e.g. paragraphs under a heading 3 will effectively have their @indent increased by 3)
  • document: relative to containing document, i.e. paragraphs take the level of their @indent.
heading
heading-adjust

Indicates when to adjust heading @level to it's effective value. Allowed values are:

  • numbering: adjust for numbering only
  • content: adjust for numbering and in document content
numbering
para-adjust

Indicates when to adjust paragraph @indent to it's effective value. Allowed values are:

  • numbering: adjust for numbering only
  • content: adjust for numbering and in document content
numbering

 

<numbering> element

There can be multiple <numbering> elements that apply different numbering to documents with different labels. If there are no numbering elements then publication numbering will be disabled. This element can have the following optional attributes:

AttributeDescriptionDefault value
skipped-levels

How skipped levels should be numbered (e.g. heading 1 following by heading 3). NOTE: DocX does not support "0" or "strip". Allowed values are:

  • 1: skipped levels will be numbered as 1 - e.g. 2.1.3
  • 0: skipped levels will be numbered as 0 - e.g. 2.0.3
  • strip: skipped levels will be stripped - e.g. 2.3
1
document-labelNumbering will only apply to documents with this label.

Note

To continue the numbering for a document-label between multiple documents they must all have the same label and be embedded in a document with that label.

<scheme> element

Defines the numbering format for a level. If not defined for a level that level will be treated as a skipped level (see above). This element can have the following attributes:

AttributeDescriptionDefault value
level

Numbering level (required).

format

Each level format (required). Defined by one or more patterns [x(level)x] where:

  • (level): is a digit which defines the level of numbering. Currently levels 1 to 9 are supported;
  • x: is any other fixed content (e.g. Fig).

The same level can only be repeated if it has a different block-label defined.

type

The type of numbering (optional). Allowed values:
decimal, upperalpha, loweralpha, upperroman, lowerroman.

decimal
element

Which PSML element this level's numbering should be applied to (optional). NOTE: DocX does not support "any". Allowed values are: heading, para, any.

heading
block-label

Creates a separate numbering stream for this block label, useful for figures and tables (optional). When block label is defined the level attribute means the actual (not adjusted) level or indent on the element. NOTE: The format may require adjustment to match DocX e.g. [Fig 1-][2])

 

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>

Versioning a publication

Publication versions are the same as ordinary document versions but are related to a particular publication. When a publication version is created, all documents cross-referenced in that publication will have a version created that is related to the publication.

To create a publication version follow these steps:

  1. Navigate to the 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 new version number. It should display something like Publication ID: [mypub1] in the pop-up box.

A publication version can also be created for a single document only as follows:

  1. Navigate to a document in the publication and click the Version tab.
  2. Click on Create version and enter the new version number.
  3. Under Publication: select the publication from the drop down menu.
  4. Click Submit.

In the fragment change history versions related to a publication will have the publication ID in square brackets after the version number.

Exporting a publication

To export a version of a publication follow these steps:

  1. Select Developer perspective from the cube icon (top left).
  2. Navigate to the root document of the publication (alternatively if the publication is in a single folder navigate to that folder and export the whole folder).
  3. Click the Export icon in the actions block (top right) or select Export from the actions menu (left) in document browse.
  4. If using the root document click Export as PSML and enter the number of XRef levels in your publication or more under Maximum depth of forward xrefs.
  5. Under Version to export select the version.
  6. Under Publication ID for version select the publication. This is the publication ID that version or compare version must be related to. If no version or compare version related to this ID can be found the original uploaded version is used.
  7. Click Export.

 

Created on , last edited on