Packaging and Use guide for yaCLI Tools

yaCLI Tools is a command-line application with a command to generate documentation of a yaCLI-based Java application in man page format.

This is a guide that explains how to obtain the .jar file and later, how use the yaCLI Tools app.

Before starting

There are some requierements (tools and programs) that are needed for the success of this processes, which are:

• Have Maven installed.
• Have Java 11 SE installed and configured.
• Recommended to have the latests version of the yaCLI Tools project.

If you already meet this requirements, you are free to continue.

Packaging

This section is all about packaging process. It will provide some insights and guidelines on how to obtain the .jar executable file for the Java To Distributable app.

The steps are rather simple:

1. First, open a command prompt.
2. Now, navigate to the project's root folder.
3. Finally, execute the following command:

user@machine:~$ mvn clean package

After all the process is completed, you should be left with all the produced files on the “target” folder of the project.

This includes the .jar executables of the yaCLI Tools app.

Use guide

This section provides a use guide for the yaCLI Tools app.

As the previous section, the use of the app is very simple:

1. Open a command prompt.
2. Now, you can use the app as follows:

user@machine:~$ java -jar <path_to_your_desired_jar> COMMAND [ARGS…]

It is recommended that you use the yacli-tools-<VERSION>-jar-with-dependencies-and-services.jar so you can use all the features of the application without problems.

You can see more about the yaCLI Tools commands and options in the “Example_yaCLI_Tools_commands.md” file.

Choices.xml file

The choices.xml file is a user provided XML for man page info overwrite. Its format is simple. All of its elements are optional, can be in any order, and all hang from the root <choice> element. But there are a few exceptions to the latter, such as the <license>, <developer> and <contributor> elements that hang from the <licenses>, <developers> and <contributors> tags respectively.

The tags that can be placed in the choices.xml file are:

• <projectName> represents the name of the application project.
• <manSection> represents the man section that this application fits into.
• <appManTitle> represents the full name of the application.
• <versionNumber> represents the current version of the application.
• <lastModifiedDate> represents the last modification date of the application's man page.
• <commandName> represents the name of the command with which the application is executed.
• <shortDescription> represents a summary of the application.
• <description> represents the description of the application.
• <documentationURL> represents the URL of the application home page.
• <licenses> represents/contains a set of <license>
  • <license> represents a license of the application.
    • <licenseName> represents the name of the license.
    • <licenseURL> represents the URL of the license information.
• <developers> represents/contains a set of <developer>
  • <developer> represents a developer of the application.
    • <developerName> represents the developer name.
• <contributors> represents/contains a set of <contributor>
  • <contributor> represents a contributor of the application.
    • <contributorName> represents the contributor name.

Commands

The execution of a command produces a different file. The commands available are:

• generate-man
• generate-completion

Small examples of the execution of these commands are:

yct generate-man --input-pom-file pom.xml --yacli-class-name es.uvigo.esei.sing.yacli.tools.cli.YaCliToolsApplication --output-directory /tmp/

yct generate-completion --input-pom-file pom.xml --yacli-class-name es.uvigo.esei.sing.yacli.tools.cli.YaCliToolsApplication --output-directory /tmp/