Subject: bug#71087: grep.in.1: some remarks and editorial changes for this man page

From: Bjarni Ingi Gislason <[email-masked]>
Date: Tue, 21 May 2024 02:26:32 +0000

Here are some notes and editorial fixes for the manual.

  The patch is in the attachment.

-.-

The difference between the formatted outputs can be seen with:

  nroff -man <file1> > <out1>
  nroff -man <file2> > <out2>
  diff -u <out1> <out2>

and for groff, using

"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "

instead of "nroff -man"

  Add the option "-t", if the file contains a table.

  Read the output of "diff -u" with "less -R" or similar.

-.-.

  If "man" (man-db) is used to check the manual for warnings,
the following must be set:

  The option "-warnings=w"

  The environmental variable:

export MAN_KEEP_STDERR=yes (or any non-empty value)

  or

  (produce only warnings):

export MANROFFOPT="-ww -z"

export MAN_KEEP_STDERR=yes (or any non-empty value)

-.-.

Output from "mandoc -T lint grep.in.1": (possibly shortened list)

mandoc: grep.in.1:27:9: WARNING: undefined string, using "": la

  The fix to eliminate this warning is to add explicitly an empty string to
its value:

.as la ""

  A similar method can be used for undefined registers:

.nr a +0

   The groff's 'an-ext.tmac' does not define the string 'la',
just the character.

-.-.

Use the correct macro for the font change of a single argument or
split the argument into two.

248:.IR FILE
677:.BR \-I

-.-.

Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.

752:.B sort -z

-.-.

Output from "groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -rCHECKSTYLE=0":
troff: backtrace: file '<stdin>':26
troff:<stdin>:26: warning: macro 'la' not defined

--- grep.in.1	2024-05-21 01:34:19.228927615 +0000
+++ grep.in.1.new	2024-05-21 01:32:13.506930462 +0000
@@ -23,6 +23,7 @@
 .	\}
 .\}
 .
+.as la \" add an empty string to avoid a warning
 .if !\w|\*(la| \{\
 .\" groff an-ext.tmac does not seem to be in use, so define the parts of
 .\" it that are used below.  For a copy of groff an-ext.tmac, please see:
@@ -245,7 +246,7 @@ If this option is used multiple times or
 option, search for all patterns given.
 The empty file contains zero patterns, and therefore matches nothing.
 If
-.IR FILE
+.I FILE
 is
 .B \-
 , read patterns from standard input.
@@ -674,7 +675,7 @@ whose base name matches
 Ignore any redundant trailing slashes in
 .IR GLOB .
 .TP
-.BR \-I
+.B \-I
 Process a binary file as if it did not contain matching data; this is
 equivalent to the
 .B \-\^\-binary\-files=without\-match
@@ -749,7 +750,7 @@ Like the
 or
 .B \-\^\-null
 option, this option can be used with commands like
-.B sort -z
+.B sort \-z
 to process arbitrary file names.
 .
 .SH "REGULAR EXPRESSIONS"