Filtering / Profiling
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.
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
osfilter attribute in the publication, Paligo will find all of the elements that are marked up to have anosfilter 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.
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:
-
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.
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 |
|
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. NotePaligo does not support using |
|
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 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:
-
Use the same content in multiple places in the same publication
and
-
Apply different filters to that content, depending on where it appears in the publication.
Note
Scoped filtering is an advanced topic. Make sure you understand the basic profiling/filtering concepts before using scoped filtering.
To show you how scoped filtering can be used, we'll guide you through an example.
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.
 |
In the image above:
-
This is for content that is only relevant to MacOS. You apply an
osfilter to this content and set the filter value tomacos. -
This is content that is only relevant to Windows. You apply an
osfilter to this content and set the filter value towindows.
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.
 |
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
osfilter with the value:windows.With this "scope filter" you are telling Paligo that if any "child" topics in this chapter contain
osfilters, 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
sectionelement of the "Installing on MacOS" topic. The scope filter is theosfilter with the value:macos.
This "scope filter" tells Paligo that if any "child" topics in this chapter contain
osfilters, 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 |
||
|---|---|---|---|
|
|
From the example, you can see that 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.
When you have read the example and understand the principles of scoped filtering, you can apply it to your own content. The workflow you should follow is:
-
Make sure scoped filtering is enabled. It is enabled by default, but it may have been disabled on your Paligo instance.
Select Layout and then edit the layout that you are going to use. Make sure the Enable scoped profiling/filtering option is set to Enabled or Default. You can find the option in the Classes and Attributes settings on HTML layouts and in the General > Filtering and taxonomies settings for PDF.
-
Organize your publication structure so that you have "parent" topics (high level) and "child" topics (lower level).
-
Apply filters to your "child" topic elements.
-
Apply the "scope filters" on "parent" topic elements. Typically, you should set the scope filters on the
sectionelement. -
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.
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.
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 Layout and edit the layout you are going to use for publishing.
-
Enable the Use xml:lang as profiling attribute setting. This is in the Classes and Attributes settings for HTML layouts and in the General > Filtering and Taxonomies section for PDF layouts.
-
In your content, select an element that you want to filter by language.
-
Use the Element attributes section to add the
xml:langfilter attribute and set its value to the appropriate language. For the language values, use the two letter language codes, for example, en for English, 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:langfiltered content, that content is included in the output.If you publish to a language that does not match the value of the
xml:langfiltered content, that content is excluded from the output. -
Set any variables and other profiles as required, and then publish.
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
phraseelement.Paligo inserts your selected content into the
phraseelement. -
Click in your selected content so that the
phraseelement 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
phraseelement.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.