Re: Error in read.1p

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- 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 --]