Refactoring
Files in a documentation set depend on one another. When you rename a file, key, or element ID, references in other files must change too. The editor's refactoring commands update those references.
The rule that makes them safe
Every refactoring prints a plan and changes nothing. You read the plan, then run the same command again with --apply.
dogsbay-xml rename-key product-name product --root .
dogsbay-xml rename-key product-name product --root . --applyIn the editor the same plan appears as a table you review before it runs.
Two commands work the other way round. edit-map and edit-reltable write unless you pass --dry-run, and so does metadata-set. They are editors rather than refactorings.
Before you change anything
Ask what depends on it:
dogsbay-xml where-used topics/installing-audacity.dita \
--root . --map audacity-guide.ditamapWith --map, the report includes references that reach the file indirectly through a key, which are the ones a search would miss.
What each refactoring is for
Moving and renaming
| Command | Use it when |
|---|---|
rename-file | A file's name or location is wrong. |
rename-key | A key's name is wrong, or you are aligning a naming scheme. |
rename-element-id | An element ID is wrong and conrefs point at it. |
rename-profile-value | A condition value changes, such as mac becoming macos. |
delete-file | A file should go. It reports inbound references first, so you find out before rather than after. |
retarget | Two files should become one: point every reference from one at the other. |
Changing how content is referenced
| Command | Use it when |
|---|---|
keyify | A file is referenced by path in many places and should be a key. |
inline-key | A key is not earning its indirection. |
extract-conref | The same content is repeated and should be reused from one place. |
inline-conref | Reused content should become a local copy again. |
create-keydef | You want a text key, such as a product name, defined once. |
merge-keydefs | A map's closure defines the same key more than once and only the first can win. |
Restructuring
| Command | Use it when |
|---|---|
split-topic | A topic has grown into several. Each top-level section becomes a topic, and the map is updated to include them. |
A worked example
This example turns a hardcoded product name into a key. It fixes one of the problems in the sample project.
- Define the key The key name and the text it resolves to are the two arguments; the map that receives the definition is an option.
bash
dogsbay-xml create-keydef product-name Audacity \ --map keydefs-product.ditamap --apply - Replace the hardcoded text as well
--replace-inrewrites whole-word occurrences of the text under a root into key references, which is the part that would otherwise be a hundred manual edits.bashdogsbay-xml create-keydef product-name Audacity \ --map keydefs-product.ditamap --replace-in topics - Apply it Run the same command with
--applyonce the plan looks right. - Check the resultbash
dogsbay-xml project-health . --map audacity-guide.ditamap
When a refactoring refuses
If a refactoring would create a broken reference, it reports the problem instead of making the change. Review the plan to find unsafe changes before they affect the output.