From: janis_papanagnou+ng@hotmail.com

On 06.11.2025 05:29, Michael Sanders wrote:
> Rounding the corner to completion on a project
> I've worked on for 5 or 6 years & now I'm stumped
> by a very simple thing...
>
> When the user passes no arguments, I default to
> the panel below, yet I wonder if its expressed
> concisely enough to avoid confusion or promote it...
>
> I don't feel its too bad, but then again I know
> what its doing while others wont.
>
> Hoping to read responses on you'd express this.

There's no clear standard and you can certainly find
various forms. It's probably also depending on taste
to some degree. But there's also a common subset that
you often find. Some impressions on the sample below...

>
> Syntax: tinybase OPTION - INPUT

I find a line like this not very useful (per se).

>
> Options (use 1 option per invocation):

If that's the case you don't really need a '-' or '--'
to terminate options.

>
> Tag query:       -q 'comma seperated queries'
> Tag index:       -t
> Tinybase manual: -m
>
> Input:
>
> File list: - file1 file2 file3
> Stdin:     - <
> Examples:
>
> tinybase -q 'query1, query2, query3' - *.txt
> tinybase -t - *.txt
> tinybase -m > manual.txt

Examples are fine (but '-' is syntactically unnecessary).
A description is completely missing. (And a manual page
should also have information about exit status codes.)

My preference for usage information goes in the direction
(despite being also - like your "Syntax" line - formally
not perfectly accurate)...


Synopsis:
    tinybase [ -q queries... | -t | -m ] files...

Options:
    -q queries...     comma separated list of queries
    -t                
    -m                show manual

Description:
    ...

Examples:
    tinybase -q 'query1, query2, query3' - *.txt
    tinybase -t - *.txt
    tinybase -m > manual.txt


Where a quick usage help would just print a single line
    Usage: tinybase [ -q queries... | -t | -m ] files...
and a verbose information or manual page would show the
complete information. (I would support both, terse usage
and full information. No arguments provided could just
show the usage and '-?' or similar could provide details.
There's various possibilities depending on the character
and complexity of the tool, what information you want to
obtain quickly and when you need details.)

I also suggest to just inspect what other programs and
tools do here. You will get a feeling then what's there
and whether it's enough for you to understand that tool.
Add thereby identifying those sections and contents in
your info page that is missing in your tool-information
to understand it.

Janis

--- SoupGate-Win32 v1.05
 * Origin: you cannot sedate... all the things you hate (1:229/2)