soxdial: tweak doc.

1 files changed, 54 insertions, 32 deletions

diff --git a/soxdial b/soxdial
index c9869a8..e445d55 100755
--- a/soxdial
+++ b/soxdial
@@ -17,6 +17,8 @@ soxdial - generate DTMF (touchtone or blue box) audio
 
 B<soxdial> [I<global-options>] [ [I<dial-options>] [I<dial-string>] ... ]
 
+B<soxdial> [I<utility-option>]
+
 =head1 DESCRIPTION
 
 B<soxdial> uses B<sox>(1) to generate DTMF tones (aka touchtone
@@ -46,6 +48,29 @@ their arguments: B<-b16> and B<-b 16> are equivalent. Also, GNU-style
 B<--option=value> is supported (and works the same as B<--option
 value>).
 
+=head2 Utility Options
+
+=over 4
+
+=item B<-V>, B<--version>
+
+Print the version number of B<soxdial>, then exit.
+
+=item B<--help>
+
+Prints this help text, via B<perldoc>(1), then exit.
+
+=item B<--man>
+
+Prints this help text as a man page, via B<pod2man>(1), then exit. Suggested use:
+
+  soxdial --man > soxdial.1
+
+Then B<soxdial.1> can be installed in e.g. /usr/man/man1 or
+/usr/share/man/man1 or wherever your OS keeps its man pages.
+
+=back
+
 =head2 Global Options
 
 These options affect the entire output. They should only be given once,
@@ -102,23 +127,6 @@ error.
 Do not execute the generated B<sox> command. This option also
 enables B<-v>.
 
-=item B<-V>, B<--version>
-
-Print the version number of B<soxdial>, then exit.
-
-=item B<--help>
-
-Prints this help text, via B<perldoc>(1), then exit.
-
-=item B<--man>
-
-Prints this help text as a man page, via B<pod2man>(1), then exit. Suggested use:
-
-  soxdial --man > soxdial.1
-
-Then B<soxdial.1> can be installed in e.g. /usr/man/man1 or
-/usr/share/man/man1 or wherever your OS keeps its man pages.
-
 =back
 
 =head2 Dial Options
@@ -190,17 +198,21 @@ Switch to bluebox dialling mode. See B<BLUEBOX MODE> below for details.
 
 =item B<-N>, B<--normal>
 
-Switch to normal dialling mode. This is the default; this option exists
-to turn off a prior B<-B>, B<--bluebox>.
+Switch to normal touchtone dialling mode. This is the default; this
+option exists to turn off a prior B<-B>, B<--bluebox>.
 
 =back
 
 =head2 Dial Strings
 
-These are the actual digits to be dialled. DTMF digits 0 to 9, #,
-and * are supported. By default, letters are also supported, and will
-be converted to digits according to the standard layout of touchtone
-phones (e.g. A through C convert to 2, D through F are 3, etc).
+These are the actual digits to be dialled. Each dial string consists
+of one or more digits (as many as desired), and they will be played
+consecutively.
+
+DTMF digits 0 to 9, #, and * are supported. By default, letters are
+also supported, and will be converted to digits according to the
+standard layout of touchtone phones (e.g. A through C convert to 2,
+D through F are 3, etc).
 
 Q and Z weren't present on classic phones, but they will be converted
 to 7 and 9, respectively (like modern cell phones).
@@ -235,15 +247,14 @@ the timing to whatever it was before entering bluebox mode.
 
 In bluebox mode, there is no letter-to-number conversion.
 
-The bluebox keypad has digits 0-9, which can be combined in a single
-dial string. The keys kp, kp2, st, st2, and st3 must appear alone
-as dial strings (meaning, put a space before and after them). The
-alternate names for 0 (10), st3 (11), and st2 (12) are not supported,
-since there's no way to tell an 11 from two 1's.
-
-See this Wikipedia article for more information on the blue box:
+The bluebox keypad has digits B<0-9>, which can be combined in a
+single dial string. The keys B<kp>, B<kp2>, B<st>, B<st2>, and B<st3>
+must appear alone as separate dial strings (meaning, put a space
+before and after them).
 
-  https://en.wikipedia.org/wiki/Bluebox
+The alternate names for B<0> (B<10>), B<st3> (B<11>), and B<st2>
+(B<12>) are not supported, since there's no way to tell an 11 from
+two 1's.
 
 =head1 NOTES
 
@@ -269,13 +280,24 @@ If you use B<-v>, B<--verbose>, you'll get warned about it at least.
 B<3.> I haven't been able to test this with a real land-line phone to
 see whether it will actually dial out.
 
-B<4.> Possibly there will be support for bluebox tones in the future.
+B<4.> I know nothing about blueboxes other than what I've read on
+Wikipedia, and there's no way I know of to test whether the bluebox
+tones are correct (you'd need a time machine).
 
 =head1 AUTHOR
 
 soxdial was written by B. Watson <urchlay@slackware.uk> and released
 under the WTFPL: Do WTF you want with this.
 
+=head1 SEE ALSO
+
+B<sox>(1)
+
+The Wikipedia articles on DTMF and the Blue Box:
+
+  https://en.wikipedia.org/wiki/Dtmf
+  https://en.wikipedia.org/wiki/Bluebox
+
 =cut
 
 %freqs = (