DITA Link Fixer Help
What Does it Do?
The DITA Link Fixer module crawls through a DITAMAP, DITAMAP of maps or all of the DITA files in a directory and follows every link in every referenced file and then produces a report in DITA XML.
When you open the report you'll find a section for every file highlighting problem links (XREF, HREF, CONREF etc.). To make manual fixes easier, clicking on a broken link takes you directly to the link in the source file.
However, Link Fixer does much more than finding broken links. It also scans the entire suite, not just referenced files, and collects possible fixes; that is it finds the closest matches to the original links and inserts them in the report as suggested fixes.
If you select a fix by putting an "X" beside it, save the report, and then re-run Link Fixer against the report, Link Fixer implements the fixes you have selected.
How does it Work?
As you would expect Link Fixer crawls through a DITAMAP, DITAMAP of maps or all of the DITA files in a directory and follows every link in every referenced file and then lists all the broken links in a report.
However, by setting the "Suite Root" parameter appropriately, you can direct Link Fixer to find link destinations similar to broken links anywhere in a suite of documents. Link These also appear in the report as suggested fixes. If you select a fix by putting an "X" beside it, save the report, and then re-run Link Fixer against the edited report, Link Fixer implements the fixes you have selected.
While scanning all DITA files in the suite, Link Fixer records all possible matches to broken links based on the element identification number, the title (if available), and the file name.
Note: Because of the way Link Fixer finds possible matches to broken links, you can rearrange DITA files in a directory structure without worrying too much about relinking. First make sure all your links are correct. Then rearrange your files in the directory structure of your suite. Finally run Link Fixer with the "Suite Root" parameter set appropriately. If all links were correct before rearranging the files, Link Fixer will generally make only one suggestion per broken link. This technique is much easier and much less expensive than manually fixing links to moved files.
- You should set the default "Output Root" and "Backup Root" directory under "Default Settings". This makes all modules in the Samalander Software Center easier to use.
- Samalander modules currently assume that all the files in a suite are on a single disk. Samalander cannot handle remote files on servers or accross disk boundaries such as C:\\ to another disk, for example, E:\\.
How to Use the Samalander DITA Link Fixer Module
- Open the DITA Link Fixer module. This dialog appears:
- Select the input type: a DITAMAP or a directory containing DITA files. DITA Link Fixer is recursive, so it will scan all directories inside the directory you select.
- Type or paste the input file or directory name. You can use the "Browse" button to the right to select the file.
- Type or paste the suite root directory name. You can use the "Browse" button to the right to select the file.
The "Suite Root" the top level directory in which your suite of documents resides. Setting the "Suite Root" tells the Link Fixer where to look for suggested fixes for broken links. Setting the "Suite Root" parameter also prevents changes that point outside of this directory.
- Type or paste the name of the "Suggestions File". You can use the "Browse" button to the right to select the file.
The "Suggestions File" is a DITA file produced by the Link Fixer module. It lists all the link errors and, where possible, suggests possible fixes. You can select a fix by placing an "X" in the field beside the suggestion.
- Click "Generate Report". The report of broken links and suggested fixes (if there are any) is written to location specified in step 5.
- Open, edit, then save the report.
- To fix a link manually, click on the broken link in the report. You will be taken directly to the broken link.
- If a suggested fix to a broken link is available it will be included in the report. Place an X beside the correct suggestion to select it for automated fixing later. If none of the suggested fixes are correct, fix the link manually.
- When you have finished editing the report save it. Do not change report's name or location.
- Click "Fix Links". Suggested fixes you have selected in the report will be fixed automatically.
- Rerun the DITA Link Fixer module again, this time with a different suggestions file name in step 5. Scan the report for any broken links you may have missed in step 7.
Tested in ...
- DITA 1.1, DITA 1.2
- FrameMaker 9, FrameMaker 10, FrameMaker 11