MAN Help Generators

The MAN help generator is provided by the airline-help-man library. It generates help output in Troff format using MAN page specific extensions to generate Linux manual pages that can be viewed with the man tool.

Available Implementations

The following implementations are available:

ManGlobalUsageGenerator - Generates help for the entire CLI as a single manual page
ManMultiPageGlobalUsageGenerator - Generates help for the entire CLI as a series of separate manual pages
ManCommandUsageGenerator - Generates manual pages for individual commands

Example Usage

Global Help

Using ManGlobalUsageGenerator:

   Cli<ExampleRunnable> cli = new Cli<ExampleRunnable>(ShipItCli.class);
        
   GlobalUsageGenerator<ExampleRunnable> helpGenerator = new ManGlobalUsageGenerator<>();
   try {
       helpGenerator.usage(cli.getMetadata(), System.out);
   } catch (IOException e) {
       e.printStackTrace();
   }

Using ManMultiPageGlobalUsageGenerator:

   Cli<ExampleRunnable> cli = new Cli<ExampleRunnable>(ShipItCli.class);
        
   GlobalUsageGenerator<ExampleRunnable> helpGenerator = new ManMultiPageGlobalUsageGenerator<>();
   try {
       helpGenerator.usage(cli.getMetadata(), System.out);
   } catch (IOException e) {
       e.printStackTrace();
   }

Command Help

Using ManCommandUsageGenerator:

SingleCommand<Price> command = new SingleCommand<Price>(Price.class);

CommandUsageGenerator generator = new ManCommandUsageGenerator();
try {
    generator.usage(null, null, "price", command.getCommandMetadata(), command.getParserConfiguration(), System.out);
} catch (IOException e) {
    e.printStackTrace();
}

Customisation

The main point of customisation for manual pages is the manual section which is typically baked into the filename of manual pages e.g. sort.1. Depending on the command you may wish to place it in a different manual section e.g.

CommandUsageGenerator generator = new ManCommandUsageGenerator(ManSections.SYSTEM_ADMIN_AND_DAEMONS);

Viewing the output

To view the generated output you will typically save it to an appropriately named file and then open it with the man tool e.g.

> man ./ship-it.1

Note the need to use ./ to refer to a local relative path rather than having man search for manual pages. Per the above note on customisation remember that manual pages are typically named with a file extension matching the manual section your manual belongs to.

If you want to be able to use the normal man functionality you will need to update the MANPATH environment variable to include the directory where your man pages are living e.g.

> export MANPATH=/your/output/directory:$MANPATH
> man ship-it

Improving this Documentation

This documentation is itself open source and lives in GitHub under the docs/ directory.

I am not a professional technical writer and as the developer of this software I can often make assumptions of knowledge that you as a user reading this may not have. Improvements to the documentation are always welcome, if you have suggestions for the documentation please submit pull requests to the main branch.

Airline