Command Line Help

command-line-help demonstrates how a regular command-line tool can use colorful output and Terminal::printParagraph() to keep a help screen readable across different terminal widths.

The demo prints directly into the normal shell history. On wider terminals it uses paragraph layout for wrapped descriptions, indents, and wrap markers. If the effective width drops below 40 columns, it deliberately falls back to simple line-based output so you can compare both approaches.

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=72

ANSI Output Example

The following excerpt shows the rich help output with a deterministic simulated width:

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 Shown

This demo highlights several practical techniques for text-heavy console tools:

• Terminal::printParagraph() for structured, width-aware command help.

• Mixed-style String values for realistic command signatures.

• Tab-stop based alignment of option descriptions.

• Configurable paragraph wrapping, break marks, ellipsis handling, and fallback behaviour.

• A 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.