path: root/tap/tap.texinfo

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename tap.info
@setcontentsaftertitlepage
@settitle Tap
@c %**end of header


@c information for a proper install
@dircategory Communication Programs
@direntry
* Tap: (tap).            A program to communicate with a serial line tap.
@end direntry


@c include commands and keystrokes with the regular index
@syncodeindex fn cp
@syncodeindex ky cp


@ifinfo
This file documents Tap, a program to read data from (and write data to)
a serial port.  Amongst other things, it may be used to facilitate the
reverse engineering of serial communication protocols.

Copyright @copyright{} 1999 Jonathan E duSaint @email{jon@@mbayweb.com}.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Copying'' and ``GNU General Public License'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end ifinfo


@titlepage
@title Tap 1.0
@subtitle A program to communicate with a serial line tap.
@author Jonathan E duSaint <jon@@mbayweb.com>

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999 Jonathan E duSaint @email{jon@@mbayweb.com}

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Copying'' and ``GNU General Public License'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end titlepage


@ifnottex
@node    Top,       Introduction, ,         (dir)
@comment node-name, next,         previous, up
@top Tap

Tap is a program designed to read data from and write data to the serial
port.  As such it has a wide variety of applications.  For example, it
can be used to prototype serial hardware, or to read data from a serial
line tap, which can facilitate the reverse engineering of serial line
communication protocols.

This documentation corresponds with version 1.0 of Tap.
@end ifnottex

@menu
* Introduction::        An introduction to @code{Tap} and the manual.
* The Command Line::    The ins and outs of the interface.
* Command Overview::    A look at the commands.
* Input and Output::    Communicating with the serial line.
* The Set Command::     Setting the environment.

* Index::               The command, concept, and keystroke index.

@detailmenu
--- The Detailed Node Listing ---
* Conventions::         Document conventions.
* Invocation::          How to start @code{Tap} and the command line options.
* Overview::            A brief tour through @code{Tap}.

* History::             How to use the history functionality.
* Editing::             Command line editing.

* C-B: Moving Left.     Moving the cursor to the left.
* Left Arrow: Moving Left.
                        Moving the cursor to the left.
* C-F: Moving Right.    Moving the cursor to the right.
* Right Arrow: Moving Right.
                        Moving the cursor to the right.
* C-A::                 Moving the cursor to the start of the line.
* C-E::                 Moving the cursor to the end of the line.
* C-D::                 Deleting the character under the point.
* C-H::                 Deleting the character to the left of the point.
* C-U::                 Entering a numerical argument.
* C-space: Killing and Yanking Text.
                        Setting the mark position.
* C-K: Killing and Yanking Text.
                        Killing from the point to the end of the line.
* C-W: Killing and Yanking Text.
                        Killing in between the mark and the point.
* C-Y: Killing and Yanking Text.
                        Yanking text from the kill ring.
* C-T::                 Transposing characters.
* C-L::                 Clearing the screen.
* tab::                 Command line completion.

* alias::               Assign a different name to a command.
* capture::             Capture incoming data to a file or a register.
* clear::               Clear the input window.
* close::               Close an open serial port.
* help::                Get help on a command.
* open::                Open a serial port.
* out::                 Write format controlled data to the serial port.
* print::               Print the contents of a file or a register.
* quit::                Quit the program.
* set::                 Change the behavior of the program.
* unalias::             Remove an alias.

* Help::                The --help command line option.
* version::             The --version command line option.
* port::                The --port command line option.
* save-history::        The --save-history command line option.
@end detailmenu
@end menu


@node    Introduction, The Command Line, Top,      Top
@comment node-name,    next,             previous, up
@chapter Introduction

This chapter serves as an introduction to the manual as well as to
@code{Tap}, and documents the command line options.

@menu
* Conventions::         Document conventions.
* Invocation::          How to start @code{Tap} and the command line options.
* Overview::            A brief tour through @code{Tap}.
@end menu


@node    Conventions, Invocation, Introduction, Introduction
@comment node-name,   next,       previous,      up
@section Conventions
@cindex Document, How to Read
@cindex Explanation of the C-? Syntax
@cindex C-? Syntax, Explanation of

The syntax @dfn{C-whatever} means to press the @kbd{Control} key and to
simultaneously press the @kbd{whatever} key.  For example, @kbd{C-P}
means to hold down the @kbd{Control} key, and then hit the @kbd{P} key.

When the command definitions are presented, the command usage is put
first.  Then follows a description of the function.  If there is more
than one way to use a function, then each invocation is shown with an
explanation after it.


@node    Invocation, Overview, Conventions, Top
@comment  node-name, next,     previous,    up
@section Invocation
@cindex Options
@cindex Command Line Options
@cindex Startup Options
@cindex Invocation

To start @code{Tap}, merely type @kbd{tap} at the shell prompt.  If it
is properly installed, you should be presented with the interface.  If
it isn't, then read the file @file{INSTALL} for information on how to do
so.  @code{Tap} can be invoked with several different command line
options.

@menu
* Help::                The --help command line option.
* version::             The --version command line option.
* port::                The --port command line option.
* save-history::        The --save-history command line option.
@end menu


@node    Help,      version, Invocation, Invocation
@comment node-name, next,    previous, up
@subsection @code{--help}
@findex --help
@findex -h
@cindex @code{help}, Command Line Option

@code{--help}, @code{-h}

Invoking @code{Tap} with this option will cause @code{Tap} to print a
short help message to @var{stdout} and then exit.


@node    version,   port, Help, Invocation
@comment node-name, next, previous,  up
@subsection @code{--version}
@findex --version
@findex -v
@cindex @code{version}, Command Line Option

@code{--version}, @code{-v}

Invoking @code{Tap} with this option will cause @code{Tap} to print
version and copyright information to @var{stdout} and then exit.


@node    port,      save-history,   version, Invocation
@comment node-name, next,           previous,  up
@subsection @code{--port}
@cindex Default Port
@cindex Port, Opening on Invocation
@findex --port
@findex -p
@cindex @code{port}, Command Line Option

@code{--port} @file{serial port}, @code{-p} @file{serial port}

With this option, @code{Tap} will open @file{serial port} at startup.
If the serial port can't be opened, @code{Tap} will print an error
message at startup.


@node    save-history,   ,     port,     Invocation
@comment node-name,      next, previous, up
@subsection @code{--save-history}
@findex --save-history
@findex -s
@cindex @code{save-history}, Command Line Option
@cindex Saving History
@cindex History, Saving
@cindex History File
@cindex Default History File

@code{--save-history} @file{history filename}, @code{-s} @file{history filename}

This option will cause @code{Tap} to read history information at startup
from the file specified and to write history information at shutdown to
the file.  If the file specified doesn't exist, it will be created, and
if no file is specified, the default will be used, which is usually
@file{~/.tap_history}.


@node    Overview,  ,     Invocation, Introduction
@comment node-name, next, previous,   up
@section Overview
@findex help, Command

This overview assumes that @code{tap} is already properly installed on
your system.  If it isn't, read the file @file{INSTALL} for instructions.

To start, invoke @code{tap} from the command line by typing @kbd{tap}.
Once it is started, you will notice that the screen is divided into two
parts, both with headers.  The top part is called the @dfn{input window}
and the bottom part is called the @dfn{output window}.  At the bottom of
the screen is the status bar.  It should state that no serial port is
open on one side, and suggest typing @code{help} for help.

As a first experiment, try typing @code{help}.  You will be presented
with a brief summary of all of the commands available.  To get more
specific help information, type @code{help command-name}


@node    The Command Line, Command Overview, Introduction, Top
@comment node-name,        next,             previous,     up
@chapter The Command Line
@cindex Command Line Interface

If you are familiar with @code{Bash} or @code{Emacs}, then you should
already have a good grasp of most of the functionality of the command
line interface.  While @code{Tap} doesn't actually use the @code{GNU
Readline} or the @code{GNU History} libraries, the interface was
designed to be very similar.  All commands are saved in a history list,
although if a command is repeated one or more times, only one copy is
saved.  Also, while entering text on the command line, a variety of
keystrokes are available for command line editing.

@menu
* History::             How to use the history functionality.
* Editing::             Command line editing.
@end menu

@node    History,   Editing, The Command Line, The Command Line
@comment node-name, next,    previous,          up
@section History
@cindex History Functionality
@cindex History List
@cindex History File
@kindex C-P
@kindex C-N
@kindex Up Arrow
@kindex Arrow, Up
@kindex Down Arrow
@kindex Arrow, Down

Every time a command is entered, it is automatically inserted into the
internal history list.  However, if the command is identical to the
previous command, a list entry is not made.

To access previous entries, press either @kbd{Up Arrow}, or
@kbd{C-P}.  To access more recent entries, press either @kbd{Down
Arrow}, or @kbd{C-N}.

If a previous entry is edited and @kbd{Enter} is not pressed, the edited
copy will be saved in the place of the original.  However, once
@kbd{Enter} is pressed, the original copy will once again be available.

When @code{Tap} is invoked with the @code{--save-history}
(@pxref{save-history}) option, all history entries are read at startup
from the file specified, or, if one isn't specified, from the default
file.  At shutdown, the current history list is appended onto the file.

If a file is specified that doesn't exist, then one will be created at
shutdown.


@node    Editing,   ,     History,  The Command Line
@comment node-name, next, previous, up
@section Editing
@cindex Command Line Editing
@cindex Editing, Command Line

@code{Tap} contains features for editing the current command line.  The
keystrokes are the same as used in @code{Emacs} and in the @code{Bash}
shell's @code{Emacs} mode.

@menu
--- list of keystrokes ---
* C-B: Moving Left.     Moving the cursor to the left.
* Left Arrow: Moving Left.
                        Moving the cursor to the left.
* C-F: Moving Right.    Moving the cursor to the right.
* Right Arrow: Moving Right.
                        Moving the cursor to the right.
* C-A::                 Moving the cursor to the start of the line.
* C-E::                 Moving the cursor to the end of the line.
* C-D::                 Deleting the character under the point.
* C-H::                 Deleting the character to the left of the point.
* C-U::                 Entering a numerical argument.
* C-space: Killing and Yanking Text.
                        Setting the mark position.
* C-K: Killing and Yanking Text.
                        Killing from the point to the end of the line.
* C-W: Killing and Yanking Text.
                        Killing in between the mark and the point.
* C-Y: Killing and Yanking Text.
                        Yanking text from the kill ring.
* C-T::                 Transposing characters.
* C-L::                 Clearing the screen.
* tab::                 Command line completion.
@end menu

@node    Moving Left, Moving Right, Editing,  Editing
@comment node-name,   next,         previous, up
@subsection Moving Left
@kindex C-B
@kindex Left Arrow
@kindex Arrow, Left
@cindex Point Movement
@cindex Cursor Movement

@kbd{C-B}, @kbd{Left Arrow}

Both of these keystrokes will move the point one character to the left,
if possible.


@node    Moving Right, C-A,  Moving Left, Editing
@comment node-name,    next, previous,    up
@subsection Moving Right
@kindex C-F
@kindex Right Arrow
@kindex Arrow, Right
@cindex Point Movement
@cindex Cursor Movement

@kbd{C-F}, @kbd{Right Arrow}

Both of these keystrokes will move the point one character to the right,
if possible.


@node    C-A,       C-E,  Moving Right, Editing
@comment node-name, next, previous,     up
@subsection @kbd{C-A}
@kindex C-A
@cindex Cursor Movement
@cindex Point Movement
@cindex Start of Line, Moving the Point to

@kbd{C-A}

This keystroke will move the point to the start of the line.


@node    C-E,       C-D,  C-A,      Editing
@comment node-name, next, previous, up
@subsection @kbd{C-E}
@kindex C-E
@cindex Cursor Movement
@cindex Point Movement
@cindex End of Line, Moving the Point to

@kbd{C-E}

This keystroke will move the point to the end of the line.


@node    C-D,       C-H,  C-E,      Editing
@comment node-name, next, previous, up
@subsection @kbd{C-D}
@kindex C-D
@kindex Delete
@cindex Deleting Characters

@kbd{C-D}, @kbd{Delete}

Both of these keystrokes will delete the character under the point.


@node    C-H,       C-U,  C-D,      Editing
@comment node-name, next, previous, up
@subsection @kbd{C-H}
@kindex C-H
@kindex Backspace
@cindex Deleting Characters

@kbd{C-H}, @kbd{Backspace}

Both of these keystrokes will delete the character to the left of the
point.


@node    C-U,       Killing and Yanking Text, C-H,      Editing
@comment node-name, next,                     previous, up
@subsection @kbd{C-U}
@kindex C-U
@cindex Entering Numerical Arguments
@cindex Numerical Arguments, Entering
@cindex Arguments, Numerical
@cindex Numerical Arguments

@kbd{C-U}

This command prompts for a number.  After the number is entered, press
@kbd{Enter}, and then the desired key.  If the key entered was @kbd{C-Y}
(@pxref{Killing and Yanking Text}), then text from the kill ring will be
entered.  If @kbd{Enter} was pressed, then it will be just as if
@kbd{Enter} had been pressed without the argument (i.e. the command line
will be processed).  Any other key will be repeated as many times as was
indicated by the number.

For example, type

@example
@kbd{C-U} @kbd{2} @kbd{0} @kbd{Enter} @kbd{a}
@end example

@noindent
to insert 20 copies of the letter `a', or type

@example
@kbd{C-U} @kbd{5} @kbd{Enter} @kbd{C-D}
@end example

@noindent
to delete the character under the point and four to the right of it.


@node    Killing and Yanking Text, C-T,  C-U,      Editing
@comment node-name,                next, previous, up
@subsection Killing and Yanking Text
@kindex C-space
@kindex C-W
@kindex C-K
@kindex C-Y
@cindex Killing Text
@cindex Yanking Text
@cindex Kill Ring
@cindex Copying Text
@cindex Cutting Text
@cindex Pasting Text
@cindex Setting the Mark
@cindex Mark, Setting

@kbd{C-space}  Set the mark.

@kbd{C-W}      Kill the text from the mark to the point.

@kbd{C-K}      Kill the text from the mark to the end of the line.

@kbd{C-Y}      Yank from the kill ring and insert it at the point.

Tap utilizes a kill ring for storage of text which has been killed using
the above commands.  The single character delete commands will not
store anything to the ring.

The @kbd{C-Y} command will only yank the most recent entry.  In order to
yank older entries than that, it must be used in combination with the
@kbd{C-U} command (@pxref{C-U}).  For example, type

@example
@kbd{C-U} @kbd{3} @kbd{Enter} @kbd{C-Y}
@end example

@noindent
to insert the text from the third to last kill.


@node    C-T,       C-L,  Killing and Yanking Text, Editing
@comment node-name, next, previous,                 up
@subsection @kbd{C-T}
@kindex C-T
@cindex Transposing Characters
@cindex Characters, Transposing

@kbd{C-T}

This keystroke transposes the character under the point with the
character to its left.


@node    C-L,       tab,  C-T,      Editing
@comment node-name, next, previous, up
@subsection @kbd{C-L}
@kindex C-T
@cindex Clearing the Screen

@kbd{C-L}

This keystroke clears the screen and redraws the current line.

@xref{clear}.


@node    tab,       ,     C-L,      Editing
@comment node-name, next, previous, up
@subsection @kbd{tab}
@kindex tab
@cindex Command Line Completion
@cindex Completion, Command
@cindex Command Completion

@kbd{tab}

Pressing the tab key will complete the token under the point, if at all
possible.  If the point is over the first token, then a command
completion will be attempted.  If it is over any other token, a
completion will be attempted, based on the arguments that the command
takes.  If only a partial completion is possible, the token is completed
as far as it can be, and all of the matching completions are printed
out.  If no completion is possible, the program just beeps.


@node    Command Overview, Input and Output, The Command Line, Top
@comment node-name,        next,             previous,          up
@chapter Command Overview
@cindex Commands
@cindex Command Overview

These are descriptions of all of the commands.  Some commands are
documented elsewhere, so for them, there will be only a short
description.

@menu
* alias::               Assign a different name to a command.
* capture::             Capture incoming data to a file or a register.
* clear::               Clear the input window.
* close::               Close an open serial port.
* help::                Get help on a command.
* open::                Open a serial port.
* out::                 Write format controlled data to the serial port.
* print::               Print the contents of a file or a register.
* quit::                Quit the program.
* set::                 Change the behavior of the program.
* unalias::             Remove an alias.
@end menu


@node alias, capture, Command Overview, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{alias}
@findex alias, Command
@cindex Aliasing Command Names
@cindex Renaming Commands

@code{alias}

Invoking @code{alias} with no arguments will print out all of the
aliases which have been assigned.

@code{alias} @var{alias}

The @code{alias} command with one argument will print out the alias and
the command to which it is aliased.

@code{alias} @var{alias} @var{command}

With two options, @code{alias} will assign @var{alias} to @var{command}
so that when @var{alias} is entered, the program will act as if
@var{command} itself had been entered.

This command can be very useful to decrease the amount of typing
necessary.  If, for example, the @code{out} (@pxref{out}) command were to
be aliased to @code{o}, then rather than typing

@example
out foo bar\n
@end example

@noindent
it would be possible to merely type

@example
o foo bar\n
@end example

@noindent
which doesn't save that much typing, but does illustrate the point.

However, @code{alias} is limited to aliasing commands only, so it is not
possible to type something like

@example
alias bin 'set if bin'
@end example

Also see @ref{unalias}.


@node capture, clear, alias, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{capture}

@code{capture} @option{file} @file{filename}

When invoked in this manner, @code{capture} starts capturing data
recieved from the serial port to @file{filename}.  Only one file may be
open at a time.

@code{capture} @option{file} @option{off}

This causes @code{Tap} to stop capturing data and to close the file.

@code{capture} @option{register} @option{1--64}

@code{capture}, when invoked like this, will cause @code{Tap} to start
capturing data to a register.  Data is captured until it is turned off,
as described below, or the register is full.  The size of the registers
may be changed by using the command @code{set}.

@code{capture} @option{register} @option{off}

This stops the capturing to the register.


@xref{set}, and @ref{The Set Command}.

@node clear, close, capture, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{clear}

@code{clear}

Invoking clear will clear the input window.

@xref{C-L}.


@node close, help, clear, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{close}

@code{close}

This command closes the currently open serial port.


@node help, open, close, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{help}

@code{help}

When invoked without a command name, @code{help} prints a short
description of every command.

@code{help} @option{command name}

This provides help on individual commands.


@node open, out, help, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{open}

@code{open} @option{serial port}

@code{open} opens a serial port and prepares it for communication.  The
properties of the serial port may be changed with the command
@code{set}.

@xref{set}.


@node out, print, open, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{out}

@code{out} @option{data}

The @code{out} command writes data to the serial port.

@xref{Input and Output}.


@node print, quit, out, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{print}

@code{print} @option{file}

If a file is currently being captured to, this will print the contents
of that file.  If no file is open, then an error will be thrown.

@code{print} @option{file} @file{filename}

This prints the contents of the file specified in @file{filename}.

@code{print} @option{file} @file{filename} @option{bytes}

This does the same as above, but only prints the first @option{bytes}
number of bytes.

@code{print} @option{register}

If a register is currently being captured to, this will print its
contents.  If one isn't being used, then an error will be thrown.

@code{print} @option{register} @option{register number}

This will print the contents of the register specified.

@code{print} @option{register} @option{register number} @option{bytes}

This will print the first @option{bytes} number of bytes of the
specified register.


@node quit, set, print, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{quit}

@code{quit}

This command quits the program, closing any open files and the serial
port, if one is open.


@node set, unalias, quit, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{set}

@code{set} @option{options}

The @code{set} command adjusts various run time parameters of
@code{Tap}.  @xref{The Set Command}, for a full explanation.


@node unalias, , set, Command Overview
@comment  node-name,  next,  previous,  up
@section @code{unalias}

@code{unalias} @option{alias}

The @code{unalias} command removes the alias @option{alias} from the
alias list.


@node    Input and Output, The Set Command, Command Overview, Top
@comment node-name,        next,            previous,          up
@chapter Input and Output



@node    The Set Command, Index, Input and Output, Top
@comment node-name,       next,  previous,         up
@chapter The Set Command

Often, while working with @code{Tap}, you will find that you might want
to change some of the operational parameters.

@node       Index,     ,     The Set Command, Top
@comment    node-name, next, previous,        up
@unnumbered Command, Concept, and Keystroke Index

@printindex cp

@contents
@bye