Is it a good practice to associate the ditaval filter file directly in the DITA Map?

[raducoravu]

Let's say I always publish a certain DITA Map only with a ditaval filter file applied. Instead of always specifying the ditaval filter file as a parameter at publishing time, do you consider it a good practice to refer to it using branch filtering in the published DITA Map?

Because I've started to see this "best practice" where some companies pair up the map and the filter by specifying the filter directly in the map. And I'm not sure if it should be considered a best practice, I would probably avoid doing this and use a DITA OT project file instead.

[raducoravu]

Taking into account there are about 13 branch filtering related issues opened in the DITA OT I would not use branch filtering if I can avoid it (in this case by specifying the filter file as a parameter when publishing):
https://github.com/dita-ot/dita-ot/issues?q=is%3Aissue+is%3Aopen+ditavalref

But should in general a ditavalref applied on the main dita map produce about the same output as it does when the filter is applied as a parameter from the command line?

[ekimbernow]

Thinking this through just now in the context of the ServiceNow content, which involves 100s of root maps, all of which use the same top-level base DITAVAL to filter out content tagged for future features, I think I agree with Radu that referencing a DITAVAL from the root map is not good practice.

While it would, in our case, ensure that all builds applied to our root maps filtered out future stuff unless overridden by a second higher-priority DITAVAL applied at run time, it would create a problem if the DITAVAL file name or location changed in that we'd have to update all the root maps (of which we have 100s) to update the DITAVAL reference.

In the face of that I would prefer referencing the DITAVAL from our build definitions.

Thus, I think I agree with Radu that referencing a DITAVAL from the root map is not good practice and that using project files would be the best solution generally, especially when the number of maps you're managing is larger than say five.

[chrispy-snps]

I think "branch-filtering" a map root is reasonable if both of the following are true:

• DITA-OT project files cannot be used for some technical reason.
• The map reuses profiled content (variables, submaps, within-topic content, etc.).

To me, it is a more primitive form of the filtering aspect of DITA-OT project files, and it guards against filtering forgetfulness on the command line.

However, I strongly prefer global filtering through DITA-OT project files for the following reasons:

• Global filtering requires a bit less preprocessing overhead than branch filtering.
• DITA-OT project files can combine multiple DITAVAL files.
  • This allows for modular files for orthogonal conditions (@product, @audience, @rev, attribute groups within an attribute, etc.).

Regarding branch filtering in lower-level map branches, I think there will always be a need for this. For example, we have a large online help collection that instantiates two versions of the same bookmap, filtered by two @product values respectively. There is no way to drive such finer-grained filtering from a DITA-OT project file.

Interesting side note on the "instantiating bookmaps in a larger online help map - when doing this, each book is published twice using two different filtering mechanism:

• For individual book PDFs, the DITAVAL conditions in the DITA-OT project files are used.
• For the full help collection, branch filtering in the online help map are applied to the bookmap submap instances.

For consistency, these two profiling conditions should align. In our flow, the online help .ditamap files are the golden file, and the DITA-OT project file deliverables are derived from them via an XSLT refactoring operation. We have heuristics to control this, such as inferring output PDF file names from bookmap keyscopes, and directives to indicate maps for which no PDF deliverables should be inferred.

[raducoravu]

Another case in which ditavalref was used as a convenient way to group the map and the ditaval file and then profiling inside conreffed content (not referenced in the DITA Map) does not properly work:
https://www.oxygenxml.com/forum/post72556.html