Document map-first preprocess #136
Description
The map-first preprocessing that landed with dita-ot/dita-ot#2497 adds a new Ant target preprocess2 that is a alternative to the old preprocess.
Map-first preprocessing handles the same functionality as the old preproessing, but taking a different processing approach. The old preprocess processes both maps and topics at the same time. The map-first preprocessing first processes maps as far as possible, and only then starts processing topics. This simplifies the processing logic and creates cleaner module responsibilities; it will be easier to e.g. process only those topics that are actually referenced after filtering, or to only process the map in order to validate the map structure.
The current preprocessing architecture was established during DITA 1.0 era when there were fewer DITA features that operated on the map level, like keys and later on key scopes. Initially the difference between processing modes was not that great, but as more features have been added to DITA, processing maps first to build the context makes sense. The old preprocessing already does this to a degree, but preprocess2 will be even more formal about it.
Only subject schemes and delayed key resolution have not been implemented in preprocess2, but support for at least subject schemes will be added later on.
The map-first preprocessing is not enabled by default on DITA-OT 2.5 release, but is released as a candidate/preview feature that will most likely be made the default on DITA-OT 3.0. The target name preprocess2 may not be the final name, due to it being a pretty bad name. At this stage most users can keep on using old preprocess, but we suggest users who extend preprocessing take a look at preprocess2 and give us feedback on possible issues with the design.