This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-cli.git
The following commit(s) were added to refs/heads/master by this push:
new d727ecff Move Introduction documentation section to Javadoc
d727ecff is described below
commit d727ecffebf1e7d029e4fbecc590bbf7ccdd708f
Author: Gary D. Gregory <[email protected]>
AuthorDate: Tue Jul 29 15:57:18 2025 -0400
Move Introduction documentation section to Javadoc
---
src/main/javadoc/overview.html | 77 ++++++++++++++++++++++++++++++-
src/site/site.xml | 10 ++--
src/site/xdoc/introduction.xml | 102 -----------------------------------------
3 files changed, 81 insertions(+), 108 deletions(-)
diff --git a/src/main/javadoc/overview.html b/src/main/javadoc/overview.html
index 40143cdf..a084606a 100644
--- a/src/main/javadoc/overview.html
+++ b/src/main/javadoc/overview.html
@@ -40,7 +40,82 @@ limitations under the License.
<p>
The homepage for the project is <a
href="https://commons.apache.org";>Apache Commons</a>
</p>
-
+ <section id="Introducing">
+ <h1>Introducing Apache Commons CLI</h1>
+ <p>
+ There are three stages to command line processing. They are the
+ definition, parsing and interrogation stages. The following
+ sections discuss each of these stages in turn, and show how
+ to implement them with CLI.
+ </p>
+ <section>
+ <h2>Defining the CLI</h2>
+ <p>
+ Each command line must define the set of options that will be used
+ to define the interface to the application.
+ </p>
+ <p>
+ CLI uses the <a
href="javadocs/api-release/org/apache/commons/cli/Options.html">
+ Options</a> class, as a container for
+ <a href="javadocs/api-release/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
+ <code>Options</code>.
+ </p>
+ <p>
+ The <a href="usage.html">Usage Scenarios</a> document provides
+ examples how to create an <code>Options</code> object and also
+ provides some real world examples.
+ </p>
+ <p>
+ The result of the definition stage is an <code>Options</code>
+ instance.
+ </p>
+ </section>
+ <section>
+ <h2>Parsing the CLI</h2>
+ <p>
+ The parsing stage is where the text passed into the
+ application via the command line is processed. The text is
+ processed according to the rules defined by the parser
+ implementation.
+ </p>
+ <p>
+ The <code>parse</code> method defined on
+ <a
href="javadocs/api-release/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">
+ CommandLine</a>.
+ </p>
+ <p>
+ The result of the parsing stage is a <code>CommandLine</code>
+ instance.
+ </p>
+ </section>
+ <section>
+ <h2>Interrogating the CLI</h2>
+ <p>
+ The interrogation stage is where the application queries the
+ <code>CommandLine</code> to decide what execution branch to
+ take depending on boolean options and uses the option values
+ to provide the application data.
+ </p>
+ <p>
+ This stage is implemented in the user code. The accessor methods
+ on <code>CommandLine</code> provide the interrogation capability
+ to the user code.
+ </p>
+ <p>
+ The result of the interrogation stage is that the user code
+ is fully informed of all the text that was supplied on the command
+ line and processed according to the parser and <code>Options</code>
+ rules.
+ </p>
+ </section>
+ </section>
<section id="Using">
<h1>Using Apache Commons CLI</h1>
<p>
diff --git a/src/site/site.xml b/src/site/site.xml
index fb507740..907eb40d 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -45,11 +45,11 @@
</menu>
<!-- Specific to this component: -->
<menu name="User Guide">
- <item name="Getting started" href="/introduction.html"/>
- <item name="Using CLI" href="/apidocs/index.html#Using"/>
- <item name="Option properties" href="/apidocs/index.html#Properties"/>
- <item name="Javadoc" href="/apidocs/index.html"/>
- <item name="Javadoc Archive"
href="https://javadoc.io/doc/commons-cli/commons-cli/latest/index.html"/>
+ <item name="Getting started" href="/apidocs/index.html#Introducing"/>
+ <item name="Using CLI" href="/apidocs/index.html#Using"/>
+ <item name="Option properties" href="/apidocs/index.html#Properties"/>
+ <item name="Javadoc" href="/apidocs/index.html"/>
+ <item name="Javadoc Archive"
href="https://javadoc.io/doc/commons-cli/commons-cli/latest/index.html"/>
</menu>
</body>
</site>
diff --git a/src/site/xdoc/introduction.xml b/src/site/xdoc/introduction.xml
deleted file mode 100644
index badace56..00000000
--- a/src/site/xdoc/introduction.xml
+++ /dev/null
@@ -1,102 +0,0 @@
-<?xml version="1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- https://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-<document xmlns="http://maven.apache.org/XDOC/2.0";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
- <properties>
- <title>Introducing Apache Commons CLI</title>
- <author email="[email protected]">Apache Commons Team</author>
- </properties>
-
- <body>
- <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 discuss each of these stages in turn, and show how
- to implement them with CLI.
- </p>
- </section>
- <section name="Defining the CLI">
- <p>
- Each command line must define the set of options that will be used
- to define the interface to the application.
- </p>
- <p>
- CLI uses the <a
href="javadocs/api-release/org/apache/commons/cli/Options.html">
- Options</a> class, as a container for
- <a href="javadocs/api-release/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
- <code>Options</code>.
- </p>
- <p>
- The <a href="usage.html">Usage Scenarios</a> document provides
- examples how to create an <code>Options</code> object and also
- provides some real world examples.
- </p>
- <p>
- The result of the definition stage is an <code>Options</code>
- instance.
- </p>
- </section>
- <section name="Parsing the CLI">
- <p>
- The parsing stage is where the text passed into the
- application via the command line is processed. The text is
- processed according to the rules defined by the parser
- implementation.
- </p>
- <p>
- The <code>parse</code> method defined on
- <a
href="javadocs/api-release/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">
- CommandLine</a>.
- </p>
- <p>
- The result of the parsing stage is a <code>CommandLine</code>
- instance.
- </p>
- </section>
- <section name="Interrogating the CLI">
- <p>
- The interrogation stage is where the application queries the
- <code>CommandLine</code> to decide what execution branch to
- take depending on boolean options and uses the option values
- to provide the application data.
- </p>
- <p>
- This stage is implemented in the user code. The accessor methods
- on <code>CommandLine</code> provide the interrogation capability
- to the user code.
- </p>
- <p>
- The result of the interrogation stage is that the user code
- is fully informed of all the text that was supplied on the command
- line and processed according to the parser and <code>Options</code>
- rules.
- </p>
- </section>
- </body>
-</document>
