Customizing Help Output

The option system builds help, version, and error output as neutral TextDocument trees. This page explains how Application renders these documents, how to render them manually, and how to customize generated wording and terminal style.

Detailed Option Help

The built-in --help=<name> form displays one visible option in detail. The name may be a case-insensitive long or internal alias, or a case-sensitive short alias. For a root request, global options are searched before modules in registration order. For a module request, that module is searched first, then global options, then the remaining modules. When the same exact alias exists in another scope, the document adds a See Also command for that scope.

Detailed documents generate one usage line for each dashed alias and use attached value syntax. They show the option title, description, an optional example configured with setHelpExample(), and any related scope commands. Use OptionManager::detailedHelpDocument() or displayDetailedHelp() when routing display requests manually. An unresolved direct request throws OptionError with an UnknownName context and fuzzy suggestions.

Plain Output Is the Default

Without terminal support, Application renders generated help as plain text. This is predictable for redirected output, build logs, tests, and simple command-line tools.

/// `Application::enableTerminal()` switches generated help from plain text to styled terminal output.
///
/// This application checks for `--terminal` before parsing and enables terminal rendering early enough for `--help`.
/// It also sets a predefined terminal document style for system output.
class HelpCustomizationApp final : public el::Application {
public:
    using Application::Application;

protected:
    void initialize() override {
        info().setApplicationName("Night Watch Help"_el);
        info().setApplicationVersion(el::Version{0, 8, 0});
        for (const auto &arg : commandLineArguments()) {
            if (arg == "--terminal"_el) {
                enableTerminal();
                setSystemOutputStyle(el::cterm::TerminalDocumentStyle::defaultStyled());
                break;
            }
        }
    }
    void registerCommandLineOptions(const el::OptionsPtr &options) override {
        addSharedOptions(options);
        options->addOption({"--terminal"_el, "terminal"_el})
            .setHelpDescription("Renders help with terminal colors."_el)
            .setHelpVisibility(el::OptionHelpVisibility::Hidden);
    }
};

/// `OptionManager` exposes neutral help documents and `DisplayTextMap` for manual rendering and wording changes.
///
/// The manager can build a `TextDocument` without owning the application lifecycle.
/// Change `DisplayTextMap` when generated labels such as `Usage`, `Options`, placeholders, or built-in option
/// descriptions need application-specific wording.
auto manualHelpRendering() -> el::ExitCode {
    auto options = el::Options::create();
    auto info = el::ApplicationInfo{};
    info.setApplicationName("Manual Help"_el);
    info.setApplicationVersion(el::Version{0, 8, 0});
    options->setApplicationInfo(info);
    options->setExecutablePath("manual-help"_el);
    addSharedOptions(options);

    auto displayText = el::DisplayTextMap::defaultMap()->clone();
    displayText->set("options.UsageLabel"_el, "Usage"_el)
        .set("options.OptionsHeading"_el, "Settings"_el)
        .set("options.OptionsPlaceholder"_el, "options"_el)
        .set("options.ChoicePlaceholder"_el, "choice"_el)
        .set("options.ChoicesLabel"_el, "Choices"_el);

    auto manager = el::OptionManager{options};
    manager.setDisplayTextMap(displayText);
    el::io::printLine(manager.helpDocument({}).toString());
    return el::ExitCode::success();
}

$ option/option_help_customization --help

Shows how option help can be rendered as a document.
Usage:
option_help_customization [options]
Options:
-g, --area <area>      Area for which to view help.
-f, --format <choice>  Output detail level. Choices: short, full.
-h, --help             Display this help.
    --version          Display version information.

$ option/option_help_customization --terminal --help

      Shows how option help can be rendered as a document.


   -◆ Usage ◆-──────────────────────────────────────────────────────────────────────────

option_help_customization options


   -◆ Options ◆-────────────────────────────────────────────────────────────────────────

-g, --area area      Area for which to view help.
-f, --format choice  Output detail level. Choices: short, full.
-h, --help           Display this help.
    --version        Display version information.

$ option/option_help_customization manual

Shows how option help can be rendered as a document.
Usage:
manual-help [options]
Settings:
-g, --area <area>      Area for which to view help.
-f, --format <choice>  Output detail level. Choices: short, full.
-h, --help             Display this help.
    --version          Display version information.

Enable Terminal Rendering in Application

Call enableTerminal() before command-line parsing when help should use terminal styling. The usual place is at the start of initialize(). If styling should depend on an early command-line switch, inspect commandLineArguments() in initialize() and enable the terminal before parsing begins.

When terminal support is enabled, Application renders help, version, errors, and other system output through its terminal document renderer. Use setSystemOutputStyle() to choose a predefined or custom TerminalDocumentStyle.

Render Help Manually

Use OptionManager directly when help or diagnostics are part of a larger workflow. The manager can build neutral documents without displaying them:

• helpDocument() builds help for the root or a module,

• versionDocument() builds version output,

• errorDocument() builds an option diagnostic.

The document can be converted to plain text with toString() or passed to a terminal document renderer. Manual rendering is useful for tests, embedded command interpreters, graphical shells, and tools that collect diagnostics before printing them.

Customize Display Text

DisplayTextMap controls generated words such as labels, headings, placeholders, built-in option descriptions, and diagnostic labels. It does not change parser behavior.

Start from DisplayTextMap::defaultMap(), clone it, adjust the keys you need, and pass it to OptionManager::setDisplayTextMap().

This is the right tool for localization, house style, or embedding option help into an application that already has its own vocabulary. Use option and set help metadata for user-facing descriptions of your own options. Use DisplayTextMap for generated framework wording.