[src/trunk]: src/usr.sbin/bta2dpd/bta2dpd Sort SYNOPSIS, descriptions, SEE ALSO.

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/79f99d73cbcf
branches:  trunk
changeset: 350968:79f99d73cbcf
user:      wiz <wiz%NetBSD.org@localhost>
date:      Sat Jan 28 23:52:45 2017 +0000

description:
Sort SYNOPSIS, descriptions, SEE ALSO.
Use more macros.
Fix sections.
New sentence, new line.
Various other improvements.

diffstat:

 usr.sbin/bta2dpd/bta2dpd/bta2dpd.8 |  207 +++++++++++++++++++-----------------
 1 files changed, 107 insertions(+), 100 deletions(-)

diffs (truncated from 354 to 300 lines):

diff -r 66d06517525d -r 79f99d73cbcf usr.sbin/bta2dpd/bta2dpd/bta2dpd.8
--- a/usr.sbin/bta2dpd/bta2dpd/bta2dpd.8        Sat Jan 28 23:42:36 2017 +0000
+++ b/usr.sbin/bta2dpd/bta2dpd/bta2dpd.8        Sat Jan 28 23:52:45 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: bta2dpd.8,v 1.1 2017/01/28 16:55:54 nat Exp $
+.\"    $NetBSD: bta2dpd.8,v 1.2 2017/01/28 23:52:45 wiz Exp $
 .\"
 .\" Copyright (c) 2015 - 2016  Nathanial Sloss <nathanialsloss%yahoo.com.au@localhost>
 .\" All rights reserved.
@@ -37,45 +37,44 @@
 .Nd Bluetooth Advanced Audio Distribution Profile daemon
 .Sh SYNOPSIS
 .Nm
-.Op Fl d Ar device
-.Op Fl m Ar mode
+.Op Fl v
+.Op Fl A Ar bitpool_allocation
 .Op Fl B Ar bitpool
-.Op Fl V Ar volume
+.Op Fl b Ar blocks
+.Op Fl d Ar device
+.Op Fl e Ar encoding_bands
+.Op Fl f Ar channel_mode
 .Op Fl M Ar mtu
-.Op Fl f Ar channel_mode
+.Op Fl m Ar mode
 .Op Fl r Ar rate
-.Op Fl b Ar blocks
-.Op Fl e Ar encoding_bands
-.Op Fl A Ar bitpool_allocation
-.Op Fl v
+.Op Fl V Ar volume
 .Fl a Ar address
-.Ar files...
+.Ar files ...
 .Nm
 .Fl K
-.Op Fl I
+.Op Fl Iv
+.Op Fl A Ar bitpool_allocation
+.Op Fl B Ar bitpool
+.Op Fl b Ar blocks
 .Op Fl d Ar device
+.Op Fl e Ar encoding_bands
+.Op Fl f Ar channel_mode
 .Op Fl m Ar mode
 .Op Fl p Ar psm
-.Op Fl B Ar bitpool
-.Op Fl f Ar channel_mode
 .Op Fl r Ar rate
-.Op Fl b Ar blocks
-.Op Fl e Ar encoding_bands
-.Op Fl A Ar bitpool_allocation
-.Op Fl v
 .Op a Ar address
 .Ar file
 .Nm
 .Fl t
+.Op Fl A Ar bitpool_allocation
 .Op Fl B Ar bitpool
-.Op Fl V Ar volume
-.Op Fl M Ar mtu
-.Op Fl f Ar channel_mode
-.Op Fl r Ar rate
 .Op Fl b Ar blocks
 .Op Fl e Ar encoding_bands
-.Op Fl A Ar bitpool_allocation
-.Ar files...
+.Op Fl f Ar channel_mode
+.Op Fl M Ar mtu
+.Op Fl r Ar rate
+.Op Fl V Ar volume
+.Ar files ...
 .Nm
 .Fl t
 .Fl K
@@ -84,12 +83,9 @@
 The
 .Nm
 daemon is used to transmit/receive audio to/from Bluetooth devices such as
-speakers or headphones, using the Advanced Audio Distribution Profile 
-(A2DP)
+speakers or headphones, using the Advanced Audio Distribution Profile
+(A2DP).
 .Bl -tag -indent width
-.It Fl d Ar device
-Local device address.
-May be given as BDADDR or device name.
 .It Fl a Ar address
 Remote device address.
 The
@@ -100,83 +96,91 @@
 .Nm
 attempts to resolve the name via
 .Xr bt_gethostbyname 3 .
-.It Ar files...
-Files to stream. These can be wav files or CD-Audio Red Book data or output from
-.Xr pad 4
-device.
-If not specified the default is stdin or stdout if -K applied and
+.It Fl B Ar bitpool
+Allows setting the maximum bitpool value for your device.
+This may have to be lowered if audio is distorted.
+.Pp
+Use
 .Nm
-is used as an audio sink.
-.Pp
-When writing to a file or stdout it is raw 16-bit little endian (pulse coded
-modulation) pcm data.
-So a utility must be used to convert the file to add a header or use the
-audioplay command as stated in EXAMPLES.
+with only the
+.Fl v
+option and the maximum bitpool for your device will be printed to stdout.
+.It Fl d Ar device
+Local device address.
+May be given as BDADDR or device name.
+.It Fl I
+Initiate a Discover command.
+ Useful when used as an audio sink as some devices need this to pair.
+.It Fl K
+Allows registering as an audio sink receiving an incoming connection.
 .It Fl M Ar mtu
 Allows setting the Maximum Transmission Unit (MTU) for the streaming
 connections.
 .Pp
 For most devices this would be 672 but if audio is broken or has gaps lowering
 this value may help.
-.It Fl I 
-Initiate a Discover command.  Useful when used as an audio sink as some
-devices need this to pair.
-.It Fl K 
-Allows registering as an audio sink receiving an incoming connection.
 .It Fl m Ar mode
 Set L2CAP connection link mode.
 Supported modes are:
 .Pp
-.Bl -tag -compact
+.Bl -tag -compact -width encrypt
 .It auth
-require devices to be paired.
+Require devices to be paired.
 .It encrypt
-auth, plus enable encryption.
+Auth, plus enable encryption.
 .It secure
-encryption, plus change of link key.
+Encryption, plus change of link key.
 .El
 .It Fl p Ar psm
 Allows changing the l2cap psm for an audio sink the default is 25.
 Most all devices will use 25.
 .It Fl t
-Test mode can be used with -K to decode and receive encoded music from
-stdout/stdin to file.
+Test mode can be used with
+.Fl K
+to decode and receive encoded music from stdout/stdin to file.
 .It Fl V Ar volume
 Allows shifting the volume of the music by 1 or 2 bits prior to encoding for
 increased volume.
 .Pp
 .Sy USE WITH CARE
 as this may mean the output is quite loud.
-.It Fl B Ar bitpool
-Allows setting the maximum bitpool value for your device.
-This may have to be lowered if audio is distorted.
-.Pp
-Use
-.Nm
-with only the -v option and the maximum bitpool for your device will be printed
-to stdout.
 .It Fl v
 Be verbose.
+.It Ar files ...
+Files to stream.
+These can be WAV files or CD-Audio Red Book data or output from a
+.Xr pad 4
+device.
+If not specified, the default is stdin or stdout if
+.Fl K
+applied and
+.Nm
+is used as an audio sink.
+.Pp
+When writing to a file or stdout it is raw 16-bit little endian (pulse coded
+modulation) PCM data.
+So a utility must be used to convert the file to add a header or use the
+.Xr audioplay 1
+command as stated in
+.Sx EXAMPLES .
 .El
 .Ss Channel Modes
 .Bl -tag -indent width
 .It Fl f Ar channel_mode
-.Ar 0
+.Bl -tag -width 2n
+.It Ar 0
 This specifies that all possible input formats are accepted and then one is
 chosen starting with joint stereo then stereo then 2 channel then mono.
-.Lp
-.Ar m
+.It Ar m
 This specifies that the input is monophonic.
-.Lp
-.Ar 2
+.It Ar 2
 This specifies that the input is dual-channel.
-.Lp
-.Ar j
+.It Ar j
 This specifies that the input is joint-stereo.
-.Lp
-.Ar s
+.It Ar s
 This specifies that the input is stereo.
 This is the default.
+.El
 .Pp
 Specifying joint stereo as opposed to stereo would allow for a slightly higher
 quality of playback as
@@ -184,95 +188,98 @@
 will only encode stereo and monophonic streams.
 .It Fl r Ar rate
 The frequency of the input.
-Where rate is one of 0 16000, 32000, 44100, 48000.
+Where rate is one of 0, 16000, 32000, 44100, 48000.
 This defaults to 44.1 kHz.
 .Pp
 A value of 0 will arbitrate from the highest to lowest frequency.
 .El
 .Ss Sub Band Codec (SBC) Encoding Options
 .Bl -tag -indent width
+.It Fl A Ar bitpool_allocation
+.Bl -tag width 2n
+.It Ar 0
+Bit Allocation is negotiated starting with Loudness then SNR.
+.It Ar S
+Audio is encoded with SNR (Signal to Noise Ratio) bit allocation.
+.It Ar L
+Audio is encoded with Loudness bit allocation.
+This is the default.
+.El
 .It Fl b Ar blocks
 Number of blocks to use for encoding.
-Where blocks is one of 0 4, 8, 12, 16.
+Where blocks is one of 0, 4, 8, 12, 16.
 This defaults to 16 blocks.
 .Pp
 In the case of 0 the number of blocks is
 negotiated starting from 16 down to 4.
 .It Fl e Ar bands
-.Ar 0
+.Bl -tag -width 2n
+.It Ar 0
 Number of SBC bands is negotiated 8 then 4.
-.Lp
-.Ar 4
-Audio is endoded with 4 SBC bands.
-.Lp
-.Ar 8
-Audio is endoded with 8 SBC bands.
+.It Ar 4
+Audio is encoded with 4 SBC bands.
+.It Ar 8
+Audio is encoded with 8 SBC bands.
 This is the default.
-.It Fl A Ar bitpool_allocation
-.Ar 0
-Bit Allocation is negotiated starting with Loudness then SNR.
-.Lp
-.Ar S
-Audio is encoded with SNR (Signal to Noise Ratio) bit allocation.
-.Lp
-.Ar L
-Audio is encoded with Loudness bit allocation.
-This is the default.
+.El
 .El
 .Pp
 It may be necessary to use
-.Xr btconfig 1
-to set the class of your bluetooth adapter to that of headphones when
+.Xr btconfig 8
+to set the class of your Bluetooth adapter to that of headphones when
 using
 .Nm
 as an audio sink.
-i.e
+I.e.,
 .Dl btconfig ubt0 class 0x200418
 Then start
 .Nm
-with -K before pairing.
+with
+.Fl K
+before pairing.
 .Pp
 This is necessary as some devices only perform an