Add document version migration guide

[alerque]

I think we should start a chapter in the manual or in some other guide for updating documents. Changes to what SILE expects in a document should be clearly explained so that old projects can effectively migrate their documents.

Things that come to mind so far:

1. Ambiguous percent units dropped in favor of explicit ones.
2. Full Lua syntax (%, {}, etc.) now allowed in TeX-flavor scripts.
3. Previously universal escapes (e.g. \{, \}, \\) passed through in script blocks.
4. Whatever comes of my top level tag proposal in Top level tags differ between XML/TeX flavors #508.

[Omikhleia]

@alerque You already do (a lot of good) work mentioning breaking changes in the release notes, for each release, in addition to having lots of deprecation warnings in the code itself.

This issue is ~7 year-old: do you still think the manual should actually have a section on how to update documents? Personally, I don't: I prefer the manual not to be encumbered with things of the past, and the release notes (and the deprecation shims) are here to cover the cases.

N.B. Would SILE be in a 1.0+ version, maybe this would make sense -- but until that point is reached, it's probably a lot of effort to get right, unless we just include some bits of the release notes in the manual, say in an appendix... But I'm not fully convinced this is the way to go. Note that we could also "pick" the necessary parts from the release notes and put them in the Wiki, as a "how-to".

[Omikhleia]

This issue did not received any activity for several years (besides... my own comment; and we do have decent release notes when breaking changes occur...)
I am closing it, but please feel free to re-open a dedicated issue if a different approach should be discussed.

Aside note: As suggested, the Wiki remains a possible solution.

[alerque]

Besides the release notes tracking anything we consider breaking, this has also been touched on with the introduction of the retrograde package and related documentation. All in all I do agree we have a pretty settled pattern relative to this issue and how we cope with document upgrades. We'll be at least if not more rigorous post 1.0.0. Supplying commands for automatically upgrading documents (such as casile already does) might be in order for any breaking changes past 1.0.0.