Command Line Help

command-line-help demonstrates how a regular command-line tool can keep a help screen readable across different terminal widths. It uses Terminal::printParagraph() together with tab stops, wrap markers, and fallback behavior to format realistic command help.

Use This Demo When You Need…

A support example for width-aware command help or option lists.
A place to study paragraph wrapping, indent handling, tab stops, and ellipsis behavior together.
A deterministic demo you can rerun with different widths and paragraph options while debugging layout issues.

Run the Demo

Start the demo from the build directory:

$ ./cmake-build-debug/demo-apps/command-line-help
$ ./cmake-build-debug/demo-apps/command-line-help --terminal-width=80

The second form is useful when you want deterministic wrapping for comparison or support work.

Captured Output (80x25)

command-line-help [<options>]

Summary
This demo prints a fictive command-line help page that adapts to the terminal
width. On wider terminals it uses Terminal::printParagraph() to keep
descriptions aligned, wrapped, and easy to scan. Below 40 columns it
intentionally falls back to plain line-oriented output so you can compare both
styles.

Preview Paragraph
Preview This paragraph keeps a visible background so options like background
mode, wrap markers, word breaks, ellipsis handling, and alignment become easier
to inspect while you adjust the rendering settings.

Options
--help/-h                          Render this formatted help output. The flag
                                   is mostly here so the demo behaves like a
                                   familiar command-line tool.
--terminal-width/-t=<columns>      Disable automatic width detection and
                                   simulate a terminal width between 20 and 200
                                   cells for deterministic wrapping.
--description-column/-c=<column>   Override the description tab stop for the
                                   options list with a fixed value. Valid values
                                   are 12 to 60.
--maximum-description-column/-d=<column>
                                   Cap the automatically chosen description tab
                                   stop. The default is 35 to force some
                                   wrapping in the options list. Valid values
                                   are 20 to 60.
--alignment/-a=<left|center|right> Choose the horizontal alignment used for the
                                   wrapped preview paragraphs.
--line-indent/-l=<columns>         Indent the preview paragraphs by 0 to 10
                                   columns before any wrapping takes place.
--first-line-indent/-f=<columns>   Override the first-line indent for preview
                                   paragraphs. Valid values are 0 to 12.
--wrapped-line-indent/-w=<columns> Override the indentation of wrapped lines.
                                   Values between 0 and 30 make the effect easy
                                   to inspect.
--background-mode/-b=<mode>        Set the background fill strategy: default,
                                   wrapped-left, wrapped-right, wrapped-both,
                                   full-right, or full-both.
--line-break-start-mark/-s=<text>  Insert a one- or two-character marker at the
                                   start of each wrapped continuation line.
--line-break-end-mark/-m=<text>    Append a one- or two-character marker at the
                                   right edge when a line wraps.
--paragraph-spacing/-p=<single|double>
                                   Switch between compact paragraphs or
                                   double-spaced output with one empty row in
                                   between.
--word-separators/-i=<tokens>      Use comma-separated separator tokens such as
                                   space,tab,slash or one-character literals
                                   like ; and |.
--word-break-mark/-k=<char>        Set the single character inserted when a word
                                   is split because it does not fit on the
                                   current line.
--maximum-line-wraps/-r=<count>    Limit the number of automatic wraps per
                                   paragraph. Use 0 for unlimited or values up
                                   to 8 to trigger ellipsis behaviour.
--paragraph-ellipsis-mark/-x=<text>
                                   Choose the marker that signals clipped
                                   paragraphs after the configured wrap limit
                                   has been reached.
--tab-stops/-u=<list>              Provide comma-separated tab stops like
                                   1,24,40 or use wrapped to align a stop with
                                   the wrapped-line indent.
--on-error/-o=<plain|empty>        Choose the fallback when the paragraph cannot
                                   be laid out: plain output or empty output.

Try It
Experiment with --terminal-width, wrap markers, custom tab stops, and the
preview paragraph settings to see how a real command help screen can stay
readable across narrow and wide terminals.

Features Demonstrated

Terminal::printParagraph() for structured, width-aware console text.
Mixed-style String values for realistic command signatures and option names.
Tab-stop based alignment of option descriptions.
Configurable paragraph wrapping, break markers, ellipsis handling, and fallback behavior.
A deliberate plain-output fallback for very narrow terminals.

Relevant Source Files

If you want to explore the implementation, start with demo/command-line-help/src/CommandLineHelpDemo.cpp.

This file contains the argument parsing, help document construction, and the two output paths for wide and narrow terminal widths.