DreamWeaver site operations show how links can be managed links when moving and renaming files and directories. The data structures needed for link management, meanwhile, can also be used to manage build-dependencies, so the DITA system can do smart builds that only regenerate files when the sources they depend on have been modified.
In essence, the data structures consist of a list of file paths, and a list of links for each file (using hash maps to improve performance). When something is moved or renamed, any links the file contains need be adjusted, as well as any links pointing to that file from elsewhere. Link-lists make it possible to rapidly identify the changes that need to be made. Transforms can then be generated and applied to the target files to make the changes.
There are two important aspects to link management:
- Link adjustments (keep them from breaking)
- Version-aware behavior (keep the VCS informed)
There are several kinds of structure changes to take into account, with somewhat different operations for each:
- File Rename: Examine lists for all files in the site. When the target file's name is found in one of the lists, fix the links in the file associated with that list.
- File Move: Perform file rename operations. In addition, adjust all relative links in the file.
- Directory Rename: For all files in the directory, and in all subdirectories, use the File Rename code to identify candidate files that might need to change. For those files, adjust all links that include the directory name in the path.
- Directory Move: Perform directory rename operations. In addition, all files in the directory, and in all subdirectories, adjust relative links. (Somewhat tricky. Relative links within the relocated hierarchy do not need to change. Only links that go outside the hierarchy need to be changed.)
Two kinds of "pre-commit" processing are needed:
- List Management: When files are submitted to the the VCS, the links they contain need to be parsed out and added to the appropriate link lists.
- Change Reflection: After links have been adjusted in a file, the changes need to be reflected in the Version Control System (VCS). The command used to submit a change depends on which VCS is in use.
Ideally, the system would identify the VCS dynamically and use the appropriate commands to find out which files have been modified by the user, and to submit automatically-generated changes. Alternatively, the type of VCS could be declared in a configuration file for the site map. At worst, the commands themselves could be configured in an installation step--but the tool would then need to be reinstalled to work with a different VCS.)