1@c A Helpful TTY (AH-TTY) 2@c Copyright 1999-2000 Randall Maas. All rights reserved. 3@c See COPYING 4 5@chapter AH-TTY: A Helpful Terminal Emulator 6 7@file{ah-tty} -- provides help at a UNIX shell prompt 8 9@heading Introduction 10 11A Helpful Termulator Emulator (@file{ah-tty} provides context-sensitive help 12at a UNIX shell prompt. @file{ah-tty} executes an inferior shell, and watches 13the output from the shell and the input to it from the user carefully, to 14determine what is a prompt, and what is actually a command typed by the user. 15 16Once it has determined what the user's command is, @file{ah-tty} compares it 17to a list of rules to determine what helpful hint to display, if any. 18 19This isn't making sense, is it? Okay, try this: 20 21@enumerate 22 23@item Start @file{ah-tty}, 24 25@item then at the shell prompt type @samp{ls }, do not press return. 26 27@item Wait a moment, and watch the bottom of the screen. 28 29@end enumerate 30 31Now does it make sense? Okay then. 32 33@emph{DO NOT} set your default shell to @file{ah-tty.} 34This is not a shell in its own right, just a kind of front-end shell 35watching thingy. If you want this to be your default shell, invoke it 36manually from the shell prompt, or in your @file{.login} or @file{.profile} 37scripts. 38 39Rules consist of regular expressions, combined with 40appropriate delays, as well as a maximum number of times the hint should 41be displayed in one session. However, any particular 42hint is only displayed once per prompt. 43 44For details of how to create and modify rules files, see RULES section 45(@pxref{Rules}). If you can create rules files yourself, you 46probably don't need to use @file{ah-tty} 8) 47 48 49@subheading Files 50 51@multitable @columnfractions 0.4 0.6 52 53@item @file{/usr/local/share/ah-tty.conf} @tab Default system rules file. 54@item @file{@var{$HOME}/.ah-ttyrc} @tab Users' own rules files. 55 56@end multitable 57 58@subheading Environment 59 60@multitable @columnfractions 0.1 0.9 61 62@item @var{PSHELL} @tab Determines the shell executed by @file{ah-tty} 63@item @var{SHELL} @tab Used if @var{PSHELL} is not set. 64 65@end multitable 66 67@subheading Installation 68 69After unpacking the tar file, do: 70@example 71 ./configure 72 make 73 make install 74@end example 75 76If you do not have installation privileges, then you can try the following: 77@example 78 ./configure 79 make 80 cp ah-tty.conf ~/.ah-ttyrc 81@end example 82 83You will also have to move @file{ah-tty} to somewhere in your @var{PATH} (ie, 84@file{~/bin}), or add @file{ah-tty}'s path to your @var{PATH} environment 85variable. 86 87 88@subheading Bugs 89 90It does not fully understand the shell's line-editing capabilities. Right now 91it works, it just may not match correctly. 92 93@subheading How to find out more 94@table @emph 95@item online documentation 96There is a set of online documentation. 97@url{http://ah-tty.sourceforge.net/} 98 99@item Contact the author: 100Randall Maas (@email{randym@@acm.org}) 101@end table 102 103@subheading Copyright 104 105Copyright @copyright{} 1999-2000, Randall Maas. All rights reserved. This 106package is free software; you can redistribute it and/or modify it 107under terms of the GNU Public License. 108 109Portions are copyright Fraser McCrossan 110 111@subheading Authors 112 113Randall Maas @email{randym@@acm.org} 114 115Fraser McCrossan @email{fraserm@@gtn.net} 116 117@c --- Configuration -------------------------------------------------------- 118@node Rules, Learned, Introduction, Top 119@chapter The Rules File 120 121@subheading Format of a rule 122 123Defining rules for @file{ah-tty}: 124 125@table @asis 126 127@item Comment lines 128 129begin with @samp{#} and are ignored. 130 131@item Rule lines 132 133are of the form: @samp{:@var{levels} @var{regexp}} 134 135@item Hint text 136 137Any line not of the form of a rule line is taken as the hint text for 138the preceding rule line. 139 140@end table 141 142@dfn{Levels} are a list of digits (0-7) marking which "help level" this rule 143will match. The idea behind help levels is that as users gain more 144experience they will increase their help level and cut down the number 145of patronizing messages they receive. Currently, the supplied 146@file{ah-tty.conf} only uses levels 0 and 1. 147 148@dfn{Regexp} is the extended POSIX regular expression that the command typed 149by the user must match before the hint is displayed. 150 151In the case where more than one rule matches the current line, only 152one hint at a time will be displayed, in the order they appear in the 153file. Each hint will only be displayed once per prompt, that is, it 154won't match again until the user hits Return. 155 156 157@subheading Kinds of rules 158 159There are typically 4 types of entries: 160 161@enumerate 162 163@item The command & its options 164 165@item A list of commands that start with that letter 166 167@item A suggestion to use some other command 168 169@item A description on how to use certain patterns (regex) 170 171@end enumerate 172 173I recommend that you go from the most general to the most specific 174 175The start of the regex pattern for a command should be something like: 176@example 177 (^|[|\;])[[:space:]]* 178@end example 179 180This makes sure to match the start of the a command line, after a pipe or 181a start of a new command. It also recognizes spaces that the user may use 182for readability. But it makes sure that it is a command, not some option 183or file name used as part of another command. 184(Yes, that regular expression prefix is hideous, ugly, and generally silly 185looking.) 186 187@subheading The most complicated rule 188 189@example 190:= (^|[|\;])[[:space:]]*mv[[:space:]]+([^-|\;&[:space:]][^|\;&[:space:]]*)[^-|\;&]*[[:space:]][^-|\;&]*\2([|;&)]|$) 191@end example 192 193That is the most complicated rule in @file{ah-tty}'s database, atleast at this 194moment. Laboratory animals contracted several new forms of extreme indigestion 195during testing of that rule. 196 197For all its bluster, the rule is meant to catch a fairly straight forward type 198of command line. Here are some examples: 199@example 200 mv foobar.c foobar.bak 201 mv foobar.c -i foobar.bak 202 mv -i foobar.c foobar.bak 203@end example 204 205The rule watches for the @file{mv} command, ignores the commnand flags and 206other options. It does notice the file names, especially when the filenames 207are very similar. 208 209If @file{ah-tty} spots a command that matches this rule, it will print the 210following helpful hint: 211@example 212Using @samp{mv} and braces to renaming files: 213 @samp{mv} @emph{fixbold@{5,6@}} Renames the file @file{fixbold5} to @file{fixbold6}. Useful to fix typos 214 @samp{mv} @emph{fixbold@{,bak@}} Renames @file{fixbold} to @file{fixbold.bak} 215@end example 216 217 218 219@subheading Markup in the help text 220 221There are some simple markup rules that are used to provide visual hints to 222the user 223 224@itemize @bullet 225 226@item Options @samp{(-xx)} are made bold. 227 228@item Things in @samp{[]} are made bold, if the stuff after the @samp{[} and 229before the @samp{]} are alphanumeric 230 231@item Things in @samp{<>} are made bold and green. Again only if the stuff 232just after the @samp{<} and before the @samp{>} are alphanumeric. 233 234@end itemize 235 236 237@node Learned, Modules, Rules, Top 238@chapter Things I learned while writing ah-tty 239 240Thing I've larned from working on ah-tty 241 242@enumerate 243 244@item Setting up a new session or tty is a very odd, poorly 245documented, and partly unportable tasked. This is a weakness in UNIX 246 247@item The GNU libc has a great deal of information on the tty and how to set 248them up. But that information isn't neccessarily portable (what if there is 249no glibc?) 250 251@item VT100 emulators are stuck with some non-deterministic parts, 252and the protocol is kinda hard to find good documentation on. 253 254@item VT100 is kinda like an RPC mechanism 255 256@item VT100 there are too many ways to do the same thing in VT100, the ones 257that aren't any more efficient shouldn't have been created. 258 259@item If you create a set of relative cursor motion schemes, you should never 260create a cursor addressing scheme that is absolute or relative depending on 261some mode flag. Just make it absolute. 262 263@item Not all termios, terminfo, termcap or curses implemenations are the same. 264 265@item There are many ok sources of information on the net 266@item VT100 specs are seldom followed (and heavily extended) 267 268@item Termcap and terminfo are usually the more definitive source of terminal 269emulation information 270 271@item My @var{$TERM} variable is not honored very much. 272 273@item @file{screen} is a great program, but not the answer to everything; 274plus it has lots of LISP like stuff. But it is truly great. 275 276@item Bash's screen managementt has a few bugs of its own (especially near 277the bottom of the display) 278 279@item I don't like CVS. It requires a lot of man-power for simple things. 280 281@item Trouble-tickets, or problem reporting software can allows techies to 282close problems too quickly. Sometimes before the problem is solved, and 283confirmed by the person needing help. 284 285@item A problem is solved only when the solution meets the acceptance criteria 286 287@item Tech support people are overworked and get stuck dealing with a lot of 288cranky folks. Okay, we all knew that. Hug a techie today. 289@end enumerate 290 291 292@node Modules, Function Index, Learned, Top 293@chapter Modules 294 295@c nodes it should add: by type, all 296@c right now I am going to have by category 297 298@menu 299 300* bykind:: 301 302* bytype:: 303 304* alphabetical:: 305 306@end menu 307 308@node bykind, bytype, Modules, Modules 309@section Modules, by kind 310 311 312@include doc/ah-tty2.texi 313 314 315