Mu-L · pull · Jun 27, 2026 · Jun 27, 2026 · Jun 27, 2026 · Jun 27, 2026
diff --git a/pom.xml b/pom.xml
@@ -24,7 +24,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>commons-cli</groupId>
   <artifactId>commons-cli</artifactId>
-  <version>1.11.1-SNAPSHOT</version>
+  <version>1.12.0-SNAPSHOT</version>
   <name>Apache Commons CLI</name>
   <inceptionYear>2002</inceptionYear>
   <description>
@@ -91,8 +91,8 @@
     <maven.compiler.target>1.8</maven.compiler.target>
     <commons.componentid>cli</commons.componentid>
     <commons.module.name>org.apache.commons.cli</commons.module.name>
-    <commons.release.version>1.11.1</commons.release.version>
-    <commons.release.next>1.11.2</commons.release.next>
+    <commons.release.version>1.12.0</commons.release.version>
+    <commons.release.next>1.12.1</commons.release.next>
     <commons.release.name>commons-cli-${commons.release.version}</commons.release.name>
     <commons.release.isDistModule>true</commons.release.isDistModule>
     <commons.rc.version>RC1</commons.rc.version>

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -22,11 +22,12 @@
     <title>Apache Commons CLI Release Notes</title>
   </properties>
   <body>
-    <release version="1.11.1" date="YYYY-MM-DD" description="This is a feature and maintenance release. Java 8 or later is required.">
+    <release version="1.12.0" date="YYYY-MM-DD" description="This is a feature and maintenance release. Java 8 or later is required.">
       <!-- FIX -->
       <action type="fix" dev="ggregory" due-to="Elric">Fix broken Introduction links on the website #417.</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Fix malformed Javadoc comments.</action>
       <action type="fix" dev="ggregory" due-to="Dan Ziemba, Ken Dombeck, Gary Gregory" issue="CLI-352">Correct HelpFormatter Javadoc #418.</action>
+      <action type="fix" dev="ggregory" due-to="Elric, Gary Gregory">Fix broken Javadoc links, replace deprecated methods in usage examples, and add a missing method to HelpFormatter (#424).</action>
       <!-- ADD -->
       <!-- UPDATE -->
       <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 91 to 102 #414, #416.</action>

diff --git a/src/main/java/org/apache/commons/cli/Converter.java b/src/main/java/org/apache/commons/cli/Converter.java
@@ -37,27 +37,27 @@ public interface Converter<T, E extends Exception> {
     // See also Apache Commons Lang FailableFunction
 
     /**
-     * The default converter. Does nothing.
+     * The default converter does nothing.
      */
     Converter<?, RuntimeException> DEFAULT = s -> s;
 
     /**
-     * Class name converter. Calls {@link Class#forName(String)}.
+     * Converts a String to a {@link Class}. Calls {@link Class#forName(String)}.
      */
     Converter<Class<?>, ClassNotFoundException> CLASS = Class::forName;
 
     /**
-     * File name converter. Calls {@link File#File(String)}.
+     * Converts a String to a {@link File}. Calls {@link File#File(String)}.
      */
     Converter<File, NullPointerException> FILE = File::new;
 
     /**
-     * Path converter. Calls {@link Paths#get(java.net.URI)}.
+     * Converts a String to a {@link Path}. Calls {@link Paths#get(String, String...)}.
      */
     Converter<Path, InvalidPathException> PATH = Paths::get;
 
     /**
-     * Number converter. Converts to a Double if a decimal point ('.') is in the string or a Long otherwise.
+     * Converts a String to a {@link Number}. Converts to a Double if a decimal point ('.') is in the string or a Long otherwise.
      */
     Converter<Number, NumberFormatException> NUMBER = s -> s.indexOf('.') != -1 ? (Number) Double.valueOf(s) : (Number) Long.valueOf(s);
 
@@ -69,12 +69,12 @@ public interface Converter<T, E extends Exception> {
     Converter<Object, ReflectiveOperationException> OBJECT = s -> CLASS.apply(s).getConstructor().newInstance();
 
     /**
-     * Creates a URL. Calls {@link URL#URL(String)}.
+     * Converts a String to a {@link URL}. Calls {@link URL#URL(String)}.
      */
     Converter<URL, MalformedURLException> URL = URL::new;
 
     /**
-     * Converts to a date using the format string Form "EEE MMM dd HH:mm:ss zzz yyyy".
+     * Converts a String to a {@link Date} using the format string Form "EEE MMM dd HH:mm:ss zzz yyyy".
      */
     Converter<Date, java.text.ParseException> DATE = s -> new SimpleDateFormat("EEE MMM dd HH:mm:ss zzz yyyy").parse(s);
 

diff --git a/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java b/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
@@ -284,6 +284,19 @@ public final String getSyntaxPrefix() {
      */
     protected abstract TableDefinition getTableDefinition(Iterable<Option> options);
 
+    /**
+     * Prints the help for {@link Options} with the specified command line syntax,
+     * without printing a header, footer, or autoUsage.
+     *
+     * @param cmdLineSyntax the syntax for this application.
+     * @param options       the collection of {@link Option} objects to print.
+     * @throws IOException If the output could not be written to the {@link HelpAppendable}.
+     * @since 1.12.0
+     */
+    public void printHelp(final String cmdLineSyntax, final Options options) throws IOException {
+        printHelp(cmdLineSyntax, null, options, null, false);
+    }
+
     /**
      * Prints the help for {@link Options} with the specified command line syntax.
      *

diff --git a/src/main/javadoc/overview.html b/src/main/javadoc/overview.html
@@ -58,9 +58,9 @@ <h2>Defining the CLI</h2>
         to define the interface to the application.
       </p>
       <p>
-        CLI uses the <a href="javadocs/api-release/org/apache/commons/cli/Options.html">
+        CLI uses the <a href="org/apache/commons/cli/Options.html">
         Options</a> class, as a container for 
-        <a href="javadocs/api-release/org/apache/commons/cli/Option.html">
+        <a href="org/apache/commons/cli/Option.html">
         Option</a> instances.  There are two ways to create
         <code>Option</code>s in CLI.  One of them is via the constructors,
         the other way is via the factory methods defined in 
@@ -86,11 +86,11 @@ <h2>Parsing the CLI</h2>
       </p>
       <p>
         The <code>parse</code> method defined on 
-        <a href="javadocs/api-release/org/apache/commons/cli/CommandLineParser.html">
+        <a href="org/apache/commons/cli/CommandLineParser.html">
         CommandLineParser</a> takes an <code>Options</code>
         instance and a <code>String[]</code> of arguments and 
         returns a 
-        <a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html">
+        <a href="org/apache/commons/cli/CommandLine.html">
         CommandLine</a>.
       </p>
       <p>
@@ -142,7 +142,7 @@ <h2>Using a boolean option</h2>
       <section>
         <h2>Creating the Options</h2>
         <p>
-          An <a href="javadocs/api-release/org/apache/commons/cli/Options.html">
+          An <a href="org/apache/commons/cli/Options.html">
           Options</a> object must be created and the <code>Option</code> must be 
           added to it.
         </p>
@@ -177,7 +177,7 @@ <h2>Parsing the command line arguments</h2>
         <p>
           Now we need to check if the <code>t</code> option is present.  To do
           this we will interrogate the 
-          <a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html">CommandLine
+          <a href="org/apache/commons/cli/CommandLine.html">CommandLine
           </a> object.  The <code>hasOption</code> method takes a 
           <code>java.lang.String</code> parameter and returns <code>true</code> if the option 
           represented by the <code>java.lang.String</code> is present, otherwise 
@@ -288,44 +288,44 @@ <h2>Defining Argument Options</h2>
                          .argName("file")
                          .hasArg()
                          .desc("use given file for log")
-                         .build();
+                         .get();
 
 Option logger = Option.builder("logger")
                          .argName("classname")
                          .hasArg()
                          .desc("the class which it to perform logging")
-                         .build();
+                         .get();
 
 Option listener = Option.builder("listener")
                          .argName("classname")
                          .hasArg()
                          .desc("add an instance of class as "
                                 + "a project listener")
-                         .build();
+                         .get();
 
 Option buildFile = Option.builder("buildfile")
                          .argName("file")
                          .hasArg()
                          .desc("use given buildfile")
-                         .build();
+                         .get();
 
 Option find = Option.builder("find")
                          .argName("file")
                          .hasArg()
                          .desc("search for buildfile towards the "
                                 + "root of the filesystem and use it")
-                         .build();</code></pre>
+                         .get();</code></pre>
       </section>
       <section>
         <h2>Defining Java Property Option</h2>
         <p>
           The last option to create is the Java property, and it is also created
           using the Option class' Builder.
         </p>
-        <code>Option property  = Option property  = Option.builder("D")
+        <pre><code>Option property = Option.builder("D")
                                 .hasArgs()
                                 .valueSeparator('=')
-                                .build();</code>
+                                .get();</code></pre>
         <p>
           The map of properties specified by this option can later be retrieved by
           calling <code>getOptionProperties("D")</code> on the <code>CommandLine</code>.
@@ -335,11 +335,11 @@ <h2>Defining Java Property Option</h2>
         <h2>Creating the Options</h2>
         <p>
           Now that we have created each 
-          <a href="javadocs/api-release/org/apache/commons/cli/Option.html">Option</a> we need
+          <a href="org/apache/commons/cli/Option.html">Option</a> we need
           to create the 
-          <a href="javadocs/api-release/org/apache/commons/cli/Options.html">Options</a>
+          <a href="org/apache/commons/cli/Options.html">Options</a>
           instance.  This is achieved using the 
-          <a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html#addOption(org.apache.commons.cli.Option)">addOption</a>
+          <a href="org/apache/commons/cli/CommandLine.html#addOption(org.apache.commons.cli.Option)">addOption</a>
           method of <code>Options</code>.
         </p>
         <pre><code>Options options = new Options();
@@ -351,10 +351,10 @@ <h2>Creating the Options</h2>
 options.addOption(verbose);
 options.addOption(debug);
 options.addOption(emacs);
-options.addOption(logfile);
+options.addOption(logFile);
 options.addOption(logger);
 options.addOption(listener);
-options.addOption(buildfile);
+options.addOption(buildFile);
 options.addOption(find);
 options.addOption(property);</code></pre>
         <p>
@@ -367,7 +367,7 @@ <h2>Creating the Parser</h2>
         <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
-          return an instance of <a href="javadocs/api-release/org/apache/commons/cli/CommandLine.html">CommandLine</a>.
+          return an instance of <a href="org/apache/commons/cli/CommandLine.html">CommandLine</a>.
         </p>
         <pre><code>public static void main(String[] args) {
     // create the parser
@@ -399,7 +399,7 @@ <h2>Displaying Usage and Help</h2>
         <p>
           CLI also provides the means to automatically generate usage
           and help information.  This is achieved with the
-          <a href="javadocs/api-release/org/apache/commons/cli/HelpFormatter.html">HelpFormatter</a>
+          <a href="apidocs/org/apache/commons/cli/help/HelpFormatter.html">HelpFormatter</a>
           class.
         </p>
         <pre><code>// automatically generate the help statement
@@ -454,7 +454,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
 -C                         list entries by columns</code></pre>
       <p>
         The following is the code that is used to create the 
-        <a href="javadocs/api-release/org/apache/commons/cli/Options.html">Options</a> for this example.
+        <a href="org/apache/commons/cli/Options.html">Options</a> for this example.
       </p>
       <pre><code>// create the command line parser
 CommandLineParser parser = new DefaultParser();
@@ -468,7 +468,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
 options.addOption(Option.builder("SIZE").longOpt("block-size")
                                 .desc("use SIZE-byte blocks")
                                 .hasArg()
-                                .build());
+                                .get());
 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 " 
@@ -506,7 +506,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
                   .hasArg()
                   .desc("the number of things")
                   .type(Integer.class)
-                  .build();
+                  .get();
     Options options = new Options().addOption(count);
     // create the parser
     CommandLineParser parser = new DefaultParser();
@@ -561,7 +561,7 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
           .hasArg()
           .desc("the foo arg")
           .converter(Foo::new)
-          .build();</code></pre>
+          .get();</code></pre>
         <p>
             The above will create an option that passes the string value to the Foo constructor when <code>commandLine.getParsedOptionValue(fooOpt)</code> is called.
         </p>
@@ -595,12 +595,12 @@ <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; pad
           .hasArg()
           .desc("the number of things")
           .type(Integer.class)
-          .build();
+          .get();
       Option count = Option.builder("count")
           .hasArg()
           .desc("the number of things")
           .type(Integer.class)
-          .build();
+          .get();
       Options options = new Options().addOption(n).addOption(count);
 
       doSomething(options);
@@ -653,7 +653,7 @@ <h2>Changing Usage Announcement</h2>
           }
           System.err.printf("ERROR: Option %s: %s%n", buf, o.getDeprecated());
       };
-      DefaultParser parser = DefaultParser.builder().setDeprecatedHandler(deprecatedUsageAnnouncement).build();
+      DefaultParser parser = DefaultParser.builder().setDeprecatedHandler(deprecatedUsageAnnouncement).get();
       CommandLine line;
       try {
           // parse the command line arguments
@@ -728,10 +728,10 @@ <h2>Changing help format</h2>
       <h1><img src="org/apache/commons/cli/doc-files/leaf.svg" style="height: 1em; padding-right: 0.25em" alt="leaf">7. Defining Option Properties</h1>
       <p>
         The following are the properties that each 
-        <a href="javadocs/api-release/org/apache/commons/cli/Option.html">Option</a> has.  All of these
+        <a href="org/apache/commons/cli/Option.html">Option</a> has.  All of these
         can be set using the accessors or using the methods
         defined in the
-        <a href="javadocs/api-release/org/apache/commons/cli/Option.Builder.html">Option.Builder</a>.
+        <a href="org/apache/commons/cli/Option.Builder.html">Option.Builder</a>.
       </p>
       <table>
         <caption>Option Properties</caption>