Merge pull request #499 from RichardHoch/openrewrite

OpenRewrite description for MTA CLI guide

Author: apinnick

docs/cli-guide/master.adoc

@@ -7,6 +7,7 @@ include::topics/templates/document-attributes.adoc[]
 :numbered:
 :imagesdir: topics/images
 :context: cli-guide
+:cli-guide:
 
 //Inclusive language statement
 include::topics/making-open-source-more-inclusive.adoc[]
@@ -22,13 +23,16 @@ include::topics/what-is-the-toolkit.adoc[leveloffset=+2]
 // About the {CLINameTitle}
 include::topics/about-cli.adoc[leveloffset=+2]
 
-== Getting started
+== Installing and Running the CLI
 
 // Install the CLI
 include::topics/installing-web-console-or-cli-tool.adoc[leveloffset=+2]
 
 // Run the CLI
-include::topics/execute.adoc[leveloffset=+2]
+include::topics/cli-run.adoc[leveloffset=+2]
+
+// Use OpenRewrite recipes
+include::topics/using-openrewrite-recipes.adoc[leveloffset=+3]
 
 // Access the Report
 include::topics/access-report.adoc[leveloffset=+2]

docs/topics/execute.adoc renamed to docs/topics/cli-run.adoc

@@ -2,7 +2,7 @@
 //
 // * docs/cli-guide/master.adoc
 
-[id="execute_{context}"]
+[id="cli-run_{context}"]
 = Running the {CLINameTitle}
 
 You can run {ProductShortName} against your application.
@@ -12,9 +12,11 @@ You can run {ProductShortName} against your application.
 . Open a terminal and navigate to the `<MTA_HOME>/bin/` directory.
 . Execute the `mta-cli` script, or `mta-cli.bat` for Windows, and specify the appropriate arguments:
 +
-[source,options="nowrap",subs="+quotes"]
+[source,terminal]
 ----
-$ ./mta-cli --input /path/to/jee-example-app-1.0.0.ear --output /path/to/output --source weblogic --target eap:6 --packages com.acme org.apache
+$ ./mta-cli --input /path/to/jee-example-app-1.0.0.ear \
+    --output /path/to/output --source weblogic --target eap:6 \
+    --packages com.acme org.apache
 ----
 +
 * `--input`: The application to be evaluated.
@@ -25,56 +27,63 @@ $ ./mta-cli --input /path/to/jee-example-app-1.0.0.ear --output /path/to/output
 
 . Access the report.
 
-[discrete]
 [id="command-examples_{context}"]
-== {ProductShortName} Command examples
+== {ProductShortName} command examples
 
 [discrete]
 === Running {ProductShortName} on an application archive
 
 The following command analyzes the `com.acme` and `org.apache` packages of the link:https://github.com/windup/windup/blob/master/test-files/jee-example-app-1.0.0.ear[jee-example-app-1.0.0.ear] example EAR archive for migrating from JBoss EAP 5 to JBoss EAP 7:
 
+[source,terminal]
 ----
-$ <MTA_HOME>/bin/mta-cli --input /path/to/jee-example-app-1.0.0.ear --output /path/to/report-output/ --source eap:5 --target eap:7 --packages com.acme org.apache
+$ <MTA_HOME>/bin/mta-cli \
+    --input /path/to/jee-example-app-1.0.0.ear \
+    --output /path/to/report-output/ --source eap:5 --target eap:7 \
+    --packages com.acme org.apache
 ----
 
 [discrete]
 === Running {ProductShortName} on source code
 
 The following command analyzes the `org.jboss.seam` packages of the link:https://github.com/windup/windup/tree/master/test-files/seam-booking-5.2[seam-booking-5.2] example source code for migrating to JBoss EAP 6.
 
-[source,options="nowrap",subs="+quotes"]
+[source,terminal]
 ----
-$ <MTA_HOME>/bin/mta-cli --sourceMode --input /path/to/seam-booking-5.2/ --output /path/to/report-output/ --target eap:6 --packages org.jboss.seam
+$ <MTA_HOME>/bin/mta-cli --sourceMode --input /path/to/seam-booking-5.2/ \
+    --output /path/to/report-output/ --target eap:6 --packages org.jboss.seam
 ----
 
 [discrete]
 === Running cloud-readiness rules
 
 The following command analyzes the `com.acme` and `org.apache` packages of the link:https://github.com/windup/windup/blob/master/test-files/jee-example-app-1.0.0.ear[jee-example-app-1.0.0.ear] example EAR archive for migrating to JBoss EAP 7. It also evaluates for cloud readiness:
 
-[source,options="nowrap",subs="+quotes"]
+[source,terminal]
 ----
-$ <MTA_HOME>/bin/mta-cli --input /path/to/jee-example-app-1.0.0.ear --output /path/to/report-output/ --target eap:7 --target cloud-readiness --packages com.acme org.apache
+$ <MTA_HOME>/bin/mta-cli --input /path/to/jee-example-app-1.0.0.ear \
+    --output /path/to/report-output/ \
+    --target eap:7 --target cloud-readiness --packages com.acme org.apache
 ----
 
 [discrete]
 === Overriding {ProductShortName} properties
 
 To override the default _Fernflower_ decompiler, pass the `-Dwindup.decompiler` argument on the command line. For example, to use the _Procyon_ decompiler, use the following syntax:
 
-[source,options="nowrap",subs="+quotes"]
+[source,terminal]
 ----
-$ <MTA_HOME>/bin/mta-cli -Dwindup.decompiler=procyon --input <INPUT_ARCHIVE_OR_DIRECTORY> --output <OUTPUT_REPORT_DIRECTORY> --target <TARGET_TECHNOLOGY> --packages <PACKAGE_1> <PACKAGE_2>
+$ <MTA_HOME>/bin/mta-cli -Dwindup.decompiler=procyon \
+    --input <INPUT_ARCHIVE_OR_DIRECTORY> --output <OUTPUT_REPORT_DIRECTORY> \
+    --target <TARGET_TECHNOLOGY> --packages <PACKAGE_1> <PACKAGE_2>
 ----
 
-[discrete]
 [id="cli-bash-completion_{context}"]
-== About {ProductShortName} {CLINameTitle} Bash completion
+== {ProductShortName} {CLINameTitle} Bash completion
 
 The {ProductShortName} {CLIName} provides an option to enable Bash completion for Linux systems, allowing the {ProductShortName} command-line arguments to be auto completed by pressing the Tab key when entering the commands. For instance, when Bash completion is enabled, entering the following displays a list of available arguments.
 
-[source,options="nowrap",subs="+quotes"]
+[source,terminal]
 ----
 $ <MTA_HOME>/bin/mta-cli [TAB]
 ----
@@ -85,7 +94,7 @@ $ <MTA_HOME>/bin/mta-cli [TAB]
 
 To enable Bash completion for the current shell, execute the following command:
 
-[source,options="nowrap",subs="+quotes"]
+[source,terminal]
 ----
 $ source <MTA_HOME>/bash-completion/mta-cli
 ----
@@ -98,25 +107,24 @@ The following commands allow Bash completion to persist across restarts:
 
 * To enable Bash completion for a specific user across system restarts, include the following line in that user's `~/.bashrc` file.
 +
-[source,options="nowrap",subs="+quotes"]
+[source,terminal]
 ----
 source <MTA_HOME>/bash-completion/mta-cli
 ----
 
 * To enable Bash completion for all users across system restarts, copy the {ProductName} {CLIName} Bash completion file to the `/etc/bash_completion.d/` directory as the root user.
 +
-[source,options="nowrap",subs="+quotes"]
+[source,terminal]
 ----
 # cp <MTA_HOME>/bash-completion/mta-cli /etc/bash_completion.d/
 ----
 
-[discrete]
 [id="accessing-help_{context}"]
 == Accessing {ProductShortName} help
 
 To see the complete list of available arguments for the `mta-cli` command, open a terminal, navigate to the `<MTA_HOME>` directory, and execute the following command:
 
-[source, options="nowrap",subs="+quotes"]
+[source,terminal]]
 ----
 $ <MTA_HOME>/bin/mta-cli --help
 ----

docs/topics/proc_cli-execute.adoc

@@ -18,7 +18,7 @@ To execute the rules, use the target `jakarta-ee`.
 
 link:https://docs.openrewrite.org/[OpenRewrite] automates large-scale, distributed source code refactoring. You can execute OpenRewrite recipes by using the link:{ProductDocUserGuideURL}[{ProductShortName} CLI].
 
-The first OpenRewrite recipe, which is shipped with {ProductShortName} 5.2.1, renames imported `javax` packages to their `jakarta` equivalents. 
+The OpenRewrite recipe `org.jboss.windup.JavaxToJakarta`, which is shipped with {ProductShortName} 5.2.1, renames imported `javax` packages to their `jakarta` equivalents.
 
 [IMPORTANT]
 ====

docs/topics/proc_using-openrewrite-recipes.adoc

@@ -0,0 +1,43 @@
+// Module included in the following module:
+//
+// * docs/topics/cli-run
+
+[id=using-openrewrite-recipes_{context}]
+= Using OpenRewrite recipes
+
+[IMPORTANT]
+====
+OpenRewrite recipe support is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
+
+See link:{KBArticleTechnologyPreview}[Technology Preview features support scope] on the Red Hat Customer Portal for information about the support scope for Technology Preview features.
+====
+
+You can refactor the source code of Java applications by using link:https://docs.openrewrite.org/[OpenRewrite] recipes with the {ProductShortName} CLI.
+
+The OpenRewrite recipe `org.jboss.windup.JavaxToJakarta` renames imported `javax` packages to their `jakarta` equivalents.
+
+.Procedure
+
+. Run`mta-cli`, specifying the recipe name and the application:
++
+[source,terminal]
+----
+$ ./mta-cli --openrewrite "-DactiveRecipes=<recipe_name>"  \
+    --input </path/to/source/project> --goal dryRun
+----
+
+* `"-DactiveRecipes=<recipe name>"`: Specify the OpenRewrite recipe, for example, `org.jboss.windup.JavaxToJakarta`.
+
+* `--input`: Specify the application to be refactored.
+
+* `--goal`: Optional: The OpenRewrite Maven goal to run.
+** `dryRun` : The script returns a list of proposed changes. Ignore the `"Run 'mvn rewrite:run' to apply the recipes"` message.
+** `run`: The script applies the changes.
+
+. Run `mta-cli` with `--goal run` to apply the recipe:
++
+[source,terminal]
+----
+$ ./mta-cli --openrewrite "-DactiveRecipes=<recipe name>"  \
+    --input </path/to/source/project> --goal run
+----

docs/topics/rn-new-features.adoc

@@ -0,0 +1,83 @@
+include::topics/templates/document-attributes.adoc[]
+[id="cli-guide"]
+= CLI Guide
+
+:toc:
+:toclevels: 4
+:numbered:
+:imagesdir: topics/images
+:context: cli-guide
+:cli-guide:
+
+//Inclusive language statement
+include::topics/making-open-source-more-inclusive.adoc[]
+
+== Introduction
+
+// About the {UserCLIBookName}
+include::topics/about-cli-guide.adoc[leveloffset=+2]
+
+// About {ProductName}
+include::topics/what-is-the-toolkit.adoc[leveloffset=+2]
+
+// About the {CLINameTitle}
+include::topics/about-cli.adoc[leveloffset=+2]
+
+== Installing and Running the CLI
+
+// Install the CLI
+include::topics/installing-web-console-or-cli-tool.adoc[leveloffset=+2]
+
+// Run the CLI
+include::topics/cli-run.adoc[leveloffset=+2]
+
+// Access the Report
+include::topics/access-report.adoc[leveloffset=+2]
+
+// Review the Reports
+include::topics/review-reports.adoc[leveloffset=+1]
+
+// Export the Report in CSV Format
+include::topics/csv-export.adoc[leveloffset=+1]
+
+// Mavenize Your Application
+include::topics/mavenize.adoc[leveloffset=+1]
+
+// Optimize {ProductShortName} Performance
+include::topics/optimize-performance.adoc[leveloffset=+1]
+
+// Configure {ProductShortName} to Exclude Files and Packages
+include::topics/exclude-files-and-packages.adoc[leveloffset=+2]
+
+[appendix]
+== Reference material
+
+// {ProductShortName} Command-line Arguments
+include::topics/cli-args.adoc[leveloffset=+2]
+
+// Added in 4.3.0: list of supported Tech Tags
+include::topics/tech-tags.adoc[leveloffset=+2]
+
+// Rule Story Points
+include::topics/about-story-points.adoc[leveloffset=+2]
+
+For more information on categorizing tasks, see link:{ProductDocRulesGuideURL}/rule_categories_rules-development-guide#rule_categories_rules-development-guide[Using custom rule categories].
+
+=== Additional Resources
+
+// Get Involved
+include::topics/get-involved.adoc[leveloffset=+3]
+
+// Important Links
+include::topics/important-links.adoc[leveloffset=+3]
+
+// Report Issues with {ProductShortName}
+
+==== Reporting issues
+
+{ProductShortName} uses Jira as its issue tracking system. If you encounter an issue executing {ProductShortName}, submit a link:{JiraWindupURL}[Jira issue].
+
+// **********************************
+// * Appendix: Revision Information *
+// **********************************
+include::topics/templates/revision-info.adoc[]