[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/installing-the-roxctl-cli.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]

🤖 Sat May 16 08:52:15 - Prow CI generated the docs preview:

https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/installing-the-roxctl-cli.html
https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.html
https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/cloud_service/installing_cloud_other/install-secured-cluster-cloud-other.html
https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.html
https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/installing/installing_ocp/install-central-ocp.html
https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/installing/installing_ocp/install-secured-cluster-ocp.html
https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/installing/installing_other/install-central-other.html
https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/installing/installing_other/install-secured-cluster-other.html
https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/integration/integrate-with-ci-systems.html
https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/upgrading/upgrade-roxctl.html

[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 Summary

This PR fixes DITA compatibility errors in the roxctl CLI installation documentation by extracting inline assembly content into a proper module structure.

Changes Overview

Files Changed: 5 (1 new, 4 modified) | +17/-9 lines

File	Type	Change
cli/installing-the-roxctl-cli.adoc	Assembly	Removed inline section, added module include
modules/install-roxctl-cli-binary.adoc	New Module	Extracted parent CONCEPT module
modules/install-roxctl-cli-linux.adoc	Module	Wording improvements ("Find" vs "Determine", "run" vs "execute")
modules/install-roxctl-cli-macos.adoc	Module	Same wording improvements as Linux
modules/run-roxctl-from-container.adoc	Module	Added [role="_abstract"] attribute

---

🔍 Step-by-Step Review Guide

Main Assembly Page

📄 Preview: https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/installing-the-roxctl-cli.html

Review checklist:

• Assembly renders without errors
• TOC shows correct hierarchy (parent H2 with 3 child H3 sections)
• "Installing the roxctl CLI by downloading the binary" appears as H2 with abstract
• Linux, macOS, Windows sections appear as H3 under parent
• "Running the roxctl CLI from a container" appears as separate H2
• No duplicate or missing content

---

Linux Installation Section

📄 Preview: https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/installing-the-roxctl-cli.html#install-roxctl-cli-linux_installing-the-roxctl-cli

Changes:

• Step 1: "Find the `roxctl` architecture..." (changed from "Determine")
• Step 4: "To check your `PATH`, run the following command:" (changed from "execute")

---

macOS Installation Section

📄 Preview: https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/installing-the-roxctl-cli.html#install-roxctl-cli-macos_installing-the-roxctl-cli

Changes: Same wording improvements as Linux ("Find" and "run")

---

Container Section

📄 Preview: https://111774--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/installing-the-roxctl-cli.html#run-roxctl-from-container_installing-the-roxctl-cli

Changes: Added [role="_abstract"] to first paragraph for DITA compliance

---

✅ DITA Compliance Improvements

Before	After
❌ Inline assembly content	✅ Proper parent module
❌ Missing abstract roles	✅ Abstract attributes added
⚠️ Less clear wording	✅ Simplified verbs

Structure Before (Non-Modular)

Assembly
├── == Inline section (in assembly)
│   ├── Inline content (in assembly)
│   └── Child modules at +2

Structure After (Modular)

Assembly
├── Parent module (CONCEPT, +1)
│   └── Child modules (+2)

---

🎯 Review Priority

High Priority

• ✅ Assembly renders correctly
• ✅ New module content matches extracted content
• ✅ Hierarchy correct (H2 parent, H3 children)

Medium Priority

• ✅ Wording improves clarity
• ✅ Abstract roles present

---

📝 Full Review Guide

Comprehensive review guide with detailed checklists: Download

---

Ready for review ✨