From 8c8124e92539f79aa187b663ae1553796116ae3f Mon Sep 17 00:00:00 2001
From: Elric V <githubelric@melnib.one>
Date: Sun, 31 May 2026 16:58:38 +0200
Subject: [PATCH] Fix broken Javadoc links, replace deprecated methods in usage
 examples, and add a missing method to HelpFormatter

---
 .../cli/help/AbstractHelpFormatter.java       | 13 +++++
 src/main/javadoc/overview.html                | 58 +++++++++----------
 .../commons/cli/help/HelpFormatterTest.java   | 20 +++++++
 3 files changed, 62 insertions(+), 29 deletions(-)

diff --git a/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java b/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
index 7a370e129..0e40df300 100644
--- 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}.
+     */
+    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
index 42929e5ca..6c142b239 100644
--- 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,33 +288,33 @@ <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>
@@ -322,10 +322,10 @@ <h2>Defining Java Property Option</h2>
           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>
diff --git a/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java b/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
index 4e54fb29f..6b3065664 100644
--- a/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
+++ b/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
@@ -147,6 +147,26 @@ void testPrintHelp() throws IOException {
         assertEquals(0, sb.length(), "Should not write to output");
     }
 
+    @Test
+    void testPrintHelpWithDefaults() throws IOException {
+        final StringBuilder sb = new StringBuilder();
+        final TextHelpAppendable serializer = new TextHelpAppendable(sb);
+        HelpFormatter formatter = HelpFormatter.builder().setHelpAppendable(serializer).get();
+
+        final Options options = new Options().addOption(Option.builder("a").since("1853").hasArg().desc("aaaa aaaa aaaa aaaa aaaa").get());
+
+        List<String> expected = new ArrayList<>();
+        expected.add(" usage:  commandSyntax");
+        expected.add("");
+        expected.add(" Options      Since           Description       ");
+        expected.add(" -a <arg>     1853      aaaa aaaa aaaa aaaa aaaa");
+        expected.add("");
+
+        formatter.printHelp("commandSyntax", options);
+        List<String> actual = IOUtils.readLines(new StringReader(sb.toString()));
+        assertEquals(expected, actual);
+    }
+
     /**
      * Tests example from the mailing list that caused an infinite loop.
      *