Re: [Groff] ASCII Minus Sign in man Pages.

[G. Branden Robinson]

At 2017-04-30T21:06:12+0100, Ralph Corderoy wrote:
> Hi Branden,
> 
> > > > Also, the linitan(1) tool that is a huge part of Debian package QA
> > > > checks man pages for many problems, and I think this is one of
> > > > them.
> > >
> > > I had a look at https://lintian.debian.org/tags-all.html, searching
> > > for `manpage', but didn't spot it?
> ...
> > Here are some manpage-related lintian tags.  Make sure you let that
> > huge page finish loading before searching.
> 
> Yes, I did.  Sorry, I was talking specifically about `-' and `\-' WRT
> Debian's bodge and it working towards fixing it.  If Ingo's realignment
> goes ahead so we've a clear target then perhaps Lintian can learn some
> new transgressions.

I'm working up a man(7) style guide that is sure to be completely
uncontroversial.  <beat>

Here is the relevant material from it.

Note that this is related to but independent of Ingo's proposal.  My
preference is not to refer to \- as a minus sign at all, but that bears
on documentation, not his proposed mapping per se.

       Hyphens, dashes, and minus signs
              As noted above, use a simple  hyphen  when  you  mean  a
              hyphen,  as  in  phrases  like “best‐known”.  Use an en‐
              dash, \[en], to express a range of numbers; for example,
              “please  allow 4–6 weeks for delivery”.  Use an em‐dash,
              \[em], to express a structural aside—somewhat like this—
              in a sentence.  Use \[mi] to obtain a mathematical minus
              sign.

              Finally,  use  \-  to  represent   the   much‐overloaded
              “hyphen‐minus”  at  code  point decimal 45 in the ASCII,
              ISO 8859, and Unicode character sets.   It  is  best  to
              think of \- as a piece of meta‐punctuation that has only
              technical and contextual  meaning,  usually  in  textual
              human/computer  interface  discussions (programming lan‐
              guages, Unix‐style command‐line options, and so on).

              Two important use cases for \- are (1) to  separate  the
              name  of  a man page from its summary in the “Name” sec‐
              tion; and (2) to indicate the hyphen‐minus character  as
              terminal  input  or output in Unix command names or com‐
              mand‐line options.

Regards,
Branden

signature.asc
Description: PGP signature