escape minus signs in sndio manpages

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

escape minus signs in sndio manpages

Peter Piwowarski
This patch replaces some literal '-' with '\-' in examples for sndio-
related manpages. Certain roff implementations may render '-' as a
hyphen (unicode U+2010) rather than a minus sign (unicode U+002D or ascii 0x2D); while mandoc renders them as intended with or without
the escape, it should be more portable to use it. Found with Debian's
lintian tool while packaging portable sndio for Debian; if there is
interest I can fix any other instances in the tree that I can find.

Index: usr.bin/aucat/aucat.1
===================================================================
RCS file: /cvs/src/usr.bin/aucat/aucat.1,v
retrieving revision 1.108
diff -u -p -r1.108 aucat.1
--- usr.bin/aucat/aucat.1 21 Jan 2015 09:21:05 -0000 1.108
+++ usr.bin/aucat/aucat.1 30 Aug 2015 19:04:24 -0000
@@ -233,7 +233,7 @@ the default
 and a MMC-controlled one
 .Va snd/0.mmc :
 .Bd -literal -offset indent
-$ sndiod -r 48000 -z 480 -s default -t slave -s mmc
+$ sndiod \-r 48000 \-z 480 \-s default \-t slave \-s mmc
 .Ed
 .Pp
 Programs using
@@ -248,7 +248,7 @@ connected to the
 .Va midithru/0
 MIDI port:
 .Bd -literal -offset indent
-$ aucat -f snd/0.mmc -q midithru/0 -i file.wav
+$ aucat \-f snd/0.mmc \-q midithru/0 \-i file.wav
 .Ed
 .Pp
 At this stage,
@@ -264,20 +264,20 @@ port as MTC clock source, assured to be
 .Sh EXAMPLES
 Mix and play two files while recording a third file:
 .Bd -literal -offset indent
-$ aucat -i file1.wav -i file2.wav -o file3.wav
+$ aucat \-i file1.wav \-i file2.wav \-o file3.wav
 .Ed
 .Pp
 Record channels 2 and 3 into one stereo file and
 channels 6 and 7 into another stereo file using a 44.1kHz sampling
 rate for both:
 .Bd -literal -offset indent
-$ aucat -r 44100 -c 2:3 -o file1.wav -c 6:7 -o file2.wav
+$ aucat \-r 44100 \-c 2:3 \-o file1.wav \-c 6:7 \-o file2.wav
 .Ed
 .Pp
 Split a stereo file into two mono files:
 .Bd -literal -offset indent
-$ aucat -n -i stereo.wav -c 0:0 -o left.wav \e
- -c 1:1 -o right.wav
+$ aucat \-n \-i stereo.wav \-c 0:0 \-o left.wav \e
+ \-c 1:1 \-o right.wav
 .Ed
 .Sh SEE ALSO
 .Xr audioctl 1 ,
Index: usr.bin/sndiod/sndiod.1
===================================================================
RCS file: /cvs/src/usr.bin/sndiod/sndiod.1,v
retrieving revision 1.4
diff -u -p -r1.4 sndiod.1
--- usr.bin/sndiod/sndiod.1 13 Aug 2014 08:42:46 -0000 1.4
+++ usr.bin/sndiod/sndiod.1 30 Aug 2015 19:04:28 -0000
@@ -474,7 +474,7 @@ the default
 and a MIDI-controlled
 .Va snd/0.mmc :
 .Bd -literal -offset indent
-$ sndiod -r 48000 -z 400 -s default -t slave -s mmc
+$ sndiod \-r 48000 \-z 400 \-s default \-t slave \-s mmc
 .Ed
 .Pp
 Streams connected to
@@ -493,7 +493,7 @@ and
 .Pa snd/0.rear
 devices:
 .Bd -literal -offset indent
-$ sndiod -s default -c 2:3 -s rear
+$ sndiod \-s default \-c 2:3 \-s rear
 .Ed
 .Pp
 Start server creating the default sub-device with low volume and
@@ -503,7 +503,7 @@ and
 .Pa snd/0.max
 devices:
 .Bd -literal -offset indent
-$ sndiod -v 65 -s default -v 127 -s max
+$ sndiod \-v 65 \-s default \-v 127 \-s max
 .Ed
 .Pp
 Start server configuring the audio device to use
@@ -512,7 +512,7 @@ and 2-block buffers.
 The corresponding latency is 10ms, which is
 the time it takes the sound to propagate 3.5 meters.
 .Bd -literal -offset indent
-$ sndiod -r 48000 -b 480 -z 240
+$ sndiod \-r 48000 \-b 480 \-z 240
 .Ed
 .Sh SEE ALSO
 .Xr sndio 7

Reply | Threaded
Open this post in threaded view
|

Re: escape minus signs in sndio manpages

Alexandre Ratchov-2
On Sun, Aug 30, 2015 at 03:35:21PM -0400, Peter Piwowarski wrote:
> This patch replaces some literal '-' with '\-' in examples for sndio-
> related manpages. Certain roff implementations may render '-' as a
> hyphen (unicode U+2010) rather than a minus sign (unicode U+002D or ascii 0x2D); while mandoc renders them as intended with or without
> the escape, it should be more portable to use it. Found with Debian's
> lintian tool while packaging portable sndio for Debian; if there is
> interest I can fix any other instances in the tree that I can find.

replacing - by \- in literals produces identical files; tried
mandoc and latest groff (1.22.3) with utf8, ps and html outputs, so
I don't see how this could hurt.

schwarze, jmc, opinions?

Reply | Threaded
Open this post in threaded view
|

Re: escape minus signs in sndio manpages

Peter Piwowarski
In reply to this post by Peter Piwowarski
Ingo Schwarze wrote:
> Until somebody shows me a specific list of roff implementations
> that do so, i challenge that statement as urban legend, and the
> advice to use \- for flags as cargo cult programming.

The reason lintian complains about this is that Debian had problems with
- rendering as a unicode hyphen in their groff at one time[1]. As far as
I can tell this no longer applies to current groff (which does indeed
weaken the rationale here).

> Can you tell me who the author and who the maintainer of that
> tool is?  I'd like to question them about the reasons for their
> recommendation, if possible.

lintian is maintained by a team who can be contacted at
mailto:[hidden email].

...however, digging further, they also don't care about this anymore[2].
In this light I'm sorry to have wasted everybody's time with this patch.

[1]
https://lists.debian.org/debian-devel/2003/debian-devel-200303/msg01481.html
[2] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=785353