From: Ingo Schwarze <schwarze@usta.de>
Subject: Re: random(6): document -h option
To: Alexander Farber <alexander.farber@gmail.com>
Cc: tech@openbsd.org
Date: Wed, 7 Jan 2026 10:43:53 +0100

Hi Alexander,

Alexander Farber wrote on Tue, Jan 06, 2026 at 04:10:50PM +0100:

> The -h option is implemented but not documented.

Options of the -h / --help kind are garbage and should better not exist.
Documenting them is particularly useless: if you are already looking at
the usage() message or at the manual page, you no longer need them because
you already look at the usage() message or at the SYNOPSIS.  Duh.

So they make the documention longer for no benefit whatsoever.

Also, typing "random -h" only duplicates what is already available
in a more logical way as "man -h random" - or if you want to
suppress random(3) and random(4), "man -h 6 random".

Finally, i looked for programs having such a -h option with

  $ man -M /usr/share/man -ak Fl~'\<h\>'

In aucat(1), chflags(1), chgrp(1), chmod(1), cksum(1), clean-old-distfiles(1),
col(1), ctfdump(1), df(1), dpb(1), du(1), fdformat(1), file(1), find(1),
finger(1), grep(1), last(1), less(1), ln(1), login(1), lpr(1), ls(1), man(1),
netstat(1), nl(1), od(1), pr(1), ps(1), rcs2log(1), rlog(1), rpcgen(1), rs(1),
rup(1), rusers(1), sh(1), sha256(1), sort(1), spell(1), ssh-add(1),
ssh-keygen(1), systat(1), tar(1), test(1), tsort(1), w(1), wc(1), whois(1),
ypwhich(1), hunt(6), amq(8), bioctl(8), chown(8), crunchgen(8), disklabel(8),
dump(8), fdisk(8), identd(8), kgmon(8), ldattach(8), mknetid(8), newfs(8),
newfs_msdos(8), ping(8), quot(8), restore(8), revnetgroup(8), route6d(8),
setnetbootinfo(8), shutdown(8), spamd(8), sshd(8), syslogd(8), umount(8),
wsfontload(8), yppoll(8), yppush(8), ypset(8), ypxfr(8) the -h option
has different and more useful meanings, so expecting -h to mean "help" is
very misguided, and typing -h to get a usage message should be discouraged
in general.

Programs using -h for "help" are much fewer: compress(1), dig(1), flex(1),
gzip(1), keynote(1), ld.lld(1), nc(1), smtp(1), tmux(1), unifdef(1),
adduser(8), ifstated(8), pfctl(8), sftp-server(8), smtpd(8).
While a few of these are important homegrown tools, more are third-party
and/or rather bloated in the first place.

Even for programs like tmux(1), pfctl(8), and smtpd(8), i consider
providing -h for "help" a bad idea.

> ok?

No OK from me.

Not a very strong objection if other developers disagree,
but i'd prefer discarding this patch and treating this fluff
as intentionally undocumented.

And do not add -h / --help to more programs, please.

Yours,
  Ingo


> Index: random.c
> ===================================================================
> RCS file: /cvs/src/games/random/random.c,v
> retrieving revision 1.22
> diff -u -r1.22 random.c
> --- random.c 18 Feb 2023 08:52:39 -0000 1.22
> +++ random.c 6 Jan 2026 15:01:26 -0000
> @@ -249,6 +249,6 @@
>  usage(void)
>  {
> 
> - (void)fprintf(stderr, "usage: %s [-er] [denominator]\n", getprogname());
> + (void)fprintf(stderr, "usage: %s [-ehr] [denominator]\n", getprogname());
>   exit(1);
>  }
> Index: random.6
> ===================================================================
> RCS file: /cvs/src/games/random/random.6,v
> retrieving revision 1.8
> diff -u -r1.8 random.6
> --- random.6 23 Aug 2022 06:35:53 -0000 1.8
> +++ random.6 6 Jan 2026 15:01:26 -0000
> @@ -37,7 +37,7 @@
>  .Nd random lines from a file or random numbers
>  .Sh SYNOPSIS
>  .Nm random
> -.Op Fl er
> +.Op Fl ehr
>  .Op Ar denominator
>  .Sh DESCRIPTION
>  .Nm
> @@ -59,6 +59,8 @@
>  exit value of 0 to the minimum of 255 and
>  .Ar denominator
>  \&- 1, inclusive.
> +.It Fl h
> +Display a usage message and exit.
>  .It Fl r
>  The
>  .Fl r