0

I stumbled upon this the first time when I wanted to add an option -h to my program and got an error that -h is already in use: With add_help=True, Python's argparse automatically creates a help page for arguments -h and --help.

But using both -h and --help to show the help page is not the case for most programs, is it? Which popular commands even have -h short for --help? I had a look at some commands and oftentimes it's the abbreviation for --human-readable or another help-unrelated option. Using -h for the help message doesn't work with ls, cd, df and diff for example - just a few commands that I've tested, not an exhaustive or representative list of course, yet very popular commands.

Possibly -h has been in use as the default argument to show the help page, historically, and --help only came later? Where do man or info pages come in?

I don't want to confuse users by using -h for something else than the help page if that's a popular default. However, personally, I've never used -h and am always going for --help.

finefoot
  • 2,940
  • 2
  • 21
  • 41

2 Answers2

7

-h is a really old convention. In DOS systems you would also often see -? or /? as well.

Do not listen to people who say that man pages are for newbies. They are highly valuable and already added to the Unix system in 1971 just 2 years after the birth of Unix. They were typeset with troff already in 1973. It is still required to be POSIX compliant (but could be an alias to info). It has a very long history and it is a pity that it does not get more interest in the web crazed world of today. People who berate man pages or their users often "forget" (cannot be bothered) to create them themselves. Documentation is important.

Unfortunately the man pages are not kept very well on Linux so many users think of them as obsolete. But on FreeBSD (and I believe other BSDs as well) they are kept up-to-date and is the best way to know both the system and commands.

info comes from a GNU background in the late 1980's and is hypertext based. It is prevalent on Linux system but unfortunately not as well integrated. You will find many tools without info pages.

--help is again a GNUism and was introduced with long options in the GNU C library in the early 90's. This is then a later convention - but a good one if you support long options.

To me a good program would emit a very short summary of the command line options using -h. If your program supports long options then do the same for --help And then put the proper instructions into the man page.

These are however just conventions. But even if you do not want to follow them - I would be very wary of using -h for anything but help. Or at least make sure that it is a non-desctructive option such as df -h.

Today I would write a manual page in mdoc. It is fairly simple and there are plenty of tools to then process that into markdown, PDF or HTML for consumption elsewhere.

A pertinent quote from mdoc

A utility without a manual is of no utility at all.

Claus Andersen
  • 3,239
  • 1
  • 12
  • 24
  • Old habits die hard. That is a personal preference of mine. As it is only conventions you are free to do what you want. Just did a quick test and I only found `fdisk`. So in all honesty I can name more unix tools that uses `-h` for something else. I came up on DOS and CP/M which might explain my preference. My default is however still `man`. – Claus Andersen Mar 02 '20 at 19:09
0

Historically, program memory was precious, no space for nonsense like "help" messages. Real Unix beards knew the programs by heart, newbies used man(1). Barely memory for reasonable error messages (the infamous "?" of ed(1) for any error, cc(1)'s only message "syntax error on line N"). When memory became (more) plentiful, some programs started accepting "-h" for help/minimal usage instructions. GNU introduced long "--options", and often "--help". Others with "-u", or "-usage", or just spitting out help for any unrecognized option.

vonbrand
  • 18,156
  • 2
  • 37
  • 59
  • 2
    That's a long-after-the-fact revisionist view of history, with no real support in fact. It ignores the existence of the (_not_ SCCS) `help` command in AT&T Unix System 5, `ed`'s _almost 40-year old_ `H`/`h` commands, the `learn` command in AT&T Unix 7th Edition 32V, and the varying and cross-platform development of the _very idea_ of such things across operating systems in the 1970s and 1980s (e.g. [F1] at the command line in 4DOS, [F1] in SCO Shell, universal /H options in DR-DOS, HELP in CP/M-Plus, Mortice-Kern `help`, `help` taking message numbers in IBM OS/2 (and SCCS `help`), and so on). – JdeBP Mar 02 '20 at 07:53
  • @finefoot, very common is `-h`, programs accepting "long options" typically also accept `--help`. – vonbrand Mar 02 '20 at 14:47
  • @JdeBP, never saw `h`on the ed(1)s I used... strange. And the F1 and so convention for help comes from IBM's CUA (published 1987). Used on their 3270 terminals, for example. – vonbrand Mar 02 '20 at 14:52
  • @finebit. On Linux, most of the GNU utilities nowadays only support `--help`. – fpmurphy Mar 02 '20 at 15:27
  • The "early days"; only applies to **early** PCs. Most whom had access to a computer back then, were involved in what was call "time shares" on a Mainframe. You've heard of IBM? PDP-11s were also popular "back then", and ran various forms of what often became some form of UNIX. Where you used a Terminal to connect to them, and run programs. **end of part I** (see part II below) – somebody Mar 04 '20 at 21:06
  • But even then, you were still involved in some sort of "time sharing" -- often called "job scheduling". The point I'm trying to make here; is that resources had little to do with the advent of `-h, --help, /?` or most of all `man(1)`. Even the earliest of (MS)DOS (3.2) provided `/?`, back in the days of the 8080,8086,8088 -- earliest _popular_ PCs. **end of part II** – somebody Mar 04 '20 at 21:07