1 files changed, 249 insertions, 0 deletions
diff --git a/lib/libocurses/PSD.doc/intro.1 b/lib/libocurses/PSD.doc/intro.1
new file mode 100644
index 00000000000..a86d7571ade
--- /dev/null
+++ b/lib/libocurses/PSD.doc/intro.1
@@ -0,0 +1,249 @@
+.\" Copyright (c) 1980, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	@(#)intro.1	8.1 (Berkeley) 6/4/93
+.\"
+.bp
+.sh 1 Overview
+.pp
+In making available the generalized terminal descriptions in \*(tc,
+much information was made available to the programmer,
+but little work was taken out of one's hands.
+The purpose of this package is to allow the C programmer
+to do the most common type of terminal dependent functions,
+those of movement optimization and optimal screen updating,
+without doing any of the dirty work,
+and with nearly as much ease as is necessary to simply print
+or read things.
+.sh 2 "Terminology"
+.pp
+In this document, the following terminology is used:
+.de Ip
+.sp
+.in 5n
+.ti 0n
+.b "\\$1" :
+..
+.Ip window
+An internal representation
+containing an image of what a section of the terminal screen may look like
+at some point in time.
+This subsection can either encompass the entire terminal screen,
+or any smaller portion down to a single character within that screen.
+.Ip terminal
+Sometimes called
+.b terminal
+.b screen .
+The package's idea of what the terminal's screen currently looks like,
+.i i.e. ,
+what the user sees now.
+This is a special
+.i screen :
+.Ip screen
+This is a subset of windows which are as large as the terminal screen,
+.i i.e. ,
+they start at the upper left hand corner
+and encompass the lower right hand corner.
+One of these,
+.Vn stdscr ,
+is automatically provided for the programmer.
+.rm Ip
+.sh 2 "Compiling Applications"
+.pp
+In order to use the library,
+it is necessary to have certain types and variables defined.
+Therefore, the programmer must have a line:
+.(l
+.b "#include <curses.h>"
+.)l
+at the top of the program source.
+Compilations should have the following form:
+.(l
+.ie t \fBcc\fR [ \fIflags\fR ] file ... \fB\-lcurses \-ltermcap\fR
+.el \fIcc\fR [ flags ] file ... \fI\-lcurses \-ltermcap\fR
+.)l
+.sh 2 "Screen Updating"
+.pp
+In order to update the screen optimally,
+it is necessary for the routines to know what the screen currently looks like
+and what the programmer wants it to look like next.
+For this purpose,
+a data type
+(structure)
+named
+.Vn WINDOW
+is defined
+which describes a window image to the routines,
+including its starting position on the screen
+(the \*y of the upper left hand corner)
+and its size.
+One of these
+(called
+.Vn curscr
+for
+.i "current screen" )
+is a screen image of what the terminal currently looks like.
+Another screen
+(called
+.Vn stdscr ,
+for
+.i "standard screen" )
+is provided
+by default
+to make changes on.
+.pp
+A window is a purely internal representation.
+It is used to build and store
+a potential image of a portion of the terminal.
+It doesn't bear any necessary relation
+to what is really on the terminal screen.
+It is more like an array of characters on which to make changes.
+.pp
+When one has a window which describes
+what some part the terminal should look like,
+the routine
+.Fn refresh
+(or
+.Fn wrefresh
+if the window is not
+.Vn stdscr )
+is called.
+.Fn Refresh
+makes the terminal,
+in the area covered by the window,
+look like that window.
+Note, therefore, that changing something on a window
+.i does
+.bi not
+.i "change the terminal" .
+Actual updates to the terminal screen
+are made only by calling
+.Fn refresh
+or
+.Fn wrefresh .
+This allows the programmer to maintain several different ideas
+of what a portion of the terminal screen should look like.
+Also, changes can be made to windows in any order,
+without regard to motion efficiency.
+Then, at will,
+the programmer can effectively say
+.q "make it look like this" ,
+and the package will execute the changes in an optimal way.
+.sh 2 "Naming Conventions"
+.pp
+As hinted above,
+the routines can use several windows,
+but two are always available:
+.Vn curscr ,
+which is the image of what the terminal looks like at present, 
+and
+.Vn stdscr ,
+which is the image of what the programmer wants the terminal to look like next.
+The user should not access
+.Vn curscr
+directly.
+Changes should be made to
+the appropriate screen,
+and then the routine
+.Fn refresh
+(or
+.Fn wrefresh )
+should be called.
+.pp
+Many functions are set up to deal with
+.Vn stdscr
+as a default screen.
+For example, to add a character to
+.Vn stdscr ,
+one calls
+.Fn addch
+with the desired character.
+If a different window is to be used,
+the routine
+.Fn waddch
+(for
+.b w indow-specific
+.Fn addch )
+is provided\**.
+.(f
+\**
+Actually,
+.Fn addch
+is really a
+.q #define
+macro with arguments,
+as are most of the "functions" which act upon
+.Vn stdscr .
+.)f
+This convention of prepending function names with a
+.Bq w
+when they are to be applied to specific windows
+is consistent.
+The only routines which do
+.i not
+do this are those
+to which a window must always be specified.
+.pp
+In order to move the current \*y from one point to another,
+the routines
+.Fn move
+and
+.Fn wmove
+are provided.
+However,
+it is often desirable to first move and then perform some I/O operation.
+In order to avoid clumsiness,
+most I/O routines can be preceded by the prefix
+.Bq mv
+and the desired \*y can then be added to the arguments to the function.
+For example,
+the calls
+.(l
+move(y\*,x);
+addch(ch);
+.)l
+can be replaced by
+.(l
+mvaddch(y\*,x\*,ch);
+.)l
+and
+.(l
+wmove(win\*,y\*,x);
+waddch(win\*,ch);
+.)l
+can be replaced by
+.(l
+mvwaddch(win\*,y\*,x\*,ch);
+.)l
+Note that the window description pointer
+.Vn win ) (
+comes before the added \*y.
+If a window pointer is needed, it is always the first parameter passed.