20060303-partial

1 files changed, 134 insertions, 0 deletions

diff --git a/man/9/0intro b/man/9/0intro
new file mode 100644
index 00000000..4b7cd4fd
--- /dev/null
+++ b/man/9/0intro
@@ -0,0 +1,134 @@
+.TH INTRO 9
+.SH NAME
+intro \- introduction to Inferno Tk
+.SH DESCRIPTION
+This section of the manual provides a reference for the Inferno
+Tk implementation,
+which is accessed by Limbo programs via
+.IR tk (2),
+and from
+.IR sh (1)
+via
+.IR sh-tk (1).
+.PP
+The following pages were derived by Vita Nuova from documentation that is
+.IP
+Copyright © 1990 The Regents of the University of California
+.br
+Copyright © 1994-1996 Sun Microsystems, Inc.
+.br
+See
+.IR copyright (9)
+for the full copyright notice.
+.PP
+The format of the pages has changed to follow the format of the rest of
+this manual, but more important, the content has been changed
+(typically in small ways) to reflect the variant of Tk implemented by
+Inferno.
+.SS Programming Interface
+The interface to Inferno Tk is exclusively through the
+.IR tk (2)
+module; all the Tk commands described in this section of
+the manual are excecuted by passing them as strings to the
+.B cmd
+function in that module.
+The Inferno Tk implementation is based on the Tk 4.0 documentation,
+but there are many differences, probably the greatest of which is that
+there is no associated Tcl implementation, so almost every
+Inferno application using Tk will need to have some Limbo code
+associated with it (the
+.IR sh-tk (1)
+shell module can also fulful this rôle). See ``An Overview of Limbo/Tk''
+in Volume 2 for a tutorial-style introduction to the use of Inferno Tk
+which summarises the differences from Tk 4.0.
+.SS Tk Commands
+The command string passed to
+.B tk->cmd
+may contain one or more Tk commands, separated by semicolons.
+A semicolon is not a command separator when it is nested in braces
+.RB ( {} )
+or brackets
+.RB ( [] )
+or it is escaped by a backslash
+.RB ( \e ).
+Each command is divided into
+.IR words :
+sequences of characters separated by one or more
+blanks and tabs.
+.PP
+There is also a `super quote' convention: at any point in the command
+string a single quote mark
+.RB ( ' )
+means that the entire rest of the string should be treated as one word.
+.PP
+A word beginning with an opening brace
+.RB ( { )
+continues until the balancing closing brace
+.RB ( } )
+is reached. The outer brace characters are stripped. A backslash
+can be used to escape a brace in this context. Backslash
+characters not used to escape braces are left unchanged.
+.PP
+A word beginning with an opening bracket
+.RB ( [ )
+continues until the balancing closing bracket
+.RB ( ] )
+is reached. The enclosed string is then evaluated as if it
+were a command string, and the resulting value
+is used as the contents of the word.
+.PP
+Single commands are executed in order until they are all done
+or an error is encountered. By convention, an error is signaled by a
+return value starting with an exclamation mark
+.RB ( ! ).
+The return value from
+.B tk->cmd
+is the return value of the first error-producing
+command or else the return value of the final single command.
+.PP
+To execute a single command, the first word is examined. It
+must either begin with dot
+.RB ( . )
+in which case it must name an existing widget, which will
+interpret the rest of the command according to its type,
+or one of the following words, each of which is
+documented in a manual page of that name in this section:
+.EX
+
+bind         focus        lower        scrollbar
+button       frame        menu         see
+canvas       grab         menubutton   send
+checkbutton  grid         pack         text
+cursor       image        radiobutton  update
+destroy      label        raise        variable
+entry        listbox      scale
+.EE
+.SS Widget Options
+Each manual page in this section documents the options
+that a particular command will accept. A number of options
+are common to several of the widgets and are named as
+``standard options'' near the beginning of the manual page
+for each widget. These options are documented in
+.IR options (9).
+The types of value required as arguments to options within
+Inferno Tk are documented under
+.IR types (9).
+.SH SEE ALSO
+.IR options (9),
+.IR types (9),
+.IR tk (2),
+.IR sh-tk (1),
+.IR tkcmd (1),
+.IR wmlib (2),
+.IR draw-intro (2),
+``An Overview of Limbo/Tk'' in Volume 2.
+.SH BUGS
+The bracket
+.RB ( [] )
+command interpretation is not applied consistently throughout
+the Inferno Tk commands (notably, the argument to
+the
+.IR send (9)
+command will not interpret this correctly).
+Moreover, if the string to be substituted is significantly bigger
+than the command it was substituting, then it will be truncated.