From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

---
 pkg/language/doc/stty.hlp | 589 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 589 insertions(+)
 create mode 100644 pkg/language/doc/stty.hlp

(limited to 'pkg/language/doc/stty.hlp')

diff --git a/pkg/language/doc/stty.hlp b/pkg/language/doc/stty.hlp
new file mode 100644
index 00000000..8556a43b
--- /dev/null
+++ b/pkg/language/doc/stty.hlp
@@ -0,0 +1,589 @@
+.help stty Feb88 language
+.ih
+NAME
+stty -- set/show terminal characteristics
+.ih
+USAGE
+stty [terminal]
+.ih
+PARAMETERS
+.ls terminal
+The logical name of the terminal to be used, i.e., the name of the device
+given in the \fIdev$termcap\fR file.
+.le
+.ls baud = 9600
+Set to some nonzero value to inform the VOS of the baud rate; the software
+does not automatically sense the baud rate.  The baud rate must be known to
+accurately generate delays.
+.le
+.ls ncols = 80
+The logical width of the screen in characters; may be set to some value less
+than the physical width to produce more readable output on very high resolution
+terminals.
+.le
+.ls nlines = 24
+The logical height of the screen in characters.
+.le
+.ls show = no
+Show the current terminal driver settings.  The \fIshow\fR function is
+automatically enabled if \fIstty\fR is called with no arguments.
+.le
+.ls all = no
+Show all terminal driver settings, including those which are not currently
+in use.  Setting \fIall\fR automatically sets \fIshow\fR.
+.le
+.ls reset = no
+Reset the terminal driver settings to their default (login time) values.
+Note that the terminal driver is not a task in the normal sense but is always
+active, and once a parameter is set the new value is retained indefinitely.
+.le
+.ls resize = no
+Recompute the terminal screen size parameters, \fBttyncols\fR and
+\fBttynlines\fR, and update their values in the environment.
+If the terminal supports runtime querying of the screen size it will be
+queried (allowing the screen size to change dynamically at runtime),
+otherwise the values from the termcap entry for the terminal will be used.
+.le
+.ls clear = no
+Clear the function(s) which follow on the command line, e.g.,
+"clear ucasein ucaseout" is equivalent to "ucasein=no ucaseout=no".
+.le
+.ls ucasein = no
+Map terminal input to lower case, e.g., when working on an old monocase
+terminal, or on a modern terminal with the shiftlock key on.
+.le
+.ls ucaseout = no
+Map terminal output to upper case.
+.le
+.ls login = "home$ttyin.log" [off]
+Log all input from the terminal to the named text file.
+.le
+.ls logio = "home$ttyio.log" [off]
+Log all terminal i/o to the named text file.  May not be used if either
+\fIlogin\fR or \fIlogout\fR mode is in effect, and vice versa.
+.le
+.ls logout = "home$ttyout.log" [off]
+Log all output to the terminal to the named text file.
+.le
+.ls playback = "home$ttyin.log" [off]
+Divert terminal driver input to the named "stty login" style text file,
+i.e., take input from a file instead of from the terminal.  The effect is
+to exactly repeat a previous terminal session executed with \fIlogin\fR
+mode in effect, e.g., to test or demo software.
+.le
+.ls verify = no
+If \fIverify\fR is enabled during \fIplayback\fR mode the terminal driver
+will read a key from the keyboard before executing each command in the
+logfile.  Tap the space bar to execute the command, \fIq\fR to terminate
+playback mode, or \fIg\fR to continue execution with \fIverify\fR mode
+disabled.  Typing any other key causes a help line to be printed.
+.le
+.ls delay = 500 (msec)
+If \fIverify\fR is disabled during \fIplayback\fR mode the terminal driver
+will pause for \fIdelay\fR milliseconds before executing each logfile command.
+.le
+
+.ih
+DESCRIPTION
+The \fIstty\fR task is used to set or display the terminal device
+characteristics and VOS terminal driver options.
+Without arguments, \fIstty\fR prints the current characteristics of the
+terminal.  The default terminal type can be changed by setting \fIttyname\fR.
+The terminal characteristics \fIncols\fR, \fInlines\fR or \fIbaud\fR,
+may be changed by typing new values explicitly on the command line.
+
+The most common use of \fIstty\fR is to inform IRAF of the type of terminal
+being used, e.g.,
+
+	cl> stty vt100
+
+would set the terminal type to "vt100".  An error message will be printed
+unless an entry for the named terminal is present in the \fBtermcap\fR file;
+if the named terminal is a graphics terminal, there must also be an entry
+in the \fBgraphcap\fR file.
+
+To find out about the current terminal settings, type
+
+.ks
+.nf
+	cl> stty
+or
+	cl> stty all
+.fi
+.ke
+
+A limited number of terminal driver options may also be set.  In particular,
+the VOS terminal driver (not to be confused with the host operating system
+terminal driver, a lower level facility) implements facilities for case
+conversion upon input or output, and for logging all i/o to the terminal
+and playing back a terminal session logged in a file.
+
+.ih 4 1
+Case Conversions
+The \fBucasein\fR option, if set,
+will cause all upper case terminal input to be mapped to lower
+case (e.g., when working from an old monocase terminal).  In this mode,
+individual upper case characters may be input by preceding them with the
+escape character ^, e.g., "^MAKEFILE" equates to "Makefile".  The full set
+of ^ escapes is summarized below.  The option \fBucaseout\fR will cause all
+terminal output to be mapped to upper case.  Preceding either or both of
+these option keywords by \fBclear\fR causes the options to be cleared.
+
+.ks
+.nf
+	^	shift next character to upper case
+	^+	shift lock (caps lock)
+	^-	clear shift lock
+	^^	the character ^
+.fi
+.ke
+
+Case shifting is disabled in raw mode, e.g., while in cursor mode, and in
+\fBeparam\fR.  All standard IRAF software, however, will sense that ucase
+mode is set before entering raw mode, and will behave as expected.  Ucase mode
+is also disabled by the STDGRAPH kernel whenever the graphics workstation is
+activated.
+
+Note that ^ is also the history meta-character, hence ^^ must be used when
+in \fIucasein\fR mode to pass a single ^ to the CL history mechanism.
+In cursor mode, upper case keystrokes are intercepted by cursor mode unless
+escaped with a backslash.  Escaped keystrokes are mapped to lower case by
+cursor mode if \fIucasein\fR mode is in effect, terminating cursor mode and
+returning a lowercase key to the applications program.
+
+.ih
+Recording Terminal I/O
+The terminal driver options \fBlogio\fR, \fBlogout\fR, and \fBlogin\fR
+may be used to log, respectively, all terminal i/o, all output to the terminal,
+or all input from the terminal.  The logfile names are "home$ttyin.log",
+"home$ttyout.log", or "home$ttyio.log", unless a different logfile name is
+specified by the user.  All logfiles are standard textfiles containing only
+printable characters.
+
+Terminal i/o logging is especially useful for debugging \fItermcap\fR and
+\fIgraphcap\fR entries for new terminals.  All IRAF terminal i/o is logged,
+including raw mode i/o and graphics output.  Terminal i/o from foreign tasks
+or OS escapes is not logged since these tasks bypass the VOS to talk directly
+to the user terminal.
+
+Each sequence of characters read from or written to the terminal (via a zgettt
+or zputtt call to the driver) appears as one logical line of text in the
+logfile, delimited by the data character \n (newline).
+When reading from a terminal in raw mode, each input character will appear
+on a separate line in the logfile with no newline, since only a single
+data character is read at a time during raw mode input.
+All control characters embedded in the data, including newline terminators,
+are rendered into printable form.  Long lines are broken near the right margin,
+adding an escaped newline and indenting continuation lines 4 spaces.
+
+Terminal i/o logging is intended primarily for debugging purposes, rather
+than for logging user commands; the IRAF command language provides a more
+user friendly facility for command logging (see the \fIlanguage.logging\fR
+manpage for further information on the CL command logging facilities).
+All unprintable ASCII codes are rendered in the logfile in a printable form
+intended to eliminate any ambiguity regarding the exact sequence of characters
+sent to or received from the terminal.  In addition to the standard escape
+sequences \n, \t, \r, etc., the following special escape sequences are used:
+
+.ks
+.nf
+	\\		\
+	\^		^
+	^@		NUL (ascii 000)
+	^[A-Z]		ctrl/a - ctrl/z (ascii 001 - 032)
+	^[		ESC (ascii 033)
+	^\		FS  (ascii 034)
+	^]		GS  (ascii 035)
+	^^		RS  (ascii 036)
+	^_		US  (ascii 037)
+	\s		blank (ascii 040)
+	\<newline>	long i/o record continued on next line
+.fi
+.ke
+
+These special escape sequences, plus any ordinary characters, constitute the
+\fIdata\fR recorded in the logfile.  The following additional escape
+sequences are used to record information about the logging session itself in
+the logfile.
+
+.ks
+.nf
+	\#		rest of line is a comment
+	\T		terminal device name at log time
+	\G		stdgraph device name at log time
+	\O		timestamp written at start of log session
+.fi
+.ke
+
+Any whitespace (unescaped blanks, tabs, or newlines) appearing
+in the logfile is put there only to make the file more readable, and is not
+considered data.  Blocks of text may be enclosed in a logfile delimited by
+escaped curly brackets, i.e., "\{ ... \}".  This is used for the \fBplayback\fR
+facility described in the next section.  
+
+.ih
+Playback of Terminal Sessions
+The terminal driver has the capability not only of recording terminal i/o
+in a file, but of taking input from a logfile to repeat a sequence of commands
+previously entered by the user with terminal input logging enabled.
+Note that we are not talking about simply playing back recorded output,
+but of actually executing an arbitrary sequence of commands formerly entered
+by the user.  This is different from executing a sequence of commands entered
+into, for example, a CL script, because \fIall\fR input is recorded,
+including not only the commands, but also all responses to parameter queries,
+all rawmode keystroke input, and all graphics cursor input occurring
+interactively during execution of the recorded commands.
+These \fBplayback scripts\fR are useful for preparing automated demos or
+tutorials of complex software, and for preparing scripts to be used to
+automatically test software.
+
+The basic sequence used to record and later playback a terminal session is as
+follows:
+
+.ks
+.nf
+	cl> stty login [= logfilename]
+		<execute an arbitrary sequence of commands>
+	cl> stty clear login			# or stty reset
+	cl> stty playback [= logfilename]
+.fi
+.ke
+
+Naturally, the playback script must be executed in the same context as when
+the script was generated, i.e., one must ensure that all necessary packages
+have been loaded, that the current directory has been set to the proper
+value if it matters, and so on.  It is not necessary to execute a playback
+script on the same type of video terminal or graphics terminal as was
+used when the script was recorded; since only the terminal input is being
+recorded, playback scripts are device independent and may be played back on
+any terminal.
+
+If desired the commands necessary to establish the starting context may be
+recorded as part of the script.  If the script is going to be repeatedly
+executed it may also be desirable to include commands at the end of the
+recording session to clean up, e.g., deleting any temporary files created
+during the recording session.  If anything has changed which causes a command
+to abort during execution of a playback script, normal terminal input is
+automatically restored, aborting the script.   Note that if the "stty playback"
+command gets into the playback script for some reason, e.g., because the
+"stty reset" (or "stty login=no" etc.) was omitted, then the script will
+repeat indefinitely.  This may or may not be what was desired.
+
+Two \fBstty\fR command line arguments are provided for controlling the
+execution of a playback script.  By default, when a script is played back
+the terminal driver will pause for \fBdelay\fR milliseconds after echoing
+the command to be executed, to give the user watching the playback a chance
+to read the command.  Aside from this programmed delay, execution is fully
+automated.  For example,
+
+	cl> stty play=filename delay=2000
+
+would playback the file "filename", with a delay of 2 seconds following echo
+of each line of recorded input text.
+
+Alternatively, the user may request that the driver pause and wait for the
+user to type a key before executing each logged command (i.e., before
+returning each input line of text to the application).  This is called the
+\fBverify\fR option.  In verify mode, the following keystrokes may be
+entered to continue execution:
+
+.ks
+.nf
+	space, return		continue execution
+	'g'			go: turn verify mode off and continue
+	'q'			quit: terminate playback mode
+.fi
+.ke
+
+Verify mode is automatically disabled during raw mode input since the input
+consists of single characters and an inordinate number of verification
+keystrokes would be required from the user.  Either of the \fBverify\fR or
+\fBdelay\fR options may be overridden by control directives embedded in the
+playback text, as we shall see in the next section.
+
+.ih
+Customizing Playback Scripts
+Although playback scripts may be and often are generated and played back
+without ever looking at or modifying the actual playback script, there are
+cases where it may be desirable to do so.  For example, when generating a
+script to be used as a demo or tutorial, it may be desirable to insert
+explanatory text into the script to be printed out on the terminal when
+the script is played back, to explain to the person running the script what
+is going on.  Likewise, it may be desirable to control the verify and delay
+options at a granularity finer than the entire script.
+
+Explanatory text and/or playback control directives may be inserted into the
+script using the following construct:
+
+	"\{" [<control_directives>] [<text>] "\}"
+
+where \fBcontrol_directive\fR refers to one of the following:
+
+.ks
+.nf
+	%V+		turn verify on
+	%V-		turn verify off
+	%NNN		set \fBdelay\fR to NNN milliseconds
+.fi
+.ke
+
+For example,
+
+.ks
+.nf
+	dir\{%5000
+	[list the current directory]\}\n
+.fi
+.ke
+
+would cause the following to be output, followed after a 5 second delay by a 
+listing of the current directory (the "<>" is not printed, but shows where
+the cursor will be during the 5 second pause):
+
+.ks
+.nf
+	cl> dir
+	[list the current directory]<>
+.fi
+.ke
+
+Note that the newline following the "\{%5000" in the above example is textual
+data, and will be output to the terminal along with whatever follows, up until
+the closing brace, i.e., "\}".  The amount of text to be output may be
+arbitrarily large; there is a builtin limit (currently 4096 characters),
+but it is unlikely that this limit will ever be exceedd, since no more than
+one pageful of text should ever be output in a single call.
+
+Normally, a %V or %NNN control directive refers only to the input record
+with which the enclosing \{...\} control block is associated.  The global
+value of \fIverify\fR or \fIdelay\fR is temporarily overridden for the
+current record.  If desired, the global value may instead be permanently
+modified by adding a ! after the %, e.g.,
+
+	\{%!V-%3000...\}
+
+would permanently disable \fIverify\fR (unless a %V+ or %!V+ directive
+follows later in the script) then output the text "..." followed by a 3
+second delay.
+
+To know where to insert the control directives into a script, it is
+important to understand that input from the script is \fBrecord oriented\fR,
+and that a control directive refers to the input record with which it is
+associated.  An input record is a single \fIlogical\fR line of text in the
+input file.  Note that a logical line of text may span multiple physical lines,
+if the newlines are escaped or present as textual data within a control
+directive.  The position of the control directive within the input record
+determines where the explanatory text will be positioned relative to the
+input text, when both are echoed to the terminal.  Any programmed delay or
+pause will always occur after echoing the full record on the terminal.
+
+.ih
+Raw Mode Playback
+When a program is executing which reads from the terminal in raw mode,
+each character is read from the terminal as soon as it is typed, and
+input characters are not echoed to the terminal unless the application
+explicitly does the echoing.  Examples of programs which use raw mode input are
+\fIeparam\fR and \fIpage\fR, which are keystroke driven, and any program
+which reads the \fBgraphics cursor\fR, since a graphics cursor read uses raw
+mode input.
+
+Playback works much the same for raw input mode as for line input mode,
+except that during raw mode input the input records normally consist of
+single characters, rather than entire lines of text.  By default, \fBverify\fR
+is turned off while reading from the terminal in raw mode, to avoid having
+the user verify each individual character.  Also, the terminal driver will not
+echo text read from the playback file in raw mode, since the text would not
+have been echoed if playback were not in effect.
+
+.ih
+Cursor Reads in Playback Mode
+A typical Tektronix style cursor read will look something like the following,
+as recorded in an \fBstty login\fR script file following a recording session:
+
+.ks
+.nf
+	K
+	3
+	)
+	'
+	*
+	\r
+.fi
+.ke
+
+This six character sequence consists of the key value of the cursor read (K),
+followed by the [x,y] cursor coordinate encoded as four ascii characters
+("3)'*" in this case), followed by the "GIN mode terminator" character or
+characters, normally a single CR (\r).  Of course, if the terminal is not a
+Tektronix compatible terminal (e.g., DEC-Regis), the details will differ
+from this example.
+
+The single character per line format of a cursor read reflects the fact that
+each input record is a single character when reading from the terminal in
+raw mode.  For the purposes of playback, however, such a sequence may be
+reformatted on a single line if desired, to improve the readability of a
+script (the extra whitespace in the second example is ignored, since if a
+space were data it would appear as \s).
+
+.ks
+.nf
+	K3)'*\r
+or
+	K 3 ) ' * \r
+or
+	K
+	3)'*
+	\r
+etc.
+.fi
+.ke
+
+To set the values of the \fIverify\fR or \fIdelay\fR parameters for a cursor
+read one may insert the \{...\} sequence anywhere before the \r delimiter
+is returned to the application, e.g.,
+
+	K3)'*\r\{%V+\}
+
+would do, since the sequence shown forms one logical input record in the
+playback file, and the control directive included will be processed before
+any input data characters from the record are returned to the application.
+If the multi-line form of a cursor read is used, the control directive may
+be tacked onto any of the records K through \r in the example.
+
+Output of explanatory text in an interactive graphics session is a little
+more tricky, since if one is not careful the text will come out while in
+graphics mode, causing it to be rendered as random lines drawn all over the
+screen.  A safe technique for outputting comments during playback of a
+graphics session is to output the text to the \fBstatus line\fR,
+taking care of course to output only a single line of text at once
+(since multiple lines written to the status line would rapidly flash by,
+leaving only the last line visible on the screen).  We can do this by taking
+advantage of the : command sequence, which can be used to put the terminal
+temporarily into status line output mode.
+
+.ks
+.nf
+	:####\r
+	\{%5000
+	This is a status line comment\}
+	^U\177
+.fi
+.ke
+
+For example, insertion of the above sequence between any two cursor reads
+in a recorded interactive graphics session would cause the text
+"This is a status line comment" to be written to the status line,
+with normal execution of the script occurring after a 5 second delay
+followed by erasure of the status line and exit from status line mode
+(due to the ctrl/u and rubout inserted as data after the colon cursor read).
+
+While executing an interactive graphics session via playback, cursor values
+are read from the playback script instead of from the terminal, hence the
+user never sees the actual cursor crosshairs on the screen.  To give the
+user some idea of what is going on, the key values of successive cursor mode
+keystrokes are echoed in ascii down the left side of the screen, starting at
+the upper left.  The keystroke value is also echoed at the position of the
+cursor, to indicate where the cursor crosshairs would have been in an actual
+interactive session.
+
+.ih
+Sample Playback Script
+We conclude with an example of a complete playback script which can be
+entered into a file and played back to demonstrate some of the features of
+the \fIimplot\fR task in the PLOT package (the PLOT package must already
+be loaded).
+
+.ks
+.nf
+	\O=NOAO/IRAF V2.6 iraf@pavo Fri 20:09:21 01-Jan-88
+	\T=gterm40
+	\G=gterm
+	\n
+	imheader\sdev$pix\slo+\suser-\n\{%3000
+	[Print image header]\}
+	\n
+	implot\sdev$pix\n
+	J3..8\r J3-,)\r J3+)9\r K3)'*\r J3((0\r l3&';\r
+	:####\r
+	\{%5000
+	[use key `o' to overplot]\}
+	^U\177
+	o3&';\r
+	K3&';\r K3%*(\r K3#,3\r l3!.?\r
+	:####\r
+	\{%5000
+	[key `X' expands the plot in x]\}
+	^U\177
+	X3!.?\r
+	qXXXX\r
+	stty\sreset\n
+.fi
+.ke
+
+.ih
+EXAMPLES
+1. Show the current terminal type and attributes.
+
+.nf
+	cl> stty
+	Terminal=vt640, ncols=80, nlines=24, 9600 baud
+	ucasein=no, ucaseout=no, logio=off
+.fi
+
+2. Tell the system that the terminal is a vt100.
+
+	cl> stty vt100
+
+3. Set the baud rate of the current terminal to 9600 baud.
+
+	cl> stty baud=9600
+
+4. Set the width of the screen to 80 columns, e.g., to get short menus on a
+workstation where the physical number of columns may be much greater than 80.
+
+	cl> stty ncols=80
+
+5. Set the terminal type to 4012 and set ucasein and ucaseout modes.
+
+	cl> stty 4012 ucasein ucaseout
+
+6. Clear the ucasein and ucaseout modes.
+
+	cl> stty clear ucasein ucaseout
+
+7. Record a terminal session in the default logfile (home$ttyio.log).
+
+	cl> stty logio
+
+8. Record input from the terminal in the file "demo".
+	
+	cl> stty login=demo
+
+9. Terminate logging and playback the terminal session recorded in this file.
+
+.nf
+	cl> stty reset
+	cl> stty playback=demo
+.fi
+.ih
+BUGS
+1. Note that, when working with a terminal which supports runtime querying
+of the screen size, the screen size is queried when the \fBstty resize\fR
+command is executed, rather than when the terminal screen actually changes size.
+Hence, the screen size parameters printed by a command such as \fBstty show\fR
+will not necessarily reflect the actual screen size.  \fBstty resize show\fR
+queries the terminal for the screen size, hence should always be correct.
+The screen size is automatically queried whenever the \fIpage\fR or \fIhelp\fR
+tasks are run.
+
+2. The terminal screen size is determined by querying the terminal for the
+screen size, and reading the response back (this technique has the advantage
+that it works remotely over IPC and network connections, and is host system
+independent).  If the terminal does not respond for some reason, e.g.,
+because the terminal type has been set improperly and the terminal does not
+support the query function, then \fBstty\fR will hang.  Typing a carriage
+return causes execution to resume, after which the error should be corrected.
+.ih
+SEE ALSO
+language.logging, fio$zfiott.x, etc$sttyco.x
+.endhelp
-- 
cgit 

