doc/cwsh.1

   1 '\"
   2 '\" Copyright (c) 1991-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1996-1999 Christian Werner
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .so man.macros
  10 .TH cwsh 1 8.0 Ck "Ck Applications"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 cwsh \- Simple curses windowing shell
  15 .SH SYNOPSIS
  16 \fBcwsh\fR ?\fIfileName arg arg ...\fR?
  17 .BE
  18
  19 .SH DESCRIPTION
  20 .PP
  21 \fBCwsh\fR is a simple program consisting of the Tcl command
  22 language, the Ck toolkit, and a main program that eventually reads
  23 commands from a file.
  24 It creates a main window and then processes Tcl commands.
  25 If \fBcwsh\fR is invoked with no arguments,
  26 then it reads Tcl commands interactively from a command window.
  27 It will continue processing commands until all windows have been
  28 deleted or until the \fBexit\fR Tcl command is evaluated.
  29 If there exists a file \fB.cwshrc\fR in the home directory of
  30 the user, \fBcwsh\fR evaluates the file as a Tcl script
  31 just before presenting the command window.
  32 .PP
  33 If \fBcwsh\fR is invoked with an initial \fIfileName\fR argument, then
  34 \fIfileName\fR is treated as the name of a script file.
  35 \fBCwsh\fR will evaluate the script in \fIfileName\fR (which
  36 presumably creates a user interface), then it will respond to events
  37 until all windows have been deleted. The command window will not
  38 be created.
  39 There is no automatic evaluation of \fB.cwshrc\fR in this
  40 case, but the script file can always \fBsource\fR it if desired.
  41
  42 .SH "APPLICATION NAME AND CLASS"
  43 .PP
  44 The name of the application, which is used for processing the
  45 option data base is taken from \fIfileName\fR, if it is specified,
  46 or from the command name by which \fBcwsh\fR was invoked.
  47 If this name contains a ``/''
  48 character, then only the characters after the last slash are used
  49 as the application name.
  50 .PP
  51 The class of the application, which is used for purposes such as
  52 specifying options, is the same as its name except that the first letter is
  53 capitalized.
  54
  55 .SH "VARIABLES"
  56 .PP
  57 \fBCwsh\fR sets the following Tcl variables:
  58 .TP 15
  59 \fBargc\fR
  60 Contains a count of the number of \fIarg\fR arguments (0 if none).
  61 .TP 15
  62 \fBargv\fR
  63 Contains a Tcl list whose elements are the \fIarg\fR arguments
  64 that follow \fIfileName\fR, in order, or an empty string
  65 if there are no such arguments.
  66 .TP 15
  67 \fBargv0\fR
  68 Contains \fIfileName\fR if it was specified.
  69 Otherwise, contains the name by which \fBcwsh\fR was invoked.
  70 .TP 15
  71 \fBtcl_interactive\fR
  72 Contains 1 if \fBcwsh\fR was started without \fIfileName\fR
  73 argument, 0 otherwise.
  74
  75 .SH "SCRIPT FILES"
  76 .PP
  77 If you create a Tcl script in a file whose first line is
  78 .DS
  79 \fB#!/usr/local/bin/cwsh\fR
  80 .DE
  81 then you can invoke the script file directly from your shell if
  82 you mark it as executable.
  83 This assumes that \fBcwsh\fR has been installed in the default
  84 location in /usr/local/bin;  if it's installed somewhere else
  85 then you'll have to modify the above line to match.
  86 Many UNIX systems do not allow the \fB#!\fR line to exceed about
  87 30 characters in length, so be sure that the \fBcwsh\fR executable
  88 can be accessed with a short file name.
  89 .PP
  90 An even better approach is to start your script files with the
  91 following three lines:
  92 .DS
  93 \fB#!/bin/sh
  94 # the next line restarts using cwsh \e
  95 exec cwsh "$0" "$@"\fR
  96 .DE
  97 This approach has three advantages over the approach in the previous
  98 paragraph.  First, the location of the \fBcwsh\fR binary doesn't have
  99 to be hard-wired into the script:  it can be anywhere in your shell
 100 search path.  Second, it gets around the 30-character file name limit
 101 in the previous approach.
 102 Third, this approach will work even if \fBcwsh\fR is
 103 itself a shell script (this is done on some systems in order to
 104 handle multiple architectures or operating systems:  the \fBcwsh\fR
 105 script selects one of several binaries to run).  The three lines
 106 cause both \fBsh\fR and \fBcwsh\fR to process the script, but the
 107 \fBexec\fR is only executed by \fBsh\fR.
 108 \fBsh\fR processes the script first;  it treats the second
 109 line as a comment and executes the third line.
 110 The \fBexec\fR statement cause the shell to stop processing and
 111 instead to start up \fBcwsh\fR to reprocess the entire script.
 112 When \fBcwsh\fR starts up, it treats all three lines as comments,
 113 since the backslash at the end of the second line causes the third
 114 line to be treated as part of the comment on the second line.
 115
 116 .SH KEYWORDS
 117 shell, toolkit