AH-TTY: A Helpful Terminal Emulator
***********************************

ah-tty -- provides help at a UNIX shell prompt

Introduction
============

A Helpful Termulator Emulator (ah-tty provides context-sensitive help at a UNIX shell prompt.  ah-tty executes an inferior shell, and watches the output from the shell and the input to it from the user carefully, to determine what is a prompt, and what is actually a command typed by the user.

Once it has determined what the user's command is, ah-tty compares it to a list of rules to determine what helpful hint to display, if any.

This isn't making sense, is it? Okay, try this:

 1. Start ah-tty,

 2. then at the shell prompt type ls , do not press return.

 3. Wait a moment, and watch the bottom of the screen.

Now does it make sense? Okay then.

DO NOT set your default shell to ah-tty. This is not a shell in its own right, just a kind of front-end shell watching thingy. If you want this to be your default shell, invoke it manually from the shell prompt, or in your .login or .profile scripts.

Rules consist of regular expressions, combined with appropriate delays, as well as a maximum number of times the hint should be displayed in one session. However, any particular hint is only displayed once per prompt.

For details of how to create and modify rules files, see RULES section (see Rules).  If you can create rules files yourself, you probably don't need to use ah-tty 8)

Files
-----

/usr/local/share/ah-tty.conf   Default system rules file.
$HOME/.ah-ttyrc          Users' own rules files.

Environment
-----------

PSHELL   Determines the shell executed by ah-tty
SHELL    Used if PSHELL is not set.

Installation
------------

After unpacking the tar file, do:

     	./configure
     	make
             make install

If you do not have installation privileges, then you can try the following:

     	./configure
     	make
             cp ah-tty.conf ~/.ah-ttyrc

You will also have to move ah-tty to somewhere in your PATH (ie, ~/bin), or add ah-tty's path to your PATH environment variable.

Bugs
----

It does not fully understand the shell's line-editing capabilities.  Right now it works, it just may not match correctly.

How to find out more
--------------------

online documentation
     There is a set of online documentation. http://ah-tty.sourceforge.net/

Contact the author:
     Randall Maas (randym@acm.org)

Copyright
---------

Copyright © 1999-2000, Randall Maas. All rights reserved.  This package is free software; you can redistribute it and/or modify it under terms of the GNU Public License.

Portions are copyright Fraser McCrossan

Authors
-------

Randall Maas randym@acm.org

Fraser McCrossan fraserm@gtn.net

The Rules File
**************

Format of a rule
----------------

Defining rules for ah-tty:

Comment lines

     begin with # and are ignored.

Rule lines

     are of the form: :LEVELS REGEXP

Hint text

     Any line not of the form of a rule line is taken as the hint text for the preceding rule line.

Levels are a list of digits (0-7) marking which "help level" this rule will match. The idea behind help levels is that as users gain more experience they will increase their help level and cut down the number of patronizing messages they receive. Currently, the supplied ah-tty.conf only uses levels 0 and 1.

Regexp is the extended POSIX regular expression that the command typed by the user must match before the hint is displayed.

In the case where more than one rule matches the current line, only one hint at a time will be displayed, in the order they appear in the file. Each hint will only be displayed once per prompt, that is, it won't match again until the user hits Return.

Kinds of rules
--------------

There are typically 4 types of entries:

 1. The command & its options

 2. A list of commands that start with that letter

 3. A suggestion to use some other command

 4. A description on how to use certain patterns (regex)

I recommend that you go from the most general to the most specific

The start of the regex pattern for a command should be something like:

     	(^|[|\;])[[:space:]]*

This makes sure to match the start of the a command line, after a pipe or a start of a new command.  It also recognizes spaces that the user may use for readability.  But it makes sure that it is a command, not some option or file name used as part of another command. (Yes, that regular expression prefix is hideous, ugly, and generally silly looking.)

The most complicated rule
-------------------------

     := (^|[|\;])[[:space:]]*mv[[:space:]]+([^-|\;&[:space:]][^|\;&[:space:]]*)[^-|\;&]*[[:space:]][^-|\;&]*\2([|;&)]|$)

That is the most complicated rule in ah-tty's database, atleast at this moment.  Laboratory animals contracted several new forms of extreme indigestion during testing of that rule.

For all its bluster, the rule is meant to catch a fairly straight forward type of command line.  Here are some examples:

     	mv foobar.c foobar.bak
             mv foobar.c -i foobar.bak
             mv -i foobar.c foobar.bak

The rule watches for the mv command, ignores the commnand flags and other options.  It does notice the file names, especially when the filenames are very similar.

If ah-tty spots a command that matches this rule, it will print the following helpful hint:

     Using mv and braces to renaming files:
      mv fixbold{5,6}   Renames the file fixbold5 to fixbold6.  Useful to fix typos
      mv fixbold{,bak}  Renames fixbold to fixbold.bak

Markup in the help text
-----------------------

There are some simple markup rules that are used to provide visual hints to the user

  * Options (-xx) are made bold.

  * Things in [] are made bold, if the stuff after the [ and before the ] are alphanumeric

  * Things in <> are made bold and green.  Again only if the stuff just after the < and before the > are alphanumeric.

Things I learned while writing ah-tty
*************************************

Thing I've larned from working on ah-tty

 1. Setting up a new session or tty is a very odd, poorly documented, and partly unportable tasked.  This is a weakness in UNIX

 2. The GNU libc has a great deal of information on the tty and how to set them up.  But that information isn't neccessarily portable (what if there is no glibc?)

 3. VT100 emulators are stuck with some non-deterministic parts, and the protocol is kinda hard to find good documentation on.

 4. VT100 is kinda like an RPC mechanism

 5. VT100 there are too many ways to do the same thing in VT100, the ones that aren't any more efficient shouldn't have been created.

 6. If you create a set of relative cursor motion schemes, you should never create a cursor addressing scheme that is absolute or relative depending on some mode flag.  Just make it absolute.

 7. Not all termios, terminfo, termcap or curses implemenations are the same.

 8. There are many ok sources of information on the net

 9. VT100 specs are seldom followed (and heavily extended)

 10. Termcap and terminfo are usually the more definitive source of terminal emulation information

 11. My $TERM variable is not honored very much.

 12. screen is a great program, but not the answer to everything; plus it has lots of LISP like stuff.  But it is truly great.

 13. Bash's screen managementt has a few bugs of its own (especially near the bottom of the display)

 14. I don't like CVS.  It requires a lot of man-power for simple things.

 15. Trouble-tickets, or problem reporting software can allows techies to close problems too quickly.  Sometimes before the problem is solved, and confirmed by the person needing help.

 16. A problem is solved only when the solution meets the acceptance criteria

 17. Tech support people are overworked and get stuck dealing with a lot of cranky folks.  Okay, we all knew that.  Hug a techie today.

Modules
*******

Modules, by kind
================

     [file ah-tty2.texi not included]