[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/image-scanning-by-using-the-roxctl-cli.adoc by agantony · Pull Request #111949 · openshift/openshift-docs

agantony · 2026-05-19T18:25:11Z

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.11

openshift-ci-robot · 2026-05-19T18:25:16Z

@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 · 2026-05-19T18:37:25Z

🤖 Wed Aug 19 12:45:43 - Prow CI generated the docs preview:

https://111949--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/image-scanning-by-using-the-roxctl-cli.html

agantony · 2026-05-19T19:51:41Z

Review Guide: image-scanning-by-using-the-roxctl-cli.adoc DITA Refactoring

📊 Executive Summary

This PR refactors cli/image-scanning-by-using-the-roxctl-cli.adoc to comply with DITA conversion requirements by extracting inline content into modular sub-modules following the OpenShift modular documentation pattern.

Key Metrics:

Files Changed: 4 (1 assembly + 3 modules)
New Modules: 2 created
Modified Modules: 2 updated
Total Lines Changed: +78 additions, -55 deletions
Net Change: +23 lines (modularization overhead)

📁 Files Changed Summary

Modified Files (2)

File	Type	Before	After	Change	Purpose
`cli/image-scanning-by-using-the-roxctl-cli.adoc`	Assembly	56 lines	11 lines	-45 lines	Extracted inline content to modules
`modules/roxctl-image-scan-command-options.adoc`	REFERENCE	No abstract	Has abstract + title change	+1 line	Added abstract, simplified title

New Modules Created (2)

File	Type	Lines	Purpose
`modules/scanning-images-remote-cluster.adoc`	CONCEPT	15	Overview and description
`modules/scanning-images-remote-cluster-procedure.adoc`	PROCEDURE	54	Step-by-step scanning procedure

🏗️ Module Hierarchy & Structure

Before Refactoring

Assembly (image-scanning-by-using-the-roxctl-cli.adoc)
├── Assembly abstract: "You can scan images..."
├── Inline: "Scanning images from a remote cluster" section (H2)
│   ├── Inline: Overview paragraph
│   ├── Inline: Prerequisites list
│   └── Inline: Procedure steps
└── Include: roxctl-image-scan-command-options.adoc [+1]
    └── Content: Options table

Total: 2 files (1 assembly + 1 module)

After Refactoring

Assembly (image-scanning-by-using-the-roxctl-cli.adoc)
├── Assembly abstract: "You can scan images..."
├── Include: scanning-images-remote-cluster.adoc [+1] ← CONCEPT
│   └── Content: Overview paragraph only
├── Include: scanning-images-remote-cluster-procedure.adoc [+1] ← PROCEDURE
│   ├── Prerequisites
│   └── Procedure steps
├── Include: roxctl-image-scan-command-options.adoc [+2] ← REFERENCE
│   └── Content: Options table
└── Additional Resources section (xref extracted from procedure)

Total: 4 files (1 assembly + 3 modules)

Leveloffset Hierarchy:

+1: Top-level sections (overview, procedure)
+2: Options subsection

Key Structural Change:

Options module moved from leveloffset +1 → +2 (now a subsection)
Inline section extracted to 2 separate modules (CONCEPT + PROCEDURE)

🔍 Step-by-Step Review Instructions

Netlify Preview Base URL:

https://111949--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/image-scanning-by-using-the-roxctl-cli.html

Step 1: Review Assembly Structure & Additional Resources

What to check: Overall page layout, TOC, assembly abstract, Additional Resources section

Netlify Preview:

🔗 Full Page

Expected Content:

Assembly Title: "Image scanning by using the roxctl CLI" (H1)
Assembly Abstract: "You can scan images for security vulnerabilities and configuration issues by using the roxctl CLI."
Additional Resources: New section at bottom with xref to "About the common vulnerabilities and exposures"

Verification Checklist:

Assembly abstract visible at top
TOC renders correctly with 3 main sections
All heading levels are hierarchical (H1 → H2 → H3)
Additional Resources section visible at page bottom (NEW)
Additional Resources contains xref to CVE overview
Page navigation works (sidebar/TOC links)

Key Changes:

✅ Additional Resources section added (extracted xref from procedure)
✅ Assembly reduced from 56 to 11 lines
✅ All inline content extracted to modules

Step 2: Review Overview Section

What to check: Overview module (CONCEPT) - description paragraph only

Netlify Preview:

🔗 Scanning images from a remote cluster

Expected Content:

Title: "Scanning images from a remote cluster" (H2)
Abstract: "When you scan images from a remote cluster, the roxctl CLI pulls the image from the remote cluster and scans it for vulnerabilities and security issues."
No inline prerequisites or procedures (moved to separate module)

Verification Checklist:

Section ID: scanning-images-remote-cluster_image-scanning-by-using-the-roxctl-cli
Heading renders as H2
Abstract paragraph visible (explains remote scanning)
No prerequisites list (moved to procedure module)
No procedure steps (moved to procedure module)
Content is descriptive/conceptual only

Key Changes:

✅ Extracted from assembly inline section
✅ Contains only CONCEPT content (overview)
✅ Prerequisites and procedure removed (now in separate module)

Step 3: Review Procedure Section

What to check: Procedure module - prerequisites + steps

Netlify Preview:

🔗 Scanning images from a remote cluster procedure

Expected Content:

Title: "Scanning images from a remote cluster" (H2)
Abstract: "Scan images from a remote cluster by running the roxctl image scan command."
Prerequisites: 3 items (ROX_API_TOKEN, Cluster connected, roxctl CLI installed)
Procedure: Numbered steps with command examples

Verification Checklist:

Key Changes:

✅ Extracted from assembly inline section
✅ Combined prerequisites and procedure in single PROCEDURE module
✅ Xref to CVE overview extracted to assembly Additional Resources
✅ Note text updated: removed xref, added descriptive text

Step 4: Review Options Section

What to check: Options module (REFERENCE) - updated title and abstract

Netlify Preview:

🔗 Options

Expected Content:

Title: "Options" (H3, simplified from "roxctl image scan command options")
Abstract: "Options for the roxctl image scan command."
Table: Command options with descriptions

Verification Checklist:

Section ID: roxctl-image-scan-command-options_image-scanning-by-using-the-roxctl-cli
Title changed: "roxctl image scan command options" → "Options"
Abstract added (new in this PR)
Heading renders as H3 (leveloffset changed from +1 to +2)
Table renders correctly (header row + data rows)
All command options present
Table formatting consistent

✅ Comprehensive Verification Checklist

Structural Integrity

All 2 new module files created successfully
Assembly includes all modules in correct order
Leveloffset hierarchy: +1 (overview, procedure) → +2 (options)
No duplicate section IDs
All includes use leveloffset parameter
Additional Resources section added to assembly

Content Integrity

No content lost during extraction
All code blocks preserved
All prerequisites preserved
All procedure steps preserved
Options table preserved
Xref extracted to Additional Resources (not lost)
Overview paragraph preserved in CONCEPT module

DITA Compliance

Rendering Quality

All headings render at correct hierarchy (H1→H2→H3)
Code blocks have syntax highlighting (terminal)
Tables render with headers and borders
TOC shows all sections with correct indentation
Anchor links work (test all 3 section links)
No broken includes or missing modules
Page navigation functional
Additional Resources section renders at page bottom

Build & CI

Netlify preview build succeeded
No AsciiDoc syntax errors
No warnings in build logs
All preview URLs return HTTP 200

🎨 Quick Visual Review Guide

Fast visual checks to catch common issues:

Scan Heading Hierarchy (30 seconds)
- Open full page
- Check sidebar TOC: Should show 2-level hierarchy (H1 → H2 → H3)
- Verify Overview and Procedure at H2, Options at H3
Check Assembly Abstract (15 seconds)
- Top of page should show abstract paragraph
- Text: "You can scan images for security vulnerabilities..."
- Verify proper AsciiDoc rendering
Check Additional Resources (30 seconds)
- Scroll to bottom of page
- Verify "Additional resources" heading visible
- Should have 1 bullet point: xref to CVE overview
- Link should be clickable
Verify Content Separation (1 minute)
- Overview section: Should contain only description paragraph
- Procedure section: Should contain prerequisites + numbered steps
- Options section: Should contain table only
Check Prerequisites (30 seconds)
- Scroll to procedure section
- Verify "Prerequisites" heading visible
- Count items: Should have 3 prerequisites
- Check formatting: bullet list, proper text
Check Code Block (30 seconds)
- Scroll to procedure steps
- Verify terminal highlighting ($ prompt, monospace font)
- Check command: $ roxctl image scan...
- No rendering issues or broken formatting
Test TOC Links (1 minute)
- Click all 3 main TOC links (Overview, Procedure, Options)
- Browser should scroll to correct section
- URL should update with #anchor-id

Total time: ~4 minutes for visual scan

📝 Summary of Key Changes

Content Transformations

Assembly Inline Section → 2 New Modules
- "Scanning images from a remote cluster" section extracted
- Overview paragraph → scanning-images-remote-cluster.adoc (CONCEPT)
- Prerequisites + Procedure → scanning-images-remote-cluster-procedure.adoc (PROCEDURE)
Xref Extraction
- Xref to CVE overview removed from procedure note
- Added to assembly Additional Resources section
- Note text updated to plain text (no xref)
Options Module Updated
- Title: "roxctl image scan command options" → "Options" (simplified)
- Abstract: Added descriptive paragraph
- Leveloffset: Changed from +1 to +2 (now subsection)

Structural Changes

Hierarchy Reorganization
- Original: Inline section (H2) + Options (H2)
- New: Overview (H2) + Procedure (H2) + Options (H3)
- More logical grouping: Options as subsection
Module Count
- Before: 2 files (assembly + 1 module)
- After: 4 files (assembly + 3 modules)
- Net increase: 2 new module files
Assembly Simplification
- Before: 56 lines (with inline section)
- After: 11 lines (only includes + Additional Resources)
- Reduction: 45 lines extracted to modules

DITA Compliance Improvements

Content Type Separation
- CONCEPT: Overview description only
- PROCEDURE: Prerequisites + steps combined
- REFERENCE: Options table
Xref Management
- Cross-reference extracted from procedure content
- Placed in assembly Additional Resources section
- Maintains accessibility while improving structure
Abstract Additions
- All modules now have [role="_abstract"]
- Descriptive abstracts for each section
- Improved metadata for DITA conversion

🎯 Rationale & Compliance

Why This Refactoring?

DITA Conversion Requirements:

DITA toolchain requires separation of CONCEPT and PROCEDURE content
Inline procedural sections in assemblies cause conversion failures
Modular structure enables proper DITA topic typing
Cross-references must be extracted from procedure modules

OpenShift Documentation Standards:

CLI reference assemblies should not contain inline procedures
Overview content (CONCEPT) must be separated from procedural content (PROCEDURE)
Prerequisites and procedure steps can be combined in single PROCEDURE module
Cross-references belong in Additional Resources sections

Benefits:

✅ DITA conversion readiness
✅ Content reusability (modules can be included in multiple assemblies)
✅ Improved maintainability (changes isolated to specific modules)
✅ Better semantic separation (CONCEPT vs PROCEDURE vs REFERENCE)
✅ Consistent structure across CLI documentation
✅ Cleaner assembly with proper Additional Resources
✅ Logical hierarchy: overview + procedure + options

Module Type Decisions

Why CONCEPT for overview?

Contains descriptive/explanatory content only
Provides context about remote cluster scanning
No procedural or reference content
Explains what remote scanning is and how it works

Why PROCEDURE for combined prerequisites + steps?

Contains task-oriented content (how to scan images)
Prerequisites are part of the procedural context
Combining prerequisites and steps in one module improves flow
DITA supports prerequisites within PROCEDURE topics

Why REFERENCE for options?

Contains command option specifications
Reference table of flags and parameters
No procedural or conceptual content

Xref Extraction Rationale

Why extract xref to Additional Resources?

DITA conversion requires xrefs outside procedure content
Cross-references in Additional Resources improve navigation
Maintains content accessibility while improving structure
Aligns with OpenShift documentation patterns

Updated note text:

Before: "For more information about common vulnerabilities and exposures, see xref:..."
After: "The command provides information about common vulnerabilities and exposures (CVE) for the scanned image."
More concise and descriptive without losing context

🔗 Related Resources

Netlify Preview: https://111949--ocpdocs-pr.netlify.app
PR: [RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/image-scanning-by-using-the-roxctl-cli.adoc #111949
JIRA: https://redhat.atlassian.net/browse/ROX-33164
Target Branches: rhacs-docs-main, rhacs-docs-4.10, rhacs-docs-4.9

✨ Reviewer Recommendations

Quick Review Path (5-10 minutes)

Open Netlify preview
Run through "Quick Visual Review Guide" (4 minutes)
Verify Additional Resources section added at bottom
Verify all 3 section IDs work as anchor links
Verify build passed (green checkmark in PR)

Detailed Review Path (15-20 minutes)

Complete all 4 step-by-step review sections
Check all verification checklists
Compare before/after diff for each module
Verify content integrity (no lost content)
Verify xref extracted to Additional Resources (not deleted)
Verify CONCEPT contains only overview (no prerequisites/procedures)

Focus Areas for This PR

✅ High Priority: CONCEPT vs PROCEDURE separation
✅ High Priority: Xref extracted to Additional Resources
✅ High Priority: Prerequisites moved from CONCEPT to PROCEDURE
✅ Medium Priority: Assembly simplified (56 → 11 lines)
✅ Medium Priority: Options module title simplified and abstract added

Common Issues to Watch For

⚠️ Completeness: Verify all prerequisites present in procedure module
⚠️ Completeness: Verify all procedure steps preserved
⚠️ Xref accessibility: Ensure xref is in Additional Resources, not lost
⚠️ Content integrity: Overview should not contain prerequisites/procedures
⚠️ Hierarchy: Ensure Options renders as H3 (subsection)

Generated: 2026-05-20
PR Author: @agantony
Reviewer: Please verify all checklist items before approval

📋 Quick Checklist for Reviewers

Essential Checks (must pass):

Overview module contains only descriptive content (no prerequisites/procedures)
Procedure module contains prerequisites + steps
Xref extracted to Additional Resources (not lost)
All content preserved during extraction
Build passed successfully

Quality Checks (should pass):

CONCEPT and PROCEDURE properly separated
Additional Resources section visible at page bottom
Options module title simplified ("Options" not "roxctl image scan command options")
All abstracts are descriptive and meaningful
Page navigation and anchor links work

Nice-to-Have (bonus points):

Abstracts provide clear value to readers
Content organization improved by modularization
Overall page readability maintained or improved

jlprevatt

LGTM

…-cli.adoc ROX33164 Fixing section ID

openshift-ci · 2026-08-19T12:47:03Z

@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 · 2026-08-19T12:52:05Z

/cherrypick rhacs-docs-4.11

agantony · 2026-08-19T12:52:09Z

/cherrypick rhacs-docs-4.10

openshift-cherrypick-robot · 2026-08-19T12:52:59Z

@agantony: new pull request created: #118376

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 · 2026-08-19T12:53:02Z

@agantony: new pull request created: #118377

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-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label May 19, 2026

agantony added RHACS Label for RHACS related PRs that go in the rhacs-docs branch rhacs-docs-4.9 rhacs-docs-4.10 and removed jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. labels May 19, 2026

openshift-ci Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label May 19, 2026

jlprevatt approved these changes Aug 3, 2026

View reviewed changes

ROX33164 Fixing DITA errors in cli/image-scanning-by-using-the-roxctl…

c23872b

…-cli.adoc ROX33164 Fixing section ID

agantony force-pushed the ROX33164-dita-rework-image-scanning-roxctl-cli branch from 4068c7c to c23872b Compare August 19, 2026 12:34

agantony merged commit f77f3b0 into openshift:rhacs-docs-main Aug 19, 2026
2 checks passed

agantony added rhacs-docs-4.11 Label for PRs that apply to RHACS 4.11 and removed rhacs-docs-4.9 labels Aug 19, 2026

openshift-cherrypick-robot mentioned this pull request Aug 19, 2026

[rhacs-docs-4.11] [RHACS] [Docs] ROX-33164: Fixing DITA errors in cli/image-scanning-by-using-the-roxctl-cli.adoc #118376

Open

openshift-cherrypick-robot mentioned this pull request Aug 19, 2026

[rhacs-docs-4.10] [RHACS] [Docs] ROX-33164: Fixing DITA errors in cli/image-scanning-by-using-the-roxctl-cli.adoc #118377

Open

Navigation Menu

Uh oh!

[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/image-scanning-by-using-the-roxctl-cli.adoc - #111949

[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/image-scanning-by-using-the-roxctl-cli.adoc#111949
agantony merged 1 commit into
openshift:rhacs-docs-mainfrom
agantony:ROX33164-dita-rework-image-scanning-roxctl-cli

agantony commented May 19, 2026 •

edited

Loading

Uh oh!

openshift-ci-robot commented May 19, 2026 •

edited by openshift-ci Bot

Loading

Uh oh!

ocpdocs-previewbot commented May 19, 2026 •

edited

Loading

Uh oh!

agantony commented May 19, 2026

Uh oh!

jlprevatt left a comment

Uh oh!

openshift-ci Bot commented Aug 19, 2026

Uh oh!

Uh oh!

agantony commented Aug 19, 2026

Uh oh!

agantony commented Aug 19, 2026

Uh oh!

openshift-cherrypick-robot commented Aug 19, 2026

Uh oh!

openshift-cherrypick-robot commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

agantony commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented May 19, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ocpdocs-previewbot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

agantony commented May 19, 2026

Review Guide: image-scanning-by-using-the-roxctl-cli.adoc DITA Refactoring

📊 Executive Summary

📁 Files Changed Summary

Modified Files (2)

New Modules Created (2)

🏗️ Module Hierarchy & Structure

Before Refactoring

After Refactoring

🔍 Step-by-Step Review Instructions

Netlify Preview Base URL:

Step 1: Review Assembly Structure & Additional Resources

Step 2: Review Overview Section

Step 3: Review Procedure Section

Step 4: Review Options Section

✅ Comprehensive Verification Checklist

Structural Integrity

Content Integrity

DITA Compliance

Rendering Quality

Build & CI

🎨 Quick Visual Review Guide

📝 Summary of Key Changes

Content Transformations

Structural Changes

DITA Compliance Improvements

🎯 Rationale & Compliance

Why This Refactoring?

Module Type Decisions

Xref Extraction Rationale

🔗 Related Resources

✨ Reviewer Recommendations

Quick Review Path (5-10 minutes)

Detailed Review Path (15-20 minutes)

Focus Areas for This PR

Common Issues to Watch For

📋 Quick Checklist for Reviewers

Uh oh!

jlprevatt left a comment

Choose a reason for hiding this comment

Uh oh!

openshift-ci Bot commented Aug 19, 2026

Uh oh!

Uh oh!

agantony commented Aug 19, 2026

Uh oh!

agantony commented Aug 19, 2026

Uh oh!

openshift-cherrypick-robot commented Aug 19, 2026

Uh oh!

openshift-cherrypick-robot commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

agantony commented May 19, 2026 •

edited

Loading

openshift-ci-robot commented May 19, 2026 •

edited by openshift-ci Bot

Loading

ocpdocs-previewbot commented May 19, 2026 •

edited

Loading