How to configure publications

Objective

This tutorial demonstrates the configuration of auto-numbering, equations, footnotes, citations, definitions and more.

One design objective, for both the PageSeeder user interface and the document model, is to avoid providing features that the user doesn’t need. Reducing features to only those necessary gives users productivity and quality, with as little training as necessary. 

Through the use of xrefs and some configuration code, PageSeeder can provide a group of users with every capability necessary for the collaborative creation of a complex reference document. These features include the following:

• Auto-numbering for headings, paragraphs, and objects such as tables and images, and the ability to reference those numbers, for example, “see paragraph x.x”, confident that the referential integrity will correctly export to Word.

• Creating or importing equations as block or inline objects.

• Creating and linking notes for export as footnotes and / or endnotes.

• The ability to collaboratively create, and share, a pool of citations with the appropriate structure, semantics, and validation for desktop or online citation tools like Word, Endnote, or Zotero.

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

• Placeholders to manage and update repeatable text strings throughout a publication.

Prerequisites

To complete this tutorial requires:

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

Tutorial

Project setup and installing configuration bundle

1. Login to PageSeeder as an administrator.
2. Go to the project where you would like to install these capabilities. Alternatively create a new project by clicking the System administration button at top right. Then click on New project under Projects & Groups and enter a project name, plus any description, then Submit.
3. Click the Project administration button at the top.
4. Select Template files from the left menu and click the Create button at the bottom of the page to open the Samples dialog.
5. Install a configuration bundle – Click the Bundle button, then in the Bundle type field, select Document type from the dropdown.
1. Click the Select button to the right of a bundle – for this example, select Advanced auto-numbered publication.
2. Install the bundle under the root document type for your publication (e.g references, shown in the Document type field on the right of the dialog). Click Install.
6. Install the import bundle used in Step 9 – Click the Create button again, click the Bundle button, then in the Bundle type field, select General from the dropdown.
1. Click the Select button to the right of Import auto-numbered publication DocX.
2. Click Install.

Verify package content - project configuration files

In the Template files page check the files as follows.

Import process

The document/docx folder contains the following files:

Export process

The document/psml/export folder contains the following files:

Publish process – Import / Export

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

Labels

The label/ folder contains the following file:

You can select Labels from the left menu and the following should be displayed:

Publication types

Select Template configuration from the left menu, then Publication types tab. In the first column, it should show the report publication type, which includes these files:

Document types

The same page will display these PSML document types:

XRef configuration

Select Edit XRef configs (top right).

The following xref 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 a para with the number of the 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 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.

Creating a publication

First create a publication root document and content.

1. Create or open an existing document of the root type you selected previously (e.g. references ).
2. In the Document info panel select Make this document a publication, ensure there is a Publication ID and for this example, select Publication type "report". Click Submit then Save.
3. If there is no existing content, double-click in the root document, click Browse and create a document (for example default type), select it and save. On the root document press Ctrl-S to save everything.
4. Click a content document, add some headings and paragraphs if required and test the auto-numbering by making them numbered with the Toggle auto-number icon in the edit toolbar. Press Ctrl-S to generate numbers.
5. Make the top level heading in the content document numbered and press Ctrl-S. Click the Document information icon on the right, click appendix next to Document labels, then click the Save button.
6. Refresh the page in your browser and “Appendix A” will appear before the first heading, with "A-" prefixing the numbering on other headings. Remove the appendix label, save, refresh and the numbering will revert.

Citations

The objective of this component is to create a bibliography from a library of references. The primary building blocks for this are a custom xref type from the publication to fragments in the bibliography document. These fragments link to “source” documents, that contain all the necessary fields for creating a full citation.

After saving a citation, the xref title to the fragment in the Bibliography document should appear in brackets as the citation. This document provides a quick way to add citations without interrupting the writer by forcing them to fully express the citation. This is done later when each citation fragment is xrefed to a document in the source library (a folder). These documents contain all the necessary information for Word to process as citations in any of the formats it supports, such as APA or Harvard.

To ensure that all the components are ready to use, do the following:

1. Go to the folder containing your content documents.
2. Create a document with document type Bibliography and add it to your publication root. You can add citation fragments now, or instructions are given at step 6. following.
3. Create a document with document type Source (creating the first Source document automatically creates a sources folder). Enter a Document title for the new source, then click Create.
4. Click to open the new source document and then click the pencil icon at top right to edit it to fill in the details. Click Save.
   
   
   
5. View a content document and double-click on a paragraph to enter edit mode.
6. Place the cursor in the text, and select the insert XRef icon .
7. To add a new citation fragment to the Bibliography document:
1. Under the Configuration dropdown, select “Citation”.
   
2. After the Bibliography document appears:
1. Click the at the top right.
2. Scroll down, mouse over the bottom of the Bibliography document, click the (+) insert fragment icon and click Citation under it.
   
3. Enter Link text (for example Smith, 2015) and a Description for the source, then click Create.
   
4. Click the new fragment and then click Save.
8. Press Ctrl-S then click the edit mode icon (top right) to turn edit mode off. In your document, you see the Link text you entered at step b.iii. above.
9. In your document, click the new citation xref to go to the Bibliography document, and then double-click on the citation fragment to enter edit mode.
10. To add an xref from the Bibliography document to the Source document, at the Source property, click the Browse documents icon next to the Source label, if you see the title of your source at the left, click the title, and it will then display in the main section, or you can start typing the title of the source.
11. In the main section, click on Select this document and then click Save.
1. If you need to create a new source, in the xref dialog, click the Browse documents icon and click on the sources folder. Enter the title for your source, click Create, click Select this document, then click Save.
   
12. Press Ctrl-S then click the edit icon  (top right) to turn edit mode off.

Footnotes or Endnotes

The model for this implementation is that a custom link type generates a simple link title and prompts the user to create a new fragment, or refer to an existing one, in the footnote or endnote document.

The generation of the link title, an “f” or an “e” with a numeric qualifier, happens when saving the xref. Upon export of the publication to Word, there is a transformation of these objects to native docx footnotes or endnotes.

This solution requires the creation of custom document types to hold the footnote or endnote fragments. Whether this document already exists will depend on whether the content came from a docx file that already had footnotes or endnotes, or whether the document is being written in PageSeeder. 

To determine this, follow these steps

1. Go to the folder containing your content documents.
2. Create a document with document type Footnotes. If you get an error then it already exists, otherwise click the icon at top right enter edit mode.
3. Add one or more fragments containing footnote content.
4. Create a document with document type Endnotes. If you get an error then it already exists, otherwise click the  icon at top right enter edit mode. 
5. Add one or more fragments containing endnote content.
6. In a content document, enter edit mode by double-clicking on a paragraph.
7. Place the cursor in the text and select the Insert/edit cross-reference icon, available either in the document toolbar at the top or in the editing context menu when you right-click in the text. The Xref dialog opens.
8. In the Configuration field, select the XRef configuration, either Footnote or Endnote, from the drop-down. The Footnotes or Endnotes document displays in the main section. The process for inserting both footnotes and endnotes is similar. The following images display the footnote process:
    
9. In the main section, click on the footnote fragment that you want to reference.
   
10. The xref details display. The "Title template" field contains the link title that displays in your document. It has the generated letter “f” and the {fragment}, which is automatically populated with a numeric qualifier – the fragment number in the footnotes document – when you save the xref details. The "Link type" field shows alternate (as specified in the footnote xref template).
    
11. Click Save to insert the xref in your document. In the following image, the link text "f4" references fragment 4 in the Footnotes document. Press Ctrl-S to finalize the insertion.
    

AsciiMath

AsciiMath  is a way to quickly write equations using a simple text-based language. While it is possible to just type and format the AsciiMath equations by using the asciimath inline label, the steps below will create an equation library that will help with maintenance and re-use.

1. In a content document, enter edit mode by double clicking on a paragraph.
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.

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. In a content document, enter edit mode by double clicking on a paragraph.
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. In a content document, enter edit mode by double clicking on a paragraph.
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 Open 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. Go to your publication root document and add a document of type glossary to it. Press Ctrl-S, then click on the glossary document and enter edit mode by double-clicking in it.
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. Mouse over the (+) just below “Definitions - will be inserted here” and click insert fragment. Enter a word used in the definition you previously created and apply the definition inline label to it here and in the original definition document.  You’ll also need to create a definition document for this word so its 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. Go to your publication root document and click on the Document validation (tick) icon in the right margin.
18. Select definition list from the Available schemas drop down menu and click Validate.
19. For your information this will list all the terms currently used in the publication.

Export as a Word document

1. Go to the root document in your publication.
2. Click the Document export (rocket) icon in the left margin.
3. Under the Choose an export action drop down, select Create custom 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

Import the exported docx file into a different group to avoid confusion.

1. Click on the Group administration (wrench icon), select your project from the left menu, then click Create group.
2. Enter a group name, 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 .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 custom document as PageSeeder PSML.
6. Click the Preview button and a preview of the import will appear. You can explore it by clicking links and using the back button at the top.
7. Click the Back to upload button and click Save.
8. Click the Continue button and click Confirm and upload when it appears.
9. When the "Successfully uploaded ..." message appears click the Close button (ignore the warnings).
10. Click the folder for your imported publication, then on the root document and you see the imported report but the Table of contents is not numbered.
11. To apply numbering click the Document information icon on the right, then on Make this document a publication at the bottom of the panel.
12. Ensure there is an ID and under Type select "report", then click Submit.
13. Click the Save button at the bottom and then close the info panel by clicking the cross at top right.
14. Refresh the page in your browser and the numbering is displayed.