From: Fabio Scotoni <email@example.com> To: firstname.lastname@example.org Subject: Handling .%P ranges with hyphen in mdoc(7); pp./p. Date: Tue, 23 Apr 2019 18:22:17 +0200 [thread overview] Message-ID: <email@example.com> (raw) 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 firstname.lastname@example.org
next reply other threads:[~2019-04-23 16:22 UTC|newest] Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top 2019-04-23 16:22 Fabio Scotoni [this message] 2019-04-23 19:12 ` Ingo Schwarze
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: Handling .%P ranges with hyphen in mdoc(7); pp./p.' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
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).