Tools for Phase 0 pre-migration work

Before migrating documentation to a new content management system, you need to assess how content is reused across your documentation set. These tools automate the analysis, generating reports that you can link directly in your Content Reuse Assessment Worksheet.

Use these doc-utils tools to complete the Pre-Migration Reuse Readiness Tasks:

Worksheet Task	Tool
Remove unused attributes	`find-unused-attributes --remove`
Inventory conditionals	`inventory-conditionals`
Inventory reused modules	`find-duplicate-includes`
Inventory reused content blocks	`find-duplicate-content`
Archive unused files	`archive-unused-files --archive`
Add abstract role for DITA	`insert-abstract-role`
Add procedure title for DITA	`insert-procedure-title`
Convert callouts for DITA	`convert-callouts-to-deflist` or `convert-callouts-interactive`

Task 1: Clean Up Attribute Files

find-unused-attributes --remove

Warning: The --remove option modifies files in place. Always review the output of find-unused-attributes (without --remove) first, then test your documentation build after removing attributes.

See find-unused-attributes for details.

Task 2: Inventory Conditionals

inventory-conditionals

Creates ./reports/conditionals-inventory_*.txt listing every ifdef, ifndef, ifeval, and endif with locations.

See inventory-conditionals for details.

Task 3: Inventory Reused Content

Run both tools to capture different types of reuse:

# Files included via include:: from multiple locations
find-duplicate-includes

# Similar notes, tables, steps, and code blocks
find-duplicate-content

Reports are written to ./reports/.

See find-duplicate-includes and find-duplicate-content for details.

Task 4: Archive Unused Files

# Preview unused files (no changes made)
archive-unused-files

# Archive unused files to ./archive/
archive-unused-files --archive

Finds AsciiDoc files in modules/ and assemblies/ directories that are not referenced by any include:: macro. Run without --archive first to review the list.

See archive-unused-files for details.

Task 5: Add Abstract Role for DITA

# Preview changes first
insert-abstract-role --dry-run

# Apply changes
insert-abstract-role

Inserts [role="_abstract"] above the first paragraph after the document title in all AsciiDoc files. This attribute is required for DITA short description conversion. Review and revise your first paragraphs as needed.

See insert-abstract-role for details.

Task 6: Add Procedure Title for DITA

Use this task to resolve AsciiDocDITA.TaskContents Vale warnings.

# Preview changes first
insert-procedure-title modules/ --dry-run

# Apply changes
insert-procedure-title modules/

Inserts .Procedure above the first numbered step in procedure files that lack this block title. Review any warnings the tool generates—these indicate files needing manual attention (wrong content type, stub files, etc.).

See insert-procedure-title for details and guidance on resolving warnings.

Task 7: Convert Callouts for DITA

Use this task to resolve AsciiDocDITA.CalloutList Vale warnings.

# Batch conversion
convert-callouts-to-deflist modules/

# Or interactive mode (choose format per code block)
convert-callouts-interactive modules/

Converts callout annotations (<1>, <2>, etc.) to definition list format. Use interactive mode to select between definition list and table formats for each code block.

See convert-callouts-to-deflist or convert-callouts-interactive for details.

Quick Reference

# Review unused attributes first
find-unused-attributes

# Then remove (after verifying build works)
find-unused-attributes --remove

# Generate reuse inventory reports
inventory-conditionals
find-duplicate-includes
find-duplicate-content

# Find and archive unused files
archive-unused-files
archive-unused-files --archive

# Add abstract role for DITA short descriptions
insert-abstract-role --dry-run
insert-abstract-role

# Add procedure title for DITA tasks
insert-procedure-title modules/ --dry-run
insert-procedure-title modules/

# Convert callouts for DITA
convert-callouts-to-deflist modules/
# Or use interactive mode:
convert-callouts-interactive modules/

Commit the reports to your repository and link them in your worksheet.