Re: Bug#1016412: dh-make: manpage.1.ex: Incorrect formatting for dash

[G. Branden Robinson]

Hi Mike,

At 2022-07-31T11:54:13-0400, Mike Bianchi wrote:
> I come into this very late and without having studied the on-going
> discussion.  For this I apologize.
> 
> > However, since many manual pages in existence are incorrect, and
> > they use '-'  >>> when they should use '\-' <<< ...
> 
> Let me take exception to the claim that  '-'  should be '\-' .  

...and permit me to rebut you!  ;-)

> In manual pages of UNIX/Linux commands, system calls, libraries, etc.
> all the examples are for strings and negative numbers expressed in
> ASCII characters.
>       man(1)
>       execve(2)
>       fileno(3)
>          :

Well, no, they're not.

Let's go to what I have earlier referred to exaggeratedly as the
"Ur-source of all correct practice", the Unix Version 7 Programmer's
Manual (1979).  Surveying its man pages we find exhibits like the
following.

Believe it or not, this is a _brief_ sampling.  I've drawn exhibits from
every section of the manual and attempt to show usage of \- in several
correct context.  (The sharp eye will spot an authentic solecism.)

man5/passwd.5-.SH NAME
man5/passwd.5:passwd \- password file
man5/passwd.5-.SH DESCRIPTION

man5/filsys.5-Thus is i-list is
man5/filsys.5:.IR s_isize \-2
man5/filsys.5-blocks long.

man5/filsys.5-array contains, in
man5/filsys.5:.I "s_free[1], ... , s_free[s_nfree\-1],"
man5/filsys.5-up to NICFREE free block numbers.

man5/a.out.5-if the program was loaded
man5/a.out.5:with the `\-s' option
man5/a.out.5-of

man5/mpxio.5-the operating system aligns records
man5/mpxio.5:on short (i.e. 16\-bit) boundaries
man5/mpxio.5-by skipping bytes when necessary.

man5/mpxio.5-.ti -.5i
man5/mpxio.5:M_WATCH \- a process `wants to attach' on this channel.
man5/mpxio.5-The second parameter is the 16-bit

man6/reversi.6-[ [
man6/reversi.6:.B \-r
man6/reversi.6-]

man6/ching.6-six straight
man6/ching.6:(\-\-\-)
man6/ching.6-and broken
man6/ching.6:(\-\ \-)
man6/ching.6-lines.

man6/ching.6-(lines)
man6/ching.6:using yarrow\-stalks
man6/ching.6-or tossed coins.

man6/ching.6-which drives a simulated
man6/ching.6:coin\-toss divination.
man6/ching.6-The answer is then piped through

man6/arithmetic.6-[
man6/arithmetic.6:.B +\-x/
man6/arithmetic.6-] [ range ]

man6/arithmetic.6-to be generated;
man6/arithmetic.6:.B +\-x/
man6/arithmetic.6-respectively cause

man6/arithmetic.6-problems will be mixed in random order; default is
man6/arithmetic.6:.B +\-
man6/arithmetic.6-.PP

man8/boot.8-    177412
man8/boot.8:    005040          clr     \-(r0)  / rkda cleared by start
man8/boot.8:    010040          mov     r0,\-(r0)
man8/boot.8:    012740          mov     $5,\-(r0)
man8/boot.8-    000005

man8/boot.8-    176726
man8/boot.8:    005040          clr     \-(r0)
man8/boot.8:    005040          clr     \-(r0)
man8/boot.8:    005040          clr     \-(r0)
man8/boot.8:    010040          mov     r0,\-(r0)
man8/boot.8:    012740          mov     $5,\-(r0)
man8/boot.8-    000005

man1/lint.1-[
man1/lint.1:.B \-abchnpuvx
man1/lint.1-]

man1/ld.1-Except for
man1/ld.1:.BR \-l ,
man1/ld.1-they should appear before the file names.
man1/ld.1-.TP
man1/ld.1:.B  \-s
man1/ld.1-`Strip' the output, that is, remove the symbol table

man1/awk.1-and are built using the operators
man1/awk.1:+, \-, *, /, %,  and concatenation (indicated by a blank).
man1/awk.1:The C operators ++, \-\-, +=, \-=, *=, /=, and %=
man1/awk.1-are also available in expressions.

man1/awk.1-or by using the
man1/awk.1:.BI \-F c
man1/awk.1-option.

man1/awk.1-.nf
man1/awk.1:     { for (i = NF; i > 0; \-\-i) print $i }
man1/awk.1-.fi

man1/quot.1m-.TP
man1/quot.1m:.B \-n
man1/quot.1m-Cause the pipeline
man1/quot.1m:.B "ncheck filesystem | sort +0n | quot \-n filesystem
man1/quot.1m-to produce a list of all files and their owners.
man1/quot.1m-.TP
man1/quot.1m:.B \-c
man1/quot.1m-Print three columns giving file size in blocks, number of

man1/make.1-.I makefile
man1/make.1:is `\-', the standard input is taken.
man1/make.1-More than one
man1/make.1:.B \-f
man1/make.1-option may appear

man7/term.7-.nf
man7/term.7:.ta \w'450\-12\-8  'u
man7/term.7-1620        DIABLO 1620 (and others using HyType II)
man7/term.7:1620\-12    same, in 12-pitch mode
man7/term.7-300 DASI/DTC/GSI 300 (and others using HyType I)
man7/term.7:300\-12     same, in 12-pitch mode
man7/term.7-300s        DASI/DTC 300/S
man7/term.7:300s\-12    same, in 12-pitch mode
man7/term.7-33  TELETYPE\*R Model 33
man7/term.7-37  TELETYPE Model 37
man7/term.7:40\-2       TELETYPE Model 40/2
man7/term.7-43  TELETYPE Model 43
man7/term.7-450 DASI 450 (same as Diablo 1620)
man7/term.7:450\-12     same, in 12-pitch mode
man7/term.7:450\-12\-8  same, in 12-pitch, 8 lines/inch mode
man7/term.7-735 Texas Instruments TI735 (and TI725)

man2/kill.2-.PP
man2/kill.2:If the process number is \-1, and the user is the super-user,
man2/kill.2-the signal is broadcast universally

man2/kill.2-Zero is returned if the process is killed;
man2/kill.2:\-1 is returned if the process does not
man2/kill.2-have the same effective user ID and the

sin.3m-.I x
sin.3m:in the range \-\(*p/2 to \(*p/2.
sin.3m-.PP

printf.3s-.TP
printf.3s:\-
printf.3s:an optional minus sign `\-' which specifies
printf.3s-.I "left adjustment"

ctime.3-day of month (1-31), month of year (0-11), day of week
ctime.3:(Sunday = 0), year \- 1900, day of year (0-365),
ctime.3-and a flag that is nonzero if daylight saving time is in effect.

tty.4-The default values for these characters are
tty.4:DEL, FS, DC1, DC3, EOT, and \-1.
tty.4:A character value of \-1
tty.4-eliminates the effect of that character.

The solecism I referred to above is "16\-bit" in mpxio(5)...this was a
mistake.  A prose hyphen as in this adjectival phrase requires only '-',
as seen nearby in the same man page.  Also above, in term(7), we see
"12-pitch", also correct usage.  (And "super-user" in kill(2), and so
on...)

So, '-' is a hyphen and '\-' is a dash or minus sign, used as an
arithmetic sign, a subtraction operator, a Unix command-line option
dash, and doubled for a decrementation operator.

AT&T troff/nroff used '-' also for en dashes, as in ranges.  I infer
that this was because the C/A/T had no glyph for an en dash.  groff
does, so we'd spell ranges as used in ctime(3) like "1\[en]31".

>  To my mind the correct solution to the  '-'  controversy is to format
>  everything at is an ASCII expression in an ASCII font which has no
>  concept of '\-' .

I suggest that that horse left the barn in 1973 with the creation of
troff.  For details, you can see the "History" section of groff_char(7)
in groff Git HEAD.

https://git.savannah.gnu.org/cgit/groff.git/tree/man/groff_char.7.man#n1901

> ((I come from the days when all UNIX documentation was formated using
> nroff.))

"The manual was intended to be typeset; some detail is sacrificed on
terminals." (man(1), _Unix Time-Sharing System Programmer's Manual_,
Eighth Edition, Volume 1, February 1985)

If you don't believe me, ask Doug.  He was there.

Or you can consult the man page sources yourself...I got them from to
Warren Toomey's invaluable TUHS archive.

https://minnie.tuhs.org/cgi-bin/utree.pl

I do freely acknowledge that many exhibits of incorrect practice have
arisen in the years since, particularly when one spreads one's net to
include all "UNIX/Linux commands" as you did.  I have ideas where the
fault lies for such errors, but I'll restrain myself from exploring that
topic in this discussion.

Regards,
Branden

signature.asc
Description: PGP signature