Fixup example files, man pages and phones parsing.

Make '/etc/remote' a working example, with some lengthy comments that
might help people trying to use it.

Remove untruths and beef up documentation for tip(1), remote(5) and
phones(5). In particular remove last reference to the 'cu' tip
interface since we use the 'cu' that comes with uucp, improve
documentation on phone numbers and flesh out documentation on
acu/modems supported. Document PHONES and REMOTE environment
variables.

Cleanup parsing of /etc/phones (so our example can be used) and ignore
lines with empty phone numbers instead of aborting the scan of the
file. This makes /etc/phones parsing consistant with ':pn:' capability
parsing. Don't try to dial empty phone numbers in either case.

ok millert@

2 files changed, 128 insertions, 73 deletions

diff --git a/share/man/man5/phones.5 b/share/man/man5/phones.5
index 3d95b21f986..e4c19c0cf47 100644
--- a/share/man/man5/phones.5
+++ b/share/man/man5/phones.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: phones.5,v 1.6 2000/10/26 00:37:05 aaron Exp $
+.\"	$OpenBSD: phones.5,v 1.7 2001/08/11 00:05:53 krw Exp $
 .\"	$NetBSD: phones.5,v 1.3 1994/11/30 19:31:25 jtc Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
@@ -39,47 +39,77 @@
 .Os
 .Sh NAME
 .Nm phones
-.Nd remote host phone number database
+.Nd remote host phone number file
 .Sh DESCRIPTION
-The
-.Pa /etc/phones
-file contains the system-wide private phone numbers for the
+.Nm
+files are used by
 .Xr tip 1
-program.
-This file is normally unreadable, and so may contain privileged information.
+to find phone numbers not included in the
+.Xr remote 5
+database(s) being used.
+.Pp
+The default file is
+.Pa /etc/phones ,
+which is used unless the
+.Ev PHONES
+environment variable has been set.
+.Pa /etc/phones
+is world readable by default, and should
+.Em not
+contain privileged information.
+.Pp
 The format of the file is a series of lines of the form:
 .Pp
-.D1 Li <system-name>[\ \et]*<phone-number>
+.D1 Li <system name>[\ \et]*<phone number>
 .Pp
-The system name is one of those defined in the
-.Xr remote 5
-file and the phone number is constructed from any sequence of
-characters terminated only by
+The system name must start at the first character on the line.
+The phone number is any sequence of characters terminated by a
 .Ql \&,
 or the end of the line.
-The
-.Ql =
-and
-.Ql *
-characters are indicators to the auto call units to pause and wait for
-a second dial tone (when going through an exchange).
-The
-.Ql =
-is required by the
-.Tn DF02-AC
-and the
-.Ql *
-is required by the
-.Tn BIZCOMP
-1030.
+Thus the phone number field can contain arbitrary dialing strings, not
+just phone numbers.
+.Pp
+Certain auto-call units or modems can use
+.Ql \&,
+in their dialing strings.
+For these units (currently Hayes, Courier and Telebit)
+.Xr tip 1
+will translate a
+.Ql \&=
+in the phone number to a
+.Ql \&,
+when actually dialing the number.
+.Pp
+If the auto-call unit is a Racal-Vadic 831,
+.Xr tip 1
+will translate a
+.Ql \&_
+in the phone number to a
+.Ql \&= .
 .Pp
-Only one phone number per line is permitted.
-However, if more than one line in the file contains the same system name,
 .Xr tip 1
-will attempt to dial each one in turn, until it establishes a connection.
+ignores all lines with a system name other than the one being
+looked up.
+Comments can be inserted into the file by making the first character
+on a line something not used to start any system name in the
+.Xr remote 5
+database(s) being used, such as 
+.Ql # .
+.Pp
+Only one phone number per line is permitted.
+To associate more than one phone number with a system name you must
+create multiple lines that have the same system name.
+.Xr tip 1 
+will try each number in sequence until it makes a connection or
+reaches the end of the file.
+.Pp
 .Sh FILES
 .Bl -tag -width /etc/phones -compact
 .It Pa /etc/phones
+The default
+.Nm
+file for
+.Xr tip 1 .
 .El
 .Sh SEE ALSO
 .Xr tip 1 ,
diff --git a/share/man/man5/remote.5 b/share/man/man5/remote.5
index 560fc942b29..088d81b77a3 100644
--- a/share/man/man5/remote.5
+++ b/share/man/man5/remote.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: remote.5,v 1.10 2001/08/02 20:37:35 hugh Exp $
+.\"	$OpenBSD: remote.5,v 1.11 2001/08/11 00:05:53 krw Exp $
 .\"	$NetBSD: remote.5,v 1.4 1997/04/20 00:05:27 mellon Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
@@ -48,8 +48,7 @@ and their attributes are stored in an
 file which is structured somewhat like the
 .Xr termcap 5
 file.
-Each line in the file provides a description for a single
-.Xr system .
+Each line in the file provides a description for a single remote host.
 Fields are separated by a colon
 .Pq Sq \&: .
 Lines ending with a
@@ -70,25 +69,29 @@ indicates a following numeric value.
 .Pp
 Entries named
 .Dq tip\&*
-and
-.Dq cu\&*
+.\"and
+.\".Dq cu\&*
 are used as default entries by
-.Xr tip ,
-and the
-.Xr cu
-interface to
-.Xr tip ,
+.Xr tip 1
+.\"and the
+.\".Xr cu 1
+.\"interface to
+.\".Xr tip 1 ,
 as follows.
 When
-.Xr tip
-is invoked with only a phone number, it looks for an entry of the form
-.Dq tip300 ,
-where 300 is the baud rate with which the connection is to be made.
-When the
-.Xr cu
-interface is used, entries of the form
-.Dq cu300
-are used.
+.Xr tip 1
+is invoked with only a baud rate, it looks for an entry of the form
+.Dq tip<baud rate> .
+E.g.
+.Ic tip -300
+will cause
+.Xr tip 1
+to look for the system tip300.
+.\"When the
+.\".Xr cu 1
+.\"interface is used, entries of the form
+.\".Dq cu300
+.\"are used.
 .Sh CAPABILITIES
 Capabilities are either strings (str), numbers (num), or boolean flags (bool).
 A string capability is specified by
@@ -107,7 +110,7 @@ Auto call unit type.
 .It Sy \&be
 (bool)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq beautify
 to
@@ -133,7 +136,7 @@ field.
 .It Sy \&dc
 (bool)
 This host is directly connected, and
-.Xr tip
+.Xr tip 1
 should not expect carrier detect to be high, nor should it exit if
 carrier detect drops.
 .It Sy \&di
@@ -153,13 +156,13 @@ one user at a time has access to the port.
 .It Sy \&ec
 (bool)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq echocheck
 to
 .Sy on ,
 so that
-.Xr tip
+.Xr tip 1
 will synchronize with the remote host during file
 transfer by waiting for the last character transmitted to echo.
 .It Sy \&el
@@ -169,14 +172,14 @@ The default is
 .Dv NULL .
 .Dq ~
 escapes are only recognized by
-.Xr tip
+.Xr tip 1
 after one of the characters in
 .Sy el ,
 or after a carriage-return.
 .It Sy \&es
 (str)
 The escape character for
-.Xr tip .
+.Xr tip 1 .
 The default is
 .Dq ~ .
 .It Sy \&et
@@ -213,7 +216,7 @@ The default is
 .It Sy \&nb
 (bool)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq beautify
 to
@@ -222,7 +225,7 @@ so that non-printable characters will not be discarded when scripting.
 .It Sy \&nt
 (bool)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq tandem
 to
@@ -232,7 +235,7 @@ from the remote host.
 .It Sy \&nv
 (bool)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq verbose
 to
@@ -244,7 +247,7 @@ Output end-of-file string.
 The default is
 .Dv NULL .
 When
-.Xr tip
+.Xr tip 1
 is transferring a file, this string is sent at end-of-file.
 .It Sy \&pa
 (str)
@@ -262,14 +265,35 @@ The default is no parity.
 .It Sy \&pn
 (str)
 Telephone number(s) for this host.
-If the telephone number field contains a
-.Ql @
-(at sign),
-.Xr tip
-searches the file
-.Pa /etc/phones
-file for a list of telephone numbers (see
-.Xr phones 5 ) .
+Either a list of arbitrary dialing strings separated by
+commas, or a
+.Ql @ .
+An at sign,
+.Ql @ ,
+tells
+.Xr tip 1
+to search the
+.Xr phones 5
+database for the list of telephone numbers.
+.Pp
+For modems or auto-call units that use a
+.Ql \&,
+in their dialing strings (hayes, courier, t3000)
+.Xr tip 1
+will convert any
+.Ql \&=
+in the string to a 
+.Ql \&,
+when dialing.
+For modems or auto-call units that use a
+.Ql \&=
+in their dial strings, (v831),
+.Xr tip 1
+will convert any
+.Ql \&_
+to a
+.Ql \&=
+when dialing.
 .It Sy \&pr
 (str)
 Character that indicates end-of-line on the remote host.
@@ -278,7 +302,7 @@ The default value is
 .It Sy \&ra
 (bool)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq raise
 to
@@ -299,7 +323,7 @@ The default value is
 .It Sy \&rw
 (str)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq rawftp
 to
@@ -308,7 +332,7 @@ so that all characters will be sent as is during file transfers.
 .It Sy \&sc
 (bool)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq script
 to
@@ -317,7 +341,7 @@ so that everything transmitted by the remote host will be recorded.
 .It Sy \&ta
 (bool)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq tandem
 to
@@ -327,7 +351,7 @@ from the remote host.
 .It Sy \&tb
 (bool)
 Initialize the 
-.Xr tip 
+.Xr tip 1 
 variable 
 .Dq tabexpand
 to
@@ -340,7 +364,7 @@ This is used primarily to share common capability information.
 .It Sy \&vb
 (bool)
 Initialize the
-.Xr tip
+.Xr tip 1
 variable
 .Dq verbose
 to
@@ -359,6 +383,7 @@ arpavax|ax:\e
 .Sh FILES
 .Bl -tag -width /etc/remote -compact
 .It Pa /etc/remote
+Global database.
 .El
 .Sh SEE ALSO
 .Xr tip 1 ,