Content Reuse

Content Reuse vs Copying

What is the difference between content reuse and copying?

With content reuse, you use the same piece of content in multiple places. There is no duplication. You reuse the same piece of content, and so if you change it, the alterations will apply in every topic where that content is used.

With reuse, the same element is inserted multiple times. Here, the "Select Save." para element (1) is used twice.

Copying is different, as you make a duplicate of the original. The copy is completely separate from the original.

With copy, the element (or text in the element) is duplicated. The copy (2) is a separate element to the original (1).

As a general rule, we recommend that you reuse content when you want to use the same content in multiple places. Use copy if you want to use an existing piece of content as a starting point for a new, customized piece of content that will be separate to the original.

Tip

Learn more about copying content, see Copy Content

Types of Content Reuse

There are many ways to reuse your content in Paligo:

Topic reuse - Reuse Topics by adding them to different publications. You can also embed one topic inside another topic as a subsection.
Publication reuse - Create a Super Publication by adding it to a main publication. For example, if you have a series of user guides, you can publish them all as one combined output by adding them to a single publication.
Structure reuse - Reuse Forks. For example, if you have a "chapter" that consists of a main topic and several sub-topics, you can reuse the entire "chapter".
Text fragment reuse - Every paragraph that you create is stored in a database and is available for reuse. This means that you can Reuse Text Fragments, Reuse Items in a List, steps in procedures and other types of block element without prior planning. For example, if you create a para element and add "Select Save" as the text, you can reuse that same paragraph everywhere that you need the "Select Save" text to appear.
Informal topic reuse - Informal topics are a way of grouping different types of elements as reusable content, for example, two paragraphs and an image. To reuse a group of elements, you can Create an Informal Topic and import it to any of your "regular" topics.
Admonition reuse - You can Reuse Admonitions to use in your topics.
Variables - You can reuse single words or phrases by using Variables. First, you create variable sets that contain the words and the text that you want to use for those words. Then you can insert these variables in your topics. Paligo has support for several types of variables, plain text variables, image variables, XML variables, and translatable variables. There are also Dynamic Text Variables, which can output today's date and similar content.
Filtering / Profiling - Filtering / Profiling makes it possible to make content more reusable by applying filtering (like the element attributes xinfo:product or xinfo:market) on parts of it, so that the topic becomes reusable in multiple context. With variable sets, it is possible to insert a variable that changes value according to chosen market or product.

Filtering is sometimes traditionally called "conditional text", but it applies to more than just text, it can be any kind of content, including images, videos and so on. This is often used when information is reused between different products or markets, for example technical specifications, to change data depending on model, change images or hide information for certain markets or models.

Note

You can also reuse the images in your Paligo Media library.

Reuse Topics

When content is added to a publication, you create special links called Forks. What you see in the publication structure is actually links to the topics. This means that you can reuse each topic in as many publications as you want. This is beneficial if you produce a range of different products that use the same information (like an introduction, a safety or scrapping chapter). You only create the content once and reuse it in various publications. Then, if you need to update the content, you make the changes in one place and the update will apply wherever that topic is reused.

If you have certain parts of the content that differentiates between products (like a product name, images or specifications) or need to be able to show or hide content (like warnings or procedure steps), you can use Variables and Filtering / Profiling.

Note

To reuse a topic multiple times in the same publication, you will need to set up the topics differently, so that the search can differentiate between each instance of the topic, see Reuse a Topic Multiple Times in the Same Publication.

Tip

You can also reuse publications, see Create a Super Publication.

The Safety topic is reused in the publication for both SmartPhone-A and SmartPhone-B.

To reuse topics in publications:

Select the publication in the Content Manager.

Paligo displays the publication's structure.
Drag and drop the topic you want to use into the publication structure.

Added content will appear at the bottom of the publication structure.
Rearrange the topic position with the arrows or drag and drop it in the structure.

Note

Top-level topics (1, 2, 3) in the publication structure will be displayed as a top sections in PDF output and as separate pages in HTML output.

Lower-level topics (1.1, 2.1, 3.1) will appear as subsections in PDF output. In HTML outputs, you can control whether you want the subsection topics to appear as separate pages or as subsections of a higher level "parent" page, see Use Chunking to Control Subsections.

To find out about controlling how subsections are used, see Headings and Subheadings.
Select Save to confirm the publication changes.
Repeat this process for each publication that needs to reuse the topic.

Reuse a Topic Multiple Times in the Same Publication

If you need to reuse the same topic multiple times in the same publication, copy and paste the topic's fork in the publication structure. The original fork and the copy will both reference the same topic, but the forks will have unique IDs. This is important for cross-references, as it means you can cross-reference to a specific fork in a publication, rather than the topic.

To learn how to copy and paste a fork, see Reuse Forks in the Same Publication.

To learn how to add cross-references to a fork, see Add Cross-References to Other Topics.

Note

If you add a cross-reference to a topic instead of a fork, the link will work, but it may expand the wrong part of the publication structure. This is because the browser will usually open the "table of contents" at the first instance of that topic in your publication.

Reuse Forks

To help you save time when creating publications, you can reuse Forks. These are the references from a publication to its topics.

There are two ways to reuse a publication's forks:

Reuse a fork in different publications

You can reuse a fork (and its lower-level forks) in a different publication. This helps to save time when creating similar publications, see Reuse Forks in Different Publications
Reuse the same fork multiple times in the same publication

If you need a topic to appear multiple times in one publication, add a fork to it and then copy-and-paste that fork, see Reuse Forks in the Same Publication.

Reuse Forks in Different Publications

You can reuse parts of a publication's structure in other publications. This will help you to save time when creating new publications that are similar to existing ones. It will also reduce the amount of work needed when updating your publications.

To share the publication structure, you reuse the Forks. These are the references from a publication to the topics that contain the content.

When you reuse forks, there is an "origin" publication, where the original forks were made and there is the "target" publication where they are reused. In the target publication, reused forks are shown with a reuse symbol and you can only see the top-level fork. You cannot expand the fork to reveal any lower-level reused forks inside it.

You can select a topic fork (origin publication) and reuse it in a different publication (target publication).

To reuse forks in different publications:

Select the target publication in the Content Manager to open its structure.
Expand the origin publication in the Content Manager.

The number to the right of a fork represents the number of forks included.
Hold down Shift and then drag-and-drop the fork you want to reuse into the target publication structure.

The fork will appear at the bottom of the publication structure.
Select the fork and use the arrow buttons to move it to a position of your choice in the structure.
Select Save to confirm the publication changes.

Reuse Forks in the Same Publication

You can copy and paste a publication fork (and its lower-level "child" forks). This is quick way to reuse parts of the structure multiple times in the same publication. For example, let's say you had a "Safety Precautions" topic that needed to appear in two different places in a publication. Instead of adding the same topic twice, you could add it once and copy and paste its fork.

Note

A fork is a reference from the publication's structure to a component, such as a topic, in the Content Manager. The fork is only the reference to the component. It is not the actual component.

To copy and paste a fork:

In the Content Manager, select the publication that you want to view.

Paligo displays the publication's structure.
Select the fork that you want to copy.
Select the dotted menu ( ... ) for the fork and then select Copy with children.

Copy with children option for a fork.

Paligo makes a copy of the fork (and any "child" forks nested at a lower level), ready for you to paste it elsewhere in the publication structure.
Select the dotted menu ( ... ) for the fork that you want to be either:
- Directly above the fork that you are going to paste into the publication
- A "parent" of the fork that you are going to paste into the publication.
Select Paste followed by either:
- Child
  
  To paste the copy so that it is one-level down from the "parent" topic.
  
  For example, in the following image, the"Customer Support" fork has been copied and pasted as a child of "Safety Precautions".
- After
  
  To paste the copy so that it appears after the fork you selected in the previous step. It is pasted below that fork, but at the same level.
  
  For example, in the following image, the "Customer Support" fork has been copied and pasted after the "Safety Precautions" fork, at the same level.
Repeat the paste process for each instance of the fork that you need in the publication.
Select Save.

You now have multiple references to the same topic(s) in your publication.

Note

When you save, Paligo gives the copy of the fork a new ID. This is so that you can add cross-references to a specific fork if required. For example, if you need to cross-reference the second instance of a topic in a publication, you can cross-reference that topic's fork rather than the topic itself (see Add Cross-References to Other Topics).

Create an Informal Topic

You can use a special type of topic called an informal topic to reuse a collection of elements. For example, if you wanted to reuse a paragraph and an image together, you could create an informal topic, and add the paragraph and image to that. Then, you could insert the informal topic into as many regular topics as needed.

To find out how to create and reuse informal topics, watch the video or read the instructions below.

Select the Dotted Menu (...) for the folder where the informal topic is to be stored.
Select Create Content.
Enter a name for the informal topic.
Select the checkbox for Informal topic.
Choose the Language(s) to support.
Select the checkbox Open in editor.
Select OK.
Add your content the same way that you add content to a regular topic.
Select Save.

Insert Component

If you have created informal topics or reusable components, you can insert them as components in topics. The components will become nested content and they can be arranged in the XML Tree View just like other content.

Position the cursor where the component is to be inserted.
Select the Insert tab in the Toolbar.
Select Component.
Select the component to be inserted.
Select OK.
Select Save.

Convert to Reusable Component

You can make a reusable component of subsections or Admonitions. A subsection will turn into a standalone topic and an admonition will turn into a reusable component. This means that you can begin creating your content in one topic and then create reusable admonitions or divide it into separate topics.

The benefit of making the subtopics into standalone topics is that it will be easier:

To find in the published output, because it will turn up as a standalone topic.
To find it in the Content Manager.

Tip

To reuse a paragraph, a list or steps in a procedure, see Create an Informal Topic.

Select the subsection or admonition in the Element Structure Menu.
Select Convert to reusable component.
Enter a name for the component.
Select where to save it.
Use the checkbox Reuse the component at position to decide whether to reuse the component at its current position or not. If you clear the box, the component is removed from its current position in the topic.

Note

When reusing the component inside the original topic, it becomes a nested component.
Select OK.
Select Save.

Remove Inserted Component

If you want to remove an inserted component from the topic:

Position the cursor inside the inserted component.
Select the component in the Element Structure Menu.
Choose Delete.
Select Save.

Convert to Informal Topic from Structure View

If you already have topics, it is possible to convert them into informal topics via the Structure View. This may save you time when making parts of a topic into an informal topic.

Make a copy of the topic.
Select the Dotted Menu (...) for the copy in the Content Manager.
Select Edit and choose Open Structure.
Change the Subtype to Informal topic in the Metadata Section. ⌄
Select Update.
Close the Structure View with the X in the top right corner.
Select the copy in the Content Manager to open it in the Editor.
Remove its title element.

Your topics will contain a title, so there is no need to have an additional title in the informal topic.
Select Save.
Select the origin topic Content Manager .
Insert the created informal topic.
Remove the part that became the informal topic.
Select Save.

Reuse Text Fragments

Every paragraph (or other textual block elements, such as titles and captions) that you write in Paligo is stored in the database and is available for reuse. Reusable paragraphs are also known as reusable text fragments. By reusing paragraphs, you can save time with content creation and updating and make your content more consistent.

The idea is to try and write a paragraph once, in one place, and then reuse it wherever needed. For example, if you are documenting software and you have a 'Click Save' paragraph, you can reuse that in all of your processes instead of writing different versions or copying and pasting. You do not need to make special types of content or store them in selected folders - as soon as you write a paragraph and save it, it becomes available for reuse.

Tip

Another way to create reusable components is to Create an Informal Topic.

Add Reusable Text Fragments

To find out how to use the Reuse text feature, watch the video or follow the instructions below.

Edit a topic and move the cursor to a position where a para element is valid. For example, directly above or below another paragraph or inside a step element in a procedure.
In the Reuse text section, search for the text that you want to insert as reused content.

Paligo will find any results that are similar to your search term.
If you see a result that is suitable for your needs, select it and choose:
- Reuse fragment to insert the text as a reused paragraph.
- Insert as content to insert the text as a regular paragraph. This is the same as entering a completely new paragraph as it will be saved with a unique id and is completely separate from other text fragments.
Select Save.

If you chose Reuse fragment, the reused text appears with a chain symbol. This shows it is reused.

Edit a Reused Text Fragment

When you add a reused text fragment to a topic, it is made unavailable for editing. This helps to prevent people from changing the content of the text fragment to suit one specific topic without considering the other topics where the fragment is used.

But it is possible to edit a reused text fragment. To find out how, watch the video or read the instructions below.

Select the reused text fragment (paragraph) you want to edit.
Select the para element in the Element Structure Menu.
Select the Edit reused fragment option.

You can now edit the reused fragment. Note that any changes you make will be applied wherever the text fragment is used, and so could affect many different topics.

Disable a Reused Text Fragment

A reused text fragment gets a chain symbol in front of it. This instruction shows how to disable a text from a reused text fragment.

Position the cursor inside the reused text fragment.
Select the para#text in the Element Structure Menu and choose Disable reuse.

The text will now be disabled from the reused text fragment and the chain symbol in front of it disappears.

Reuse Items in a List

In technical publications, it is quite common to have list items and steps that are repeated in various different topics. For example, if you are documenting software, it is likely that you will use a 'Save' step in lots of different procedures.

In Paligo, there are two different ways to reuse steps. You can use:

The reuse text feature for single list items or steps
An informal topic to reuse a sequence of list items or steps.

Note

If you want to reuse an entire list or procedure, add the list/procedure to an informal topic. You can then add the informal topic to other topics where appropriate.

To find out how to reuse items in lists, see the following sections.

Reuse a Single Item in a List

If you only want to reuse a single item or step in a list, you can use the Reuse text feature. This works in the same way as reusing a text fragment.

The text in a step or list item is enclosed in a para element. For example, a step in a procedure looks like this: <step><para>The text for the step.</para></step>. So to reuse a single step, you should first create a new step, and then reuse a para element inside it.

To find out how to reuse a single step, watch the video or read the following instructions:

Open the topic that you will insert the reused step into.
Add an extra step for the list or procedure. You can add an extra step by clicking at the end of the previous step and pressing Enter. Alternatively, position the cursor at the appropriate position and use the Element Context Menu to add a new step or listitem element.
Click in the para element that is created for the new step.
In the Reuse text section, search for the text of the step/listitem that you want to reuse.
When Paligo finds the step/listitem, select it and choose the Reuse fragment option.

Paligo adds the text into the step.

The text is a reused fragment and is locked. If you want to edit it, you will need to unlock it, but be aware that any changes you make will apply wherever that text is used, not just in your topic.

Reuse a Sequence of Items in a List

To reuse a sequence of items or steps in a list, add the sequence to an informal topic. You can then insert the informal topic inside a list in a regular topic. This is useful when you have multiple steps that are the same in many different topics.

You will also want to make sure that any numbering flows with the rest of the list. Paligo has a role attribute called reuse-range that makes this possible.

To find out how to reuse a sequence of steps in a list, watch the video or follow the instructions:

Create an informal topic.

To do this, select the options menu ( ... ) on a group folder, and select Create content. On the Create content dialog, give the informal topic a name, select the Informal topic option. Select the language you want to support and then select ok.
Open the informal topic in the editor and add the list or procedure steps you want to reuse in other topics. You can add a bullet list, number list, or procedure by using the toolbar icons in the Edit menu.
In the Element Structure Menu, select the top-level element for the list (itemized list, orderedlist, or procedure, depending on the type of list). Select the Go to element option.
In the Element attributes section, add the role attribute and set its attribute value to reuse-range. This allows Paligo to apply the correct sequence of numbering before and after the informal topic.
Save the informal topic.
Open the topic that contains the list you are going to add the sequence to.
If the topic does not already contain the list or procedure, insert one.
Position the cursor at the position where you want the steps in the informal topic to appear.

The cursor position is very important, as if it is an incorrect position, the informal topic cannot be added.

If you want the informal topic steps to appear between other steps in a list, position the cursor between the steps. Use the Element Structure Menu to make sure that the cursor position is at the top-level item for the list (itemized list, orderedlist, or procedure, depending on the type of list).

If you want the informal topic steps to appear at the start or end of an existing list, position the cursor above the first step or below the last step. Use the Element Structure Menu to make sure that the cursor position is at the top-level item for the list (itemized list, orderedlist, or procedure, depending on the type of list).
Select Insert > Component and browse to the informal topic.

Paligo adds the informal topic at the selected position (as long as you selected a valid position in step 8). The numbers of the steps in the informal topic adjust to fit in with the sequence of numbers in the existing list. If you add steps before or after the informal topic, they will also continue the correct numbering sequence.

Reuse Admonitions

You can draw the reader's attention to information by using admonitions, such as warning, caution, danger, tip and note. These are special pieces of content that stand out from the rest of your content and often have a special icon.

This type of content is often highly repetitive and so ideal for content reuse. In Paligo, you can create a library of notes, warnings, and other messages and reuse them wherever they are needed. There is no need to copy and paste or duplicate the information.

Warning Icon

Create a Reusable Admonition

There are two ways to create admonitions. You can create them as elements in a topic, see Admonitions or you can create them as reusable pieces of content. Here, we are going to explain how to:

Create a reusable admonition
Insert a reusable admonition into a topic.

The following video shows how to create a reusable warning and insert it in a topic. You can use the same technique to create different types of admonitions, just select the appropriate option instead of warning. Alternatively, follow the instructions below.

In the Content Manager, select the options menu ( ... ) for the folder that you want to contain your reusable admonition. If a suitable folder does not already exist, create a new one.
Select Create Content.
Enter a name for the admonition and select the appropriate type (Note, Warning, Caution, Danger, Notice, Important, or Tip).

Paligo creates the admonition and adds it to the relevant folder.
Select the admonition to open it in the editor and add the text and/or images you need it to include. Save the admonition when you have finished.
Find a topic that you want to add the admonition to, and then open the topic in the editor.
Place the cursor at a valid position for the admonition. This can be any position where text can be added. (Paligo will display an error message if you try to add an admonition in an invalid position).
Select Insert > Component.
Choose the reusable admonition that you want to add to the topic and select OK.

The reusable admonition is added to the topic.

Insert a Reusable Admonition

To insert a reusable admonition, such as a warning or note, in a topic:

Find a topic that you want to add the admonition to, and then open the topic in the editor.
Place the cursor at a valid position for the admonition. This can be any position where text can be added. (Paligo will display an error message if you try to add an admonition in an invalid position).
Select Insert > Component.
Choose the reusable admonition that you want to add to the topic and select OK.

The reusable admonition is added to the topic. For example, in the image below, a reusable warning admonition is added to a topic.

Convert Regular Admonitions to Reusable Admonitions

You can add "regular" admonitions by selecting Insert and choosing an admonition. Regular admonitions are designed as "one-off" messages that will not be reused. However, it is quite possible that you will add a regular admonition to a topic and later realise that you need to use it again. In these situations, you can quickly convert the regular admonition into a reusable component.

To learn how to convert a regular admonition into a reusable component, watch the video or follow the instructions below:

Open the topic that contains the regular admonition that you want to reuse, and select any part of the admonition.
In the Element Structure Menu, select the top-level element of the admonition to display a menu. For example, if you have selected a warning admonition, select the warning element.
From the menu, select Convert to reusable component.
Give the component a suitable name and choose a folder to store it in.
Use Reuse the component at position option to choose whether you want to replace the existing regular admonition with the reusable version that Paligo will create.
Select Ok to confirm and Paligo will create a reusable component that matches the admonition you selected in step 1.

To add the admonition to topics, open a topic in the editor and position the cursor at a valid position. Then select Insert > Component, and select the reusable admonition.

Content Reuse for Front Matter

If you are creating many publications, you may want to reuse some of the information in a publication topic. For example, you may have 5 different publications, but you want them all to use the same legal notice "info elements".

To reuse "info elements", such as copyright and legalinfo, you need to take a different approach than you would for reusing most other elements. This is because "info elements" cannot be reused in informal topics. Instead, you should use a publication template.

Note

To find out about publication topics and the info elements that you can add to them, see Publication Topic - "Front Matter".

There are several things that you need to set up to reuse "info elements". To make the information easier to follow, we have broken it down into these stages:

Create a publication template and add the info elements to that.
Create a variable set to define the reusable text for the info elements.
Add the Variables to the Publication Template.
Create new publications based on the template. These publications will automatically inherit the text from the variable set.
Choose the Variable Set when you Publish .

With the template and variable set in place, you can update the variable values by making the changes once in the variable set. The changes you make there will be applied wherever the variables are used.

If you are new to the concept of variables and variable sets, you can find out about them in Variables.

Create a Publication Template to Contain the Reusable Info Elements

A publication template contains content that is inherited automatically by "real" publications that are based on the template. So by adding "info elements" there, you can make sure those "info elements" also appear in your publications.

In the Content Manager, find Templates and select its options menu ( ... ). Select the Create Content option.
Enter a name for the publication template and select Publication as the type of content you are creating. Remember that this is going to be a template publication, not a "real" publication.
Check the Open in editor box in the bottom-left corner and then select OK.

Paligo opens the publication's topic in the editor. It contains the default "info elements", including subtitle, copyright, and abstract.
Edit the publication topic so that it contains the "info elements" that you want to appear in all of the publications that are based on this template.
Consider what information you are going to need as the content for each of the "info elements" in your publications.
- For content that is always going to be the same for all publications, add it directly to the template elements.
  
  For example, if all publications are going to have the same legal notice, you could add the text for it in the legalnotice element on the template.
- For content that you want to reuse in some, but not all, publications based on the template, use a variable.
At this stage, you can add the text that is always going to be the same. For variables, you will need to create a variable set and we will explain that in the next stage of this process.
Select Save.

Create a Variable Set for the Reusable Info Elements

To reuse the content of "info elements", you need to add the content to the template as variables. These are containers that can contain different content, depending on the choices you make when you publish.

To use variables, you need a variable set:

In the Variable Sets section of the Content Manager, select the options menu ( ... ) and then create a new variable set and give it a suitable name.
Edit the variable set and add variables for those "info elements" that you want to reuse in different publications. Use translatable text variables for text content and images for images.

For example, let's say that for your publications, you want to reuse the subtitle and also the legalinfo. So in your variable set, you add a variable for the subtitle and a variable for the legal information.
Add a variant for each different publishing scenario. Each variant is shown as a column and it is a collection of values that Paligo can insert into your publication topic.

For example, if you publish developer guides, engineer guides, and operator guides, you might want each type of guide to have a different subtitle and legal information. So you would create a variant for each guide, and in each variant, define the content that should be used.

When you publish, you can tell Paligo which variant to use, and then it will "push" the values of that column into your publication topic.

Tip

To learn more about creating variable sets and variants, see Variables.

Now that you have your variable set, variants, and values, you can add the variables to your publication template.

Add the Variables to the Publication Template

When you have a variable set, you can add its variables to your publication template:

In the Content Manager, select the options menu ( ... ) for your publication template, and then select Edit > Open in editor.
Position the cursor inside an element that is going to contain a variable.
Select the Insert menu, then Variable, and choose the variable set that you created for your reusable "info elements". Then choose the appropriate variable from the list.
Repeat steps 2 and 3 until you have added variables to the various elements.

The variables are shown as blue boxes, with the name of the variable set and variable shown.
Select Save.

Next, you will create publications that are based on the template.

Create a New Publication from the Template

Now that your publication template is in place, you can use it to create new, "real" publications.

In the Content Manager, select the options menu ( ... ) for the folder that is going to contain your new publication. Then select Create content.
On the Create content dialog, select From template, and then select your publication template. Give your new publication a name, select what languages you want it to support, and then select OK to create it.
In the Content Manager, select your new publication to open its structure and then add topics to it. Organize its structure, and edit its publication topic, just as you would for any other publication. The only difference here is that the publication topic automatically inherits the elements from the publication topic in your template. This inheritance from the template is how the "info elements" are reused. The variables are also inherited and you will set the values for these when you publish.
Repeat this process for as many publications as you need.

You will set the values for the variables in the publication topic when you are ready to publish.

Choose the Variable Set when you Publish

To set the values that will be used for the variables in your publication topics, choose the variable set and variant when you publish:

Select the options menu ( ... ) for the publication, and then select Publish.
On the Publish document dialog, select the output type, language, and all the other settings that you would normally choose when publishing.

To learn more about the publishing settings, see Publishing Process.
In the Variables section, select the variable set that contains the "info element" variables that you created for your publication template. Then select the variant that you want to use from that set.

Remember that the variant is a collection of values that will be inserted into the relevant variables. In this case, the values from the variant set that you choose will be inserted into the variables that are in your publication topic.

Note

If you have used other variables in the other topics in the publication, add those variable sets in the publication settings too. For each of the variable sets, choose which variant you want to use.
Select Publish document to publish your content.

Paligo will generate the content and it will download as a zip file in your browser. You can then unzip the file and move its contents to a web server, so that people can access it.

Lock and Unlock Content

If you have a paragraph that you do not want other users to change, you can lock it. The lock means that the content is more difficult to change, as if someone wants to edit it, they first have to unlock it. You can lock and unlock any para element.

To find out how to lock and unlock content, watch the video or read the instructions below:

Tip

Locking your content can be a good idea if you have a team of writers and some are new to the concept of content reuse. Sometimes people do not realise that if they change a paragraph, it changes wherever that paragraph is used.

Lock Content

To lock content so that it cannot be edited:

Select any part of the paragraph.
Select the para element in the Element Structure Menu.
Select Lock content from the menu to lock the paragraph.
Select Save.

Unlock Content

To unlock content so that it can be edited again:

Select any part of the paragraph.
Select the para element in the Element Structure Menu.
Select Unlock content from the menu to unlock the paragraph.
Select Save.

Find Reusable Content

Paligo has many convenient ways to find reusable content that you can add to your topics and publications. The features you will use vary, depending on whether you want to Find Text Fragments to Reuse in Topics or Find Topics and Publications to Reuse.

Tip

Another way of finding reusable topics and other components is to use Classify Content with Taxonomies to categorize them.

Note

Paligo also has "where used" features so that you can Find Out Where Content is Used.

Find Text Fragments to Reuse in Topics

Every paragraph that you write in Paligo is stored in the database as a "text fragment". So there's no need to store individual paragraphs separately for reuse, as every paragraph is made available for reuse automatically.

To find a paragraph to reuse in a topic:

Edit a topic and position the cursor at a valid position for a paragraph element (para).
In the Reuse text section on the right side of the editor, search for the text that you want to reuse. Paligo will find any close matches that already exist in the database.

Search for the text that you want to reuse.

Paligo will find close matches to your search term.
Select the entry that you want to reuse and Paligo will insert it into the topic.

Find Topics and Publications to Reuse

You can reuse topics inside other topics or in many different publications. Similarly, you can reuse a publication inside another publication. Reusing topics and publications in this way is a great way to save time when producing similar user guides.

There are several ways to find the topics and publications you want to reuse:

Edit the structure of a publication and then use the search bar at the bottom of the Content Manager. Enter the name of any topic or publication in here, and Paligo will find any close matches. You can then drag the topic or publication into the structure of the publication.
Browse through the folders in your Content Manager to find the publication or topic, and then drag and drop it into the structure of publication.
If you are editing a topic and want to add another topic as a subsection, select Insert > Component and then search or browse for the topic you want to reuse.
If you have added taxonomy tags to your topics, you can use the taxonomy manager to find topics.
1. In the Taxonomy Manager, select the taxonomy tag that relates to the content you want to reuse.
  
  Paligo displays a list of the topics that use that taxonomy tag.
2. Select the topic from the list to open it in the editor. You can then see where the topic is located in the Content Manager. Now that you know where the topic is located, you can open a publication and drag the topic into it. Or you can edit a topic and use Insert > Component and browse to the topic to insert it as a subsection inside the topic.

Find Out Where Content is Used

Paligo has several features you can use to find out where your content is used. These are especially useful when you have reused content, as as you will need to make sure that any changes you make are appropriate for all of the places where the content appears.

Also, being able to find topics is important when you want to delete content, as you cannot delete topics or publications that are included in another topic or publication. Similarly, you cannot delete topics that other topics link to. So you will need to remove those instances of reuse and the links before you can delete a topic. (For information on how to delete reused content, see Delete Content).

What type of content are you looking for?

Find Reusable Content like text fragments, topics and publications
Search with Taxonomy Tags
Search for a Topic in a Publication

Tip

If you frequently reuse the same text elements, informal topics, admonitions, you can Create an Informal Topic and insert it in as many topics as needed.

Find Out Where Topics and Publications are Reused

When you are updating and organizing your content, you may want to find out where each topic or publication is used. You can find out this information in the structure view and also in the resource view.

To find the reuse information in the structure view:

In the Content Manager, select the options menu ( ... ) for the topic or publication you are interested in. Select Edit > Open Structure.
In the Metadata section, look at the following entries:
- Used in - Shows where the selected topic or publication is used, either as a subsection inside another topic or as part of a publication.
  
  Entries marked "Component" are where the topic is embedded inside another topic as a component (subsection).
  
  Entries marked "Fork" are a reference between the selected topic/publication and a position in another publication. For example, in the image shown, the metadata is for a topic called "Specifications". It has been added to a publication, and the "fork" reference from the publication goes to the "Specifications" topic.
- Uses - The selected topic or publication can contain other topics and publications. They are listed here.
- Related publications - The selected topic or publication is reused in each publication shown in this list.

To find the reuse information in resource view:

In the Content Manager, select the folder that contains the topic or publication of interest.

If the topic or publication is not in a folder, create a new folder and move the topic or publication into it.

Paligo displays the folder's contents in the resource view. It shows each folder, publication, and topic stored in that folder.
Select the arrow icon next to the topic or publication of interest. Then select the Related Resources tab.

The reuse information is shown in these sections:
- Related publications - The selected topic or publication is reused in each publication shown in this list.
- Reused content - The selected topic or publication can contain other topics and publications. They are listed here.
- Reused in - Shows where the selected topic or publication is reused. This includes publications and topics.
- Related images - Shows any images that are used in the selected topic (this only applies to topics and is always set to 0 for publications).

Find Out Where Text Fragments are Reused

To find out where a text fragment (paragraph) is reused in your content, you can use:

This is useful when you are considering making a change to reused text, but need to understand how those changes will affect other topics.

Note

When you edit a topic that contains reused text fragments (paragraphs), each reused text fragment is shown with a chain icon. It is also highlighted.

Access Reuse Information with the Element Structure Menu

To use the element structure menu to find out where a text fragment is reused:

Edit a topic and select the paragraph that you are interested in.
In the element structure menu, select the #text element that comes after the para element. Then select Text> Usage information.

Paligo displays the Text usage dialog. It lists the topics that use the selected text fragment, and provides information about the taxonomies, status, language. It also shows the name of the user that last edited the paragraph, and the time when that edit took place.

If you select the topic in the list, Paligo will display that topic in the editor.

At the end of each row, there is an options menu ( ... ) where you can access other features for the topic. These include a preview, the assignments feature, the review and contributor editors and more.
Select Close.

Access Reuse Information with the Reuse Text Feature

To find out which topics use a text fragment, you can use the Reuse Text feature. This is available when you edit a topic and is shown on the right-hand side of the editor.

In the search field, enter the text for the fragment that you want to find out about. Paligo will present you with a list of close matches.
Find the entry that matches your search and then select its cog icon. From the menu, choose Usage Information.

Paligo displays the Text usage dialog. It lists the topics that use the selected text fragment, and provides information about the taxonomies, status, language. It also shows the name of the user that last edited the paragraph, and the time when that edit took place.

If you select the topic in the list, Paligo will display that topic in the editor.

At the end of each row, there is an options menu ( ... ) where you can access other features for the topic. These include a preview, the assignments feature, the review and contributor editors and more.

Find Out Where Images are Used

To find out where images are used, access the metadata for the media file.

Open a topic that contains the media in the Paligo editor.
Right-click on the topic and select Edit Properties.
Look at the Reused in section on the dialog. It contains links to the topics where the media is reused.

Alternatively:

In the Content Manager, expand the Media section and find the media file you are interested in.
Select the options menu ( ... ) for the media file and then select Edit Image.
Look at the Reused in section on the dialog. It contains links to the topics where the media is reused.

Filtering / Profiling

Abstract

Learn how to use filtering, also known as profiling, to control which content is included in your outputs. Find out what you can filter and how the filtering works.

Filtering is also known as "profiling" or "conditional content" and you can use it to include or exclude content depending on certain conditions. For example, you can set a topic to be included in your publication if the intended audience is beginners, but excluded if the audience is experts.

You can use filtering to include or exclude:

Entire topics in a publication
Elements in a topic, such as paragraphs, procedures, or steps in a list.

Filtering gives you more control over your content and can also give you more opportunities for your topics. Let's say that you have a topic that could be reused, if only it did not contain a particular paragraph. By filtering that paragraph, you can make the topic suitable for reuse, as you can include or exclude the paragraph when needed.

How Filtering Works

Paligo has several different types of filtering, but to begin with, we recommend you learn about "regular" filtering.

The workflow for "regular" filtering is:

You mark up the content that you want to filter. This tells Paligo what content can be filtered, and what conditions apply.

To set the conditions, you choose a type of filtering to apply and you set a filter value.

Paligo does not have one generic filter for everything. Instead, it has a range of filter types, called filter attributes. There are different filter attributes for filtering by product name, by audience, by country, and by market, among others.

For example, to filter a paragraph so that it only appears in a user guide for a Windows version of a product, you could set a filter attribute of os (operating system) and a filter value of Windows.
You set the filters you want Paligo to apply to the published output.
Paligo then:
- Includes all of the content that does not use the filters attributes you chose for publishing.
- Searches through your content to find any elements that have the filter attribute(s) that you set for the publication. For example, if you set an os filter attribute in the publication, Paligo will find all of the elements that are marked up to have an os filter attribute. These are the "matching" elements.
- Searches through the "matching" elements to check the filter values. Those with the same value that you set for the publication are included in the published output. Those that have different values are excluded.
  
  Tip
  
  If you want to exclude content, create filter values for the conditions where it should be included and also for where it should be excluded. For examples, see Mark Up Elements for Filtering and Mark Up Topics for Filtering.

Note

The process for setting up filtering is different for scoped filtering, taxonomy filtering, and filtering by language.

Regular Filters, Taxonomy Filters and Scoped Filters

There are several ways of applying filters to your content in Paligo. They all involve marking up your content for filtering and then setting filters on the publication. But the process for doing this is different depending on which method of filtering you choose to use.

The two main types of filtering are:

"Regular" filtering, where you edit a topic and apply a filter attribute and filter value to one or more elements. You can use "regular" filtering for filtering entire topics or individual elements in a topic.

To get started with "regular" filtering, see:

Filter Topics in a Publication

Filter Block Elements in a Topic
Taxonomy filtering, where you set up taxonomy tags to represent the filter attributes and values, and you drag and drop them on to your topics. You can also set Paligo to use the taxonomy hierarchy for more complex filters, where Paligo uses the taxonomy hierarchy to determine which topics to include or exclude.

See taxonomy filtering for more details.

There is also scoped filtering. This is for when you want to use the same content in the same publication, but apply different filters depending on where the content appears.

You can use a mix of the different filtering types, if needed.

Filter Attributes

When you set a filter in Paligo, there are many different types of filter you can use. Some are defined by the DocBook standard and some are custom filters that we have created for Paligo.

The following table shows the filters you can use:

Filter attribute	Source	Description
arch	DocBook	Filter by computer or chip architecture.
audience	DocBook	Filter the content based on the intended users, for example, internal staff or customers. You could use audience for the knowledge level too, such as beginner or expert. But there is a `userlevel` attribute specifically for that, so can use `audience` or `userlevel`, but it is important to be consistent.
condition	DocBook	This is a general purpose filter attribute. Use this filter if the other filters do not meet your requirements.
conformance	DocBook	Filter by conformance standards.
os	DocBook	Filter by operating system, for example, Windows.
revision	DocBook	Filter by publication revision, for example, v.3.1.
security	DocBook	Filter by security level, for example, Low.
userlevel	DocBook	Filter by knowledge level of the intended audience, for example, expert.
vendor	DocBook	Filter by product provider, such as a manufacturer or seller.
outputformat	DocBook	Filter by the type of output, for example PDF.
xinfo:product	Paligo	Filter by product name or model.
xinfo:country	Paligo	Filter by the country that the documentation is designed for, for example, USA.
xinfo:market	Paligo	This is similar to xinfo:country except that it is less geographically rigid, for example, you can filter for the Asia market or the North America market.
xinfo:version	Paligo	Filter by version. You can use this in combination with the version management features of Paligo, but this is not a requirement. The usage is up to you.
xinfo:proglang	Paligo	Filter by programming language or to publish to API style "on-the-fly" filtering HTML5. Note Paligo does not support using `xinfo:proglang` on table rows.
xml:lang	DocBook	Filter by natural language, for example, filter Swedish content. This filter attribute is a special case, as there is a different process for using language filters. To find out more, see Filter by Language.

To find out how to use filters in your content, see Filter Block Elements in a Topic , Filter Topics in a Publication, and Filter by Language.

Scoped Filtering

Scoped filtering is a powerful feature in Paligo that allows you even more flexibility when it comes to profiling / filtering content. It is designed for when you want to reuse your content in multiple places within the publication and to be able to apply different filters depending on where it appears in the publication. Scoped Filtering can be used in combination with Taxonomy Filters.

The workflow for scoped filtering:

Make sure scoped filtering is enabled. It is enabled by default, but it may have been disabled on your Paligo instance, see Enable Scoped Filtering.
Organize your publication structure so that you have "parent" topics (high level) with the "child" topics (lower level) as subsections.
Apply filters to your "child" topic elements.
Apply the "scope filters" on "parent" topic elements. Typically, you should set the scope filters on the section element.
Publish your content and include the filter attributes that are set on the "scope filters" and all of the filter values that should be used.

Note

Scoped filtering is advanced. Make sure you understand the basic profiling/filtering concepts before using scoped filtering, see Principles of Scoped Filtering

Principles of Scoped Filtering

The important principles of scoped filtering are:

Scoped filtering applies to content that is reused in the same publication.
With scoped filtering you can reuse topics and set them to use different filter values, depending on where the topic is positioned in the publication structure.
You tell Paligo which filter values a "child" topic should use by setting a "scope filter" on the "parent" topic
When you publish, you set the filters and include all of the values that you want to use in the publication.

To show you how scoped filtering can be used, we'll guide you through an example.

Example 1. Scoped filtering for applying different filters to reused content

Let's say you are documenting a product, for example, a fictional video conference software called ACME VCT. The software supports MacOS and Windows, and as most of the documentation is the same for both versions, you want to create a single user guide rather than two separate versions. The user guide will have a MacOS section and a Windows section.

In Paligo, you create the content and organize it in a publication structure like this:

You have a "chapter" for Windows content, called "Installing on Windows", and you have "Installing on MacOS" as a chapter about MacOS.

You have also reused two topics. The "Prerequisites" topic and the "System Requirements" topic are both used in the Windows and MacOS chapters. For this example, we will focus on the "System Requirements" topic.

In the "System Requirements" topic, you have some information that is for Windows only, and some that is for MacOS only.

A screenshot of a section of a Paligo topic in HTML5 output. There is an image and then an "Operating System Version" subsection and a "Supported Browsers" subsection. In each subsection is some content only relevant to Windows, and this is marked with a callout number (2). There is also some content only for Mac OS and this is marked with a callout number (1).

In the image above:

This is for content that is only relevant to MacOS. You apply an os filter to this content and set the filter value to macos.
This is content that is only relevant to Windows. You apply an os filter to this content and set the filter value to windows.

If you published the content as it is, you would only be able to set the os filter to be either Windows only, MacOS only, or include Windows and MacOS.

This is where scoped filtering comes in. You can use it to tell Paligo to use an os:windows filter in some places, but an os:macos filter in others.

To set the scoped filtering, set a "scope filter" on the section element of a topic that is at a higher level than the topic you want to filter. In this scenario, the higher-level topic is called a "parent" and the lower-level topic is called a "child".

Note that the "scope filter" is not a type of filter, it is the term we use to describe the filter that is set on the "parent" topic.

The structure view of a publication. It has an Installing on MacOS top level topic with a Prerequisites subtopic and a System Requirements subtopic. There is also an Installing on Windows top-level topic which also has Prerequisites and System Requirements subtopics. The Installing on Mac OS topic has a callout with number 1 on it. The Installing on Windows topic has a callout with number 2 on it.

In this example, there are two "scope filters" to set (1 and 2 on the image above):

Set the "scope filter" for the Windows chapter on the section element of the "Installing on Windows" topic. The "scope filter" is the os filter with the value: windows.

With this "scope filter" you are telling Paligo that if any "child" topics in this chapter contain os filters, Paligo should include any that have the value: windows. But it should exclude any that have different values.

Set the "scope filter" for the MacOS chapter on the section element of the "Installing on MacOS" topic. The scope filter is the os filter with the value: macos.

This "scope filter" tells Paligo that if any "child" topics in this chapter contain os filters, Paligo can include any that have the value: macos. But it should exclude any that have different values.

You now have your content marked up for scoped filtering. The final step is to set the filter and values when you publish.

You publish your content and you edit the Profiling attributes on the Publish document dialog. You choose to include the os filter. Importantly, for scoped filtering, you include all of the os values that need to appear in the published output. In this case, you want the Windows filtered content to appear in one chapter and the MacOS content to appear in another chapter, so you include both values.

The published output will now have reused the same topic "System Requirements" in two parts of the documentation, but it will appear differently in the Windows and MacOS sections respectively, even though it is in the same output:

Windows version

MacOS version

Enable Scoped Filtering

In the Layout Editor it is possible to enable scoped filtering for both HTML5 and PDF output. Make sure the option is set to Yes or Default.

Note

For PDF output, you find this setting under General / Filtering and taxonomies / Enable scoped profiling / filtering.

The following instruction shows how to enable this setting for HTML5 output:

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 configuration 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 need to frequently switch between your Paligo content and the layout settings.

Select Classes and attributes in the left menu.

Select Yes to Enable scoped profiling / filtering.

Select Save.

Preview Your Filters

When you mark up your content for filtering, you can use the preview feature to see the effects of the filters. This is a good way of making sure that the filters work as expected, and is especially useful if you have used a combination of filters.

To preview the filters:

Find the topic that contains the filters in the Content Manager, and open it in the editor.
Select Preview > Profile settings.
Select Profiling.
For each filter attribute, select the field and choose the filter you want to apply for the preview. If you do not want to apply a particular filter, leave its field blank.
Select Apply.

The filter is applied to the preview of the topic:
- Any content that is not marked up to use the types of filter you have applied is included in the content.
- Any content that is marked up to use the filters you have applied, with the same values you have set, is included in the content.
- Any content that is marked up to use the filters you have applied, but with different values, is excluded.
For example, if you set the preview to show the Market filter attribute with a value of Europe, the topic would show:
- Any content that is not marked up to use the Market filter attribute
- Any content that is marked up to use the Market filter attribute and a value of Europe
The preview would exclude any content that has the Market filter attribute and any other value, such as Asia, North America, Australasia, etc.
Repeat steps 4 and 5 to change the filters for the preview and see how they affect the content.

To stop applying the filter preview, display the Profile settings dialog select the Profiling tab, and then select Reset.

Filter by Language

You can use the xml:lang attribute to filter content by (natural) language for HTML and PDF outputs. This means you can mark an element as being appropriate for a language, and the element will only be included if the content is published to that language. If you publish to different languages, the element is excluded.

The xml:lang attribute works a little differently to the other filter attributes. Firstly, to use it, you need to enable the feature on the layout that you will use for publishing. Then you can add it to elements that you want to filter, and finally, you publish and choose what languages to publish to. Paligo applies the language filters automatically, based on what languages you are publishing to.

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 configuration 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 need to frequently switch between your Paligo content and the layout settings.
Select Classes and Attributes for HTML layouts OR General > Filtering and Taxonomies for PDF layouts.
Select Enable for Use xml:lang as profiling attribute.
In your content, select an element that you want to filter by language.
Use the Element Attributes Panel to add the xml:lang filter attribute and set its value to the appropriate language. For the language values, use the two-letter language codes, for example, en for English and sv for Swedish.

Important

Use the two-letter codes shown in the Languages section (see step 6). Only these two-letter codes are supported. You cannot use alternative language codes.
Repeat steps 3 and 4 for other any other elements you want to filter by language.
Publish your content and choose the layout you edited in step 1 and the language(s) that you want to publish to:
- If you publish to a language that matches the value of the xml:lang filtered content, that content is included in the output.
- If you publish to a language that does not match the value of the xml:lang filtered content, that content is excluded from the output.
Set any variables and other profiles as required and then publish.

Filter Inline Content

You can use the phrase element to apply filters to inline content. This is useful when you need to filter part of a block element, for example, if you wanted to filter one sentence in a paragraph rather than the entire paragraph.

To filter inline content:

Select the content you want to filter.
To display the element context menu, press Alt and Enter (Windows) or Option ⌥ and Enter (Mac).
Add the phrase element.

Paligo inserts your selected content into the phrase element.
Click in your selected content so that the phrase element is shown in the Element Structure Menu.
In the Element attributes section, add the filter condition that you want to apply to the phrase. This works in the same way as filtering any other element, for example, you could set an xinfo:country attribute if you wanted to be able to include/exclude the phrase based on the country.

To find out about filter types, see Filter Attributes.
Set the value for the filter and apply it to your phrase element.

To find out about filter values, see Filter Block Elements in a Topic.
Select Save.

When you publish, you can choose which filters to apply to your content. As the inline content is now wrapped in a phrase element, it can be filtered in the same way as any other element. The settings you choose when you publish will determine whether the phrase is included or excluded from the published content.

Filter Block Elements in a Topic

In this section, you can learn how to apply filters to block elements, such as paragraphs, lists, and images. These filters apply to an entire block of content. If you want to filter inline content, such as one sentence or one word in a paragraph, see Filter Inline Content.

Filtering block elements is useful when you have entire elements that you want to include or exclude, depending on certain criteria. For example, you could have a paragraph that is only relevant to Mac users, so you could add a filter to include or exclude it, depending on whether the publication is for Windows or Mac.

Note

To apply filters to elements in a topic, use the "regular" type of filtering (you cannot use taxonomy filters for filtering elements in a topic).

To learn how to set up filters on block elements, watch the video or read the following sections. The video shows a list item being filtered, and you can use the same technique to filter other block elements.

To filter elements in a topic:

Mark up your content for filtering. For filtering elements in a topic, use the "regular" type of filtering. You cannot use taxonomy filters for filtering elements in a topic.
Preview your content to see how the filters will affect your content (this is an optional step).
Set the filters that you want your publication to use and then publish.

Mark Up Elements for Filtering

Before you can apply filtering to your publications, you need to tell Paligo what elements can be filtered, and what filter conditions apply. You can do this by "marking up" the elements that you want to filter.

To mark up your content, you can select an element and then apply a filter attribute and a filter value. The filter attribute tells Paligo which type of filter to use, and the filter value sets the condition for the filter.

Element (1), filter attribute (2), filter value (3).

Paligo does not have one generic filter for everything. Instead, it has a range of filter types, called filter attributes. There are different filter attributes for filtering by product name, by audience, by country, and by market, among others.

Note

Marking up the content tells Paligo what content can be filtered. It does not apply the filter. You apply the filter in the publishing settings when you publish the content.

Edit the topic that contains the element you want to filter. Select any part of the element so that it is shown in the Element Structure Menu.

In the Element Structure Menu, select the element you want to filter and then select Go to element.

Tip

If you want to filter text inside a paragraph, and not the entire paragraph, highlight the text and add the phrase element to it. You will then be able to apply the filter attribute and value to the phrase element so that it can be included/excluded when you publish.

In the Element attributes section, select Add attribute and search for the filter attribute you want to use. Note that the Add attribute list includes all attributes, not just filters

There are many different types of profile attribute (filter) that you can use, including product name, country, and audience. To find out about the different profile attributes, see Filter Attributes.

Use the Profiling values dialog to set the filter value. Think of setting the value as a way of telling Paligo where the content is applicable.

For example, if you have a paragraph that is only applicable to a product named "ACME 1050", you could give it the xinfo:product filter attribute and set the filter value to ACME 1050.

You can have single values or you can add multiple values, where Paligo will include the content if either of the values are a match.

Choose from any of the available values or use Add value to create more values if needed.

Note

We have included some more detailed examples of how you can use filter conditions to include and exclude content at the end of this section.

Repeat steps 2-4 inclusive to apply filters to as many elements as needed.

You have now set the profile attributes and values for the content you want to filter. We recommend that you preview the filters to see how they work before you publish.

Example 2. Use multiple filter values to create an OR filter

Let's say you have a paragraph that is only applicable for customers in North America and the EU. You want to include the paragraph when you are publishing to those markets, but want to exclude it when you are publishing to the Middle East, Australia, and other markets. This is where you need an OR filter, as you want the content to appear when the market is North America OR the EU.

To mark up the paragraph, you:

Select the para element.
Add the xinfo:market attribute
Set the attribute value. As the content applies to two markets, you have to set two values: North America and EU. Another option would be to create another filter that represents North America and the EU combined, but this could be cumbersome in this case.

When you publish the content, you can choose the filters for the publication.

If you set the publication's market filter to North America, EU, or both North America and EU, the filtered paragraph is included.
If you set the publication's market filter to another region, such as Australia, the filtered paragraph is excluded.
If you do not set a market filter for the publication, the filtered paragraph is included. It is only excluded from the publication if the market filter is applied and the value for the market filter does not match North America or EU.

Example 3. Exclude a filter value rather than include it

Paligo's filtering is inclusive, which means that when you set a filter, you are telling Paligo what content you want to be included in the output. But there may be times where you want to exclude certain content rather than include it. For these situations, set up filter values for:

The conditions where you want the content to be included
The conditions where you want the content to be excluded.

Then, when you publish, you can tell Paligo which content to include. By including one condition, you automatically exclude the other possible conditions.

Note

The "inclusive" filtering strategy may take a while to wrap your head around if you are new to filtering or if you come from another environment where you used filters for both including and excluding specifically. But once you get the idea, the inclusive strategy is very powerful in that it can accomplish exactly the same, but with a much cleaner structure, so you will have a more robust long-term solution.

Let's say you have three types of users: administrators, engineers, and operators. You have a paragraph that you want to be included for the engineers and operators, but excluded for the administrators. To set this up you:

Select the para element.
Add the audience attribute.

Select the value for the audience attribute and create these values: "administrators", "engineers", "operators".

Note that it is important to create values for where you want the content to be included and also for where you want it to be excluded.

Set the audience attribute value to "engineers" and "operators".

When you publish the content, you can choose the filters for the publication.

To publish for the administrator audience, you set the audience to "administrators".

The published output will then include:

Any content that has an audience filter with a value of "administrators". The paragraph that you marked up has an audience filter with a value of "engineers" and "operators", and so it is not included in the published output.
All content that does not have an audience filter

To publish for the engineers or operators, you set the publication's audience filter to "Engineers" and "Operators".

The published output will then include:

Any content that has an audience filter with a value of "Engineers" or "Operators". So the paragraph that you marked up is included in the published output.
All content that does not have an audience filter.

Preview Your Filters

When you mark up your content for filtering, you can use the preview feature to see the effects of the filters. This is a good way of making sure that the filters work as expected, and is especially useful if you have used a combination of filters.

To preview the filters:

Find the topic that contains the filters in the Content Manager, and open it in the editor.
Select Preview > Profile settings.

Select Profiling.

For each filter attribute, select the field and choose the filter you want to apply for the preview. If you do not want to apply a particular filter, leave its field blank.

Select Apply.

The filter is applied to the preview of the topic:
- Any content that is not marked up to use the types of filter you have applied is included in the content.
- Any content that is marked up to use the filters you have applied, with the same values you have set, is included in the content.
- Any content that is marked up to use the filters you have applied, but with different values, is excluded.
For example, if you set the preview to show the Market filter attribute with a value of Europe, the topic would show:
- Any content that is not marked up to use the Market filter attribute
- Any content that is marked up to use the Market filter attribute and a value of Europe
The preview would exclude any content that has the Market filter attribute and any other value, such as Asia, North America, Australasia, etc.
Repeat steps 4 and 5 to change the filters for the preview and see how they affect the content.

To stop applying the filter preview, display the Profile settings dialog select the Profiling tab, and then select Reset.

Apply Filters for Publishing

When you publish your content, you can choose which filters to apply to the published output (HTML5 help center, PDF, etc.).

In the Content Manager, find the topic or publication that you want to publish. Select its options menu ( ... ) and select Publish.
On the Publish document dialog, select an output type (PDF, HTML5, etc.), and set the Languages, Variables, and Optional Parameters.

These are common publishing settings. To find out more, see Publishing Process.

Select the Edit option in the Profiling attributes section. Paligo displays the Profiling attributes dialog.

The Profiling attributes dialog contains a list of the filter attributes that you can use. There is a field for each attribute.

Select the field for a filter attribute that you want to apply to your publication. A drop-down list of the available values appears. These are the values that have been created for the filter when the content was marked up for filtering.

Choose the value that you want to apply.

You would normally just choose one value for each filter attribute, the variant that you want to publish at the moment. This is usually the recommended strategy. It's possible to choose multiple values for a filter, however. The filter then works as an OR filter, where Paligo will filter topics that contain any of the values you set (value 1 or value 2 or value 3, etc.).

Tip

When you choose filters, you are telling Paligo which content to include in the published output. But sometimes, you may want to exclude content rather than include it. For example, you might want to publish content for all audience types except administrators. To do this, you need to mark up the content so that:

The content you want to include has a condition (filter attribute) and a value
The content you want to exclude has the same condition as those that you want to include. But set a different value for the topics you want to exclude.

When you publish, you choose which condition value to include. Paligo will then:

Include any content that has the matching condition and value
Include any content that does not use the matching condition
Exclude any content that uses the matching condition, but has a different value.

Repeat step 4 for each attribute and value that you want to apply and then select OK.

Note

Only set a value for those filter attributes that you want to apply to your publication. For any attributes that you do not want to use, leave their fields blank. When there is no attribute set, Paligo ignores that type of filter.
Select Publish document to publish your content.

Filter Topics in a Publication

You can filter topics so that they are included/excluded in your published output. For example, if you have a topic that is only relevant to Mac users, you could set an os (operating system) filter on the topic, with a filter value of macos. Then, when you publish, you can set Paligo to include the topic if you are publishing a Mac user guide or exclude it if you are publishing a Windows user guide.

In this section, we explain how to filter topics using the "regular" way of filtering. But you can also filter topics by using taxonomy filtering, where you apply the filter attributes and values by dragging and dropping taxonomy tags.

To find out about using the "regular" way of filtering topics, watch the video or read the following instructions:

To use the "regular" way:

Mark up the topics that you want to filter. Apply the filter attributes and values to the top section element in your topic.
Apply the filters you want to use for publishing your output.

For more details on marking up and applying the filters, see the following sections.

Mark Up Topics for Filtering

If you want to filter entire topics, you need to mark them up so that Paligo knows which topics can be filtered and what filter conditions apply. Marking up involves giving the top section element (1) of a topic a filter attribute (2) and a filter value (3).

Note

Marking up the content tells Paligo what content can be filtered. It does not apply the filter. You apply the filter in the publishing settings when you publish the content.

To mark up a topic for filtering:

Edit the topic that you want to filter, and then select the top section element in the Element Structure Menu. Select Go to element.

In the Element attributes section, select Add attribute and search for the filter attribute you want to use. Note that the Add attribute list includes all attributes, not just filters

There are many different types of profile attribute (filter) that you can use, including product name, country, and audience. To find out about the different profile attributes, see Filter Attributes.

Use the Profiling values dialog to set the filter value. Think of setting the value as a way of telling Paligo where the content is applicable.

For example, if you have a topic that is only applicable to a product named "ACME 1050", you could give it the xinfo:product filter attribute and set the filter value to ACME 1050.

Choose from any of the available values or use Add value to create more values if needed.

You can have single values or you can add multiple values, where Paligo will include the topic if either of the values are a match.

Note

We have included some more detailed examples of how you can use filter conditions to include and exclude content at the end of this section.

Repeat this process to markup any other topics you want to filter.

Example 4. Use multiple filter values to create an OR filter

Let's say you have a topic that is only applicable for customers in North America and the EU. You want to include the topic when you are publishing to those markets, but want to exclude it when you are publishing to the Middle East, Australia, and other markets. This is where you need an OR filter, as you want the content to appear when the market is North America or the EU.

To mark up the topic, you:

Select the top section element in the topic.
Add the xinfo:market attribute
Set the attribute value. As the content applies to two markets, you have to set two values: North America and EU. Another option would be to create another filter that represents North America and the EU combined, but this could be cumbersome in this case.

When you publish the content, you can choose the filters for the publication.

If you set the publication's market filter to North America, EU, or both North America and EU, the filtered topic is included.
If you set the publication's market filter to another region, such as Australia, the filtered topic is excluded.
If you do not set a market filter for the publication, the filtered topic is included. It is only excluded from the publication if the market filter is applied and the value for the market filter does not match North America or EU.

Example 5. Exclude a filter value rather than include it

Paligo's filtering is inclusive, which means that when you set a filter, you are telling Paligo what content you want to be included in the output. But there may be times where you want to exclude certain content rather than include it. For these situations, set up filter values for:

The conditions where you want the topic to be included
The conditions where you want the topic to be excluded.

Then, when you publish, you can tell Paligo which content to include. By including one condition, you automatically exclude the other possible conditions.

Let's say you have three types of users: administrators, engineers, and operators. You have a topic that you want to be included for the engineers and operators, but excluded for the administrators. To set this up you:

Select the top section element in the topic.
Add the audience attribute.

Select the value for the audience attribute and create these values: "administrators", "engineers", "operators".

Note that it is important to create values for where you want the topic to be included and also for where you want it to be excluded.

Set the audience attribute value to "engineers" and "operators".

When you publish the content, you can choose the filters for the publication.

To publish for the administrator audience, you set the audience to "administrators".

The published output will then include:

Any topics that have an audience filter with a value of "administrators". The topic that you marked up has an audience filter with a value of "engineers" and "operators", and so it is not included in the published output.
All topics that do not have an audience filter

To publish for the engineers or operators, you set the publication's audience filter to "Engineers" and "Operators".

The published output will then include:

Any topics that have an audience filter with a value of "Engineers" or "Operators". So the topic that you marked up is included in the published output.
All topics that do not have an audience filter.

Apply Filters for Publishing

When you publish your content, you can choose which filters to apply to the published output (HTML5 help center, PDF, etc.).

In the Content Manager, find the topic or publication that you want to publish. Select its options menu ( ... ) and select Publish.
On the Publish document dialog, select an output type (PDF, HTML5, etc.), and set the Languages, Variables, and Optional Parameters.

These are common publishing settings. To find out more, see Publishing Process.

Select the Edit option in the Profiling attributes section. Paligo displays the Profiling attributes dialog.

The Profiling attributes dialog contains a list of the filter attributes that you can use. There is a field for each attribute.

Select the field for a filter attribute that you want to apply to your publication. A drop-down list of the available values appears. These are the values that have been created for the filter when the content was marked up for filtering.

Choose the value that you want to apply.

You would normally just choose one value for each filter attribute, the variant that you want to publish at the moment. This is usually the recommended strategy. It's possible to choose multiple values for a filter, however. The filter then works as an OR filter, where Paligo will filter topics that contain any of the values you set (value 1 or value 2 or value 3, etc.).

Tip

When you choose filters, you are telling Paligo which content to include in the published output. But sometimes, you may want to exclude content rather than include it. For example, you might want to publish content for all audience types except administrators. To do this, you need to mark up the content so that:

The content you want to include has a condition (filter attribute) and a value
The content you want to exclude has the same condition as those that you want to include. But set a different value for the topics you want to exclude.

When you publish, you choose which condition value to include. Paligo will then:

Include any content that has the matching condition and value
Include any content that does not use the matching condition
Exclude any content that uses the matching condition, but has a different value.

Repeat step 4 for each attribute and value that you want to apply and then select OK.

Note

Only set a value for those filter attributes that you want to apply to your publication. For any attributes that you do not want to use, leave their fields blank. When there is no attribute set, Paligo ignores that type of filter.
Select Publish document to publish your content.

Taxonomy Filters

You can use taxonomy filters to control whether a topic is included in a publication. For example, you could use them on a topic so that it is included when you publish a Mac version of a user guide, but excluded when you publish a Windows version.

Some Paligo users prefer to use taxonomy filters instead of the "regular" filters, see Filter Topics in a Publication, as they are quick and easy to use. All you need to do is create your taxonomy tags, drag and drop them onto your topics and choose which tags to include when you publish. Taxonomy filters can be used in combination with Scoped Filtering.

Another benefit of taxonomy tags is that you can use them to create more complex filters, similar to Scoped Filtering. For this, you organize the tags into a hierarchy. You can then set Paligo to include all of the tags in a branch of the hierarchy, rather than one specific taxonomy tag.

For example, let's say you have set up the following taxonomy tag hierarchy:

1 is the tag that represents the type of filter you want to use, in this case, the filter is called "Market". This is known as the filter attribute.

2 are all tags for individual filter values. Note that the value tags can be organized into a hierarchy too. Here we have a value tag for the overall market, "USA", and then at a lower level, value tags for the different sub-markets. In this case, the sub-markets are states of the USA.

You can then set Paligo to use the hierarchy in different ways. For example, you can set Paligo to only include those topics that have the "Arizona" tag. Or you could set Paligo to include topics that have the "USA" tag and/or the "Arizona" tag.

To find out about using taxonomy filters, watch the video or read the following instructions.

Note

You only need to Add Filter Values for Taxonomy Tags and Create Tags for Taxonomy Filtering when you first set up taxonomy filtering or when you want to add a new filter or filter value.

Add Filter Values for Taxonomy Tags

Before you create taxonomy tags for filtering, you should add the filter values you need. Then, when you create your taxonomy filter tags, you can give them the same names as the filter tags. This is how Paligo recognizes the relationship between a taxonomy tag and a filter value - they have to have the same name.

Note

If your Paligo instance already contains the filter attributes and values that you need to use, ignore this procedure. Your next step is to Create Tags for Taxonomy Filtering.

Select the Publish option for any publication or topic, and then edit the Profiling attributes.

When you select Edit, Paligo displays the Profiling attributes dialog, which contains a list of the filter attributes that are available. The filter attributes define the types of filter, for example, there is a Market attribute for filtering by different regions.

Select the field for each profiling attribute to see what values are available.

If you need to add values, create a new topic and select an element in it, such as a para element. Then use the Element attributes section to add a new filter attribute, for example, xinfo:product. Paligo displays the Profiling values dialog and you can use that to add new values for the element.

Repeat this step for each filter attribute and value that you need for your publication.

When Paligo has all of the filter values that you need, you can Create Tags for Taxonomy Filtering.

Create Tags for Taxonomy Filtering

When you have added the filter values you need to Paligo, you can create the taxonomy tags that you will use to mark your content for filtering.

Note

For this section, we assume that you already know how to create taxonomy tags. If you need to find out more, see Create Taxonomies.

You should create a taxonomy tag to represent:

Each filter attribute that you want to use. The filter attributes define the type of filter, for example, PRODUCT.
Each filter value that you want to use. The filter values define the condition, for example, ACME 1050 could be a condition for a PRODUCT filter.

The filter value tags have to be at a lower-level than the filter attribute tags in the taxonomy hierarchy.

The taxonomy tags you create need to have the same names as the filters and filter values that they represent. For example, if you have a topic that is only relevant to an "ACME 1050" product, you could use an xinfo:product filter. For this, you would create a tag called "product" and then add a lower-level tag for "ACME 1050". (When setting the taxonomy tag names, do not include the xinfo prefix).

Note that the taxonomy tags for filter attributes should be named to match the filter attribute name

To set up taxonomy tags for filtering:

Select the Taxonomy Manager in the Content Manager to open the structure.

Create taxonomy tags for the filter attributes and the filter values that you need.

For filter attribute tags, the tag name has to match the attribute name (but do not include any xinfo prefix). For example, if you want a taxonomy filter for the xinfo:market filter attribute, create a tag named: market.

To find out more about the attributes you can use, see Filter Attributes.

For filter value tags, set the name to match the value. For example, if you have a market filter with a value of "USA", the taxonomy tag for this should also be named "USA".

Drag and drop the taxonomy tags into a logical hierarchy. The hierarchy has to be organized so that:

The filter attribute tags are at the highest level (below the taxonomies tag, but above all other tags)
The value tags are at a lower level than the filter attribute that they relate to.

The filter attribute tags must be the "parent" and the value tags must be "children" in the hierarchy.

In the image "Market" (1) is the filter attribute tag. All of the other tags are filter value tags (2). Note that you can have many levels of filter value tags, so that you can have greater control when filtering.

Tip

When you have set up the taxonomy tags, you can Apply Taxonomy Tags to Topics.

Apply Taxonomy Tags to Topics

When you have the appropriate tags and hierarchy in place, you can apply the taxonomy filter tags to your topics.

In the Content Manager, select the dotted menu ( ... ) for the Taxonomies tag, and then select Floating content panel.
In the floating content panel, find the tag that you want to apply to a topic. Drag the tag onto the topic in the Content Manager. Repeat this step for each topic that you want to filter.

When you have applied the taxonomy tags to your topics, the next step is to choose how Paligo uses the taxonomy hierarchy when it applies the filters.

Set Taxonomy Filter Strategy

For taxonomy filters, Paligo gives you the option to choose a filter strategy. The strategy affects how Paligo matches the filters and determines what topics should be included or excluded from your publication.

To choose the taxonomy filter strategy:

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 configuration 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 need to frequently switch between your Paligo content and the layout settings.

Select Classes and attributes.

Note

For PDF layouts, they are in the General > Filtering and Taxonomies settings.

Select Enable for Output taxonomies.

This setting has to be enabled for taxonomy filtering to work.

Select Exact Value or Descendants for Taxonomy filtering strategy.

This setting is labelled as Taxonomy filtering on some layouts.

Exact value

If you choose Exact value, Paligo will ignore the taxonomy hierarchy. When you publish and choose what filters to apply, Paligo will only include topics that:
- Have a taxonomy tag that matches the filter attribute and filter value that you set for the publication.
- Are not marked up to use the filter attribute that you set for the publication.
Descendants

If you choose Descendants, Paligo will use the taxonomy hierarchy to determine which topics should be included or excluded.

When you publish and choose what filters to apply, Paligo will only include:
- Topics that have a taxonomy tag that matches the filter attribute and filter value. We will call this tag the "descendant" tag.
- Topics that have a tag that is a "parent" of the "descendant" tag in the taxonomy hierarchy. Note that Paligo includes not only the immediate "parent" tag, but also the "parent" of that tag and so on, until the top-level is reached.
- Topics that are not marked up to use the filter attribute that you set for the publication.

Note

There is also a Disabled option, which turns off the taxonomy filter feature.

Select Save.

When you have set a taxonomy strategy, you can publish your content and set the filters that you want it to use.

Taxonomy Strategi Example

This example gives a detailed look at how the exact value and descendant value taxonomy strategies affect the results of a filter.

Example 6. Taxonomy strategy

Let's say you have the following hierarchy for a Product filter, and you filter the publication to include Product: ACME 1050. This is how the filtering strategies will work:

Exact value filter strategy applied

Descendants filter strategy applied

The first image shows how the Exact value filter strategy works.

Paligo will ignore the structure of the taxonomy hierarchy. This means that the published output will include:

Topics that have the "ACME 1050" tag. Note that it has to be a "child" of the "Product" tag.
Topics that do not have any "Product" taxonomy tag

Paligo will exclude any topics that have a "Product" tag but with a different value to "ACME 1050".

The second image shows how the Descendants filter strategy works. Paligo uses the taxonomy hierarchy and includes topics that have the matching tag ("ACME 1050") or are "parents" of the matching tag. This means that the published output will contain:

Topics that have the "ACME 1050" tag. Note that it has to be a "child" of the "Product" tag.
Topics that have the "ACME 1000" tag or "ACME" tag, as these are "parent" tags of the "ACME 1050" tag in the taxonomy hierarchy.
Topics that do not have any "Product" taxonomy tag

Paligo will exclude any topics that have a "Product" tag but with a different value to "ACME 1050".

Apply Filters for Publishing

When you publish your content, you can choose which filters to apply to the published output (HTML5 help center, PDF, etc.).

In the Content Manager, find the topic or publication that you want to publish. Select its options menu ( ... ) and select Publish.
On the Publish document dialog, select an output type (PDF, HTML5, etc.), and set the Languages, Variables, and Optional Parameters.

These are common publishing settings. To find out more, see Publishing Process.

Select the Edit option in the Profiling attributes section. Paligo displays the Profiling attributes dialog.

The Profiling attributes dialog contains a list of the filter attributes that you can use. There is a field for each attribute.

Select the field for a filter attribute that you want to apply to your publication. A drop-down list of the available values appears. These are the values that have been created for the filter when the content was marked up for filtering.

Choose the value that you want to apply.

You would normally just choose one value for each filter attribute, the variant that you want to publish at the moment. This is usually the recommended strategy. It's possible to choose multiple values for a filter, however. The filter then works as an OR filter, where Paligo will filter topics that contain any of the values you set (value 1 or value 2 or value 3, etc.).

Tip

When you choose filters, you are telling Paligo which content to include in the published output. But sometimes, you may want to exclude content rather than include it. For example, you might want to publish content for all audience types except administrators. To do this, you need to mark up the content so that:

The content you want to include has a condition (filter attribute) and a value
The content you want to exclude has the same condition as those that you want to include. But set a different value for the topics you want to exclude.

When you publish, you choose which condition value to include. Paligo will then:

Include any content that has the matching condition and value
Include any content that does not use the matching condition
Exclude any content that uses the matching condition, but has a different value.

Repeat step 4 for each attribute and value that you want to apply and then select OK.

Note

Only set a value for those filter attributes that you want to apply to your publication. For any attributes that you do not want to use, leave their fields blank. When there is no attribute set, Paligo ignores that type of filter.
Select Publish document to publish your content.

Variables

Variables allow you to swap out small parts of content for different publications. They are very useful when you have topics that you want to reuse, but need to have parts of the text changed, such as product names.

For example, let's say you have a topic and you insert the product name "Acme 100" as plain text. By adding it as plain text, you have limited where the topic can be reused, as it is specific to the "Acme 100" and so cannot be used for other products. But if you use a variable to set the product name, you can reuse the topic and tell Paligo which product name to use each time you publish.

Variable Types

In Paligo, there are several types of variable that you can use:

Text: for plain text that does not need to be translated, such as product names, number values, etc.
Text (translatable): this variable type will let you enter translations of each variable value (for the languages you have selected). If you use this type of variable, remember that different languages can have very different grammars. Translated variables can read badly if the grammar, gender, etc., of each language has not been considered.
Image: these variables allow you to swap out images. They are useful when you have topics that contain images that need to be changed for different variants or publications. It is often more convenient to have a variable for the image, rather than many images with filtering.
XML: these variables are similar to plain text variables, but allow you to add XML tags too, so you can include inline tags if needed.
Dynamic text variables: These are a special type of variable, and you can use them for inserting things like today's date or for inserting the content from an element that is elsewhere in the publication. They are different to other variable types as you do not create them in variable sets. Read more about them in Dynamic Text Variables.

Variables Workflow

To use variables in your topics and publications, follow this process:

Create a variable set. This is a collection of variables and the possible values that they can contain.
- In the variable set, add variables for each type of information that needs to change in different scenarios.
- Create variants for the variables. A variant is a collection of values that will be inserted into the variables when you publish. For example, if you have a product name variable, you could have a variant where the product name is "ACME 100X" and you could have another variant where the product name is "ACME 200X". Think of each variant as the values that will be used in one particular scenario.
You can skip this step if you already have suitable variable sets available in Paligo.
Insert variables into your topics where appropriate.
Preview the variables to check that they are providing the correct information.
Publish your content and choose the variants that Paligo should use.

Note

The process is different for Dynamic Text Variables.

Superscript Text in Variables

You can use variables for many different types of changeable content, but one of the most popular uses is for product names and company names. With these, you may want to add superscript text to the variable, for example, to add a trademark ^TM after the product name.

To add superscript text to a variable:

Create or edit a variable set (see Create a Variable Set).
In the variable set, create an XML variable and give it a name, for example, ProductNameTM.
Set the value for the XML variable. The value is called a variant. As this is an XML variable, include the inline <superscript> element. For example:
```
ACME<superscript>TM</superscript> 1000
```
Insert the variable in your topics as needed.

Use XML Variables for Links

Using XML variables is the only way to have links that change depending on publish settings. Unlike text variables, they allow you to use full XML strings. A link's destination is determined by the URL in the underlying XML, so you can use XML variables to change the link dynamically.

With XML variables, your link label can have the same name, but the destination can change depending on your publishing settings. You can use a different label altogether or disable linking completely in some versions of your documentation. XML variables give you more flexibility than other types of variables.

As an example, if there is a product that has two versions for different markets (one for the US market and one for the European market), the link label can be the same but the link destination can point to different distribution websites. You can also change the link label to something like "US Store" for the US version of the documentation, and "Europe Store" for the European version, with different link destinations for each.

This instruction shows how to use different web pages depending on market.

Select the Dotted Menu (...) for the Variable sets in Content Manager.
Select Create variable set from the menu.
Enter a name for the variable set and select the check mark.
Expand the Variable sets with the arrow to the left.
Select the new variable set.
Select Add variable for each variable that is to be inserted in a topic.
Name it and select XML to make it a link variable.
Select Add variant for each variant to publish to.
Copy the XML code below:
```
<link xlink:href="ZZZ">XXX</link>
```
Replace ZZZ with the URL.
Replace XXX with the visible link label.

In the example, we used "Car window" and "Electric motor" as the visible link names. Scroll down to see the result.

Note

To show the URL instead, remove the XXX.
Open a topic and insert the created XML link variables.
Select Preview in the toolbar to be able to evaluate the result.
Select Profile settings.
Select the Variables tab.
Select the variable set and XML link variable to be used.
Select Apply.

Chosen XML link variable will be shown in the topic.
Publish the topic to see the visible link name.

Variable Sets

With variables you can alter small pieces of content (text, images, values, links) that you want to change for different scenarios. This makes it possible to reuse more content. The variables are defined in a Variable Set, which is a collection of variables and their possible values.

When you publish with a variable set containing variants, you can choose which variant to be used. The variables (like height, product name, variant image, weight and width) fetch the values from the column that represents the chosen variant.

The left column contains the variables, which are the placeholders that you add to your topics. In this column, you enter the variable names.
The second, third and fourth columns contain variants. Each variant column represents a different scenario and contains the terms or values that will be used for the variables, for example different weights.

Tip

Once the Variable Set is created, you can use the variables in your topics, see Use Variables.

Create a Variable Set

To create a variable set, watch the following video or read the instructions below.

Scroll down to Variable sets in Content Manager.

Select the Dotted Menu (...) for Variable Sets.

Select Create variable set.
Name the variable set.

Select the new variable set to open it in the Variable Editor.

Paligo displays it in the Variables Editor.

Select Add Variable .

Select the Variable type to create.

Text: for plain text that does not need to be translated, such as product names, number values.
Text (translatable): this variable type will let you enter translations of each variable value (for the languages you have selected). If you use this type of variable, remember that different languages can have very different grammars. Translated variables can read badly if the grammar, gender of each language has not been considered.
Image: these variables allow you to swap out images. They are useful when you have topics that contain images that need to be changed for different variants or publications. It is often more convenient to have a variable for the image, rather than many images with filtering.
XML: these variables are similar to plain text variables, but allow you to add XML tags too, so you can include inline tags if needed.

Tip

If you create a text variable and later realize that you need it to be a translatable variable, you can convert it by using the Convert Variable Type option. Similarly, you can convert a translatable variable into a text variable.

Repeat step 4 to create as many new variable types as needed for this variable set.
Select Add variant and enter a name.

The variant is going to be one set of values that can be used for the variables. You might want different values for depending on the product model you are publishing for, so add product models as the variant columns.

Enter values for each variable.

These values will only be used if this particular variant is selected when publishing.

Repeat steps 9 and 10 to create as many variants and variant values as needed.

Convert Variables

You can convert an existing text variable into a translatable variable or vice versa by using the Convert Variable Type option. Paligo automatically detects the type of variable you have selected and will convert it into the other type.

Tip

If you have made a mistake, you can always do another conversion to change the variable back to its previous type.

To convert a variable:

Scroll down to Variable sets in Content Manager.

Select the arrow in front of the Variable sets to expand it.

Paligo content manager side panel. It has sections for Documents, Media, Templates, and Variable sets. The Variable sets section is expanded to reveal two variable sets in a list.

Select the variable set that contains the variables you want to convert.

Paligo displays it in the Variables Editor.

Select the Dotted Menu (...) for the variable you want to convert.

Select Convert Variable Type.

Select Confirm to convert the variable.

Copy a Variable Set

You can copy an existing variable set to use as a starting point for a new set. This is sometimes quicker than creating a new variable set from scratch.

Note

For performance reasons, we recommend that your variable sets have less than 2,000 entries. For example 100 variables x 20 variants = 2,000. In most cases it's better to divide your variables into a number of smaller sets in different categories.

Scroll down to Variable sets in Content Manager.

Select the arrow in front of the Variable sets to expand it.

Select the Dotted Menu (...) for the variable set you want to copy.

Select Copy.

Paligo makes a copy of the variable set and adds it to the list of variable sets. It has the same name as the original version, but is appended with a number.

Delete a Variable Set

A variable set cannot be deleted unless all the variables from the variable sets are removed from the instances where they are used. To see where a variable is used, see Display Usage Information.

Scroll down to Variable sets in Content Manager.

Select the arrow in front of the Variable sets to expand it.

Select the Dotted Menu (...) for the variable set you want to delete.

Select Delete.

Display Usage Information

Scroll down to Variable sets in Content Manager.

Select the arrow in front of the Variable sets to expand it.

Select the variable set that contains the variables you want to display.

Paligo displays it in the Variables Editor.

Select the Dotted Menu (...) for the variable you want to display the usage information for.

Select Usage information.

Paligo shows the usage information for the chosen variable.

Move Variables between Variable Sets

If you need to reorganize your variables, you can move them from one variable set to another.

Scroll down to Variable sets in Content Manager.

Select the arrow in front of the Variable sets to expand it.

Select the variable set that contains the variable you want to move.

Paligo displays it in the Variables Editor.

Select the Dotted Menu (...) for the variable you want to move.

Select Move variable.

Choose the Variable set that will receive the variable.

Select OK.

Paligo moves the variable to chosen variable set.

Remove Variables

A variable cannot be deleted unless it has been removed from the instances where it is used. To see where a variable is used, see Display Usage Information.

Scroll down to Variable sets in Content Manager.

Select the arrow in front of the Variable sets to expand it.

Select the variable set that contains the variables you want to remove.

Paligo displays it in the Variables Editor.

Select the Dotted Menu (...) for the variable you want to remove.

Select Remove Variable.

Use Variables

A variable is a piece of content that can have many different values, and when you publish, you choose which value Paligo should use. For example, you can have a product name variable and when you publish, you choose which product name should be used in the published content.

To use variables in your topics, you first need to create a variable set. In the variable set, you define what variables you need, and the different possible values that they can have. Each set of possible values is called a variant.

To find out how to insert variables in a topic, watch this video or read the sections that follow:

Insert a Variable

To insert a variable in your content:

Open the topic you want to add a variable to.

Place the cursor in a valid position for a variable.

Place the cursor in a valid position for a variable. You can insert variables into most types of text block, including para elements.

Select Insert > Variable in the toolbar.

A dialog opens, showing all of the variable sets you have available.

Select the variable set that contains the variable you want to use. Alternatively, use the Search field to find the variable.

Select the variable you want. In this case, we have selected "Product Name".

The variable is inserted at the cursor position.

After adding a variable, you can use the Preview feature to choose different variants. These allow you to see what value Paligo will use for the variable for each different variant.

When you are ready to publish your content, you can choose which variant Paligo should use for the published output.

Preview Variables in a Topic

You can use Preview to see what values Paligo can use for your variables. This is useful for checking that the value you need is actually included in a variable set. If the value is not there, you will need to edit the variable set or create a new one.

To preview variables:

Select Preview.
Select Profile settings.

On the Variables tab, select the variant that you want to preview in the topic. The variant is a collection of values, as defined in a variable set.

Paligo updates the topic so that it shows the values that will be used with the variant you have selected.

Choose Variable Sets for Publishing

When you publish your content, you can choose which values (variants) should be used for the variables in your content.

In the Content Manager, select the options menu ( ... ) for the topic or publication you want to publish, and then select Publish.
On the publish dialog, choose the type of output you want Paligo to create, and set the Languages and Profiling Attributes.

Select the Edit option for Variables.

Paligo displays a list of all of the variable sets that are available.

For each variable set that is used in your topic or publication, select a variant. The variant's values will be inserted into the relevant variables in your content. Select OK to confirm.

Select Publish document to publish your content.

Dynamic Text Variables

Dynamic text variables are pieces of content that take their value from either the client session or from other elements in your content. They are resolved when you publish and you can use them to insert content such as:

Current date and time, which is taken from your client session and so is accurate for your local time zone.

To learn how to add these variables, see Dynamic Text Variables for Time and Date.
The content of any element in your publication. This can be elements in the publication or elements in your topics. For example, you could have dynamic text variables for the author, edition or releaseinfo elements.

To learn how to add these variables, see Dynamic Text Variables for Elements and Attributes.

Note

If you publish to PDF in multiple languages, there is an option to Combine selected languages in the PDF layout. You can only use dynamic text variables if Combine selected language is disabled (unchecked).

Dynamic text variables are only supported when publishing individual PDFs.

Dynamic Text Variables for Elements and Attributes

You can use dynamic text variables to insert the value of an element or an attribute from your content into a topic. For example, you could add the value of the edition element from a publication into the text in a topic.

To reference elements and attributes, you will need:

A basic understanding of XPath 1.0. XPath is required for navigating the elements in the XML output.
Access to the XML file that contains all of your content (see Plan your References with the Debug XML File). You can use this file to plan your XPath references. Once you know which elements and attributes are needed, you can insert the appropriate references in your dynamic text variables.
To insert dynamic text variables in your topics, and add the references using the appropriate syntax.

To learn about XPath 1.0, see https://www.w3schools.com/xml/xpath_intro.asp.

Dynamic Text Variables for Time and Date

To add automatically generated time and date information to your content, use dynamic text variables. The time and date are inserted during the publishing process and they are taken from your browser's client session, so the time is accurate for your location.

To insert a dynamic text variable for time and/or date:

Add a phrase element and give it a role attribute with the value:

dyntextvar

For more details, see Insert a Dynamic Text Variable.

In the phrase element, enter the syntax for the time or date format. Use the Java simple date format.

There are many different ways of displaying the time and date and we have included some examples below.

Syntax	Returns
${date:date-time()}$	The current date, time, and timezone information.
${date:format-usertime('h:m')}$	The current hour and minutes.
${date:format-usertime('EEE, MMM d, yyyy')}$	The current day, month, and year.

To find out more about the syntax for time and date variables, see: SimpleDateFormat (Java 2 Platform SE 5.0).

Note

Use the date:format-usertime function for greater control over the format of the date and time in the output. Set the arguments for the function in brackets, where string arguments must be enclosed in single quotes (as shown in the table).

Insert a Dynamic Text Variable

When you know what elements and attributes you want to use for your dynamic text variables, you can start adding them to your topics.

To insert a dynamic text variable:

Find the topic that is going to contain the dynamic text variable and open it in the editor.
Position the cursor at a valid position for the dynamic text variable. This can be any position where a phrase element is valid can be added, for example, inside a para element.
Use the element context menu to add a phrase element.

To access the element context menu, press Alt and Enter (Windows) or Option ⌥ and Enter (Mac).

Select the phrase element and then in the Element attributes panel, add the role attribute. Set its value to:

dyntextvar

This will add the minimum required syntax for the dynamic variable:

<phrase role="dyntextvar">${}$</phrase>

When you have added the dynamic text variable, enter the relevant XPath expression to access the element or attribute you want to use.

Note

If you use an expression to access an element or attribute that does not exist, the dynamic text variable will be empty (blank) in the output.

When you are writing XPath expressions, there are several things you need to be aware of:

Include the "d:" prefix for navigating the XML, for example:

${/*[1]/d:info/d:title}$

The namespace prefix d is bound to http://docbook.org/ns/docbook
There are DocBook attributes that do not require a prefix and there are also some custom Paligo attributes, known as extension attributes. To access the extension attributes, use the @xinfo prefix, for example:

${@xinfo:time-modified}$

The namespace prefix xinfo is bound to http://ns.expertinfo.se/cms/xmlns/1.0.
For PDF outputs, the top-level node that you can access is article. You cannot access the article's parent node (part).

Plan your References with the Debug XML File

Paligo can provide you with a single XML file that contains all of the content in a publication (the publication itself and all of the topics). You can use this XML file to get a better understanding of the structure of your content, so that you plan the XPath expressions for your dynamic text variables. Use XPath 1.0 expressions to access the elements and attributes in your content.

To find out how to get the XML file, watch the video or read the following instructions:

In the Content Manager, find your publication, select its option ( ... ) button, and then select Publish.

On the Publish document dialog, choose the type of output you want, set the Languages, Profiling Attributes, and regular Variables, and then select the Make debug build option.

The Make debug build option tells Paligo to include the build files in the output as well as the actual output. One of the build files is an XML file that contains your content.

Publish document settings. Make debug build is enabled.

Select Publish document to publish your content.

When it downloads, unzip it and look for the XML file that contains your content.

For PDF outputs, the XML file has the same name as the publication and has a language suffix. For example, "Acme_100_user_guide-en.xml".

For HTML, HTML5, XML, Word, and SCORM outputs, the XML file is named index and has a language suffix, for example, index-en.xml.
Open the XML file from step 3 and use it to plan your XPath 1.0 expressions. When you have planned the expressions, you can insert dynamic text variables into your content and add the relevant expressions.