Tutorials

Task-driven tutorials and recipes for PageSeeder

How to configure publications

Skills requiredXML
Time required (minutes)60
Intended audienceDeveloper
DifficultyEasy
CategoryDocument

Objective

This tutorial includes configuration of auto-numbering, equations, footnotes, endnotes, citations, defintions and placeholders.

A design goal for PageSeeder is to avoid the user interface having a lot of features just in case they are needed. What this tutorial demonstrates is that through the use of XRefs and a small amount of additional code, features required for complex reference publishing can be added to PageSeeder Publications. These include:

  • auto-numbering for headings, paragraphs and objects such as tables and images and the ability to refer to numbered items elsewhere in a document,

  • embedding equations as block or inline objects,

  • footnotes and / or endnotes,

  • collaborative citation management with support for the structure and semantics expected by Microsoft Word or 3rd party applications such as Zotero.

  • term management for controlled vocabularies such as glossaries, definition lists, ontologies and so on,

  • placeholders to easily manage and update simple text content repeated throughout the publication.

Prerequisites

To complete this tutorial requires:

  • PageSeeder administrator access to a server with PageSeeder version 5.98 or later installed.

All the necessary files for this tutorial are on Github .

Tutorial

Project setup

  1. Login to PageSeeder as an administrator.
  2. If not already in the v6 user interface click the Pageseeder v6 (beta) link at the top right.
  3. Click the Administration button at top right.
  4. Click on New project under Projects & Groups and enter the project name "report", plus any description, then Submit.
  5. Click Go to project then Create group from the left hand menu and enter the group name "tutorial", plus any description, then Submit.
  6. Select Developer perspective from the cube icon (top left).
  7. Select Template files from the left hand menu.
  8. Click Import and select the ps-report-[date].zip file (downloaded from Github) then click the Import button.
  9. Refresh the page and the contents should be listed.

Package Content

Under the document/psml/export folder will be the following files:

FilenameDescription
build.xmlANT script for exporting to docx.
docx-citation-transform.xslXSLT to convert PSML properties to docx citations, see Export citations to docx: Post-processing.
psml-post-transform.xslXSLT that adds the inline labels necessary for figure / table captions to autonumber in docx.

Select Labels from the left hand menu and the following should be displayed:

LabelTypeDescription
appendixdocumentIdentify appendix for alternate numbering.
figure-captionblockTo identify text for a figure or image caption.
table-captionblockTo identify text for a table caption.
titleblockTo format a publication title without using a heading so as not to interfere with the content numbering
asciimathinlineIdentifies an AsciiMath inline equation (not from library).
definitioninlineIdentifies words that should be linked to a definition
pagesinlineUsed directly after citation XRef to indicate page no. or range (e.g. 10 - 20)

Select Document types from the left hand menu and it should show the report publication type which includes these files:

FilenameDescription
publication-config.xmlThe configuration file that determines numbering in PageSeeder, including paragraph, heading and figure / table numbering, see Publications and publication types.
pdf-export-config.xmlThe configuration file that determines the formatting of PSML as pdf, see Exporting to PDF.
word-export-config.xmlThe configuration file that determines the formatting of PSML as docx, see Export Microsoft Word docx config usage.
word-export-template.docxA customized docx template with additional heading and para styles.

The same page will display these PSML document types:

Document typeDescription
asciimathDocuments in AsciiMath  equation library. One equation per document.
bibliographyA collection of references used in a publication (contains XRefs to source documents). This document must be embedded in the publication but only the <section id="title"> content will be used.
componentThe content of a publication. Includes a schematron to check definitions and a CSS style to display footnote and endnote references as superscripts.
endnotesEndnotes for a publication.
footnotesFootnotes for a publication.
glossaryA container for defintions used in a publication. When exported to docx the defintions for any defined terms used in the publication will autoatically be inserted here.
indentIncludes CSS for content with indented headings.
mathmlDocuments in MathML  equation library (experimental). One equation per document. Can only be edited in lab perspective.
publicationThe top level (root) document of a publication. Includes a schematron to list all the definitions used in the publication.
sourceDocuments in source library (bibliography document points to these). One source per document.

Select Edit XRef configs (top right) and the following configs should be listed (see XRef config):

  • footnote – to insert a footnote reference.
  • endnote – to insert an endnote reference.
  • citation – to insert a citation.
  • para – to create an xref to with the number of a paragraph as the title. For example, “see clause 14.2.a” where the xref will automatically adjust if the paragraph number changes.
  • internal-para – when an xref source and destination are both under the same parent number and can therefore use “relative references”. For example , “see (a)” instead of “see clause 14.2.a”. 
  • numbered-heading – to a refernce to a numbered heading.
  • asciimath – for inserting an AsciiMath equation.
  • mathml – for inserting a MathML equation.

Import sample publications

  1. Select the the "report-tutorial" group from the top left menu.
  2. Click Group documents (folder icon) at the top, then click on the documents folder.
  3. Click the Upload button on the right and drag the documents-[date].zip file (downloaded from Github) to the upload dialogue.
  4. Click the Unzip icon next to this zip file.
  5. Click the Upload button at the bottom of the dialogue.
  6. Click the Confirm button and wait for the "Successfully uploaded" message, then click Close.
  7. Click the "System Report" folder, then click the "System Report" document.
  8. Click the (i) Document information icon in the right margin and click Make this document a publication at the bottom.
  9. Under ID enter: sysreport-1 and under Type select "report", then click Submit.
  10. Click the Save button at the bottom and then close the info panel by clicking the cross at top right.
  11. In the Table of Contents choose the Functionality heading for examples of footnotes, citations, equations and autonumbering for headings, paragraphs, tables and figures.

Insert xrefs

Footnote or Endnote

Footnotes and endnotes are xrefs to fragments in a footnotes or endnotes document. After being saved they should appear as an 'f' or 'e' followed by a unique number. When the publication is exported to Word these will be replaced by the correct numbers calculated by Word.

  1. Enter edit mode by double clicking on a paragraph in the document.
  2. Place the cursor in the text and select the insert XRef icon .
  3. Under Configuration select Footnote or Endnote.
  4. After the Footnotes or Endnotes document appears click the edit icon at the top of it.
  5. Mouse over the bottom of the Footnotes or Endnotes document and click the (+) insert fragment icon.
  6. Type some content text for the note and click Create.
  7. Click on the new fragment and then click Save.
  8. Press Ctrl-S then click the edit icon (top right) to turn edit mode off.

AsciiMath

AsciiMath  is a quick way to write equations by typing text. Normally you would just type the AsciiMath text and then apply the asciimath inline label, however the steps below show how to create a library of equations that you can re-use.

  1. Enter edit mode by double clicking on a paragraph in the document.
  2. Place the cursor in the text and select the insert XRef icon .
  3. Under Configuration select AsciiMath.
  4. Select an existing equation from the libarary or click the folders icon (next to search), enter a Document title and an AsciiMath equation, for example y = x^2, then click Create.
  5. Click on the equation and then click Save.
  6. Press Ctrl-S then click the edit icon (top right) to turn edit mode off.

Citation

In this example citations are xrefs to citation fragments in a bibliography document. After being saved they should appear as the citation Link text in brackets. The bibliography document is designed as a quick way to add citations without having to interrupt your writing to enter all the details. Later you can find or create the correct source document. Each citation fragment has a Source xref which points to a document in a source library. The source library documents contain all the information required by Word so that when the publication is exported they will appear as Word citations. Word can then automatically format these citations in different styles, for example APA or Harvard.

  1. Enter edit mode by double clicking on a paragraph in the document.
  2. Place the cursor in the text and select the insert XRef icon .
  3. Under Configuration select Citation (click the search icon if it's not select).
  4. After the Bibliography document appears click the edit icon at the top of it.
  5. Scroll down, mouse over the bottom of the Bibliography document and click Citation under the (+) insert fragment icon.
  6. Enter Link text (for example Jones, 2015) and Description for the source, then click Create.
  7. Click on the new fragment and then click Save.
  8. Press Ctrl-S then click the edit icon (top right) to turn edit mode off.
  9. Click the new citation xref and then double click on the source fragment to enter edit mode.
  10. Click the [+] Create new document icon next to Source.
  11. Enter a Document name for the source, then click Create.
  12. Click on Select this document and then click Save.
  13. Press Ctrl-S then click the edit icon (top right) to turn edit mode off.
  14. Click on the new source document and then edit it to fill in the details.

Insert placeholders

A placeholder is a marker for some simple text content that is repeated throughout the publication, for example [company name]. These placeholders will be replaced by their corresponding actual value in the publication metadata properties.

  1. Enter edit mode by double clicking on a paragraph in the document.
  2. Place the cursor in the text and type [[company name]] and press space.
  3. Press Ctrl-S then click on another location in a paragraph.
  4. Type [c and click on the [company name] that appears. This will automatically add an existing placeholdler.
  5. Press Ctrl-S then click the edit icon (top right) to turn edit mode off.
  6. A warning should appear next to the placeholders to indicate they have not been defined.
  7. Click the (i) Document information icon in the right margin.
  8. Click on the Publication tab and then on Add property.
  9. For Title enter Company name and for Value enter ACME Pty Ltd
  10. Click Submit then click Save.
  11. Click the [iii] Resolve placeholders icon at the top and ACME Pty Ltd should appear in multiple places.

Manage definitions

Linking terms to their definition in a glossary can be done using xrefs but if there are a large volume of definitions the xrefs might make the server and user interface slow. That's why this example uses 'weak linking' instead of xrefs, which means that a definition inline label is applied to a term which then matches with a corresponding definition document in the group that has the term as its title. There is no actual link between the two, but an implied link which we call 'weak linking'. It is much easier to add weak links and faster to process or display documents containing them.

  1. Enter edit mode by double clicking on a paragraph in the document.
  2. Select a word in the paragraph you want to be a term.
  3. Click on the Inline label (highlighter) icon at the top and select Inline label definition.
  4. Press Ctrl-S to save.
  5. Click on the Document validation (tick) icon in the right margin and the following message should appear "The definition for "[your term]" does not exist".
  6. Click the Group documents (folder) icon at the top and then on Create document.
  7. Type your term as the Document title and select Definition as the Document type, then click Create.
  8. Click Go to document and double click the empty fragment under Synonym to edit it.
  9. Enter a definition for your term.
  10. Click next to Synonym and type another term which should match this definition (for example if your term was subsystem you could type sub-system). Then press Enter.
  11. Press Ctrl-S to save.
  12. Go back to the original document. You can use the RECENTLY VIEWED list in the navigation drop down menu (top left).
  13. Click on the Document validation (tick) icon in the right margin and the message "No reports or errors" should appear because your term has now been defined.
  14. Click on Definitions at the top of the Table of contents (left).
  15. At the top right you can see this is a document of type glossary. It contains a marker section titled "Definitions - will be inserted here". When the publication is exported to Word the full definitions will be inserted here and the terms will be linked to them.
  16. You will see the term "Berlioz" in this section. It was inserted here so that it's definition will be included even though this term doesn't appear in the publication. This term actually appears in another definition so we want to include it. Use this method to include any extra definitions you would like.
  17. Click on System Report at the top of the Table of contents (left) to go to the root document of the publication.
  18. Click on the Document validation (tick) icon in the right margin.
  19. Select definition list from the Available schemas drop down menu and click Validate.
  20. For your information this will list all the terms currently used in the publication.

Reuse content

To understand how content can be re-used in different publications, that may have different numbering schemes, do the following:

  1. Click the search icon  at the top and in the search box type "system report 2" and click the "System report 2" document.
  2. Click the (i) Document information icon in the right margin and click Make this document a publication at the bottom.
  3. Under ID enter: sysreport-2 and under Type select "report", then click Submit.
  4. Click the Save button at the bottom and then close the info panel by clicking the cross at top right.
  5. In the Table of Contents click Requirements then click on Functionality under it.

This is the same document as Step 2 but because it has been included in a different publication all the numbering is different. This demonstrates how the same content components can be assembled into multiple publications without the numbering properties leaking from one publication to another.

Click on the menu at the top of the Table of Contents. This shows the publications that the document is used in. Select System Report and the document will be displayed in the context of that publication.

Export as a Word document

  1. Go to the root document in the System Report publication by clicking the Group home icon (top left), clicking the Publications tab and clicking System Report.
  2. Click the Document export (rocket) icon in the left margin.
  3. Under the Choose an export action drop down, select Create DocX and click Run.
  4. Open the document in Microsoft Word and see how the footnotes, endnotes, citations, placeholders, definitions and math equations are displayed by Word.

Created on , last edited on