Topics

Editing Topics

To create and change topics in Paligo, you use the built-in XML Editor. When you click a topic in the Content Manager , it automatically opens the topic in the Editor.

To learn more about the various parts of the Editor, see Editor.

When you create or edit a topic, add elements to create the structure and then add your content inside the elements. For example, if you want to add a new paragraph, create a new para element and then add your text to it.

You can add some of the commonly used elements by using the Edit and Insert Toolbar options. You can also add elements by using the Element Context Menu.

The Element Context Menu. At the top, there is a search field for searching for specific elements. Below that, there is a list of elements that are valid for the current cursor position.

You can display the Element Context Menu by using these shortcuts:

Windows: Alt + Enter

Mac: Command ⌘ + Enter

To learn more about using the Element Context Menu, see: Add Topic Content.

The Basics of Topic Editing

The Paligo editor is made to be as easy to use as possible, more or less like a word processor. But in fact it is an XML editor. The structure of the underlying XML is what enables a lot of the power for single-sourcing and reuse.

This means, that although Paligo does not clutter the interface with lots of XML tags, there is still a strict structure underneath the surface. So if you haven't authored in a structured environment before, you need to at least get used to the basic concepts of adding and using "elements". The following procedure shows you how to do that.

Note

Paligo's content model is based on DocBook, but a customized topic-based version of it. But even with the customization, it is close enough so you can in most cases refer to this reference for a list of the elements, and what they are used for: Element reference.

In-context editing

Sometimes you may be working on topics in a specific publication (for example for a certain product), and may prefer to be able to browse it in context while editing the various topics.

You can do that, and do simple editing, in the Contributor Editor. While mainly intended for Reviewers and Contributors, Authors also have access to it of course. And it provides a very convenient way to browse and edit content in context.

In the Content manager, open a topic in one of the following ways:
- Click on the topic name
- Select Open in editor in the options menu of the topic
The topic is opened in the editor.
By default, you get a title (same as the topic name) and an empty paragraph (para element) to start with.

Note

Note that in most cases you should only have one title/heading in a topic. Subheadings are created automatically by the nesting when you build your publication structure in the Structure View. See Headings and Subheadings for more details on this.
In the editor, place the cursor where you want to add content (insert an element) and do one of the following:
- Use the toolbar icons to insert the type of content (element) you want.
- Press Alt/Cmd+Enter to show a list of available elements (types of content) at that place.
  
  Tip
  
  Start typing to narrow down the list of elements. E.g if you start typing "par"... you will see the element para only, which will create a paragraph.
To add a new element of the same kind that you just inserted, e.g a paragraph (para), listitem or step in a procedure, just press Enter.

Tip

See Keyboard Shortcuts for more tips on speeding up your authoring in the editor.
To delete an element:
1. Place the cursor in the document element you want to delete.
2. The Element structure menu (also called "breadcrumbs") at the top of the editor, shows hierarchic in which element you are. Place the cursor over the element name you want to delete and click to open a pop-up-menu.
3. Place the cursor (without clicking) over the Delete menu item. Result: The element to be deleted is highlighted with yellow background and text that is crossed with red bars.
4. Click Delete to delete the selected element.
Use the Element structure menu in a similar way to manipulate your content with full control, for example:
- Highlight elements in the Editor
- Cut, copy and paste elements
- Move elements up and down (needs to be elements on the same level in the structure)

Splitting elements

If you have started writing content into a para or a step, for example, and you want to turn that content into two separate elements, just place the cursor where you want to split the element, and press Enter. This splits the element into two elements of the same type. A paragraph for instance will then be split into two paragraphs at the place where you had the cursor.

Removing bold or italic

If you have used the bold or italic elements to format text, and you want to change it, simply place the cursor in the formatted text and click the Eraser icon, or use the keyboard shortcuts. You can also toggle the common ones just using the same shortcut again (like CtrlB to toggle bold)

Create a Topic

We recommend that you create a new topic for each section of content that needs a heading (either a top-level heading or a subheading). By having your content in separate topics, it becomes more versatile. For example, you could have a topic as a subsection in one publication but as a top-level topic in another publication.

When you create a topic, you can either:

Create a Topic in Content Manager. It will not be associated with any publications.
Create a Topic from the Publication Structure that will automatically to associated with a publication. It can still be used in other publications as well, if needed.

Note

For an introduction to topics and publications, see Topic-Based Authoring.

Create a Topic in Content Manager

There are two ways to create a topic from the Content Manager:

Either:
- Select the menu at the top of the Content Manager and then select Topic.
- Select the dotted menu ( ...) for a folder and then select Create Content.
Use the Create content dialog to set the properties for the new component:
- Make sure that the Document Type is set to Topic.
- Enter a name for the new topic in the Document Title field.
  
  Note
  
  The characters you can use for titles are: numbers, language characters, punctuation characters and spaces. The punctuation characters are:
  
  ! " # $ % / & ' ( ) * + , - . : ; < = > ? @ [ \ ] ^ _ ` { | } ~
- Use the Language section to choose which languages Paligo should include for the topic. You can select individual languages or check the Select all languages box to include all languages.
  
  Note
  
  You can only choose from those languages that are enabled on your Paligo instance. To learn about adding languages, see Language Management.
- Use Open in editor to choose whether you want Paligo to display the new topic in the editor.
  - Check the box if you want Paligo to display the topic in the editor
  - Clear the box if you do not want Paligo to display the topic in the editor
- Use Create another to choose whether you want Paligo to leave the Create content dialog open, ready for you to add another topic.
  - Check the box if you want Paligo to leave the Create content dialog open
  - Clear the box if you do not want Paligo to leave the Create content dialog open
Select OK.

Paligo creates the new topic.

Depending on your selections, Paligo may open the new topic in the editor automatically. Alternatively, you can select the topic in the Content Manager to display it in the editor.

To learn about the structure that is included in a new topic by default, see Structure of a New Topic.

Tip

Remember that your new topic is not included in any publications. To learn how to add it to a publication, see Add Content to a Publication.

Create a Topic from the Publication Structure

It is possible to create new topics from the publication structure. The two benefits of this method is that:

The topic is automatically included in the publication.
The topic can instantly be moved to the intended position in the publication structure

Tip

At the top of the Content Manager, you also have the option to create content. This will however not automatically end up in the publication.

Select the publication in the Content Manager.

Paligo displays the publication's structure.
Select the arrow next to the New topic button to choose where to save the new topic.

Note

If not done, the topic will by default be saved in the same folder as the topmost publication or topic.
Select New topic.
Name the new topic.
Move the topic to its intended position in the publication structure.
Select Save to confirm the publication changes.

Note

The new topic is created at the chosen location and can now be edited.

Structure of a New Topic

When you create a new topic, Paligo automatically adds some structural elements to it. By default, a new topic consists of a section element, a title element, and a para element:

A new topic shown in the full editor. There are numbered callouts next to the section element (1), topic title (2), and the first paragraph (3).

section is the container for the topic's other elements.
title is the topic's heading.
para is the first paragraph in the topic.

To add content to a topic, you need to add suitable elements to form the structure. You can then add your content inside the elements. For example, if you wanted to have two paragraphs and an image, you would need to add two para elements and also the mediaobject, imageobject, and imagedata elements that are needed for an image. Paligo has toolbar options that make it easy to add commonly used structures in just a few clicks. There is also an element context menu that you can use to build structures one element at a time.

To learn about adding content to a topic, see Add Topic Content.

Copy Topics

You can make a copy of a topic and then use the copy as the starting point for a different topic.

When you copy a topic:

Paligo creates a new topic with the same name as the original, with "copy" and a number added at the end. The copy topic has its own unique ID and is a completely separate topic from the original.
The content inside the new topic is a copy of the content in the original topic but with a different ID.

For example, if your original topic contains a paragraph with ID 2245, the copy version will have a paragraph with the same text, but a different ID, for example ID 2248. There is no content reuse with a copy, the same content is recreated.
You can edit the copy and the content inside it without affecting the original topic.

Note

If you want to create different versions of a topic, the Branching feature may be a better option. With branching, you can create a copy that can later be merged back into the original if needed.

To copy a topic:

In the Content Manager, select the options menu ( ... ) for the topic you want to copy.
Select Copy.

Paligo creates a copy of the topic.
To change the name of the copy, select its options menu ( ... ), select Rename, and then enter the new name.

Check-in and Check-out

Every time you open a topic in Paligo for editing, the topic is automatically checked out. This means that you have ownership of the topic and other users cannot edit it. This helps to avoid conflicts, where two users might try to change each other's work at the same time.

When a topic is checked out, you will see this both in the Content Manager and in the Resource View. Paligo uses a check mark to show the checked-out status.

Overview folder containing three topics. The first topic has a green check next to its name to show that it is checked out.

If a topic is checked-out by you, you can open it in the editor. If it is checked-out by someone else, it is locked and you cannot open it unless you check it in. By default, Paligo is not overly restrictive about checkouts - a user can check in someone else's documents if needed. This is to stop check-outs hampering your work, for example, in case someone forgets to check in before going on vacation or is otherwise unavailable.

Content Manager. The options menu is shown for a topic. It has various options, including Check in.

You can set Paligo to automatically check in a document whenever you close the editor (recommended). To set this up, use the Editor Settings. These are available from the toolbar menu in the Editor (select the cog icon):

Paligo editor toolbar. There is a series of icons. A callout is under a cog icon and the callout text says Editor settings.

In the Resource View you can hover your cursor over the checkmark to see who has checked an item out:

Resource view for a topic. A topic has a green check next to it to show that it is checked out. A hover caption is shown and it explains that the resource is checked out by a user.

You can also see a list of checked-out topics in the Checked out documents section on your dashboard:

Checked out documents section on the dashboard. It shows a list of checked out topics. At the top, there is a button for checking in the topics and there is a filter to restrict the list.

Enable or Disable Author Remarks (PDF)

Author remarks are comments in code, where the comment is part of the topic, but not displayed to your end users. Author remarks have no relation to the feedback comments in reviews and are not part of the review "conversation".

Via the Layout Editor you can choose to include Author remarks in your PDF output.

Select the Layout tab in the top menu.

Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.
Select the layout to be updated or Create a Layout.

Tip

You can copy the URL of the layout editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the layout settings.
Select General and choose Draft and Watermark in the sidebar.
Scroll down to Show Comments.
Select:
- Enabled to include author remarks in PDF output.
- Disabled to exclude author remarks in PDF output. Default
Note

You can show remarks (comments) with Draft mode set to Yes, Default, or No. The Draft mode setting has no effect on whether remarks are visible in the output.
Select Save.

Preview a Topic

You can preview how your topic will appear in different outputs which gives you the chance to resize images, consider reducing the amount of text to better suit your output format, use accordions to easier overview a page, detect broken links, or discover necessary updates to your layout settings. Paligo strongly recommends that you preview every time you create or update content.

Make the preview use your customized output, see Set Preview Layouts. To learn more about filtering / profiling, see Filtering / Profiling.

Note

The preview feature is not available for certain components, such as informal topics. But if you add it to a regular topic as a component, you can preview the regular topic, see Insert Component.

To preview a topic:

Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.
Select the Preview tab in the Toolbar.
Select Profile settings.
Choose the Variables and Filtering / Profiling that you want to be used for the preview.

Tip

You can save the variables and profiling settings so that they become the default preview settings, see Create a Favorite Profile (Preview Tab) and Set a Favorite Profile as Default.
Select Apply and close the Profile settings dialog.
Select the type of output (PDF, HTML or HTML5).

Paligo shows the preview in a new tap topic. It uses the default Layout for each type of output. This gives you a good idea of what your topic will look like when it is published.

Important

If you make changes to your topic, you have to regenerate the preview. Refreshing the existing preview in the browser will only reload the preview that was previously generated.

Topic File Names

For HTML5 outputs, the file names are normally generated automatically, but it is also possible to set it individually.

Paligo has a number of options for how the HTML5 output file name is auto-generated. It uses either the UUID (Universally Unique Identifier), the title of a topic, or the name of the resource to generate the HTML5 file name, depending on your settings in the Layout Editor.

However, you can also set the output file name individually for particular topics if needed. This can be useful if you are using the option to create the file name from the topic title, for instance, and then need to change the title. By setting the output file as below, you make sure it does not change even though you change the title.

To manually set the file name for a topic:

Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.
Select the section element in the Element Structure Menu.
Select Go to element.
Add xinfo:outname in the Element Attributes Panel.
Set the value to the name you want for the published file.

Note

You only need to enter the file name. Do not include the file extension at the end.
Select Save.

When you publish to HTML5, the file name for the topic is set to the value you defined for the xinfo:outname attribute.

Exclude a Topic from Search

You can set up topics to be included in your HTML5 output, but not to appear as results in the search. This way you make your search more useful by only including more detailed topics that give your users the information they need.

Example 1. Often excluded content

Release notes are often excluded from the search results because they are useful to have in your documentation, but they rarely provide enough detail.

Tip

You can also exclude topics from the navigation sidebar (also known as the TOC), see Exclude Content from Publication TOC.

To exclude a topic from the search results:

Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.
Select the section element in the Element Structure Menu.
Select Go to element.
Add the role attribute in the Element Attributes Panel and set the value to notinsearch.

Note

The role attribute is not inherited. If you have different levels of topics, you need to add the role to all of the sections that you want to exclude from the search, not just the section of the top-level topic.
Select Save.

When you publish the topic to your HTML5 help center, the search will not include the topic in its results.

Open a Topic

To open a topic, either:

Click on the topic's name in the Content Manager, Resource View.

Example of a topic being selected in the Content Manager.
Click on the topic's link on the Dashboard. This is only possible for topics and publications that have been worked on recently.

Example of link to open topic from the Dashboard
Select the topic's dotted menu ( ... ) and choose Edit and then Open in editor. There are also options for opening the topic in Review View, Contributor View, and Translation View.

The topic dotted menu ( ... ) is available in the Content Manager, Resource View, and also in the publication structure.

Example of opening topic from publication structure
Select the link to one of your Assignments (either in the email Paligo sends to you or from your Dashboard). Paligo will open the topics in that assignment in the view that is appropriate for your user account. For example, for contributors, the topics will open in the Contributor View.

Appendix Topic

An appendix is a section that provides useful context or background material in your publication. The appendix topic is created the same way as a normal topic, except that you select the document type Appendix.

Appendix titles, when published, are automatically lettered (Appendix A, Appendix B, Appendix C). This lettering continues for every appendix that follows.

The most common use cases for appendices are to insert elements like glossaries, bibliographies, indices and Table of Contents (TOC). All these elements can be placed inside a normal topic, but you will not get the automatic title lettering that comes with appendices.

Example 2. How will the appendix be named?

If an appendix title is "Specifications" and it is the first appendix in the publication, it will be published as Appendix A. Specifications.

Create an Appendix Topic

To create an appendix topic:

Select the Dotted menu (... ) to the right of the folder that is to contain the appendix in the Content Manager.

If a suitable folder does not already exist, you can create a new one (Create Folder).
Select Create content.
Name the content.

Note

The characters you can use for titles are: numbers, language characters, punctuation characters and spaces. The punctuation characters are:

! " # $ % / & ' ( ) * + , - . : ; < = > ? @ [ \ ] ^ _ ` { | } ~
Select the checkbox in front of Appendix.

The checkbox for topic is preselected.
Select Open in editor in the lower left corner to start editing.
Select OK.
Position the cursor straight under the title.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Insert elements like:
- toc - Add a table of contents. It must be placed straight under the section title. When you publish to PDF, Paligo will automatically create the TOC.
- glossary - See Create a Glossary Topic
- bibliography
- index - See Create an Index Topic
- section - To add subtopics.
Tip

It is also possible to use existing topics in your appendix, see Insert Component.
Add the index to your publication.

Note

An important rule of thumb is that appendices must always be at the top level of your publication. Appendices cannot be nested under other topics.

The best practice is to place appendices at the very end of your publication, though Paligo will not prevent you from doing otherwise.
Select Save.
Publish your publication.

Glossary Topic

Abstract

Learn how to make a glossary topic in Paligo and then add references to your glossary in your content.

Technical documentation often includes a glossary, where technical terms are listed alphabetically with a brief explanation. They act as a quick reference for terms that may not be commonly understood outside of your organization or industry.

To create a glossary in Paligo:

Create a Glossary Topic. This is where you add your glossary terms and their definitions.

When you are creating your glossary, you should consider whether you want to use an automatic glossary title. You can also sort the glossary so that the entries appear in alphabetical order.
If you want terms in your glossary to reference other terms in your glossary, you can use "see" and "see also" links. These need to be set up in the glossary topic.
This is an optional step. If you want your topics to contain hyperlinks to the explanations in the glossary, you need to add references in your content.

Alternatively, you can use the glossary topic without any references in your content. This will give you the glossary topic and the definitions you add, but there will be no links from your topics to your glossary.
If you are publishing to PDF, you can set the glossary to only include those terms that are used in your publication. This is useful when you have a single glossary topic that you reuse in several different publications.
If you are publishing to an HTML5 help center, you can choose whether your references to the glossary have "popovers" that appear when you hover the cursor over the term.
Add your glossary topic to a publication in the same way as you would add any other topic to a publication. Typically, the Glossary topic is placed at the end of the publication.

When you publish your content, the glossary is included. It contains a list of the glossary terms you have defined. If you have included references to the glossary in your content, those references appear as links. There are also popovers that appear if you publish to a HTML5 help center.

Create a Glossary Topic

To create a glossary for your publication, a glossary element must be added to a topic. When added, Paligo adds the basic structure that is required for a glossary. Some of the elements are optional and can be deleted if not needed. The use of glossterm in topics allows you to change the formatting of terms in the publication and generates a link to the corresponding definitions on the glossary page.

Consider how you want the glossary to appear in the published output:

Glossary as a topic with the glossary entries to follow it.

This is the most common approach for glossaries. To set this up, use "Glossary" as the topic's title. When you add a glossary element, it has its own title. You can delete the glossary's title element, so that only the topic's title is used.
Glossary as a subsection with the glossary entries to follow it.

To create this, give the topic the title that you want to use. When you add the glossary element, it has its own title. You can set the glossary title to "Glossary" or any other name that you want.

A topic with Glossary as its title. It contains a glossary element and inside that there are some glossary definitions.

A topic called "Reference" and it contains a glossary. The glossary has its own title, which is labelled "Glossary".

Tip

If you want to sort the glossary entries in alphabetical order, see Sort the Glossary.

You can also add references, so that the terms in your topics contain links to the explanations in your glossary, see Glossary References.

Create a new topic or open an existing topic.
Position the cursor at a valid position for the glossary element.

For example, after the topic title, but before the first para element.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Enter Glossary and select it from the menu.

Paligo adds the basic structure for a glossary.
Add a glossary title and an introduction text in the para(both elements are optional).
Add the glossterm (the name of the term).

Add an acronym for the glossary term (optional).

For example, if the glossary term is Extensible Markup Language, you could add the acronym XML.

<glossentry>
    <glossterm>Extensible Markup Language</glossterm>
    <acronym>XML</acronym>
    <glossdef><para>A self-descriptive language used to store and transfer data.</para></glossdef></glossentry>

Add a glossdef that explains what the term means.
Use the Element Context Menu to add one glossentry per glossary term.
Select Save.
Add your glossary topic to your publication, see Add Content to a Publication.

Glossary References

Abstract

Learn how to add references to glossary terms and definitions in your regular topics. The references can be the same text as the glossary term, different text, or you can have a "see" or "see also" reference.

When you have created a glossary topic that contains the glossary terms and definitions, you can reference those terms in your topics. For example, if you have a glossary definition of "XML", you can reference it when you mention "XML" in your content. In your published output, the reference guides the reader to the glossary (PDF) or displays the definition (HTML).

Example of a glossary shown as a hover pop-up when published to HTML

Example of a hover popover showing a glossary definition in HTML output.

There are several types of glossary reference that you can use:

Exact match to the term in the glossary, for example, you have "Intake" in your content and the glossary term is also called "Intake"
Text that is different to the glossary term, for example, you might have "wireless" in your content but you want to link that to a glossary term called "WiFi".
"See" references, where there is no glossary term definition, only a "see" reference to another entry in the glossary.
"See also" references, where there can be a glossary term definition as well as a "see also" reference to another entry in the glossary.

Topic Term is Same as Glossary Term

You can associate terms in your topics with definitions in a glossary. If the term in your topic is an exact match for the term in the glossary, follow the steps below. This approach is suitable for content that is in a single language and content that is going to be translated.

Open the topic that will reference a term in your glossary.

Highlight the text that you want to reference the term in the glossary. This text has to be an exact match of the text for a glossary term in your glossary topic.

Some text with the term XML highlighted.

Use the element context menu to add the glossterm element.

The Paligo editor shows the element context menu being used to add the glossterm element

The Paligo editor shows that the glossterm element is selected. In the content, the term XML is shown in italic to show that it links to a glossary term.

Check the box Use gateway to enable IP Allowlisting. Optional

When you publish, Paligo will automatically detect the references in your content and will match them to the terms in your glossary.

Note

As long as your term in the topic text and the glossary term are the same, you can use this technique for as many languages as you need. Because in the underlying XML, the code will be <glossterm>text-term<glossterm>, where text-term is the word you want to use. As long as the text-term exists in the glossary for the same language, it will work. For example, if you have an English topic with <glossterm>valve</glossterm>, your English glossary needs to contain a glossary term called "valve", and in the French version, your topic would contain <glossterm>vanne</glossterm> and the French glossary would need a term called "vanne".

Topic Term is Different to Glossary Term

In a topic, you may have text that needs to refer to the glossary, but it does not match the glossary term. For example, you could have "configurable" in your topic, but you want it to reference a "Configure" glossary term.

There are two different ways to create this type of glossary reference:

Use the linkend attribute and reference the glossary term by its xml:id

If you have translations or are going to translate your content in the future, you should use references by xml:id.
Use the baseform attribute to reference the glossary term.

This is only suitable if your content is only going to be written and published in one language. If you have translations, this technique will only work on the source language.

Reference Glossary Entry by XML ID

If you are going to translate your content, you will most likely want to refer to glossary terms that are also translated. For example, if you have English and French content, you probably want the French topics to reference French glossary terms. To do this, use an xml:id reference.

With an xml:id reference, the underlying code is the same for all language versions. So if you have a glossary entry with an xml:id of N5f84b058951b3 in your English content, that same id is also used for the glossary entry in any other languages.

If you used a baseform reference instead, the glossary term would only work for one language. This is because the baseform term is language-specific. For example, let's say you have English content and you use baseform: valve for a glossary reference. Paligo will look for valve in the English glossary, and will find it (assuming it exists). But for the French glossary, Paligo will still look for baseform:valve, and valve will not exist in the French glossary as it is translated to vanne.

Tip

You can use xml:id references for content in a single language too. This is a good idea if you do not translate your content now, but may need to translate it in the future.

To use the xml:id to reference a glossary entry:

Open your glossary topic. This is the topic that contains your glossary and the entries and definitions.
Select a glossentry element. Check that it does not have an xml:id entry in the Element attributes section. If it does, check the other glossentry elements too. If they all have xml:ids, ignore step 3 and continue from step 4. If any glossentry does not have an xml:id, you will need to add one (see step 3).

Select the glossentry element on the Element Structure Menu and then select Generate ID. This gives the glossentry a unique ID (xml:id).

Glossentry element selected in the element structure menu. The generate ID option is highlighted.

When all of the glossentry elements have an xml:id, you can reference them from your topics.

Tip

You can manually change an xml:id to something that is more meaningful, if you wish. This can make it easier to work with xml:ids for glossary references.

When changing an xml:id, there are some rules to follow:

The xml:id must start with a letter
There is a 36 character limit
You cannot use spaces, so use an underscore instead. For example, glid valve is not allowed, but you could use glid_valve.

It is a good idea to have a consistent xml:id naming strategy for your glossary entries.

Open a topic and select the text that you want to reference a glossary term.

Use the element context menu to apply the glossterm element.

Select the glossterm element and then add the linkend attribute in the Element attributes section.

The element attributes section shows the glossterm element is selected. It has been given the linkend attribute.

Set the value of the linkend attribute to match the xml:id of the glossary entry you want to reference.

The element attributes section shows the glossterm element is selected. It has been given the linkend attribute. The linkend attribute has a reference as its value.

Repeat steps 4 to 7 inclusive for each reference.
Select Save.

When you publish, Paligo will automatically detect the references in your content and will match them to the terms in your glossary.

Reference with Baseform and Term Name

One way to reference a glossary term that does not match the text in your content is to use the baseform attribute. But this is only suitable if you write and publish your content in a single language.

Important

If you have translations or are going to translate your content, use the xml:id to reference your glossary.

To use the baseform attribute to reference a glossary term that does not match the text in your content:

Open a topic and select the text that you want to reference a glossary term.
Use the element context menu to add the glossterm element.

To find out more about using the element context menu to add content, see Add Topic Content

Select the glossterm element and then use the Element attributes section to add the baseform attribute.

element attributes section shows glossterm is selected. The baseform attribute has been added.

Set the value of the baseform attribute to the name of the term in the glossary. This has to be an exact match for the term in the glossary.

The element attributes section shows the glossterm element is selected. It has a baseform attribute and the value for the baseform is Extensible Markup Language

Repeat this process for other references, as needed.
Select Save.

When you publish, Paligo will automatically detect the references in your content and will match them to the terms in your glossary.

See Glossary Reference

If you want a glossary term to refer to another glossary term, you can use a "see" reference. For example, if you have a glossary term for "Coolant" you could use a "see" reference to guide the reader towards a related term, such as "See refrigeration".

Tip

You can also use a "see also" reference.

To use a "see" reference:

Edit your glossary topic. Alternatively, you can create a new glossary.
Click inside the glossary element and then use the element context menu to add a glossentry element. Paligo adds a glossentry element and it contains a glossterm, acronym, glossdef, and para element (the para is in the glossdef).
Click after the glossterm element but before the acronym element. This selects the glossentry element, which you can see in the element structure menu and in the Element attributes section.
Use the element context menu to add the glossee element:

To learn more about using the Element Context Menu, see: Add Topic Content.
Delete the acronym, glossdef, and para elements for the glossary entry. You should now be left with the glossentry and glosssee elements.

Note

You can have either a glossee element or a glossdef element in a glossentry, but not both.
In your glossary definitions, find the glossary term that you want to reference. For example, if you want to have a "See Refrigeration" reference, find the glossary definition for "Refrigeration".
Select the glossentry element for the term that you want to reference.
In the Element attributes section, copy the xml:id attribute for the glossentry.

Note

If the glossentry does not have an xml:id, select the glossentry element in the element structure menu, and then select Generate ID. Paligo will create an xml:id for the glossentry element.
Select the glosseealso or glossee element that you added in step 4.
In the Element attributes section, add the Otherterm attribute and paste in the xml:id from step 7 as the value.

The Otherterm attribute links the glossee element with the other glossary term that you are referencing. The xml:id is what Paligo needs to identify the other glossary term.
Select Save.

When you publish your content (including your glossary), you will get a "See" reference to the glossary term you chose in step 4.

Example 3. "See" reference in a glossary

For this example, imagine you have a glossary term for "Profiling" and instead of a description, you want a reference to show "See Filters".

In your glossary topic, you already have a "Filters" glossary entry that has this structure:

<glossentry xml:id="N5fa17485ec783">
      <glossterm xinfo:text="14442">Filters</glossterm>
      <glossdef>
        <para>Filters are also known as profiles or conditional text. You can use them to markup your topics so that when you publish, you can choose whether to include of exclude parts of your content.</para>
      </glossdef>
    </glossentry>

The first step is to create a new glossary entry, so you add a new glossentry element and name the entry "Profiling".

glossary entry, with the term set to Profiling, and a blank acronym element and a blank definition.

You delete its acronymn and glossdef elements as there is no need for an acronym and you cannot have a definition and a "see" reference in the same glossary term.

Glossary entry has its term, but the acronym and definition have been deleted.

You add the glossee element.

Glossary term with the glossee element added.

You select the glossentry element for the glossary term you want to reference, in this case, "Filters". Then you copy its xml:id value from the Element attributes section.

Glossary topic in Paligo editor. The glossentry element is highlighted in the element structure menu and the element attributes section. Its xml id is shown in the element attributes section and is also highlighted.

You select the glossee element for the "Profiling" glossary entry, and then add the Otherterm attribute in the Element attributes section.

You copy the xml:id of the "Filters" glossary entry into the value field for the Otherterm attribute.

Glossary topic open in Paligo editor. The glosssee element is selected. In the element attributes section, the otherterm attribute has been added to the glosssee element and it has its value set to the xml id of another glossary term.

You save the glossary and publish it as part of a publication. In the output, the entry for Profiling shows "See Filtering".

Example of a glossary output. There is a glossary heading with a list of glossary terms and their definitions. An arrow points to the term for "Profiling" and its entry shows "see Filters"

Tip

You can also use a "see " reference.

To use a "see also" reference:

Edit your glossary topic. Alternatively, you can create a new glossary.
Click inside the glossary element and then use the element context menu to add a glossentry element. Paligo adds a glossentry element and it contains a glossterm, acronym, glossdef, and para element (the para is in the glossdef).

Note

You can have either a glossee element or a glossdef element in a glossentry, but not both.
Click below the glossdef "Definition". The glossseealso element has to be inside the glossdef, but after the para that is inside the glossdef.
Use the element context menu to add the glosseealso element:

To learn more about using the Element Context Menu, see: Add Topic Content.
In your glossary definitions, find the glossary term that you want to reference. For example, if you want to have a "See also Refrigeration" reference, find the glossary definition for "Refrigeration".
Select the glossentry element for the term that you want to reference.
In the Element attributes section, copy the xml:id attribute for the glossentry.

Note

If the glossentry does not have an xml:id, select the glossentry element in the element structure menu, and then select Generate ID. Paligo will create an xml:id for the glossentry element.
Select the glosseealso element that you added in step 4.
In the Element attributes section, add the Otherterm attribute and paste in the xml:id from step 7 as the value.

The Otherterm attribute links the glosseealso element with the other glossary term that you are referencing. The xml:id is what Paligo needs to identify the other glossary term.
Select Save.

When you publish your content (including your glossary), you will get a "See also" reference to the glossary term you chose in step 4.

Example 4. "See Also" reference in a glossary

For this example, imagine you want a glossary term for "Profiling" and you need it to provide a definition and also to guide readers to also see the term "Filters".

In your glossary topic, you already have a "Filters" glossary entry that has this structure:

<glossentry xml:id="N5fa17485ec783">
      <glossterm xinfo:text="14442">Filters</glossterm>
      <glossdef>
        <para>Filters are also known as profiles or conditional text. You can use them to markup your topics so that when you publish, you can choose whether to include of exclude parts of your content.</para>
      </glossdef>
    </glossentry>

The first step is to create a new glossary entry, so you add a new glossentry element and name the entry "Profiling".

You delete its acronym element as that is not needed in this case.

You enter a definition for "Profiling".

You add the glossseealso element.

You select the glossentry element for the glossary term you want to reference, in this case, "Filters". Then you copy its xml:id value from the Element attributes section.

You select the glosseealso element for the "Profiling" glossary entry, and then add the Otherterm attribute in the Element attributes section.

You copy the xml:id of the "Filters" glossary entry into the value field for the Otherterm attribute.

You save the glossary and publish it as part of a publication. In the output, the entry for Profiling shows the definition for profiling and it has a "See also Filtering" reference.

Glossary Title

Abstract

Learn how to add a glossary title element and set it to be auto-generated or manually generated. You can also control if a glossary title is bookmarked for PDF and whether it appears in HTML outputs.

When you create a glossary, you add a glossary element, and by default, this includes a title element inside it. You can use the glossary title to name the glossary. But depending on how you have set up your glossary, you may decide that you do not want a title at all.

One of the most common ways to set up a glossary is to create a topic called "Glossary" and then add a glossary element to it. In this scenario, the topic's title is glossary, so there is no real need for a glossary title as well. That's not a problem - you can delete the glossary title and the glossary will still work as expected. In the following image, "Glossary" is the topic's title and then the actual glossary has no title of its own.

But it is also possible to add a glossary to a topic that is not called "Glossary". For example, you could add a glossary to a topic called "Reference". In this scenario, it can be a good idea to include a glossary title as well. The title will make it easier for your readers to find your glossary, seeing as there is no "Glossary" topic. In the following image, a glossary has been added to a "Reference" topic, and the glossary has a title called "Glossary".

If you are going to use a glossary title, you should consider:

Do you want Paligo to automatically generate the title?

You can Add a Glossary Title yourself or you can get Paligo to generate a glossary title for you.

To use an automatically generated glossary title, see Automatic Glossary Title for PDF Outputs and Glossary Title for HTML5 Output.
If you publish to PDF, do you want the bookmarks to have a link to the glossary title?

If yes, you can set Paligo to include the glossary title as a bookmark, if needed.
For HTML5 outputs, do you want the glossary title to be shown?

They are hidden by default, but you can use custom CSS to display them if you prefer.

Add a Glossary Title

By default, when you add a glossary element, it also contains a title. You can enter the text for your title inside the title element.

Glossary topic containing a glossary element. The glossary element contains a title element by default.

If you have removed the glossary title and later decide that you do want a title, you can either:

Add a glossary title manually, by adding the title element
Set Paligo to generate a glossary title automatically.

To use an automatically generated glossary title, see Automatic Glossary Title for PDF Outputs and Glossary Title for HTML5 Output.

To manually add a glossary title:

Open the topic that contains your glossary in the Paligo Editor.

Select the glossary element.

A References topic containing a glossary element. The glossary element is selected. There is no title element for the glossary.

Use the element context menu to add the title element.

A References topic containing a glossary element. The glossary element has a title element, which is selected, ready for the writer to enter the title text.

Enter the text for your glossary title inside the title element.
Check the box Use gateway to enable IP Allowlisting. Optional

Automatic Glossary Title for PDF Outputs

Paligo can automatically add a title to your glossary. The automatic title has the text "Glossary" and if you publish to other languages, a translation of "Glossary" is provided as well.

To use an automatic glossary title for PDF outputs:

Create a PDF layout. Alternatively, you can edit an existing PDF layout.
Select General and choose Glossary and Index.
Set Glossary auto title to Enable.

When you publish, Paligo will check to see if your glossary has a title.
- If the glossary already has a title, Paligo will use that title. It will not generate an automatic title.
- If the glossary does not have a title, Paligo will add a title element with "Glossary" as the title text.
If you set Glossary auto title to Disable, Paligo will not create an automatic glossary title.
Check the box Use gateway to enable IP Allowlisting. Optional

When you publish to PDF with this layout, the output will include or exclude the automatic glossary title.

Glossary Title included in PDF Bookmarks

PDFs can have bookmarks that act like a table of contents in a side panel, where your topics are shown in order. If you have a glossary, it's likely that you will want a link to the glossary to appear here.

If your glossary is inside a topic called "Glossary", you will not need to take any action. The "Glossary" topic will appear in the bookmarks by default.

But if your glossary is inside a topic with a different title, there will be no obvious way for the reader to access the glossary. For example, let's say you have added your glossary to a topic called "references" and you have removed the title for the glossary. In the published PDF, the bookmarks will only show "References", which makes it harder for your readers to find the glossary.

A PDF output showing a bookmarks side panel and a references topic. The topic contains a glossary that has no title and there is no bookmark link for "Glossary".

To fix this, you can set Paligo to include the glossary's title in the bookmarks as well. If your glossary does not have a title, you can add one or you can set Paligo to generate one automatically.

Create a PDF layout. Alternatively, you can edit an existing PDF layout.
Select General and choose Glossary and Index.

Enable the Glossary title or auto title in bookmarks setting to get Paligo to include the title of the glossary element in the bookmarks.

PDF layout setting called Glossary title or auto title in bookmarks. It is set to Enable.

Note

This setting will only work if your glossary has a title, or you have set Paligo to generate a title automatically.

Check the box Use gateway to enable IP Allowlisting. Optional

When you publish to PDF with this layout, the output will include or exclude the automatic glossary title.

When you publish to PDF with this layout, Paligo includes the glossary title in the bookmarks. It is a subsection of its parent topic.

PDF output showing a References topic on display. The topic contains a glossary and the glossary has its own title called "Glossary". In the bookmarks side panel, there is a top-level entry for the References topic and it has a sub-level link to the glossary title.

Glossary Title for HTML5 Output

By default, Paligo includes a glossary title for HTML5 outputs, but it is hidden from view. The title varies, depending on how your glossary is set up:

If your glossary contains a title element, Paligo includes that title in the HTML5 output
If your glossary has no title element, Paligo creates an automatic title for the HTML5 output. The automatic title is called "Glossary" (or a translation of Glossary for other languages).

To display the glossary title in your HTML5 help center, you need to add some custom CSS:

Create or edit an existing custom CSS file and add the following code:
```
.glossary .titlepage{
    display: block;
}
```
To learn more about creating custom CSS, see Style with CSS.
Create an HTML5 Help Center layout. Alternatively, you can Edit a Layout.
Upload your custom CSS to the HTML5 layout.
Select Save.

When you publish to HTML5 using this layout, the glossary title is shown.

Filter Out Unused Glossary Terms

Abstract

Learn how to filter out unused glossary terms from the published PDF output.

For PDF output, you can make the Paligo Glossary filter out unused glossary terms from the published output. This is useful when you reuse the same glossary topic for different publications.

When you Publish to PDF, Paligo will look for the references in your publication. It will then filter the glossary to only include those terms that are actually referenced in your publication. Any other terms are excluded from the published glossary.

Example 5. Range of publications for a single product

For example, let's say you have a range of publications for a single product, such as an industrial fan:

A user guide aimed at customers who will use the fan controls in the factory.
An installation guide aimed at electricians who will fit the fan in the factory.
A firmware guide that is used by your service engineers who can visit the factory and apply updates to the fan.

Rather than creating separate glossaries for these publications, you create one glossary that is reused in all three. However, the glossary will contain some terms that you do not want to appear in the user guide, as they are technical terms that are not intended for the customers.

If you set the glossary to filter out unused glossary terms, each output will only include the terms that appear in the publication. In other words, you will get a user guide with a glossary that only contains the terms that appear in the user guide, the installation guide will only have terms that appear in the installation guide, and so on.

Important

HTML outputs do not support the role="auto" functionality. If role="auto" is in place for HTML outputs, you will get an empty glossary, without glossary terms.

When you publish to both PDF and HTML:

Add the role="auto" attribute when you publish to PDF.
Remove it when you publish to HTML.

To set your glossary to only include terms that appear in a publication:

Create a Glossary Topic and add glossary terms and definitions.
Mark up your topics with Glossary References for the filtering to work. Each glossary term needs to be referenced at least once.
Open your glossary topic and click inside the Paligo Glossary.
Select the glossary element in the Element Structure Menu and choose Go to element.
Add the role attribute in the Element Attributes Panel and set its value to auto.

Note

The automatic filtering of glossary terms only applies if the glossary has the role attribute set to auto.

If you have a topic that contains multiple glossaries and some of them without the role="auto" element, you will get all their glossary terms, even if they are not used in the publication.
Select Save.

Sort the Glossary

You can sort the glossary entries so that they are listed in alphabetical order in the Paligo editor.

Open the glossary topic and position the cursor inside the glossary element but before the first glossterm element.
Use a keyboard shortcut to sort the entries:
- On Mac, use:
  
  Control ^Option ⌥ Shift ⇧ G
  
  On Windows, use:
  
  CtrlAlt Shift G

Glossary Popovers

Abstract

Learn how to set up glossary popovers. These are panels that appear when you hover the cursor over a glossary term in HTML5 Help Center outputs. The panel contains the glossary term and its definition.

Glossary popovers are panels that appear when you hover the cursor over a term that is linked to the glossary. They contain the glossary term and definition from the matching term in your glossary, and are only available in HTML5 help center outputs.

Paligo creates glossary popovers for you automatically. But if you prefer, you can disable them so that your glossary references only have a link to your glossary topic.

To control whether glossary popovers are used:

Create an HTML5 Help Center layout. Alternatively, you can Edit a Layout.
Select Classes and Attributes and use the Glossary Popovers setting to enable or disable them.
Check the box Use gateway to enable IP Allowlisting. Optional

When you publish to HTML5 using this layout, your output will have glossary popovers if you enabled them. You can test it by hovering the cursor over text that references a term in your glossary. If you disabled popovers, the glossary references will appear as links only.

Glossaries and Translations

Abstract

Learn how to manage glossaries when your content is going to be translated. You can have a glossary in multiple languages, but you need to reference the terms by their xml:id.

Glossaries, like any other topic, can be in multiple languages. You add each required language to the topic, and then the topic can contain the content for the source language and the translations for each additional language (see Working in Translation View).

For a glossary in multiple languages, you need:

A "glossary" topic to contain the glossary term definitions.

This topic will be translated into different languages, so you have a single glossary topic with versions in English, French, German, Spanish, etc. To find out more, see Create a Glossary Topic.
Regular topics that contain text that references your "glossary" topic.

These topics will also be translated into different languages. For the glossary references, Paligo will look in the version of the glossary that matches the language of the topic. For example, if the French version of a regular topic references "vanne", Paligo will look for "vanne" in the French version of the glossary topic.

Most types of glossary reference will work in all languages (see Glossary References), but there is one exception. If you want a term in your text to refer to a glossary entry, but the text does not match the glossary term, you will need to use an xml:id reference. To find out more, see Topic Term is Different to Glossary Term.

When your content is translated, it is important that only the text is translated. Do not translate element names, attribute names, or attribute values.

Glossary Terms in the Translation Editor

If you translate your content manually using the Translation Editor, make sure to follow these steps for any content that has a glossary term (or any other inline XML element):

In the Translation Editor, select the part that you want to translate. The translation dialog appears.
If the source content that you are translating contains a glossary term element, select Copy Source Text. This copies the entry in the original source language version into the translation dialog. Importantly, it copies the inline elements, such as glossterm too. The inline element is highlighted in the translation dialog.
Translate the content into the relevant language, including the highlighted content, and then save.

Note

If you do not use Copy Source Text, the text you enter in the translation dialog will not include the elements that are needed for glossary terms. It will only be regular text.

Index Topic

Abstract

Learn how to set up an index in Paligo and add index references to your topics.

Paligo has several index-related elements that you can use to create an index with references to your topics. These are especially useful in PDF outputs, where users are more likely to need to refer to an index to find out where certain subjects are explained in a document. With HTML and other outputs that will be read digitally, the index is often less useful as there is a search tool to use instead. However, you may still decide to include an index in your online content too.

A PDF output showing an index with many index entries. They are ordered into 3 equal sized columns.

To set up an index for your Paligo content:

Create an Index Topic and add it to your publication.
Add Index References to your content.
Edit your PDF layout to set the number of columns for the index and the column spacing (PDF outputs only).
Publish your content, see General Publishing Process.

Note

Paligo can generate and sort your index automatically, if you Create an Index Topic and there are index references added in your content.

Create an Index Topic

Abstract

Learn how to create an index in Paligo. The index will contain a list of terms with a reference to the relevant parts of the content.

An index topic is a regular topic where an index element has been added. When you add the index topic to your publication, Paligo will automatically gather all index references from the topics. The index references will be categorized by letter and sorted alphabetically and each has a page reference or a link.

If the publication does not contain any index references, the index will be empty. You need to add index references to your topics before you publish, see Add Index References.

Consider how you want your index to appear in the published output:

The index used as a main topic. This is the most common approach for an index.
The index used as a subsection inside a main topic (for example References).

A topic with a title set to "Index" and below that, it contains an index element.

A References topic that contains an index. The index has its own title, which is "Index"

To the left - The index as a main topic. To the right - The index as a subsection.

Note

The index element will automatically add a title named Index. This means that if you have a main topic called Index, the subsection will also be called Index. This extra title can be hidden, see Hide Index Title for HTML5 Output or Enable or Disable Index Auto Title for PDF Output.

Tip

To find out more about using the Element Context Menu to add content, see Add Topic Content

To create an index topic:

Create a new topic.
Position the cursor at a valid position for the index element.

For example, after the section title, but before the first para element.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Enter index and select it in the menu.
Delete the para element that is included by default, if not needed.
Select Save.
Add your index topic to your publication, see Add Content to a Publication.

When you publish your publication, Paligo will automatically gather the index references.

Index Title

Abstract

Learn how to add a title element to an Index in Paligo. Typically, index titles are used when you what to give the index topic a different name than "Index".

When you Create an Index Topic the index element includes an extra title named Index. It is possible to hide this title for both PDF and HTML5 output or include them in PDF bookmarks.

To the left - the index as a main topic. To the right - the index as a subsection.

Enable or Disable Index Auto Title for PDF Output

Paligo can automatically add a title to your index for PDF output. The automatic title will be "Index" and if you publish to other languages, a translation of "Index" is provided as well.

To include or exclude the automatically generated index title:

Select the Layout tab in the top menu.

Paligo editor. The Layout option in the header menu is highlighted.

Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

Select the layout to be updated or Create a Layout.

Tip

You can copy the URL of the layout editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the layout settings.
Select General and choose Glossary and Index.
Set Index auto title to Enable or Disable.

If enabled during publish, Paligo will check to see if your index has a title:
- If the index already has a title, Paligo will use that title. It will not generate an automatic title.
- If the index does not have a title, Paligo will add a title element with "Index" as the title text.
If disabled Paligo will not create an automatic index title.
Select Save.

When you publish to PDF with this layout, the output will include / exclude an automatic index title.

Include Index Title in PDF Bookmarks

PDFs can have bookmarks that act like a table of contents in a side panel, where your topics are shown in order. If you have an index, it's likely that you will want a link to the index to appear here.

If your index is inside a topic called "Index", you will not need to take any action. The "Index" topic will appear in the bookmarks by default.

But if your index is inside a topic with a different title, there will be no obvious way for the reader to access the index. For example, let's say you have added your index to a topic called "references". In the published PDF, the bookmarks will only show "References", which makes it harder for your readers to find the index.

To fix this, you can set Paligo to include the index's title in the bookmarks as well. If your index does not have a title, you can add one or you can set Paligo to generate one automatically.

Select the Layout tab in the top menu.

Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

Select the layout to be updated or Create a Layout.

Tip

You can copy the URL of the layout editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the layout settings.
Select General and choose Glossary and Index.

Enable the Index title or auto title in bookmarks setting to get Paligo to include the title of the index element in the bookmarks.

Note

This setting will only work if your index has a title, or you have set Paligo to generate a title automatically.

Select Save.

When you publish to PDF with this layout, Paligo includes the index title in the bookmarks. It is a subsection of its parent topic.

A PDF output that shows a references topic. There is an index inside the references topic. In the bookmarks sidebar, there is a link for the references topic, and at a lower level, a link for the index title.

Hide Index Title for HTML5 Output

Your HTML5 output will show your index title by default if your index:

Contains a title element
Has no title element, but your HTML5 layout is set to generate an index title automatically. The automatic title is called "Index" (or a translation of Index for other languages).

This can mean that your HTML index has two "Index" titles, one for the topic and one for the index element. To hide the title for the index element, use CSS:

Create or edit an existing custom CSS file and add the following code:
```
.index .titlepage{
    display: none;
}
```
To learn more about creating custom CSS, see Style with CSS.
Create an HTML5 Help Center layout. Alternatively, you can Edit a Layout.
Upload your custom CSS to the HTML5 layout.
Select Save.

When you publish to HTML5 using this layout, the index element's title is hidden.

Note

If you want to show the index title again, change the CSS to:

.index .titlepage{
    display: block;
}

Add Index References

Abstract

Learn how to add index references to your topics in Paligo. The references tell Paligo what terms should appear in the index and what type of reference should be used.

To get index entries to appear when you Create an Index Topic, you need to markup the topics with index references. These references tell Paligo what terms should appear in the index topic and what type of reference should be used. If your content does not contain any index references, your index topic will be empty when you publish. There are four types of index references that you can use depending on which information to be included in the index topic.

Appearance	Type	Description
	Primary Index References	The index topic will only show the main terms in alphabetical order with page numbers. Learn more, see Add a Primary Index Reference.
	Secondary Index References	The index topic will show both main terms and subterms in alphabetical order with page numbers. Learn more, see Add a Secondary Index Reference.
	See Index References	The index topic will show the main terms in alphabetical order without page numbers with a link within brackets to another term. Might be that you want to include terms that could be used for the same thing and refer the reader to the proper term instead. Learn more about how to add these extra references, see Add a See Index Reference.
	See Also Index References	The index topic will show the main terms in alphabetical order with page numbers including a link within brackets to an additional term. Learn more about how to add these extra references, see Add a See Also Index Reference.

Note

If you publish to HTML or HTML5 there will be hyperlinks instead of page numbers.

Add a Primary Index Reference

If you use a primary index reference, the index topic will only show the main terms in alphabetical order with page numbers. If you publish to HTML, there is a hyperlink to the page instead of a page number.

Index for letter T, showing Temperature with a page number, Thermal image with a page number, and Thresholds with a page number.

The index topic will look like this with primary index references.

Tip

To find out more about using the Element Context Menu to add content, see Add Topic Content.

To add a primary index reference to your content:

Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.

Position the cursor immediately before the text for the term that you want to use.

Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

Enter indexterm and select it from the menu.

Paligo adds an indexterm element with an primary element inside it.
Enter the main term inside the primary element to make it appear in the index.
Note

You should now have a structure like that shown in the example below. Here, we have used "temperature" as an example of a primary term.
```
<para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</pr
```
Select Save.

When you publish, Paligo will automatically add your index entries to your index topic. If you do not have an index topic, see Create an Index Topic.

Add a Secondary Index Reference

If you use a secondary index reference, the index topic will show both main terms and subterms in alphabetical order with page numbers. If you publish to HTML, there is a hyperlink to the page instead of a page number.

Index for letter T. It shows Temperature and a page number at the top level. Indented at the second level are entries for Alarms, Maximum, Minimum, and Shutdown, each with a page number.

The index topic will look like this with secondary index references.

Tip

To find out more about using the Element Context Menu to add content, see Add Topic Content.

To add a secondary index reference to your content:

Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.

Position the cursor immediately before the text for the term that you want to use.

Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

Enter indexterm and select it from the menu.

Paligo adds an indexterm element with an primary element inside it.
Enter the main term inside the primary element to make it appear in the index.
Note

You should now have a structure like that shown in the example below. Here, we have used "temperature" as an example of a primary term.
```
<para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</pr
```

Position the cursor after the primary reference, but before the end of the indexterm.

Tip

Move the cursor with the keyboard arrows to easier position it between the chevrons.

Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

Enter secondary and select it from the menu.

Enter the subterm inside the secondary element to make it appear in the index.

Paligo editor shows a para that contains an indexentry element. Inside the indexentry element there is a primary element with the main term. After the primary element is a secondary element.

Note

You should now have a structure like this (where we have used "alarm" as an example of a secondary term):

<para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</primary><secondary>alarm</secondary></indexterm>temperature alarm.</para>

Select Save.

When you publish, Paligo will automatically add your index entries to your index topic. If you do not have an index topic, see Create an Index Topic.

Add a See Index Reference

If you use a see index reference, the index topic will show the main terms in alphabetical order without page numbers with a link within brackets to another term. Might be that you want to include terms that could be used for the same thing and refer the reader to the proper term instead.

A see index reference is a combination of a primary element for the main term and a see element for the link to the additional term.

Index for letter T. It has an entry for Thermal and next to that it shows see Temperature.

The index topic will look like this with see index references.

Note

It is also possible to use a see element for a secondary term, but these entries can become complicated. It is usually better to keep your index entries as simple as possible, so that your readers can find the information they need quickly.

To add a see index reference:

Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.

Position the cursor immediately before the text for the term that you want to use.

Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

Enter indexterm and select it from the menu.

Paligo adds an indexterm element with an primary element inside it.
Enter the main term inside the primary element to make it appear in the index.
Note

You should now have a structure like that shown in the example below. Here, we have used "temperature" as an example of a primary term.
```
<para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</pr
```

Position the cursor after the primary reference, but before the end of the indexterm.

Tip

Move the cursor with the keyboard arrows to easier position it between the chevrons.

Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

Enter see and select it from the menu.
Enter the term inside the see element that is to appear as link within brackets in the index.

The entered term must be an existing index term.
Note

You should now have a structure like that shown below, where we have used "Temperature" as the "see" index entry.
```
<para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Thermal</primary><see>Temperature</see></indexterm>temperature alarm.</para>
```
Select Save.

When you publish, Paligo will automatically add your index entries to your index topic. If you do not have an index topic, see Create an Index Topic.

Add a See Also Index Reference

If you use a see also index reference, the index topic will show the main terms in alphabetical order with page numbers including a link within brackets to an additional term. If you publish to HTML, there is a hyperlink to the page instead of a page number.

A see also index reference is a combination of a primary element for the main term and a seealso element for the link to the additional term.

Index for the letter T. It shows Temperature as an entry. It has two page numbers for references and also another reference that shows see also Thermal.

The index topic will look like this with see also index references.

Note

It is also possible to use a seealso element for a secondary term, but these entries can become complicated. It is usually better to keep your index entries as simple as possible, so that your readers can find the information they need quickly.

To add a see also index reference:

Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.

Position the cursor immediately before the text for the term that you want to use.

Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

Enter indexterm and select it from the menu.

Paligo adds an indexterm element with an primary element inside it.
Enter the main term inside the primary element to make it appear in the index.
Note

You should now have a structure like that shown in the example below. Here, we have used "temperature" as an example of a primary term.
```
<para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</pr
```

Position the cursor after the primary reference, but before the end of the indexterm.

Tip

Move the cursor with the keyboard arrows to easier position it between the chevrons.

Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

Enter seealso and select it from the menu.
Enter the term inside the seealso element that is to appear as a link within brackets in the index.

The entered term must be an existing index term.
Note

You should now have a structure like that shown below, where we have used "Thermal" as the "seealso" index entry.
```
<para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</primary><seealso>Thermal</seealso></indexterm>temperature alarm.</para>
```
Select Save.

When you publish, Paligo will automatically add your index entries to your index topic. If you do not have an index topic, see Create an Index Topic.

Search for Index References

Use the Advanced Search to find topics that include index references. Depending on what you want to find, you can choose to:

Include all topics with index references by using the indexterm element in the search.
Narrow down the search by specifying the type of index reference (primary, secondary, see or seealso).

To search for index references:

Select Quick Search in the top menu.
Select Advanced Search.
Select the Search tab.
Enter indexterm or specify a particular index reference type (primary , secondary, see or seealso) in the Contains field.

To the left search for content with the indexterm element. To the right search for content with the seealso element.
Select the Content checkbox and clear the others in the Search in field.
Select Search.
All topics that match the search criteria will be presented below the search area.

Index Sorting for Language Symbols

Paligo can currently only use UTF-8 to define the sort order in an index. This means that languages that use symbols or a mix of symbols and phonemic characters (like Japanese, Korean and Chinese) will encounter problems when publishing in multiple languages.

A possible workaround for PDF output is by defining an indexterm that uses a phonemic word (alphabetic writing) for index sorting. The indexterm is invisible in the topics and works in the background to sort and group the index references.

The sortas attribute on the primary, secondary and tertiary elements is used to express a key. Usually the key is the same word as used as the value of the primary, secondary and tertiary element. This key is subsequently used to look up the actual phonemic version of the term in a lookup file for the language being published to.

The image above shows a possible Japanese index.

Enable Lookup Files for Index Sorting

For languages that require a mapping between a symbolic term and a phonemic sortas value, you have to enable the feature in the System settings. Also, you have to prepare one lookup file for each language that includes the sortas key and the translated phonemic word to replace it.

The sortas key will control the sort order of the element sortas attribute and group the indexterms in the index topic.

Select the avatar in the top-right corner.
Select Settings from the menu.

Select the System Settings tab. Cog icon.

Enable Use lookup files for index sortering with the slider.

Prepare a lookup file for each language and name it like this: sortas-lookup-language code.xml.

Replace the text "language code" with a two-letter or four-letter code (for example "sortas-lookup-ja.xml", "sortas-lookup-zh.xml" or "sortas-lookup-ko.xml". Learn more, see Language Codes.

Build the file like this:

<sortas-lookup lang="language code">
  <sortas key="phonemic word" value="phonemic word translated"/>
</sortas-lookup>

The image shows what a sortas-lookup file for Japanese could look like in an instance that uses English as source language.

Upload the lookup file to the xsl folder, see WebDAV Access to your Paligo Instance Folders.

Prepare Topics for Lookup files

Prepare the topics with indexterms that will be replaced with translated phonemic words from a file called sortas-lookup, see Enable Lookup Files for Index Sorting. Once the topics are ready, you add them to a publication containing an index topic and translate them.

The output index will be sorted according to the translated phonemic words (sortas keys) from the sortas-lookup files, but show the language symbols instead of the sortas attribute value.

To the left - the English source topic. To the right - the translated topic shows the symbol instead of the phonemic word.

Note

When you have this feature enabled and Paligo cannot find a lookup file for a language, all sortas attributes for this language will automatically be removed during the publishing process.

This means that you only require lookup files for languages that use symbols or a mix of symbols and phonemic characters (like Japanese, Korean and Chinese), but not for languages that use the Latin alphabet (like Swedish and English).

Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.

Position the cursor after the word that needs an indexterm added.

Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

Enter indexterm and select it from the menu.

Enter the word (within the chevrons) to be shown in the index topic. (Probably a symbol, if your source language is Japanese.)

It will be replaced with a translated phonemic version from the sortas-lookup file.

The indexterm is invisible in the topic and used for sorting and grouping the index.

Select the primary element in the Element Structure Menu and choose Go to element.

Note

This also works for secondary and tertiary elements.

Enter sortas in the Element Attributes Panel and select it from the menu.

Enter the key word that will fetch the phonemic word from the lookup file.

The sortas key will control the sort order of the element sortas attribute and group the indexterms in the index topic. For a Japanese source language this can actually be the symbol.
Select Save.

Revision History Topic

A revision history topic is a summary of the changes made to a document recorded in the Paligo Revision Control. They are useful to include in your publication as they provide an audit trail of the changes made to a document, with details of who made the changes, what the changes were, and when they were added.

When you publish your content, the revision history topic is included as part of the output (unless you have filtered it out).

For HTML outputs, you can use your CSS to style the revision history details, see Style with CSS.
For PDF output, only the default styling is available, although it is possible to change the styling as part of a customization project. Contact customer support for details.

Revision history page from a PDF output. There is a list of revisions, each with details of the date, author, and a summary of the changes.

Above an example of a revision history topic for PDF output.

Tip

To view the revision history in Paligo, see View Revision History.

Example 6. Revhistory and revision structure

The following code shows the XML for a valid revision history topic. We have removed the XML IDs and attributes for clarity. When you create your own revision history, the elements will have XML IDs and attributes added when you save.

<?xml version="1.0"?>
<section>
    <title>Revision History</title>
    <info>
        <revhistory>
            <revision>
                <revnumber>2</revnumber> 
                <date>24 May 2022</date> 
                <authorinitials>CW</authorinitials> 
                <revremark>Added information on recycling and ordering replacement parts.</revremark>
            </revision>
            <revision>
                <revnumber>1</revnumber> 
                <date>20 May 2022</date> 
                <authorinitials>CW</authorinitials>
                <revremark>Added legal information in front matter.</revremark>
            </revision>
        </revhistory>
    </info>
</section>

Create a Revision History Topic

To create a revision history topic:

Create a new topic with a suitable name, such as "Revision History".
Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.
Position the cursor below the title.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Enter info and select it from the menu.
Position the cursor inside the info element.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Enter revhistory and select it from the menu.

When you add a revhistory element, Paligo adds child elements to it automatically.

The child elements are:
- revision - This is a container element for the revnumber, date, authorinitials and revremark elements. You need the revision for the structure, but do not enter any information directly into it.
- revnumber - Enter the number of the revision, for example, 6 if this is the sixth revision to the content.
- date - Paligo inserts the date automatically, by default. You can overwrite it with a different date if you wish.
- authorinitials - Paligo inserts the name of the person who adds the revision element, by default. You can overwrite it with a different name or initials if you wish.
- revremark - Enter a brief description of the changes that have been made. This will help other users to understand what each revision included and why the changes were made.
Tip

You can delete an element if you do not want to include that information in the revision history.
Repeat step 8 to add more revisions.

You can add multiple revision elements inside a revhistory element.
Select Save.
Add your revision history topic to your publication.

It is recommended to position it as the first topic in the publication structure.

Tip

You may also want to put an output filter on its section element to exclude it from outputs, but remains in the publication for internal use, see Filtering / Profiling).

Make Topics Non-clickable (HTML5)

If you want to use a topic to categorize information, you can make the main topic non-clickable. It means that the topic title will be visible but only the subtopics are clickable.

By adding the role attribute (to the main section element) with the value set to topichead, the topic becomes:

Visible, but non-clickable in the HTML5 output sidebar (TOC), Category Panel Section and Featured Content Section.
Excluded from internal search, Google search and from the site map.
Skipped by Previous and Next navigation because it cannot locate its position on the site map.
Non-clickable in breadcrumbs.

To make a topic non-clickable for HTML5 output:

Select the topic or component in the Content Manager.

Paligo opens the content in the Editor.
Select the section element in the Element Structure Menu.
Select Go to element.
Add role attribute in the Element Attributes Panel and set the value to topichead.
Select Save.
Repeat this procedure for all topics that are to be non-clickable.

Topics

Editing Topics

The Basics of Topic Editing

Note

In-context editing

Note

Tip

Tip

Splitting elements

Removing bold or italic

Create a Topic

Note

Create a Topic in Content Manager

Note

Note

Tip

Create a Topic from the Publication Structure

Tip

Note

Note

Structure of a New Topic

Copy Topics

Note

Check-in and Check-out

Enable or Disable Author Remarks (PDF)

Tip

Note

Preview a Topic

Note

Tip

Important

Topic File Names

Note

Exclude a Topic from Search

Tip

Note

Open a Topic

Appendix Topic

Create an Appendix Topic

Note

Tip

Note

Glossary Topic

Create a Glossary Topic

Tip

Glossary References

Topic Term is Same as Glossary Term

Note

Topic Term is Different to Glossary Term

Reference Glossary Entry by XML ID

Tip

Tip

Reference with Baseform and Term Name

Important

See Glossary Reference

Tip

Note

Note

See Also Glossary Reference

Tip

Note

Note

Glossary Title

Add a Glossary Title

Automatic Glossary Title for PDF Outputs

Glossary Title included in PDF Bookmarks

Note

Glossary Title for HTML5 Output

Filter Out Unused Glossary Terms

Important

Note

Sort the Glossary

Glossary Popovers

Glossaries and Translations

Glossary Terms in the Translation Editor

Note

Index Topic

Note

Create an Index Topic

Note