Error in read.1p

Error in read.1p

[Ian Hunter]

Hello,

The man page for read.1p incorrectly uses a unicode minus ("−")
instead of a hyphen ("-") in places where flags are being used or
described. It made searching for the information on the "-r" flag
difficult. :)

Thanks for your help and hard work

Ian

Re: Error in read.1p

[Arkadiusz Drabczyk]

On Wed, Sep 25, 2019 at 09:41:30PM -0500, Ian Hunter wrote:
> Hello,
> 
> The man page for read.1p incorrectly uses a unicode minus ("−")
> instead of a hyphen ("-") in places where flags are being used or
> described.

A quick ag '\(mi' done in man-pages-posix-2013-a.tar.xz shows that
a lot of manpages in this tarball have this problem.

-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: Error in read.1p

[Arkadiusz Drabczyk]

On Thu, Sep 26, 2019 at 08:17:54PM +0200, Arkadiusz Drabczyk wrote:
> On Wed, Sep 25, 2019 at 09:41:30PM -0500, Ian Hunter wrote:
> > Hello,
> > 
> > The man page for read.1p incorrectly uses a unicode minus ("−")
> > instead of a hyphen ("-") in places where flags are being used or
> > described.
> 
> A quick ag '\(mi' done in man-pages-posix-2013-a.tar.xz shows that
> a lot of manpages in this tarball have this problem.

... but it can be solved by setting non-UTF LANG:

$ LANG=en_US  man ./read.1p
-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: Error in read.1p

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2670 bytes --]

Hi Ian & Arkadiusz,

There are a few issues here.

At 2019-09-26T20:17:54+0200, Arkadiusz Drabczyk wrote:
> On Wed, Sep 25, 2019 at 09:41:30PM -0500, Ian Hunter wrote:
> > Hello,
> > 
> > The man page for read.1p incorrectly uses a unicode minus ("−")
> > instead of a hyphen ("-") in places where flags are being used or
> > described.

First is that the above pages are not maintained by the Linux man-pages
project.  They are maintained by the Austin Group, the folks behind the
POSIX standard.  They have an issue reporting site[1].

I believe you will have to register on the site to actually file a
report, however.  (Issues can be _viewed_ anonymously.)

> A quick ag '\(mi' done in man-pages-posix-2013-a.tar.xz shows that
> a lot of manpages in this tarball have this problem.

Yes.  Using the character escape for "minus" is a bad idea in prose
contexts.  The nroff and troff of the 1970s defined this to be a minus
in the "special font", i.e., one used for equation displays, which may
not have the same metrics as the so-calld normal fonts used to typeset
prose.

Long story short, writers of man pages and *roff documents generally
should use the escape sequence "\-" when they require the hybrid
"hyphen-minus" character that is used in programming languages, the Unix
command line, and for similar purposes.  The hyphens used in phrases
like "mother-in-law" can be typed as-is (i.e., ASCII 45).

I invite readers to the groff mailing list[2] if they wish to know more
about the complexities of typesetting, the myriad variety of dashes and
dash-like symbols available, their semantics, the reasons why the *roff
authors made the choices they did for the input language, why these
choices are sometimes surprising to or frustrating for man page writers,
and related issues.

At 2019-09-26T20:23:57+0200, Arkadiusz Drabczyk wrote:
> ... but it can be solved by setting non-UTF LANG:
> 
> $ LANG=en_US  man ./read.1p

That solution gives up a lot of output glyps ("man groff_char" to see a
large list).  There are better ways to get these hyphens to output as
ASCII 45 characters without having to patch every (or even any) man
page.

For instance, adding the line:

.char \- \N'45'

to an appropriate configuration file (like /etc/groff/man.local) could
do the trick, but this is a crude fix and I think I can come up with
better solutions if I know a little bit more.

What *roff implementation are you using (Ian, Arkadiusz)?  If you don't
know how to ask the system, try "troff -v" at the shell prompt.

Regards,
Branden

[1] http://austingroupbugs.net/main_page.php
[2] groff@gnu.org

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Error in read.1p

[Arkadiusz Drabczyk]

On Fri, Sep 27, 2019 at 06:45:02AM +1000, G. Branden Robinson wrote:
> Hi Ian & Arkadiusz,
> 
> There are a few issues here.
> 
> At 2019-09-26T20:17:54+0200, Arkadiusz Drabczyk wrote:
> > On Wed, Sep 25, 2019 at 09:41:30PM -0500, Ian Hunter wrote:
> > > Hello,
> > > 
> > > The man page for read.1p incorrectly uses a unicode minus ("−")
> > > instead of a hyphen ("-") in places where flags are being used or
> > > described.
> 
> First is that the above pages are not maintained by the Linux man-pages
> project.  They are maintained by the Austin Group, the folks behind the
> POSIX standard.  They have an issue reporting site[1].

Good to know, I couldn't find read.1p in the repository.  But at the
bottom of read.1p it says:

"Any typographical or formatting errors that appear in this page are
most likely to have been introduced during the conversion of the
source files to man page format.  To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html. "

I think this might make people want to report such bugs here.  Also, I
also wasn't able to find any mention of austingroupbugs.net neither in
man-pages-posix-2013-a/README nor at
https://www.kernel.org/doc/man-pages except for this
http://man7.org/linux/man-pages/changelog.html (at least using
Google's site: operator).  Could this information be put somewhere?

> I believe you will have to register on the site to actually file a
> report, however.  (Issues can be _viewed_ anonymously.)

Here http://austingroupbugs.net/view.php?id=1158 someone says that the
issue is already solved in `troff source' but I don't know where to
get it.

> For instance, adding the line:
> 
> .char \- \N'45'
> 
> to an appropriate configuration file (like /etc/groff/man.local) could
> do the trick, but this is a crude fix and I think I can come up with
> better solutions if I know a little bit more.

That didn't work for me because /etc/groff/man.local is never opened:

$ strace -f /usr/bin/man ./read.1p |& grep 'man.local'
[pid 13682] open("/home/ja/man.local", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 13682] open("/usr/lib64/groff/site-tmac/man.local", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 13682] open("/usr/share/groff/site-tmac/man.local", O_RDONLY) = 5

Adding .char \- \N'45' to ~/man.local didn't help.  And I already have
this in /usr/share/groff/site-tmac/man.local:

.  \" Map \- to the Unicode HYPHEN-MINUS character, to make
.  \" searching in man pages easier.
.  if '\*[.T]'utf8' \
.    char \- \N'45'

I have a hard time trying to understand the whole process and need
some reading on the subject.

> What *roff implementation are you using (Ian, Arkadiusz)?  If you don't
> know how to ask the system, try "troff -v" at the shell prompt.

$ troff -v
GNU troff (groff) version 1.22.3

-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: Error in read.1p

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 6626 bytes --]

Hi Arkadiusz!

> > First is that the above pages are not maintained by the Linux
> > man-pages project.  They are maintained by the Austin Group, the
> > folks behind the POSIX standard.  They have an issue reporting
> > site[1].

Mmmm.  It looks like I was imprecise.  Details below.

> Good to know, I couldn't find read.1p in the repository.  But at the
> bottom of read.1p it says:
> 
> "Any typographical or formatting errors that appear in this page are
> most likely to have been introduced during the conversion of the
> source files to man page format.  To report such errors, see
> https://www.kernel.org/doc/man-pages/reporting_bugs.html. "

Yes.  I don't have manpages-posix-2013a installed (because I'm a Debian
user and the package is in Debian's unofficial non-free package archive,
which I don't use).

But I grabbed the source package, unpacked it, and took a closer look.

The text of the man page sources is derived from the POSIX standard
which is copyrighted by IEEE, and not licensed for modification.

Nothing indicates who was responsible for the preparation of these man
page sources.  As you noted below, recent Austin Group bug traffic
suggests to me that they maintain nroff sources for at least part of the
IEEE 1003 standards documentation; whether these man pages were
generated or hand-written is not clear, but on inspection they're clean
enough to be the latter.

> I think this might make people want to report such bugs here.

You're right, it sure looks that way.  I was mistaken if I suggested you
came to the wrong place--the documentation clearly directs you here.
Other files in the distribution, like man-pages-posix-2013-a.Announce,
speak of "the Linux man-pages maintainer", and
man-pages-posix-2013-a.lsm identifies Michael Kerrisk as the maintainer.

> Also, I also wasn't able to find any mention of austingroupbugs.net
> neither in man-pages-posix-2013-a/README nor at
> https://www.kernel.org/doc/man-pages except for this
> http://man7.org/linux/man-pages/changelog.html (at least using
> Google's site: operator).  Could this information be put somewhere?

This is a good question for Michael.

> > I believe you will have to register on the site to actually file a
> > report, however.  (Issues can be _viewed_ anonymously.)
> 
> Here http://austingroupbugs.net/view.php?id=1158 someone says that the
> issue is already solved in `troff source' but I don't know where to
> get it.

I suspect it is not publicly available at all.  If it is, I know nothing
about it.

> That didn't work for me because /etc/groff/man.local is never opened:

Hmm!  What happens when you type "man --version"?

On my Debian-based system, even just running "nroff -man" over an
(uncompressed) man page source file opens it (I tested it by adding:
.ab FOO
to /etc/groff/man.local).

> Adding .char \- \N'45' to ~/man.local didn't help.  And I already have
> this in /usr/share/groff/site-tmac/man.local:
> 
> .  \" Map \- to the Unicode HYPHEN-MINUS character, to make
> .  \" searching in man pages easier.
> .  if '\*[.T]'utf8' \
> .    char \- \N'45'

The above conditional checks for the utf8 device; when you're using a
non-UTF-8 locale (like en_US), it will not be applied.  If it's not
applied even when you _are_ using a UTF-8 locale, that's a further data
point for our troubleshooting; see the end of this message.

> I have a hard time trying to understand the whole process and need
> some reading on the subject.

groff is the GNU implementation of a family of programming languages for
typesetting whose names end in "OFF" (from the expression "run off" [a
copy of a document]) that date back to the 1960s.  At some point it
became sophisticated enough to be Turing-complete, and grew sufficiently
complex (and powerful) that people started writing macro packages for
it.  Most man pages are written predominantly with the macros defined by
a package designed for on-line documentation and purposefully limited to
the abilities of the Teletype machines used as terminals at Bell Labs in
the 1970s.

In addition to macros, which are expanded by *roff itself at the time it
processes a document, a variety of preprocessors are available.  The
most famous of these originally came from Bell Labs as well, and were
also reimplemented by GNU.  These include "tbl" for formatting tables,
"eqn" and "pic", which define mini-languages for presenting mathematical
equations and diagrams, respectively; and "refer", which expands
bibliographic references from a database prepared by some companion
tools.  Tables are often seen in man pages; the others, less so, either
due to the limitations of traditional terminals or because Unix systems
tended to be distributed without supporting documentation or because a
tradition of citing references apart from other man pages in a scrupulous
way did not become entrenched in the Unix community, and that is in turn
possibly due to the fact that a curated global database of references
useful to the corpus of Unix man pages ever arose.  (Bell Labs had one;
I don't know if any distributions outside of it ever managed.)

After preprocessing, macro expansion, and interpretation of the *roff
language has occurred, the *roff command generates a representation of a
document in device-independent format of its own, popularly known as
ditroff (for "device-independent typesetter r(un)off").  This
intermediate format is then transformed by output drivers into a format
that is consumable by another device or program; examples include HP
LaserJet 4 printers, PostScript readers or devices, PDF viewers, HTML
documents, or text (perhaps with embedded ANSI SGR escape sequences that
exercise terminal features like bold or underscored glyphs).
Historically, many other output drivers have been written for other
*roff implementations.

> $ troff -v
> GNU troff (groff) version 1.22.3

groff 1.22.4 was released last December.  It includes many improvements
I and others have made to its man pages, though much work remains to be
done, especially on the larger pages.

Which distribution are you using?  The man page macros in groff load the
local settings.  It sounds like your distribution has something
misconfigured; either the macro package was patched to not load the
local settings, or something has defined the macro directory search path
in such a way that /etc/groff doesn't get inspected.  Or something
weirder is going on.

Does "echo $GROFF_TMAC_PATH" emit anything on your system?

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Error in read.1p

[Arkadiusz Drabczyk]

On Sat, Sep 28, 2019 at 03:45:43AM +1000, G. Branden Robinson wrote:
> I don't have manpages-posix-2013a installed (because I'm a Debian
> user and the package is in Debian's unofficial non-free package archive,
> which I don't use).
> 
> But I grabbed the source package, unpacked it, and took a closer look.
> 
> The text of the man page sources is derived from the POSIX standard
> which is copyrighted by IEEE, and not licensed for modification.
> 
> Nothing indicates who was responsible for the preparation of these man
> page sources.  As you noted below, recent Austin Group bug traffic
> suggests to me that they maintain nroff sources for at least part of the
> IEEE 1003 standards documentation; whether these man pages were
> generated or hand-written is not clear, but on inspection they're clean
> enough to be the latter.
> 
> > I think this might make people want to report such bugs here.
> 
> You're right, it sure looks that way.  I was mistaken if I suggested you
> came to the wrong place--the documentation clearly directs you here.
> Other files in the distribution, like man-pages-posix-2013-a.Announce,
> speak of "the Linux man-pages maintainer", and
> man-pages-posix-2013-a.lsm identifies Michael Kerrisk as the maintainer.
> 
> > Also, I also wasn't able to find any mention of austingroupbugs.net
> > neither in man-pages-posix-2013-a/README nor at
> > https://www.kernel.org/doc/man-pages except for this
> > http://man7.org/linux/man-pages/changelog.html (at least using
> > Google's site: operator).  Could this information be put somewhere?
> 
> This is a good question for Michael.

Thank you for this explanation, it's clear that info in the tarball is
misleading.

> > That didn't work for me because /etc/groff/man.local is never opened:
> 
> Hmm!  What happens when you type "man --version"?

Actually, I have 2 man programs installed: /opt/man-db/bin/man which
is a part of man-db package and /usr/bin/man which is the default man
that Slackware comes with. Their versions are:

$ /usr/bin/man --version
man, version 1.6g

$ /opt/man-db/bin/man --version
man 2.8.4

I needed man-db because the default man had some problems with showing
manpages in Japanese:
https://www.linuxquestions.org/questions/slackware-14/%60lang%3Dja_jp-utf-8-man-man%27-doesn%27t-work-4175606785/#post5715992. Not
that I can read Japanese, it was just a test.

Back to the point - neither /usr/bin/man nor /opt/man-db/bin/man look
for /etc/groff/man.local:

$ strace -f /usr/bin/man ./read.1p |& grep 'man.local'
[pid 24026] open("/home/ja/man.local", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 24026] open("/usr/lib64/groff/site-tmac/man.local", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 24026] open("/usr/share/groff/site-tmac/man.local", O_RDONLY) = 5
$ strace -f /opt/man-db/bin/man ./read.1p |& grep 'man.local'
[pid 24139] open("/home/ja/man.local", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 24139] open("/usr/lib64/groff/site-tmac/man.local", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 24139] open("/usr/share/groff/site-tmac/man.local", O_RDONLY) = 4

I think that /etc/groff is Debian addition:
http://soc.if.usp.br/manual/groff/README.Debian. Official
documentation in `man troff' says:

-mname
Read in the file name.tmac.  If it isn't found, try tmac.name instead.
It will be first searched for in directories given with the -M command
line option, then in directories given in the GROFF_TMAC_PATH
environment variable, then in the current directory (only if in unsafe
mode), the home directory, /usr/lib64/groff/site-tmac,
/usr/share/groff/site-tmac, and /usr/share/groff/1.22.3/tmac.

> On my Debian-based system, even just running "nroff -man" over an
> (uncompressed) man page source file opens it

It does for me as well.

> > I have a hard time trying to understand the whole process and need
> > some reading on the subject.
> 
> groff is the GNU implementation of a family of programming languages for
> (...)

Wow, fantastic explanation!

> Which distribution are you using?

Slackware 14.2.

> Does "echo $GROFF_TMAC_PATH" emit anything on your system?

No, it's not set.

-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>