CBM Funet Archive/cbm-funet-archive-2003.iso/cbm/c128/os/unix128v3/unix311b.sfx/intro.2

Text File | 1990-02-12 | 19.5 KB | 463 lines

Unix 128 v3.10 Manual           15 January 1992                          Page 8


12.  Introduction to nroff.

nroff is a text formatting package that is "mostly" compatible with plain nroff
and  troff  source  files  (no  macros are included with this release for table
(tbl) or equation (eqn) processing).   nroff  is  not  a  "word  processor"  or
"editor", but a pass-thru text formatter.  You must enter text on any editor or
word processor (emacs is fine) and then type  % nroff -p file to print it or  %
nroff  -v  file  to preview it. nroff provides the powerful features associated
with many word processors.

12.1  Command Line Options:

nroff may be invoked with several command-line options in the format:
    % nroff (options) filename
The options are:
      -i  Interactive formatting setup first.
      -v  Video preview only
      -p  Print document
      -S  Use my own symbol table instead of 'nroff.tbl.'  Example:  -Smytable

A command line might look like: % nroff -i -Smytable -p thisfile.
The nroff command takes a single document filename,  which  must  be  specified
last on the command line.

12.2  Formatting Commands:

All formatting commands must begin with a period (.) that is at  the  far  left
(first column) of the source document.   A complete list of formatting commands
can be viewed by typing % more nroff.hlp from the shell, or from  within  emacs
by typing ESC-X NROFF.


13.  Introduction to the as Assembler Development Package

as is the Unix 128 8510 assembler.  It takes a single  source  file,  processes
the  Unix  128 extensions, writes an object file (*.o) that contains only valid
8510 assembler opcodes / operands, then converts the object  files  and  writes
the C128 machine language file 'a.out.'

The first two bytes of 'a.out' contain the start address of the code (where  it
is loaded) and the rest of the file contains the machine language code.

13.1  Language Extensions:

The extensions to standard assembler are as follows:
1.  The first line of any assembler  source  code  must  be  the  word  'start'
followed by either a decimal number or a '$' and a hexidecimal number.  This is
the start address of the code which is  written  directly  to  'a.out.'   If  a
'start' line is not found, an error will be printed, and the compiler will halt
and catch fire.

2.  One or more lines may be given that begin with the  word  'include'  and  a
source  filename that contains valid macro definitions (see 4).  The purpose of
this statement is similar to the C #include <library.h>: to include  macros  of
standard  code.   An include file, 'stdlib.i', is given with this package as an
example.  Example:  include stdlib.i







Unix 128 v3.10 Manual           15 January 1992                          Page 9


3.   A  data  section  may be given, so that you may label common constants.  A
data section consists of the word 'data' on its own line, followed  by  one  or
more data lines, and followed by the word 'endd' (end-data) on its own line.  A
data line consists of a data label, the word 'equ', and a decimal  value  or  a
hexidecimal value preceeded by a '$'
Example:
   data
     zero equ $00
     two equ 2
   endd
Wherever the names 'zero' or 'two' are encountered, they are replaced with  the
appropriate data value.

4.  Macros are units of code that are given a name.  They are defined once, and
expanded  wherever the macro name is found.  A macro definition begins with the
word 'macro', a single space, and the macro name.  One or more lines  of  valid
8510  source  code are given on separate lines, and the word 'endm' (end-macro)
is given to conclude the macro definition.
Example:
   macro foo           (start a macro named foo)
     lda #$00
   endm                (end of this macro)
Whenever the name 'foo' is encountered in the source code, it is replaced  with
the  line  'lda #$00'.  Macros cannot be given parameters.  Standard macros are
usually used for system calls such as setting fast mode or clearing the screen.

5.  Comments can be given on separate lines  by  beginning  that  line  with  a
semicolon (;).  Example:
   ;This is a comment

6.  Any line may be given a name by which it can be referred.  This removes the
tedium  of keeping track of addresses for jumps and branches.  The name must be
followed immediately by a colon (:).  Example:
 line:  ldx #zero
        sta $0400,x
        jmp line

**WARNING**  Be very careful not to use valid operand names  for  line  labels,
data labels or macro names.  The preparser will replace all occurences of label
names with the appropriate data.  (For example, if you label a line with  jsr:,
every  time  you used jsr in your program it will be replaced by the address of
the line to which the line label refers!)

13.2  Command Line Options:
      as can be invoked with  several  different  options  from  the  Unix  128
command line:
   % as -h           :Prints a help screen.
   % as -d beg end   :Disassembles memory from beg to end
   % as -v beg end   :Views memory from beg to end
   % as filename     :Parses 'filename' --> 'filename.o' --compiles--> 'a.out'

as accepts all valid 8510 opcodes, and the following reserved keywords:
   start   macro   endm    data    endd    include equ








Unix 128 v3.10 Manual           15 January 1992                         Page 10


13.3  General Notes:
1.  Use all lower case for keywords and op-codes, and use a single space
       between op-codes and operands.
2.  There is a limit of 1500 lines of source code (255 characters per line)
3.  There is a limit of 75 macros of 50 lines (255 char/line) each.
4.  There is a limit of 100 unique line labels.
5.  There is a limit of 100 data items in the data section.


14.  Programming in BASIC Under Unix 128.

It is quite feasible to write BASIC 7.0 code using emacs.  There are no special
features  included  for  writing  BASIC code under emacs.  To convert an editor
(SEQ) file to BASIC format,  simply  type  '%  basic'.   The  BASIC  conversion
utility  will  load  the  requested  file  into  memory,  where you can run it.
Remember to save the file after the conversion is complete (When the conversion
completes,  either  a  syntax  error will occur or the disk drive will halt and
you'll need to press RUN/STOP - RESTORE; either is normal  -  your  program  is
safely in memory.)
     To convert a BASIC program to SEQ format for emacs, load the file normally
from BASIC then type:
           OPEN 5,8,4,"0:seq-filename,s,w"
           CMD5:LIST
           PRINT#5
           CLOSE 5


15.  Introduction to the emacs Text Editor.

Emacs is a powerful text editor for use under Unix 128.  It is not  a  document
formatter  or  'word  processor'-  the most advanced text previewing feature is
word-wrap.  Text should be  passed  to  nroff  for  formatting  (line  spacing,
columns, justification etc.)

Emacs allows up to 700 lines of text (of 80 characters / line).  It  loads  and
saves  SEQ  type  files  that  are  compatible with most other word processors.
Emacs also features DiskEd, to enter CBM-DOS commands.  It has help screens for
itself  as  well as a command reference for writing nroff source files.  It has
multiple text editing features like setting and copying regions, 'killing'  and
'yanking' lines of text, commands to move to the start and end of lines, up and
down by screens, and commands to move to the start and end of text.  Files  can
be inserted into the text.  There is font support, and 2 partial fonts (one for
special Polish characters and one for  the  Russian  (cyrillic)  alphabet)  are
included.

15.1  Regions:
      A region is defined as all the text in between the 'mark' and the current
cursor  position.   A mark is set by typing (Commodore) (SPACE).  Once a region
is defined, you can:
        CONTROL-c : copy region as kill.  This allows you to  copy  the  region
into the kill buffer to be copied back into the text with CONTROL-y (yank).
        Rot-13 region : Perform the rot-13 transformation on the region  (which
maps each letter 13 positions away; a-->m, b-->n, m-->a etc)

15.2  Expanded Command Reference:
(C-key - Control+key    E-key - Hit ESC then key)
C-a      Move the cursor to the beginning of the current line.
C-b      Move the cursor back one character (same as 'cursor left')







Unix 128 v3.10 Manual           15 January 1992                         Page 11


C-c      Copy the currently marked region into memory, to be retrieved with
         C-y (yank line)
C-d      Enter DiskEd, which allows CBM DOS commands to be executed.
C-e      Move the cursor to the end of the current line.
C-f      Move the cursor forward one character (='cursor right')
C-g      Quit prompt (general abort for commands)
C-h      Get Help!!!
C-k      Delete line from cursor to end of line, copying the line to memory.
C-l      Redraw the screen.
C-n      Move the cursor to the next line (='cursor down')
C-p      Move the cursor to the previous line (='cursor up')
C-r      Rot-13 a previously marked region
C-v      Move down by a full screen
C-w      Write this file as...
C-y      Yank a line from memory to the current cursor position.
C-x c    Clear text memory.
C-x e    Copy the keyboard macro defined with C-( and C-)
C-x f    Find phrase (maybe).
C-x i    Insert a file at the current cursor position.
C-x p    Print the contents of memory.
C-x s    Save file with current filename.
C-x v    View document with word-wrap.
C-x C-c  Quit to Unix 128.
C-x C-f  Load a file into memory, erasing current memory contents.
C-x (    Write keyboard macro
C-x )    End keyboard macro
C-x =    Cursor information (what line, character etc)
C-x +    Insert a line at the cursor.
E-<      Move the cursor to the beginning of the file.
E->      Move the cursor to the end of the file.
E-v      Move up by 1 full screen.
E-x ?    Show bound commands (nroff help, fonts etc.)

Of course, the abbreviated command reference may  be  viewed  at  any  time  by
typing C-h, without disturbing your document.


16.  The tip Telecommunications Program.

     Tip is used to connect to mainframes or other Unix 128 systems  using  the
telephone  lines.   It can use a wide variety of protocol and terminal settings
and will be compatible with most systems.
     All of the features of tip can be accessed  through  the  main  menu.   To
bring  up  the  main menu, press the ALT key on the upper left of the keyboard.
This brings up the following menu heirarchy (may not be in the same order):

16.1  Protocol Menu:
     -Baud Rate:    the speed of communication (300 and 1200 are most common)
     -Data Bits:    7 or 8 data bits are supported
     -Parity:       even, odd, space, mark or no parity are supported
     -Stop Bits:    1 or 2 stop bits are allowed
     -Duplex:       full(no local echo) or half(local echo) duplex
16.2  Terminal Type Menu:
     -VT100:        use VT100 emulation.  For some reason, not all of the codes
                     work all of the time.  Hope to have that fixed soon....
     -VT52:         use VT52 emulation.







Unix 128 v3.10 Manual           15 January 1992                         Page 12


     -Commodore:    also called 'raw' mode, this doesn't interpret any of the
                     control codes encountered.  This is useful when talking
                     to other Commodore systems.
16.3  Dial:
       Enter a phone number (no parentheses or hyphens, a comma (,) makes a 2
       second pause) and tip will dial it and attempt to connect.  One of the
       the following messages will be returned:
         CONNECT       = connected at 300 baud
         CONNECT 1200  = connected at 1200 baud
         BUSY          = the host is busy
         VOICE         = a human being answered the phone.
16.4  Hang Up Menu:
         Hang Up: obviously, hang up the phone.
         Don't Hang Up: obviously, don't hang up the phone.
16.5  Clear Display:
         This just clears the screen.
16.6  Buffer Menu:
         Capture On:   This will copy everything that comes across the screen
                        (except menus etc.) to memory
         Capture Off:  This turns off the copy-to-memory feature.
         Clear Buffer: Erase all buffer memory.
         Save Buffer:  Save the contents of the buffer in a disk file.
         Print Buffer: Print the contents of the buffer on the printer.
         View Buffer:  Type the contents of the buffer on the screen (use the
                        NO SCROLL key to pause / resume.)
16.7  ASCII Upload:
         Enter a filename and tip will just type the file to the modem.  To
         receive a file, you must first type:
           VAX / VMS:  $ create filename  (when upload is done, type CTRL-Z)
           Unix:       % cat > filename   (when done, type CTRL-D)
16.8  Quit to Unix:
         Returns to the Unix 128 shell prompt (%).  You can leave tip without
         hanging up, do other work, and return to tip safely.  Remember to hang
         up the phone when you're all done (note that shutting off the computer
         will hang up the phone automatically)
16.9  (Terminal Mode):
         Return to terminal mode without doing anything.


17.  dc:
     dc is the  Unix  128  desktop  calculator.   It  can  be  used  for  doing
arithmetic  calculations,  base conversions and trigonometry.  dc can be run in
one of two modes: interactive and single expression.
     If you type % dc at the shell prompt, dc will load and  place  you  in  an
interactive environment.  Pressing '?' will list all of the features.
     If you type % dc (expr) at the shell prompt (example:  % dc 3+2), dc  will
be  loaded,  and  it  will evaluate the given expression, print the result, and
return to the shell immediately.
     The valid operations are:
          Help:       ?
          Arithmetic: + - * /  ( ) !
          Functions:  (functions take a single argument)
                      log sqr sqrt sin cos tan sec csc cot
          Arguments:  can be:
                      -numeric (example: 3+2)
                      -e or pi (defined constants)
                      -ans (ans is the previous answer variable)






Unix 128 v3.10 Manual           15 January 1992                         Page 13



          Conversion: hd (hex arg)    hexadecimal to decimal
                      hb (hex arg)    hexadecimal to binary
                      dh (dec arg)decimal to hexadecimal
                      db (dec arg)    decimal to binary
                      bd (bin arg)    binary to decimal
                      bh (bin arg)    binary to hexadecimal
                Example:  to convert $ff to decimal, type:  hd ff.

18.  mail:

mail invokes the Unix 128 mail system.  This mailer was set up so that multiple
users  of  Unix 128 on a single system could send mail between each other.  The
operation of mail is almost exactly identical to Berkeley mail (/usr/ucb/mail).

The mailer uses 'mailboxes' named username.mbox; if one doesn't exist  for  you
it  will  be created if needed.  If you have no mail, mail will probably return
an error message like 'user.mbox doesn't exist.'.

mail contains all the standard Unix mailer commands: n (next message), s  (save
message(s)), p (print message(s)), mail (mail to another user), and d (delete).


19.  spread:
     spread is the Unix 128 spreadsheet program.  It is similar in function  to
Lotus  1-2-3,  but  a  lot  smaller  and  skimpier.   spread provides a maximum
spreadsheet size of 26 rows (A-Z) by 99 columns (1-99).  There  are  facilities
for entering text strings, numbers, functions, and math expressions.  Functions
and math expressions may apply to multiple cells ('ranges').
     In most cases, ranges are entered in two ways:
        -explicitly:  two opposite corners (usually top-left and  bottom-right)
are  given,  separated by a hyphen (-).  The column letter must come before the
row number.  Example: a1-b10
        -by name:  commonly used ranges may be given a  name  (type  CTRL-n  to
name  a  range.)   Once  a  range  is  named,  its name may be given instead of
explicitly defining the range.
     In some cases (such as when entering a range to print) you  can  also  use
the  cursor  keys  to  scroll the top left cell address, press '.', and use the
cursor keys to select a bottom right cell address.
     Functions act on ranges.  Functions are preceded by the  '@'  sign.   Some
available  functions  are  sum  (@sum),  average  (@avg), maximum value (@max),
minimum value (@min), number of numeric items in a range  (@count),  log,  sin,
cos,  tan,  and  sqrt  (square root).  Ranges are specified after the function:
@sum a1-b9.
     Spread can also calculate binary math expressions  (expressions  with  two
numbers).   Math  expressions  are  preceded by a percent sign, contain a singe
operator (+,-,* or /), and two arguments (arguments may be  either  numeric  or
single cell names).  Examples:  %497-334  %a1-b1  %d49-10.
     NOTE:   Functions  or  expressions  that  act  on  other  cells  are   not
automatically changed to reflect changes in arguments; a screen redraw (CTRL-r)
will make these changes.
     Complete information on the current version  of  spread  is  available  by
typing Control-h.










Unix 128 v3.10 Manual           15 January 1992                         Page 14


20.  Other miscellaneous applications:

20.1  Games:
     Four 'games' have been included with Unix 128:  banner, maze, puzzle,  and
wump (these are traditionally found in /usr/games on "real" unix systems.)
     -Banner will print the given phrase  in  large  letters  on  the  standard
output device.  Thus, % banner i love unix 128 {SHIFT-POUND} lpr   will print a big sign on
your printer.
     -Maze creates a random maze and prints it to the standard output.   Again,
you'll probably want to pipe this command to the printer.
     -Puzzle is a Unix 128 implementation of the sliding tile game whose object
is to get the tiles in numerical order by sliding them around.
     -Wump is an implementation of Hunt The Wumpus, a game by Gregory Yob  that
has  been  on  Unix  systems since their inception.  The object is to shoot the
Wumpus while avoiding hazards like pits and Superbats.

20.2  Tar:
     Tar is the tape archive program that exists to  take  multiple  files  and
concatenate them into a single archive file (called a tarfile) for archiving or
mailing.  The Unix 128 version seems to be compatible with Sun's  tar  and  DEC
Ultrix tar.  Other mainframe Unix tarfiles have not been tested.
     The command line to archive multiple files into a single tarfile is:
         % tar -c [ tarfile ] [ filelist...]
and the command to unarchive (eXtract) a tarfile is:
         % tar -x [ tarfile ].
     Tar is very slow in either archiving or de-archiving  files.   Also,  note
that  mainframe-produced  tarfiles  will unarchive in ASCII format, not CBMSCII
format, so that all the cases will be reversed (lIKE tHIS).

20.3  uuencode/uudecode:
     Also in the area of things that are binary compatible with Unix mainframes
are  uuencode  and  uudecode.   Uuencode  (pronounced you-you-encode; short for
unix-to-unix  encode)  takes  an  input  file  and  maps  all  the   bytes   to
ASCII-printable  characters.   The  original purpose of this was to make binary
files (programs) readable by the mail system for file transfers.
     To encode a file, type %  uuencode  (-c)  inputfile  outputfile.   The  -c
option will convert ASCII<>PETSCII as it encodes.  The inputfile is the file to
be encoded, and the outputfile is the encoded file.
     To decode a file, type % uudecode  (-c)  filename.   The  -c  option  will
convert ASCII<>PETSCII as it decodes.

20.4  style:
     style will analyze the surface characteristics of the writing style  of  a
document.   It  reports  on  readability,  sentence  length and structure, word
length and usage.  The grade it gives is somewhere around 0-12, and the  higher
the grade the better the document.