Older documents may need different entities etc.

Situation in doc-sle:

• There are book name entities
• The Security Guide and the Hardening Guide were merged into the Security and Hardening Guide a few SPs back
• The &secguide; entity now expands to "Security and Hardening Guide", making it incompatible with older documents.
• You're supposed to be able to run doc-kit from any branch, old or new.

What end to attack this situation from is not 100% clear to me and it's also not clear if it really is a bug, and if it is, whether it is a bug of the template or the tool or ...:

• You could just leave the &secguide; entity in place and create an additional &sec_har_guide; entity and that might solve the issue. (Disadvantages: Maybe just the fact that it leads to an ever-expanding entity list. Not sure if there are more.)
• You could introduce a policy of never updating doc-kit template files within older branches. (Disadvantages: If there are legitimate changes that need to be part of older documents, you have to perform those manually; policies have a way of not being propagated to everyone, so someone will eventually try to perform a doc-kit update anyway.)
• You could introduce an explicit variant entity file for older releases and use that on old branches. (Disadvantages: Two massive entity files to maintain, that both need to be kept in lockstep.)
• Not sure what the tool-based fix would be... maybe allowing in-file variant handling ("include line 28 for variant new_document, include line 29 for variant old_document")? That sounds like a lot of work for a feature that no one would understand and would massively increase fragility of the tool. (Disadvantages: Seems there are plenty.)

(via @taroth21 )

Start by reproducing doc-kit on an older and newer branch, then inspect the template files and entity definitions involved in the Security Guide name. Determine whether the incompatibility belongs in the templates or the tool, and finish with a validated approach that lets old documents run doc-kit without incorrect entity expansion.