discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Handling .%P ranges with hyphen in mdoc(7); pp./p.
@ 2019-04-23 16:22 Fabio Scotoni
  2019-04-23 19:12 ` Ingo Schwarze
  0 siblings, 1 reply; 2+ messages in thread
From: Fabio Scotoni @ 2019-04-23 16:22 UTC (permalink / raw)
  To: discuss

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

^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2019-04-23 19:12 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-04-23 16:22 Handling .%P ranges with hyphen in mdoc(7); pp./p Fabio Scotoni
2019-04-23 19:12 ` Ingo Schwarze

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).