[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/command-reference/roxctl-scanner.adoc

[agantony]

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

[openshift-ci-robot]

@agantony: This pull request references ROX-33164 which is a valid jira issue.

Details

In response to this:

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[ocpdocs-previewbot]

🤖 Mon May 18 15:28:30 - Prow CI generated the docs preview:
https://111827--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

[openshift-ci]

@agantony: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[agantony]

PR Review Guide: roxctl-scanner DITA Refactoring

Summary

This PR refactors roxctl-scanner.adoc to follow Red Hat modular documentation standards and resolve DITA conversion errors. This PR also fixes all passive voice issues identified by Vale linting.

Files Changed: 14 (+225, -111)
Pattern: Standard CLI Reference (Pattern 4)
Netlify Preview: https://111827--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-scanner.html

---

What Changed

Assembly refactored:

• cli/command-reference/roxctl-scanner.adoc - Inline content extracted to modules

New modules created (9):

1. modules/roxctl-scanner-overview.adoc - Command overview (CONCEPT)
2. modules/roxctl-scanner-usage.adoc - Usage syntax (REFERENCE)
3. modules/roxctl-scanner-available-commands.adoc - Available commands table (REFERENCE)
4. modules/roxctl-scanner-generate-usage.adoc - Generate command usage (REFERENCE)
5. modules/roxctl-scanner-generate-options.adoc - Generate command options (REFERENCE)
6. modules/roxctl-scanner-upload-db-usage.adoc - Upload-db command usage (REFERENCE)
7. modules/roxctl-scanner-upload-db-options.adoc - Upload-db command options (REFERENCE)
8. modules/roxctl-scanner-download-db-usage.adoc - Download-db command usage (REFERENCE)
9. modules/roxctl-scanner-download-db-options.adoc - Download-db command options (REFERENCE)

Parent modules updated (3):

• modules/roxctl-scanner-generate.adoc - Reduced from 40 to 9 lines (REFERENCE → CONCEPT)
• modules/roxctl-scanner-upload-db.adoc - Reduced from 25 to 9 lines (REFERENCE → CONCEPT)
• modules/roxctl-scanner-download-db.adoc - Reduced from 37 to 10 lines (REFERENCE → CONCEPT)

Shared modules updated (1):

• modules/options-inherited-from-the-parent-command.adoc - Added abstract role

Module Hierarchy:

roxctl-scanner.adoc (assembly)
├── roxctl-scanner-overview.adoc (+1)
├── roxctl-scanner-usage.adoc (+2)
├── roxctl-scanner-available-commands.adoc (+2)
├── options-inherited-from-the-parent-command.adoc (+1)
├── roxctl-scanner-generate.adoc (+1)
│   ├── roxctl-scanner-generate-usage.adoc (+2)
│   └── roxctl-scanner-generate-options.adoc (+2)
├── roxctl-scanner-upload-db.adoc (+1)
│   ├── roxctl-scanner-upload-db-usage.adoc (+2)
│   └── roxctl-scanner-upload-db-options.adoc (+2)
└── roxctl-scanner-download-db.adoc (+1)
    ├── roxctl-scanner-download-db-usage.adoc (+2)
    └── roxctl-scanner-download-db-options.adoc (+2)

---

Step-by-Step Review

1. Main Page

Preview: https://111827--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-scanner.html

Check:

• ✅ Assembly abstract appears at top
• ✅ Table of contents renders correctly
• ✅ Command overview section displays
• ✅ Usage syntax visible
• ✅ Available commands table (3 commands: download-db, generate, upload-db)
• ✅ Inherited options section

2. Section: roxctl scanner (Overview)

Location: First content section after TOC

Check:

• ✅ Heading: "roxctl scanner"
• ✅ Abstract: "Manage RHACS scanner-related operations."
• ✅ Heading level is H2 (from H1 with leveloffset=+1)

3. Section: roxctl scanner usage

Location: Scroll to "roxctl scanner usage" heading

Check:

• ✅ Heading: "roxctl scanner usage"
• ✅ Abstract: "Usage syntax for the `roxctl scanner` command."
• ✅ Usage syntax: `$ roxctl scanner [command]`
• ✅ Heading level is H3 (from H1 with leveloffset=+2)

4. Section: Available commands

Location: Scroll to "Available commands" heading

Check:

• ✅ Heading: "Available commands"
• ✅ Abstract: "Commands available for the `roxctl scanner` command."
• ✅ Commands table with 3 rows:
  • download-db (Download scanner vulnerability database)
  • generate (Generate scanner bundle)
  • upload-db (Upload vulnerability database to Central)
• ✅ Heading level is H3 (from H1 with leveloffset=+2)

5. Command: roxctl scanner generate

Location: Scroll to "roxctl scanner generate" heading

Check:

• ✅ Command description appears
• ✅ Usage section displays
• ✅ Options table with ~8 flags:
  • `--image-defaults`, `--istio-support`, `--openshift-version`
  • `--output-dir`, `--retry`, `--scanner-image`
  • `--scanner-db-image`, `--timeout`
• ✅ Heading level is H2 (from H1 with leveloffset=+1)

Passive voice fixes:

• "are retried" → "the system retries"
• "is waited" → "the system waits"

6. Command: roxctl scanner upload-db

Location: Scroll to "roxctl scanner upload-db" heading

Check:

• ✅ Command description appears
• ✅ Usage section displays
• ✅ Options table with 1 flag: `--scanner-db-file`
• ✅ Heading level is H2 (from H1 with leveloffset=+1)

7. Command: roxctl scanner download-db

Location: Scroll to "roxctl scanner download-db" heading

Check:

• ✅ Command description appears
• ✅ Usage section displays
• ✅ Options table with ~5 flags:
  • `--db-bundle-file`, `--max-offline-days`, `--max-retries`
  • `--output-dir`, `--retry-delay`
• ✅ Heading level is H2 (from H1 with leveloffset=+1)

Passive voice fixes:

• "is specified" → "you specify"
• "will be attempted" → "the command attempts"
• "is downloaded" → "you download"

8. Section: Options inherited from the parent command

Location: Scroll to "roxctl scanner command options inherited from the parent command" heading

Check:

• ✅ Full heading title appears
• ✅ Abstract describes inherited options
• ✅ Options table with 11 rows (all roxctl global options)
• ✅ Heading level is H2 (from H1 with leveloffset=+1)

---

Verification Checklist

Structural:

• All headings at correct hierarchy (H1 → H2 → H3)
• TOC includes all sections
• No broken includes
• Proper 2-level hierarchy

Content:

• All command descriptions present
• Usage syntax displays correctly
• All options tables render properly
• Available commands table lists 3 commands
• No content lost
• Abstracts appear under each section

DITA Compliance:

• Assembly has [role="_abstract"]
• Each module has [role="_abstract"]
• Content types correct (CONCEPT/REFERENCE)
• Overview module is CONCEPT
• Usage/options/available-commands modules are REFERENCE

Passive Voice Fixes:

• All passive voice converted to active voice
• "are retried" → "the system retries"
• "is waited" → "the system waits"
• "is specified" → "you specify"
• "will be attempted" → "the command attempts"
• "is downloaded" → "you download"

---

Comparison with Other PRs

Feature	This PR	Other PRs
Files changed	14	5-100 (mid-range)
New modules	9	2-70 (moderate)
Commands	3 simple	Varies
Assembly-level options	No	Some have them
Hierarchy depth	2 levels	Standard
Pattern	Pattern 4	Most common

Related PRs:

• #111737 - roxctl-declarative-config
• #111782 - roxctl-netpol (3-level)
• #111785 - roxctl-image (assembly options)
• #111791 - roxctl-sensor (3-level)
• #111792 - roxctl-central (4-level, 100 files)
• #111795 - roxctl-version (minimal, 5 files)

---

📝 Full review guide saved: /tmp/pr-111827-review-guide.md

[jlprevatt]

LGTM

[agantony]

/cherrypick rhacs-docs-4.11

[agantony]

/cherrypick rhacs-docs-4.10

[agantony]

/cherrypick rhacs-docs-4.9

[openshift-cherrypick-robot]

@agantony: new pull request created: #113803

Details

In response to this:

/cherrypick rhacs-docs-4.11

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[openshift-cherrypick-robot]

@agantony: new pull request created: #113804

Details

In response to this:

/cherrypick rhacs-docs-4.10

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[openshift-cherrypick-robot]

@agantony: new pull request created: #113805

Details

In response to this:

/cherrypick rhacs-docs-4.9

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.