discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Fabio Scotoni <fabio@esse.ch>
To: discuss@mandoc.bsd.lv
Subject: Handling .%P ranges with hyphen in mdoc(7); pp./p.
Date: Tue, 23 Apr 2019 18:22:17 +0200	[thread overview]
Message-ID: <74971648-e4d7-ace2-5a96-b80f304fc259@esse.ch> (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 discuss+unsubscribe@mandoc.bsd.lv

             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 \
    --in-reply-to=74971648-e4d7-ace2-5a96-b80f304fc259@esse.ch \
    --to=fabio@esse.ch \
    --cc=discuss@mandoc.bsd.lv \
    --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).