How to configure publications

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.9903 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 Template files from the left hand menu.
7. Click Import and select the ps-report-[date].zip file (downloaded from Github) then click the Import button.
8. Refresh the page and the contents should be listed.

Package Content

Under the document/docx folder are the following files:

Under the document/psml/export folder are the following files:

Scroll to the bottom of the page to see the publish folder which contains the following file:

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

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

The same page will display these PSML document types:

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 reference to a numbered heading. For example, “see section 14 Privacy” where the xref will automatically adjust if the heading number or text changes.
• 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 the documents folder.
3. Select Upload document from the (+) menu top 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. If no Footnotes or Endnotes document appears, click the Browse icon, then click Create.
5. After the Footnotes or Endnotes document appears click the edit icon  at the top of it.
6. Mouse over the bottom of the Footnotes or Endnotes document and click the (+) insert fragment icon.
7. Type some content text for the note and click Create.
8. Click on the new fragment and then click Save.
9. 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 library 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.
4. If no Bibliography document appears, click the Browse icon, then click Create.
5. After the Bibliography document appears click the edit icon  at the top of it.
6. Scroll down, mouse over the bottom of the Bibliography document, click the (+) insert fragment icon and click Citation under it.
7. Enter Link text (for example Jones, 2015) and Description for the source, then click Create.
8. Click on the new fragment and then click Save.
9. Press Ctrl-S then click the edit icon  (top right) to turn edit mode off.
10. Click the new citation xref and then double click on the source fragment to enter edit mode.
11. Click the browse document icon next to Source, then click the browse document icon at the top.
12. Enter a Document title for the source, then click Create.
13. Click on Select this document and then click Save.
14. Press Ctrl-S then click the edit icon  (top right) to turn edit mode off.
15. 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 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. This document 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.

Import a report Word document as PSML

1. Click on the Group administration (wrench icon), select the REPORT project from the left hand menu, then click Create group.
2. Enter the group name "import", plus any description, then Submit.
3. Click Go to group and on Group documents (folder icon) at the top, then click the documents folder.
4. Select Upload document from the (+) menu top right and drag the system_report.docx file (you exported) to the upload dialogue.
5. Click the Import options icon (arrow on the right of the file) and then on Import document as PageSeeder PSML.
6. Click the Preview button and a preview of the import will appear. You can explor it by clicking links and using the back button at the top.
7. Click the Back to upload button and click the Import options icon (arrow on the right of the file) and then on Import document as PageSeeder PSML again.
8. This time click the close (X) on the options dialog and then on the Continue button.
9. Click the Confirm and upload button when it appears.
10. When the "Successfully uploaded ..." message appears click the Close button (ignore the warnings).
11. Click the system_report folder, then the System Report document and you see the imported report but the Table of contents is not numbered.
12. To apply numbering click the Document information icon on the right, then on Make this document a publication at the bottom of the panel.
13. Under ID enter: sysreport-import and under Type select "report", then click Submit.
14. Click the Save button at the bottom and then close the info panel by clicking the cross at top right.
15. Click the Refresh icon at the top of the Table of contents (TOC) and the numbering is displayed.
16. Click on "Legal, Copyright and Other Notices" at the bottom of the TOC.
17. Click the Document information icon on the right, click appendix next to Document labels, then click the Save button. Repeat this for the "Applicable Standards" and "Future Development" documents.
18. Click the Refresh icon at the top of the TOC and the appendix numbering is displayed.