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 )