Better documentation.

garydgregory · garydgregory · commit 0c7e21457a74 · 2021-10-18T17:28:41.000-04:00
diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml
@@ -20,12 +20,12 @@
 <document>
 
   <properties>
-    <title>Home</title>
+    <title>Apache Commons CLI</title>
     <author email="dev@commons.apache.org">commons-dev</author>
   </properties>
 
   <body>
-    <section name="Commons CLI">
+    <section name="Apache Commons CLI">
       <p>
         The Apache Commons CLI library provides an API for parsing command line options passed to programs.
         It's also able to print help messages detailing the options available for a command line tool.
@@ -61,15 +61,6 @@ usage: ls
       </p>
     </section>
 
-    <section name="CLI 2?">
-      <p>
-        Commons CLI 1.0 was formed from the merger of ideas and code from three different libraries -
-        Werken, Avalon and Optz. In dealing with the bugs and the feature requests a freshly designed and not
-        backwards compatible CLI 2 was created in 2004, but never finished or released.
-      </p>
-      <p>The current plan is to continue to maintain the 1.x line. The CLI2 work may be found in the Commons Sandbox. </p>
-    </section>
-
     <section name="Documentation">
       <p>
         A full <a href="introduction.html">User's Guide</a> is available
@@ -112,6 +103,15 @@ usage: ls
       </p>
     </section>
 
+    <section name="CLI 2?">
+      <p>
+        Commons CLI 1.0 was formed from the merger of ideas and code from three different libraries -
+        Werken, Avalon and Optz. In dealing with the bugs and the feature requests a freshly designed and not
+        backwards compatible CLI 2 was created in 2004, but never finished or released.
+      </p>
+      <p>The current plan is to continue to maintain the 1.x line. The CLI2 work may be found in the Commons Sandbox. </p>
+    </section>
+
   </body>
 
 </document>
diff --git a/src/site/xdoc/introduction.xml b/src/site/xdoc/introduction.xml
@@ -21,19 +21,19 @@
 
   <properties>
     <author email="dev@commons.apache.org">commons-dev</author>
-    <title>Introduction</title>
+    <title>Introducing Apache Commons CLI</title>
   </properties>
 
   <body>
-    <section name="Introduction">
+    <section name="Introducing Apache Commons CLI">
       <p>
         There are three stages to command line processing.  They are the
         definition, parsing and interrogation stages.  The following 
         sections will discuss each of these stages in turn, and discuss how
         to implement them with CLI.
       </p>
     </section>
-    <section name="Definition Stage">
+    <section name="The Definition Stage">
       <p>
         Each command line must define the set of options that will be used 
         to define the interface to the application.
@@ -57,7 +57,7 @@
         instance.
       </p>
     </section>
-    <section name="Parsing Stage">
+    <section name="The Parsing Stage">
       <p>
         The parsing stage is where the text passed into the 
         application via the command line is processed.  The text is 
@@ -78,7 +78,7 @@
         instance.
       </p>
     </section>
-    <section name="Interrogation Stage">
+    <section name="The Interrogation Stage">
       <p>
         The interrogation stage is where the application queries the
         <code>CommandLine</code> to decide what execution branch to
diff --git a/src/site/xdoc/properties.xml b/src/site/xdoc/properties.xml
@@ -21,11 +21,11 @@
 
   <properties>
     <author email="dev@commons.apache.org">commons-dev</author>
-    <title>Option Properties</title>
+    <title>Defining Option Properties</title>
   </properties>
 
   <body>
-    <section name="Option Properties">
+    <section name="Defining Option Properties">
       <p>
         The following are the properties that each 
         <a href="api-release/org/apache/commons/cli/Option.html">Option</a> has.  All of these
diff --git a/src/site/xdoc/usage.xml b/src/site/xdoc/usage.xml
@@ -21,11 +21,11 @@
 
   <properties>
     <author email="dev@commons.apache.org">commons-dev</author>
-    <title>Usage Scenarios</title>
+    <title>Using Apache Commons CLI</title>
   </properties>
 
   <body>
-    <section name="Usage Scenarios">
+    <section name="Using Apache Commons CLI">
       <p>
         The following sections describe some example scenarios on how to 
         use CLI in applications.
@@ -43,7 +43,7 @@
           also printed.
         </p>
       </subsection>
-      <subsection name="Create the Options">
+      <subsection name="Creating the Options">
         <p>
           An <a href="api-release/org/apache/commons/cli/Options.html">
           Options</a> object must be created and the <code>Option</code> must be 
@@ -92,7 +92,7 @@ else {
 }</source>
         <p>
           <h4>Note.</h4>
-          As of version 1.5-SNAPSHOT (as of 7/31/2017), the
+          As of version 1.5, the
           <code>DefaultParser</code>'s constructor now has an override with
           the signature <code>DefaultParser(final boolean allowPartialMatching)</code>.
           Given the following code:
@@ -139,9 +139,8 @@ else {
       </subsection>
     </section>
 
-    <section name="Ant Example">
+    <section name="Using Ant as an Example">
       <p>
-        One of the most ubiquitous Java applications 
         <a href="http://ant.apache.org/">Ant</a> will be used
         here to illustrate how to create the <code>Options</code> required.  The following
         is the help output for Ant.
@@ -162,7 +161,7 @@ else {
   -D&lt;property>=&lt;value&gt;   use value for given property
   -find &lt;file&gt;           search for buildfile towards the root of the
                          filesystem and use it</source>
-      <subsection name="Boolean Options">
+      <subsection name="Defining Boolean Options">
         <p>
           Lets create the boolean options for the application as they
           are the easiest to create.  For clarity the constructors for
@@ -177,7 +176,7 @@ Option debug = new Option("debug", "print debugging information");
 Option emacs = new Option("emacs",
                            "produce logging information without adornments");</source>
       </subsection>
-      <subsection name="Argument Options">
+      <subsection name="Defining Argument Options">
         <p> 
           The argument options are created using the <code>Option#Builder</code>.
         </p>
@@ -213,22 +212,21 @@ Option find      = Option.builde("find")
                                 + "root of the filesystem and use it")
                          .build();</source>
       </subsection>
-      <subsection name="Java Property Option">
+      <subsection name="Defining Java Property Option">
         <p>
           The last option to create is the Java property and it is also created
           using the OptionBuilder.
         </p>
-        <source>Option property  = OptionBuilder.withArgName("property=value")
-                                .hasArgs(2)
-                                .withValueSeparator()
-                                .withDescription("use value for given property")
-                                .create("D");</source>
+        <source>Option property  = Option property  = Option.builder("D")
+                                .hasArgs()
+                                .valueSeparator('=')
+                                .build();</source>
 
           The map of properties specified by this option can later be retrieved by
           calling <code>getOptionProperties("D")</code> on the <code>CommandLine</code>.
 
       </subsection>
-      <subsection name="Create the Options">
+      <subsection name="Creating the Options">
         <p>
           Now that we have created each 
           <a href="api-release/org/apache/commons/cli/Option.html">Option</a> we need
@@ -258,7 +256,7 @@ options.addOption(property);</source>
           parse the command line arguments.
         </p>
       </subsection>
-      <subsection name="Create the Parser">
+      <subsection name="Creating the Parser">
         <p>
           We now need to create a <code>CommandLineParser</code>. This will parse the command
           line arguments, using the rules specified by the <code>Options</code> and
@@ -289,7 +287,7 @@ if(line.hasOption("buildfile")) {
     this.buildfile = line.getOptionValue("buildfile");
 }</source>
       </subsection>
-      <subsection name="Usage/Help">
+      <subsection name="Displaying Usage and Help">
         <p>
           CLI also provides the means to automatically generate usage
           and help information.  This is achieved with the
@@ -324,7 +322,7 @@ formatter.printHelp("ant", options);</source>
       </subsection>
     </section>
 
-    <section name="ls Example">
+    <section name="Creating an ls Example">
       <p>
         One of the most widely used command line applications in the *nix world
         is <code>ls</code>. Due to the large number of options required for <code>ls</code> 
@@ -337,7 +335,7 @@ Sort entries alphabetically if none of -cftuSUX nor --sort.
 
 -a, --all                  do not hide entries starting with .
 -A, --almost-all           do not list implied . and ..
--b, --escape               print octal escapes for nongraphic characters
+-b, --escape               print octal escapes for non-graphic characters
     --block-size=SIZE      use SIZE-byte blocks
 -B, --ignore-backups       do not list implied entries ending with ~
 -c                         with -lt: sort by, and show, ctime (time of last
@@ -356,14 +354,13 @@ CommandLineParser parser = new DefaultParser();
 Options options = new Options();
 options.addOption("a", "all", false, "do not hide entries starting with .");
 options.addOption("A", "almost-all", false, "do not list implied . and ..");
-options.addOption("b", "escape", false, "print octal escapes for nongraphic "
+options.addOption("b", "escape", false, "print octal escapes for non-graphic "
                                          + "characters");
-options.addOption(OptionBuilder.withLongOpt("block-size")
-                                .withDescription("use SIZE-byte blocks")
+options.addOption(Option.builder("SIZE").longOpt("block-size")
+                                .desc("use SIZE-byte blocks")
                                 .hasArg()
-                                .withArgName("SIZE")
-                                .create());
-options.addOption("B", "ignore-backups", false, "do not list implied entried "
+                                .build());
+options.addOption("B", "ignore-backups", false, "do not list implied entries "
                                                  + "ending with ~");
 options.addOption("c", false, "with -lt: sort by, and show, ctime (time of last " 
                                + "modification of file status information) with "
