*** empty log message ***

3 files changed, 313 insertions, 9 deletions

diff --git a/Makefile.am b/Makefile.am
index b82e068..a6250cd 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -8,6 +8,9 @@
 # $Id$
 #
 # $Log$
+# Revision 1.7  2008/02/27 18:29:49  james
+# *** empty log message ***
+#
 # Revision 1.6  2008/02/27 16:01:24  james
 # *** empty log message ***
 #
@@ -55,20 +58,21 @@ VCHK=${shell cat ${VFS} | @MD5SUM@ | @AWK@ '{print $$1 }' }
 VNUM=${shell @GREP@ ${VCHK} ${VFD}/version-md5sums | @AWK@ '{ print $$2 }'  }
 VSTP=${shell @GREP@ ${VCHK} ${VFD}/version-stamps  | @AWK@  'BEGIN { FS="\t" }; { print $$2 }'  }
 VDEF=${shell echo `cat ${VFD}/version-major`.`cat ${VFD}/version-minor`.`cat ${VFD}/version-micro` }
+VSDF=${shell tail -1 ${VFD}/version-stamps  | @AWK@  'BEGIN { FS="\t" }; { print $$2 }'  }
 
-EXTRA_DIST=version-files version-major version-minor version-micro version-md5sums version-stamps
+EXTRA_DIST=version-files version-major version-minor version-micro version-md5sums version-stamps sympathy.1
 
 version.sed: $(VFD)/version-files $(VFD)/version-major \
 	$(VFD)/version-minor $(VFD)/version-micro \
 	$(VFD)/version-md5sums $(VFD)/version-stamps ${VFS} Makefile
 	if [ .${VNUM} = . ]; then \
 		echo "s/%VERSION%/${VDEF}-E/g" > version.sed; \
-		echo "s/%VERSIONSTAMP%/After ${VSTP}/g" >> version.sed; \
-		echo "s/%LONGVERSION%/libsympathy version ${VNUM} + Edits/g" >> version.sed; \
+		echo "s/%VERSIONSTAMP%/After ${VSDF}/g" >> version.sed; \
+		echo "s/%LONGVERSION%/Version ${VDEF} + Edits/g" >> version.sed; \
 	else \
 		echo "s/%VERSION%/${VNUM}/g" > version.sed; \
 		echo "s/%VERSIONSTAMP%/${VSTP}/g" >> version.sed; \
-		echo "s/%LONGVERSION%/libsympathy version ${VNUM}/g" >> version.sed; \
+		echo "s/%LONGVERSION%/Version ${VNUM}/g" >> version.sed; \
 	fi
 
 protos:
diff --git a/apps/usage.c b/apps/usage.c
index 5a00619..d76f9d9 100644
--- a/apps/usage.c
+++ b/apps/usage.c
@@ -10,6 +10,9 @@ static char rcsid[] = "$Id$";
 
 /*
  * $Log$
+ * Revision 1.16  2008/02/27 18:29:49  james
+ * *** empty log message ***
+ *
  * Revision 1.15  2008/02/27 16:01:24  james
  * *** empty log message ***
  *
@@ -65,11 +68,12 @@ usage (void)
 {
 
   fprintf (stderr, "Usage:\n"
-           "sympathy -t      [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u]\n"
-           "sympathy -s      [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u] [-k skt]\n"
+           "sympathy -t      [-K] [-d serialdev|-p] [-b baud] [-f] [-L log]\n"
+           "                                  [-w WxH] [-u]\n"
+           "sympathy -s      [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-k skt]\n"
            "                      [-n hlines] [-w WxH] [-F]\n"
-           "sympathy [-s -c] [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u] [-k skt]\n"
-           "                      [-n hlines] [-w WxH]\n"
+           "sympathy [-s -c] [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-k skt]\n"
+           "                      [-n hlines] [-w WxH] [-u]\n"
            "sympathy -c      [-H] [-u] -k skt\n"
            "sympathy -r id   [-H] [-u]\n"
            "sympathy {-l|-ls}\n"
diff --git a/sympathy.1 b/sympathy.1
index 06afdbc..8da2be1 100644
--- a/sympathy.1
+++ b/sympathy.1
@@ -2,6 +2,44 @@
 .SH NAME
 sympathy \- client/server terminal emulator with logging
 .SH SYNOPSIS
+.B sympathy \-\fBt\fP
+[
+.B \fIterminal_options\fP
+] [
+.B \fIdisplay_options\fP
+]
+.br
+.B sympathy \-\fBs\fP
+[
+.B \fIterminal_options\fP
+] [
+.B \fIserver_options\fP
+]
+.br
+.B sympathy 
+[
+.B \-\fBc\fP \-\fBs\fP
+] [
+.B \fIterminal_options\fP
+] [
+.B \fIserver_options\fP
+] [
+.B \fIclient_options\fP
+]
+.br
+.B sympathy \-\fBc\fP
+[
+.B \fIclient_options\fP
+] 
+.br
+.B sympathy \-\fBr\fP
+id
+[
+.B \fIclient_options\fP
+] 
+.br
+.B sympathy \-\fBv\fP
+.br
 .\"           "sympathy -t      [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u]\n"
 .\"           "sympathy -s      [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u] [-k skt]\n"
 .\"           "                      [-n hlines] [-w WxH] [-F]\n"
@@ -14,9 +52,262 @@ sympathy \- client/server terminal emulator with logging
 .\"           "sympathy -h\n"
 
 .SH DESCRIPTION
+.I Sympathy
+is a VT52/VT100/ANSI terminal emulator with some special features. In normal use
+.I sympathy
+would sit between a terminal device (a serial port or a ptty) and
+the user's usual terminal emaulator (eg xterm(1)). 
+.I Sympathy
+renders data from the terminal device into an internal frame buffer
+and then expresses changes in this frame buffer to the outer terminal
+emulator using a small subset of ANSI escape codes. 
+.I Sympathy 
+always generates valid escape codes to the outer terminal, and will 
+reset the state of its internal terminal emulator when it detects
+framing errors on the terminal device.
+.PP
+.I Sympathy\fP,
+unlike screen(1), takes care to preserve the scrollback features
+of the outer terminal emulator: lines that scroll of the top of the internal 
+frame buffer are scrolled off the top of the outer terminal emaultor. When
+sympathy is used in client/server mode, some history is added to the outer 
+terminal emulator when the client connects.
+.PP
+.I Sympathy
+also supports automatic baud rate detection, and advanced logging features.
+.I Sympathy
+logs whenever any of the modem control lines change state, receive errors,
+and the contents
+of any line on the frame buffer as the cursor moves off it.
 .SH OPTIONS
+.B \fImajor mode options\fP:
+.TP 5
+.B \-t
+act as terminal emulator only:
+.I sympathy
+opens the terminal device and outputs into the outer terminal emulator, when sympathy exits the 
+device is closed and no process remains. In this mode sympathy behaves like a traditional
+terminal emulator such as cu(1) or minicom(1).
+.TP 5
+.B \-s
+act as server only:
+.I sympathy
+opens the terminal device and renders into an internal frame buffer, listens for clients
+on the socket and logs activity. By default the server will fork into a daemon processes
+but can be forced to remain in the forground with the \-\fBF\fP option.
+.TP 5
+.B \-c\fP or \fB\-r\fP \fIid\fP
+act as client only:
+.I sympathy
+connects to a sympathy server process and injects the history into the outer terminal
+emulator,
+and connects the user with the terminal device. One server process can support multiple 
+client processes. This mode can also be used to obtain a dump of the current screen
+in HTML format (see the \-\fBH\fP option). The \-\fPr\fP option connects to a server
+on the socket ~/.sympathy/\fIid\fP  or if \fIid\fP is an integer 
+~/.sympathy/\fIhostname\fP.\fIid\fP mimicking the behaviour of screen(1). With the 
+\-\fBc\fP option the socket must be specified with the \-\fBk\fP option.
+.TP 5
+.B \fP[\fB \-c \-s \fP]
+act as both client and server:
+.I sympathy
+forks. The child process becomes a server, and the orginal process becomes a client
+which then connects to the server. This is the default major mode if no other is specified. 
+Since the default terminal device is a ptty, running 
+.I sympathy
+with no arguments will start a new shell in a daemonized process and connect to it
+as a client from the original process, mimicking the behaviour of screen(1)
+.TP 5 
+.B \-l\fP or \fB\-ls
+show active sockets:
+.I sympathy 
+will show active sockets, ones to which a call to connect(2) succeeds, 
+in ~/.sympathy. If the socket name begins with the hostname of the machine, and
+the call to connect(2) fails, then socket will be unlinked. 
+.TP 5 
+.B \-v
+show current version:
+.I sympathy 
+will print the the version number of the code it was compiled with.
+.TP 5
+.B \-h
+show help:
+.I sympathy 
+will show brief usage instructions
+.PP
+.B \fIterminal_options\fP:
+.TP 5
+.B \-d \fIserialdev\fP
+connect to terminal device \fIserialdev\fP, eg /dev/ttyS0. 
+By default 
+.I sympathy
+doesn't
+lock the terminal device, but checks periodically for lock files of other processes. If 
+sympathy detects another lock file it displays \fBLocked\fP in the status line 
+and refuses I/O on the device until the lock file is removed or becomes invalid.
+To lock the device use the \-\fBK\fP option. 
+.I Sympathy 
+will in addition check that the name of the device does not occur in /proc/cmdline
+as an argument to the \fIconsole\fP kernel parameter. 
+The \-\fBd\fP option is incompatible with the \-\fBp\fP option. 
+.TP 5
+.B \-p
+connect to a pseudo-tty instead of a terminal device, and fork a login shell in
+it. The \-\fBd\fP option is incompatible with the \-\fBd\fP option. This is the default 
+terminal device if none is specified.
+.TP 5
+.B \-K
+lock the terminal device specificed in the \-\fBd\fP option. 
+.I Sympathy
+generates lock files in a staggering variety of formats and places. For locks
+based on the name of the device sympathy generates lock files for all devices
+with the same major and minor in /dev, /dev/usb and /dev/tts, it uses both normal
+and lower case and replaces occurances of '/' in the device name with both '.' and '_'.
+.I Sympathy
+also generates locks based on the device major and minor numbers, and for all lock file
+names generates them in any of the follwoing directories that are writable:
+/var/lock/uucp, /var/spool/lock, /var/spool/uucp, /etc/locks, /usr/spool/uucp, 
+/var/spool/locks, /usr/spool/lock, /usr/spool/locks, /usr/spool/uucp/LCK, /var/lock. 
+Lock files are assumed to be in HDB format.
+.TP 5
+.B \-b \fIbaudrate\fP
+set the baud rate of the terminal device specificed in the \-\fBd\fP to baudrate, if omitted
+the current baudrate of the serial port will be used.
+.TP 5
+.B \-f
+turn on flow control on the terminal device. This option add \fICRTSCTS\fP to sympathy's default 
+\fIc_cflag\fPs of \fICS8|CREAD|CLOCAL\fP.
+.TP 5
+.B \-L \fIlogfile\fP
+log activity to the file \fIlogfile\fP. If \fIlogfile\fP is '-' then log to \fIstdout\fP. Note
+that logging to \fIstdout\fP only makes sense with the \-\fBF\fP \fIserver_option\fP. 
+.TP 5
+.B \-w \fIwidth\fP[x\fIheight\fP]
+set the initalize size of the terminal emulator's frame buffer to be \fIwidth\fP columns
+by \fIheight\fP rows. If \fIheight\fP is ommited it defaults to 24, the default width
+is 80. These values may
+be overridden later by terminal escape sequences. If \-\fBp\fP is also specificed
+the ptty will have its window size set to match.
+.PP
+.B \fIdisplay_options\fP:
+.TP 5
+.B \-u
+attempt to render unicode characters in the internal frame buffer to the outer terminal 
+emulator by using ISO-2202 sequences. 
+.I Sympathy
+currently only checks to see if an appropriate character appears in the VT102 
+US character set, or in the VT102 'special characters and line drawing' character set.
+If the character appears in neither of these then it will be rendered on the outer
+terminal emulator as a '?'.
+.TP 5
+.B \-H
+render the current state of the internal frame buffer to stdout as HTML, then quit.
+.PP
+.B \fIclient_options\fP:
+.TP 5
+.B -k \fIsocket\fP
+set the name in the filesystem of the socket to which
+.I sympathy
+should connect. This option is \fBmanditory\fP unless the \-\fBs\fP or \-\fBr\fP options
+have also been given. If \-\fBs\fP is given then it will default to the socket which
+the forked server process opens. See the discusion of the \-\fPr\fP option above, for
+information on how 
+.I sympathy 
+chooses a socket name if \-\fBr\fP is specified.
+.PP
+.B \fIserver_options\fP:
+.TP 5
+.B -k \fIsocket\fP
+set the name in the filesystem of the socket on which
+.I sympathy
+should listen for clients. If this option is omitted 
+.I sympathy 
+will create a 
+socket in ~/.sympathy, creating that directory if neccessary, and named
+\fIhostname\fP.\fIpid\fP where \fIpid\fP is the process id of the 
+.I sympathy
+process that created the socket.
+.TP 5
+.B -F
+tells the 
+.I sympathy
+server process not to become a daemon but to remain the the foreground. This option is
+incompatible with the \-\fBc\fP \-\fBs\fP major mode.
+.TP 5
+.B -n \fInlines\fP
+sets the number of lines of history that the server process stores to \fInlines\fP. When 
+a client connects \fInlines\fP of history are injected into the outer terminal emulator
+so that they can be seen when scrolling back. By default the server stores 200 lines of
+history.
+.SH OPERATION
+When 
+.I sympathy
+is relaying data to the outer terminal emulator a reverse video status line 
+will be visible at the bottom of the screen. The status line shows pertinent
+information. The first item on the line reminds you what the current escape character
+is, the second indicates the terminal device to which 
+.I sympathy
+is connected, and the third shows the current baudrate. Other messages are:
+.TP 5
+.B Flow
+indicates that that RTS/CTS flow control is in operation on the terminal device.
+.TP 5
+.B RTS
+indicates that the terminal device is asserting the RTS line which indicates that 
+the local system is ready to accept data from the remote system. If RTS/CTS
+flow control is in operation then the operating system or hardware may
+de-assert RTS even if RTS is shown. See the section on SERIAL PORT THEORY for
+more information.
+.TP 5
+.B CTS
+indicates that the terminal device has detected that the local system's CTS
+line is being asserted, indicating that the remote system is ready to receive
+data from the local system. See the section on SERIAL PORT THEORY for
+more information.
+.TP 5
+.B DTR
+indicates that the terminal device is asserting the DTR line indicating that the local
+system would like the local DCE to establish a connection to the remote
+DCE.  See the section on SERIAL PORT THEORY for more information.
+.TP 5
+.B DSR
+indicates that the terminal device has detected that the local system's DSR line is
+being asserted, indicating that the local DCE is ready. See the section on
+SERIAL PORT THEORY for more information.
+.TP 5
+.B CD
+indicates that the terminal device has detected that the local system's CD line is
+being asserted, indicating that the local DCE has a connection to the remote DCE.
+See the section on SERIAL PORT THEORY for more information.
+.TP 5
+.B RI
+indicates that the terminal device has detected that the local system's RI line is
+being asserted, indicating that the DCE has detected a ringing signal or incoming 
+connexion.
+.TP 5
+.B n clients
+shows the number of connected client processes. In the \-\fBt\fP major mode, this will 
+always be zero.
+.TP 5
+.B Locked
+the terminal device was opened without the \-\fbK\fP flag and another process is
+currently using it. I/O to the device is currently suspended until the process dies
+or removes its lock file.
+.TP 5
+.B n errs
+indicates the number of frames recived by the terminal device with errors. The count
+resets if no errors are detected by the device for 10 seconds.
+
+
+.PP
+ you can send commands by sending
+ascii(7) STX from the outer terminal emulator (usally by pressing CTRL-B). 
+
+the s
+.SH LOG FILES
 .SH EXIT STATUS
 .SH ENVIRONMENT
+.SH SERIAL PORT THEORY
 .SH FILES
 .SH EXAMPLES
 .SH ERRORS
@@ -24,6 +315,11 @@ sympathy \- client/server terminal emulator with logging
 screen(1) minicom(1) consolidate(1)
 .SH STANDARDS
 .SH BUGS
+.PD
+.IP \(bu 3
+when the \-\fBc\fP \-\fBs\fP major mode is used without the \-\fBk\fP option the pid
+used in the socket is that of the client process and therefore not unique.
+.IP \(bu 3
+the HTML generated with the \-\fBH\fP option is ugly.
 .SH SECURITY CONSIDERATIONS
 .SH AUTHOR
-.\" vi: set syn=groff