build-manual

This tasks builds the application manual. It uses the metadata provided by the element definitions (e.g. for a task in the task’s .adoc file) and the general text from the application manual folder in etc/manual. The actual manual text comes from the AsciiDoctor files with the extension adoc. Element lists (e.g. for tasks or parameters) also use the description from the elements definition (in the id file).

Building the manual involves different steps, depending on the selected target:

  • ADOC: generate an aggregated ADOC file with all text and lists.

  • TEXT: convert the ADOC text into well-formatted paragraphs of plain or ANSI text, then build aggregated documents for text or ANSI formatted text. The converted text is saved in the txt file along with the original adoc file, since it is also used for the online help.

  • MANP, PDF, HTML: use the aggregated ADOC file and the AsciiDoctor tool chain to generate a manpage, a single HTML file, or a PDF file. These targets require AsciiDoctor (manp, html) and AsciiDoctor-PDF (pdf) installed.

For all targets, the task will validate the installation to ensure that all required manual source files (adoc and txt files) are accessible. If the validation does not pass successfully, no manual artifact will be build.

The general structure is the same for all targets, i.e. the task will create the same manual just for different output formats. The structure is similar to other manual pages:

  • Name and Synopsis: name, tag line, general description on how to start the application

  • Description: a description of the application

  • Options: a description of command line (CLI) options, including a list of options Options are further categorized as exit options (application will process option and exit) and runtime options (directing runtime behavior).

  • Parameters: a description and list of parameters that can be used to configure the application and its tasks.

  • Tasks: a description and list of tasks provided by the application

  • Dependencies: a description and list of dependencies (that tasks might require)

  • Shell Commands: a description and list of commands the interactive shell provides

  • Exit Status: a description and list of the different exit status codes and messages.

  • Scenarios: a description and list of scenarios provided by the application

  • Security Concerns: remarks on potential or actual security concerns when running the application

  • Bugs: notes on known bugs

  • Authors: list of authors

  • Resources: list of resources

  • Copying: notes on copyright and other related aspects

The task then provides negative filters to exclude parts of this general structure (with the exception of name and synopsis). This allows to generate tailored manuals for any application need.

The generated targets can also be tested, i.e. shown using external applications. All text formats (adoc, plain text, ANSI formatted text, annotated text) are shown using less. The manpage is shown using the command man. HTML and PDF files are shown with a web browser and a PDF reader, respectively. Note: the parameters BROWSER and PDF_READER must be set to test these targets.

Depending on the selected targets, the task generates the following output files:

  • $APP_HOME/doc/manual/{app-name}.adoc - aggregated ADOC file with all text for the manual

  • $APP_HOME/doc/manual/{app-name}.text - plain text file manual

  • $APP_HOME/doc/manual/{app-name}.text-anon - annotated plain text manual

  • $APP_HOME/doc/manual/{app-name}.ansi - ANSI formatted text manual

  • $APP_HOME/doc/manual/{app-name}.html - single file HTML manual

  • $APP_HOME/doc/manual/{app-name}.pdf - single file PDF manual

  • $APP_HOME/man/man1/{app-name}.1 - the generated manpage

In warning and info level, the task does not output any information (except errors). In debug level, the task provides detailed information about the progress. Build all targets, including the ADOC to text transformation, can take a few minutes even on a powerful host.

Configuration

The task can be configured with two parameters:

  • SKB_FW_TOOL - optional, to find the tool for ADOC to text conversion, if not set, the target src cannot be build. This also requires the dependency jre to execute the tool.

  • MANUAL_SRC - optional, to set the source directory for the application related parts of the manual. If used, it must be a directory, readable, and with the correct source files (to pass validation).

Manual Source

The general text for the manual is located in the directory pointed to by the parameter MANUAL_SRC. This directory must have the following layout and contents:

MANUAL_SRC
    ├─── application                (1)
    │    ├─── authors.adoc          (2)
    │    ├─── bugs.adoc             (3)
    │    ├─── copying.adoc          (4)
    │    ├─── description.adoc      (5)
    │    ├─── resources.adoc        (6)
    │    └─── security.adoc         (7)
    ├─── elements                   (8)
    │    ├─── commands.adoc         (9)
    │    ├─── dependencies.adoc     (10)
    │    ├─── exit-options.adoc     (11)
    │    ├─── exit-status.adoc      (12)
    │    ├─── options.adoc          (13)
    │    ├─── parameters.adoc       (14)
    │    ├─── run-options.adoc      (15)
    │    ├─── scenarios.adoc        (16)
    │    └─── tasks.adoc            (17)
    └─── tags                       (18)
         ├─── authors.txt           (19)
         └─── name.txt              (20)

  1. Directory with general application text, the .adoc source must be present, the .txt files can be generated using the target src. For multi-paragraph text, use an empty line to separate paragraphs. To add a list, add an empty line and then each list element in a single line starting with an asteriks *. Finish the list with an empty line. Nested lists are not supported.

  2. List of authors.

  3. Statements on bugs, known problems, etc.

  4. Statements on copyright, licenses, etc.

  5. A description of the application.

  6. Links to resources, for instance a source repository or issue management or a web site.

  7. Statements on security concerns when using the application.

  8. Directory with text for the framework elements, the .adoc source must be present, the .txt files can be generated using the target src. For the ADOC source, the same rules as for the application directory apply.

  9. Introduction to shell commands.

  10. Introduction and text for dependencies.

  11. Text for exit command line options.

  12. Text for exit status codes and error messages.

  13. Introduction and text for command line options.

  14. Introduction and text for parameters.

  15. Text for runtime command line options.

  16. Introduction and text for scenarios.

  17. Introduction and text for tasks.

  18. Directory with tags, these files are used as plain text files.

  19. A list of authors, used in the ADOC file header.

  20. A tag line for the application, used in the name and synopsis sections.

General Options

Following the SKB-Framework convention, the task has two main options: clean to remove built manual artifacts and build to build them. When build is used, other general options and filters can be used to direct the build:

  • all - build everything (src, primary targets, secondary targets)

  • primary - build all primary targets, i.e. src and adoc

  • secondary - build all secondary targets, i.e. text (plain, ANSI, annotated), manp, html, and pdf

-A | --all         set all targets, overwrites other options
-b | --build       builds a manual (manpage), requires a target
-c | --clean       removes all target artifacts
-h | --help        print help screen and exit
-p | --primary     set all primary targets
-s | --secondary   set all secondary targets
-t | --test        test a manual (show results), requires a target

Target Options

Targets can also be selected individually. The target options can be used in any sequence in the command line, the task will automatically generate all manual artifacts in the correct order. For the secondary targets that require adoc to be build, the task will also automatically generate adoc if the file does not exist. Text sources (target src) are not created automatically, only on request.

--adoc        secondary target: text versions: ansi, text
--html        secondary target: HTML file
--manp        secondary target: man page file
--pdf         secondary target: PDF file)
--text        secondary target: text versions: ansi, text
--src         primary target: text source files from ADOC

Element List Filters

Some parts of the manual list application elements. For selected element types, the element list filters can be used to direct what these lists contain:

  • loaded - applies to task lists and scenario lists. If not used, all tasks and all scenarios will be listed. If this option is used, only the loaded tasks and scenarios are listed. Loaded here means that the elements are defined for mode the application was started in and have been successfully loaded.

  • install - do list tasks and scenarios that are defined for the application mode flavor install By default, tasks and scenarios defined for the application mode flavor install are not listed in the manual. If used, any task or scenario defined for the flavor install will be listed. This filter also extends to parameters and dependencies. If used, parameters and dependencies that are only required by one or more install tasks or scenarios will be listed.

  • requested - applies to dependency lists and parameter lists. If not used, all dependencies and all parameters will be listed. If this option is used, only the requested dependencies and parameters are listed. Requested here means any dependency or parameter requested by a loaded task.

-I | --install     do list 'install' app mode flavor tasks and scenarios
-l | --loaded      list only loaded tasks and scenarios
-r | --requested   list only requested dependencies and parameters

Application Filters

These filters are negative filters to exclude general (application related) parts of the manual. The option name corresponds to the heading in the general manual structure described above. The default behavior is to include all general parts.

--no-authors           do not include authors
--no-bugs              do not include bugs
--no-copying           do not include copying
--no-resources         do not include resources
--no-security          do not include security

Element Filters

These filters are negative filters to exclude element description or element lists. By default, all element descriptions and all element lists are included in the manual. To no show a list, use the no-*-list options. To now show any description for an element type, use the no-* options (without -list).

To give an example: to show all information about tasks do not use any of these filters. To show the general text, but no task list, use --no-task-list. To no show any information about tasks, use --no-tasks.

--no-commands          do not include commands
--no-command-list      include command text, but no list
--no-deps              include dependency text, but no list
--no-dep-list          do not include dependencies
--no-exitstatus        do not include exit status
--no-exitstatus-list   include exit status text, but no list
--no-options           do not include options
--no-option-list       include option test, but no list
--no-params            do not include parameters
--no-param-list        include parameter text, but no list
--no-scenarios         do not include scenarios
--no-scenario-list     include scenario text, but no list
--no-tasks             do not include tasks
--no-task-list         include task text, but no list

Examples

The following example will use the framework tool to convert adoc sources into well-formatted plain text.

build-manual --build --src

The following examples builds the targets adoc, text, manp, html, and pdf. All tasks and scenarios will be listed. Only requested dependencies and parameters will be listed.

build-manual --build --requested --adoc --text --manp --html --pdf

Task Requirements

The task has the following requirements:

  • SKB_FW_TOOL - optional, to find the tool for ADOC to text conversion, if not set, the target src cannot be build. This also requires the dependency jre to execute the tool.

  • MANUAL_SRC - optional, to set the source directory for the application related parts of the manual. If used, it must be a directory, readable, and with the correct source files (to pass validation).

  • asciidoctor - optional dependency required to generate manp and html targets. If it does not exist, these targets cannot be generated.

  • asciidoctor-pdf - optional dependency required to generate the pdf target. If it does not exist, this target cannot be generated.

  • start-browser - optional task to start a web browser testing the generated html target. If not present,not successfully loaded, or has missing parameters, the target html cannot be tested.

  • start-pdf-viewer - optional task to start a PDF reader testing the generated pdf target If not present,not successfully loaded, or has missing parameters, the target pdf cannot be tested.

The task will automatically test of the required directories exist. If not, they need to be created manually, since the task does not create any directories:

  • $APP_HOME/man/man1 - for the manp target

  • $APP_HOME/doc/manual - for all other targets

A few standard framework tasks are also required (all of them are mandatory and included in a standard framework installation):

  • describe-option - this task is used to generate option lists.

  • describe-parameter - this task is used to generate the parameter list.

  • describe-task - this task is used to generate the task list it is a mandatory.

  • describe-dependency - this task is used to generate the dependency list.

  • describe-existatus - this task is used to generate the exit status list.

  • describe-command - this task is used to generate the command list.

  • describe-scenario - this task is used to generate the scenario list.

  • validate-installation - this task is used to validate all input required for the manual, i.e. adoc and txt files

Notes

This task will change directories and files in the application (or framework) installation. Sufficient permissions must exist to run this task successfully.