How to Display Help Text in Multiple Sections (Paged Help) in Batch Script

As your Batch tools grow in complexity, a single screen of help text (triggered by myapp.bat /?) is often not enough. Trying to jam documentation for 20 different flags and commands into one screen results in "Information Overload," where the user misses critical details because they are scrolling too fast. Paged Help allows you to divide your documentation into sections, like "Basic Usage," "Advanced Flags," and "Examples," managing the user's attention.

In this guide, we will demonstrate how to build a sectioned help system using labels and the choice command.

The Strategy: The Help Router

Instead of one long echo block, we create a menu for the help system itself. When a user runs the script with a help flag, we jump to a :HelpMenu label.

Implementation Script: Sectioned Help System

@echo off
setlocal

:: Detect help flag
if "%~1"=="/?" goto :HelpMenu
if /i "%~1"=="-h" goto :HelpMenu
if /i "%~1"=="/h" goto :HelpMenu

:: Show quick help if no arguments provided
if "%~1"=="" (
    echo Usage: mytool.bat [source] [target] [options]
    echo Run "mytool.bat /?" for full documentation.
    exit /b 0
)

:: Normal script execution starts here
echo Normal script logic...
pause
exit /b 0

:HelpMenu
cls
echo ======================================================
echo             MY TOOL - DOCUMENTATION CENTER
echo ======================================================
echo.
echo    [1] Basic Syntax ^& Overview
echo    [2] Advanced Connection Flags
echo    [3] Real-world Examples
echo    [X] Return to Console
echo.
echo ======================================================
choice /c 123X /n /m "Select a help section: "

if %errorlevel% equ 4 exit /b 0
if %errorlevel% equ 3 goto :HelpEx
if %errorlevel% equ 2 goto :HelpAdv
if %errorlevel% equ 1 goto :HelpBasic
goto :HelpMenu

:HelpBasic
cls
echo [ SECTION 1: BASIC SYNTAX ]
echo ------------------------------------------------------
echo Usage: mytool.bat [source] [target] [/v]
echo.
echo   [source]  Path to the input folder.
echo   [target]  Destination for the backup.
echo   [/v]      Verbose mode.
echo.
pause
goto :HelpMenu

:HelpAdv
cls
echo [ SECTION 2: ADVANCED FLAGS ]
echo ------------------------------------------------------
echo   /S        Synchronize subdirectories.
echo   /LOG      Path to a custom log file.
echo   /QUIET    Disable all console outputs.
echo.
pause
goto :HelpMenu

:HelpEx
cls
echo [ SECTION 3: EXAMPLES ]
echo ------------------------------------------------------
echo 1. Simple Copy:
echo    mytool.bat C:\Data D:\Backup
echo.
echo 2. Quiet Sync with Logging:
echo    mytool.bat C:\Data D:\Backup /S /QUIET /LOG:res.txt
echo.
pause
goto :HelpMenu

tip

The choice /n flag suppresses printing the option characters in brackets after the prompt. This keeps the output clean when you have already listed the options in the menu above.

Using the MORE Command for Long Pages

If a single help section is still too long for one screen, you can use the more command to handle the internal pagination within that section.

:HelpBasic
cls
(
    echo [ SECTION 1: BASIC SYNTAX ]
    echo ------------------------------------------------------
    echo Usage: mytool.bat [source] [target] [/v]
    echo.
    echo   [source]  Path to the input folder.
    echo   [target]  Destination for the backup.
    echo   [/v]      Verbose mode.
    echo.
    echo Additional details follow below...
    echo.
    echo The [source] parameter accepts both local paths and
    echo UNC network paths. Ensure the path exists before
    echo running the tool, or use the /VALIDATE flag to
    echo enable automatic path checking.
    echo.
    echo The [target] parameter must point to a writable
    echo directory. If the directory does not exist, the
    echo tool will attempt to create it unless /NOCREATE
    echo is specified.
) | more
pause
goto :HelpMenu

warning

When piping to more, the echo. command that prints a blank line may display ECHO is off. in some Windows versions. If you encounter this, use echo( instead of echo. to produce reliable blank lines inside parenthesized blocks.

Why Sectioned Help is Better

1. Searchability: It is easier for a user to find a specific flag if they know it is in the "Advanced" category.
2. Formatting: You can use colors or ASCII art for each header to make the sections distinct.
3. Scalability: You can add documentation for new features without cluttering the main screen.

Best Practices

1. Standard Hotkeys: Use /h, -h, and /? to trigger the help. These are the expected standards for Windows command-line tools.
2. No-Argument Handling: When a user runs your script without any arguments, display a brief usage summary and point them to the full help flag rather than doing nothing or showing an error.
3. Navigation: Always provide a clear way to return to the main help menu (e.g., pause followed by goto :HelpMenu).
4. Conciseness: Even with sections, keep your descriptions short. Use the "Example" section to show, not just tell, how the flags work.
5. Fallback Safety: Add a goto :HelpMenu after the last if %errorlevel% check in the menu so that unexpected return values do not cause the script to fall through into a help section unintentionally.

info

For scripts with more than five or six help sections, consider accepting a direct section argument such as mytool.bat /? advanced so experienced users can jump straight to the section they need without navigating the interactive menu.

Conclusion

Paged help text transforms your Batch script from a "black box" into a well-documented tool. By separating your documentation into logical, manageable sections, you ensure that your users have access to all the information they need without being overwhelmed by a secondary wall of text. This professional approach to documentation significantly improves the usability and adoption of your automation solutions.