From: rjh@cpax.org.uk   
      
   On 06/11/2025 04: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.   
      
   Don't try and teach in an if(argc <   
      
   People who type the program name alone need one of two things:   
      
   a) a brief description of the program's purpose;   
      
   OR   
      
   b) a brief reminder of usage.   
      
   Here's an example from my own corpus:   
      
   $ transpose   
   transpose infile amount [outfile]   
   transposes a Lilypond metafile ($TRANSPOSE$ tag present)   
   from one key to another.   
   infile:  the file to transpose   
   amount:  number of semitones to transpose (-ve = down, +ve = up)   
   outfile: if specified, output is written here.   
             Otherwise, the input file is modified.   
      
      
   That's enough to   
   a) tell you whether it's the program you wanted, or   
   b) remind you of how you use it   
      
   It doesn't try to teach you music theory. If your program needs a   
   manual, your descriptive passage should point at it - eg See   
   README for more details.   
      
   > Syntax: tinybase OPTION - INPUT   
      
   I'd say FILE(S) rather than INPUT   
      
   > Options (use 1 option per invocation):   
      
   OPTION: one of   
      
   > Tag query:       -q 'comma seperated queries'   
      
   sepArated - but it's not clear whether the 'text in quotes' is   
   part of the syntax or just an aside.   
      
   > Input:   
      
   FILE(S) is less ambiguous. If your user doesn't know what files   
   are and you try to teach him, you're in for a world of hurt.   
      
   --   
   Richard Heathfield   
   Email: rjh at cpax dot org dot uk   
   "Usenet is a strange place" - dmr 29 July 1999   
   Sig line 4 vacant - apply within   
      
   --- SoupGate-Win32 v1.05   
    * Origin: you cannot sedate... all the things you hate (1:229/2)