Handling .%P ranges with hyphen in mdoc(7); pp./p.

[Fabio Scotoni <fabio@esse.ch>]

Summary:
a. .%P does not insert "pp." or "p." and this may need to be
   documented or changed;
b. A hyphen in .%P should be converted to an en dash in the output.



In mdoc(7), .%P specifies a "book or journal page of an Rs block".
It leaves open how exactly this is meant to be specified.

Regarding the question of whether inserting "pp."/"p." is the
responsibility of -mdoc or the user:

As an example, there seem to be five different variants of how .%P is
invoked in the OpenBSD tree:
- lib/libc/db/man/btree.3: .%P pp 121-138 ("pp" with no dot, range with
  hyphen)
- lib/libc/hash/rmd160.3: .%P pp. 24-28 ("pp." with dot, range with
  hyphen)
- lib/libc/stdlib/qsort.3: .%P pp. 114\-123, 145\-149 ("pp." with dot,
  range with explicit ASCII hyphen)
- share/man/man4/kate.4: .%P pp. 21--23 and pp. 179--184 ("pp." with
  dot, range with double hyphen)
- share/man/man7/eqn.7: %P 151\(en157 (no page number, range with \(en)
These probably cover just about everything that could be found in the wild.
While it seems most of the pages specify "pp."/"p." themselves,
but it may be worthwhile to insert "pp."/"p." if the first character of
the first argument is a number ("pp." if a hyphen is found, "p." otherwise).

The .%P macro seems inspired by refer(1), as it mostly follows the
format of .[ .] references except for specifiers having to begin with a dot.

Checking with the GNU refer(1) man page, it says that "A range of pages
can be specified as m-n", using \- in the troff source of refer.1,
apparently without specifying "p." or "pp.".
The example for UNIX refer(1) %P in "Some Applications of Inverted
Indexes on the UNIX System" by M. E. Lesk in Vol. 2A of the Seventh
Edition UNIX Programmer's Manual also suggests using a hyphen for a
range of pages with no leading "p." or "pp.".
Seventh Edition refer(1) would indeed prepend "p." and "pp.",
as do GNU refer(1) and heirloom-doctools refer(1).

Neither groff -mdoc nor mandoc do this, however.
The cause is probably tradition in 4.4BSD, where .%P arguments
consistently specified "p."/"pp.".



Regarding the question of what to do with the hyphen:

It seems that common typographical wisdom suggests that ranges of
numbers are specified with an en dash (see the section on hyphens and
dashes in Matthew Butterick's Practical Typography).
However, neither GNU refer and heirloom-doctools refer do this.
Some man pages do this manually (e.g. eqn.7 in the mandoc distribution).

To improve the quality of output, mandoc should convert hyphens in .%P
to en dashes in HTML, PostScript and PDF output, possibly also in UTF-8
output.



The benefit of changing the behavior of .%P would be fairly minimal
(typographically correct dashes), but it may be worth considering
nonetheless.

Fabio
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv