Getting Started with Paligo

Scoped Filtering

Scoped filtering is a very powerful feature in Paligo that allows you even more flexibility when it comes to profiling/filtering content.

Note

This is an advanced topic, make sure you understand the basic profiling/filtering concepts first.

Regular filtering will work well for most situations where you need to reuse topics but still create variants of those topics.

However, what if you wanted to reuse the same topic two or more times in the same publication, but each time with different filtering? Since you can normally only select one value when publishing, that wouldn't work.

To make this a bit clearer, here's an example use case:

Let's say you are documenting a product, in our example the fictional video conference software ACME VCT.

The software supports Mac and Windows, but most of the documentation is the same, so you don't want to produce two separately filtered outputs.

This is where scoped filtering comes in. You need to be able to mark up parts of the documentation as pertaining to the version for Mac, another for Windows, etc.

  1. A topic at a high level for the Windows section ("Installing on Windows") is filtered for Windows (attribute os = "windows")

    You would set this filter at the root element in the "Installing on Windows" topic:

  2. In the section about the MacOS-specific instructions, do the same for the top-level topic, but now filtered instead for MacOS (attribute os = "macos")

  3. "System Requirements" is a reused topic in both these sections. But it has filters inside it for whatever is specific for each operating system:

Now when you publish, for a profiling filter that you use with scopes like this, you would set both values (instead of the normal way of just choosing one when you want separate outputs):

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