'\"       To get a copy of this ROADMAP on your terminal, type:
'\"              nroff -mm roadmap
'\"
'\"       To get a typeset copy, type:
'\"              troff -mm roadmap
'\"
.nr Pt 0
.if n .nr a 5
.if t .nr a 4
.nr Si \na
.if n .ds p .\"
.if t .ds p \fB.\fP\"
.if n .ds ` ""\"
.if t .ds ` ``\"
.if n .ds ' ""\"
.if t .ds ' ''\"
.if n .ds > =>\"
.if t .ds > \(->\"
.if n .ds d " -- \"
.if t .ds d \(em\"
.TL
P\s-2WB/UNIX\s0 Documentation Roadmap
.AU "J. R. Mashey" JRM PY 123 456 789
.MT 4
.H 1 INTRODUCTION
A great deal of documentation exists for
\s-2PWB/UNIX\s0.
It has different formats,
is contributed by many different people,
and is modified frequently.
New users are often overcome by the volume and distributed
nature of the documentation.
This \*`roadmap\*' attempts to be a terse, up-to-date outline of
crucial documents and information sources.
.P
Numerous people have contributed comments and
information for this \*`roadmap,\*'
in order to make it as helpful as possible for \s-2PWB/UNIX\s0 users.
.I
However, many of these comments are accurate only with regard
to \s-2PWB/UNIX\s0 and may well be totally inapplicable to
other versions of \s-2UNIX\s0.
.R
.H 2 "Things to Do"
See a local \s-2PWB/UNIX\s0 system administrator to obtain a \*`login name\*' and
get other appropriate system \%information.
'''	PUT LOCAL INFORMATION HERE.
.H 2 "Notation Used in this Roadmap"
.if n .VL 10 \na 1
.if t .VL 9 \na 1
.LI "{\fIN\fP\^}"
\*>\ \ Section N in this \*`roadmap.\*'
.LI "++"
\*>\ \ item required for everyone.
.LI "+"
\*>\ \ item recommended for most users.
.LE 1
All other items are optional and depend on specific interest
(a list of relevant documents appears in the
Table of Contents of
.I "Documents for the P\s-2WB/UNIX\s0 Time-Sharing System\^" ).
.P
Items in Section
.I "N"
of the \fIP\s-2WB/UNIX\s0 User's Manual\fP
are referred to by
.I "name\^" "(N)."
.H 2 "Prerequisite Structure of Following Sections"
.DS 1
.in +15
.in +6
{2}
.if n \& |
.if t \&  |
.in -6
.if n \&   --------------------------
.if t \&    ---------------------------
.if t \    |        |    |     |      |      |
.if n \   |      |   |   |    |    |
  {3}    {6} {7} {9}  {10} {11}
.if n \\  / \\\\     \\\\ /
.if t \\  / \\\\       \\\\ /
{4} {5}   {8}
.in -15
.DE
.br
.H 1 "BASIC INFORMATION"
Don't do anything else until you have learned most of this section.
You must know how to log onto the system,
make your terminal work correctly,
enter and edit files,
and perform basic operations on directories and files.
.H 2 "PWB/UNIX User's Manual ++"
.BL "" 1
.LI
Read
.I Introduction
and
.I "How to Get Started."
.LI
Look through Section I
to become familiar
with command names.
.LI
Note the existence of the
.I "Table of Contents"
and of the
.I "Permuted Index."
.LE 1
Section I will be especially needed for reference use.
.H 2 "UNIX for Beginners ++"
.H 2 "A Tutorial Introduction to the UNIX Text Editor ++"
.H 2 "Advanced Editing on UNIX +"
.H 2 "PWB Papers from the Second International Conference on Software Engineering +"
Gives an overview of the Programmer's Workbench.
.H 2 "Things to Do"
.BL "" 1
.LI
Do all the exercises found in {2.2} and {2.3}, and maybe {2.4}.
.LI
Create a file named \*`\*pmail\*' in your login directory,*
.FS *
The directory you are in right after logging into the system.
.FE
so that other
people (such as system administrators) can send you mail.
This can be done by:
.DS 1
cp \ /dev/null \ \*pmail
.DE
.LI
If you want some sequence of commands
to be executed each time you log in,
create a file named \*`\*pprofile\*' in your login directory containing the commands
you want executed.
For more information, see
.I "Initialization"
in
.I "sh\^" "(I)."
.LI
Files in directory \*`/usr/news\*' contain recent information
on various topics.
To see what has been updated recently, type:
.DS 1
ls\ \ \-lt\ \ /usr/news
.DE
and then print any files that look interesting.
Other useful actions include:
.VL 36 \na 1
.LI "mail\ \ \*-f\ \ /usr/news/\*pmail"
gives recent history from primary
system mailbox.
.if n .bp
.LI "cat\ \ /usr/news/helpers"
gives contacts and telephone numbers for counseling,
file restorals,
trouble reporting,
and other services.
.LI "nroff\ \ \-mm\ \ /usr/news/roadmap"
prints current copy of this \*`roadmap.\*'
.LI "cat\ \ /usr/news/terminals"
gives recommendations on selection of computer terminals.
.LE 1
.LE 1
.H 2 "Manual Pages to Be Studied"
The following commands are described in Section I
of the \fIP\s-2WB/UNIX\s0 User's Manual,\fP and are used for creating,
editing, moving (i.e., renaming), and removing files:
.VL 21 \na 1
.LI "cat(I)"
concatenate and print files (no pagination).
.LI "chdir(I)"
change working (current) directory; a.k.a. \fIcd\fP\^(I).
.LI "cp(I)"
make a copy of an existing file.
.LI "ed(I)"
text editor.
.LI "ls(I)"
list a directory;
file names beginning with \*`\*p\*' are not listed
unless the \*`\-a\*' flag is used.
.LI "mkdir(I)"
make a (new) directory.
.LI "mv(I)"
move (rename) file.
.LI "pr(I)"
print files (paginated listings).
.LI "rm(I)"
remove (delete) file(s).
.LI "rmdir(I)"
remove directory(ies).
.LE 1
The following help you communicate with other users,
make proper use of different kinds of terminals,
and print manual pages \%on-line:
.VL 21 \na 1
.LI "login(I)"
sign on.
.LI "mail(I)"
send mail to other users; inspect mail from them,
or contents of the system mailbox.
.LI "man(I)"
print pages of \fIP\s-2WB/UNIX\s0 User's Manual.\fP
.LI "stty(I)"
set terminal options;
i.e., inform the system about the hardware characteristics
of your terminal.
.LI "tabs(I)"
set tab stops on your terminal.
.LI "terminals(VII)"
gives descriptions of commonly-used terminals.
.LI "who(I)"
print list of users currently logged in.
.LI "write(I)"
communicate with another (logged in) user.
.LE 1
.H 1 "BASIC TEXT PROCESSING AND DOCUMENT PREPARATION"
You should read this section if you want to
.I "use"
existing text processing tools to write letters,
memoranda, manuals, etc.
.H 2 "PWB/MM\*dProgrammer's Workbench Memorandum Macros ++"
This is a reference manual, and can be moderately heavy going for a beginner.
Try out some of the examples,
and stick close to the default options.
.H 2 "Typing Documents with PWB/MM ++"
A handy fold-out.
.H 2 "NROFF/TROFF User's Manual +"
Describes the text formatting language in great detail;
look at the \s-2REQUEST\s0 \s-2SUMMARY\s0,
but don't try to digest the whole manual on first reading.
.H 2 "Documentation Tools and Techniques +"
This overview of \s-2UNIX\s0 text processing
methods is one of
the papers from the Second International Conference on Software Engineering.
(See {2.5} above).
.H 2 "Manual Pages to Be Studied"
.VL 21 \na 1
.LI "mm(I)"
makes it easy to specify
standard options to \fInroff\fP\^(I).
.LI "nroff(I)"
read to see formatter option flags.
.LI "spell(I)"
identifies possible spelling errors.
.LI "tmac.name(VII)"
list of text-formatting macro packages.
.LI "typo(I)"
identifies possible typographical errors.
.LE 1
To obtain some special functions (e.g., reverse
paper
motion, subscripts, superscripts),
you must either indicate the terminal type to
.I "nroff"
or post-process
.I "nroff"
output through one of the following:
.VL 21 \na 1
.LI "450(I)"
newer Diablo printer terminals, such as the \s-2DASI\s0450, \s-2DIABLO\s0 1620, \s-2XEROX\s0 1700, etc.
.LI "col(I)"
terminals lacking physical reverse motion, such as the Texas Instrument 700 series.
.LI "gsi(I)"
older Diablo printer terminals, such as the \s-2GSI\s0300, \s-2DASI\s0300, \s-2DTC\s0300, etc.
.LI "hp(I)"
Hewlett-Packard 2640 terminals (\s-2HP\s02640A, \s-2HP\s02640B, \s-2HP\s02644A, \s-2HP\s02645A, etc.).
.LE 1
.H 1 "SPECIALIZED TEXT PROCESSING"
The tools listed in this section are of a more specialized nature than those
in {3}.
.H 2 "TBL\*dA Program to Format Tables +"
Great help in formatting tabular data
(see
.I "tbl\^" "(I))."
.H 2 "Typesetting Mathematics\*dUser's Guide (2nd Edition) +"
Read this if you need to produce mathematical equations.
It describes the use of the equation setting commands
.I "eqn\^" "(I)"
and
.I "neqn\^" "(I)."
.H 2 "A TROFF Tutorial"
An introduction to formatting text with the phototypesetter.
.H 2 "Manual Pages to Be Studied"
.VL 21 \na 1
.LI "diffmark(I)"
marks changes between versions of a file,
using output of
.I "diff\^" "(I)"
to produce \*`revision bars\*' in the right margin.
.LI "eqn(I)"
preprocessor for
mathematical equations (phototypesetter).
.LI "neqn(I)"
preprocessor for
mathematical equations (terminals).
.LI "tbl(I)"
preprocessor for
tabular data.
.LI "troff(I)"
formatter for phototypesetter.
.LE 1
.H 1 "ADVANCED TEXT PROCESSING"
You should read this section if you
need
to
.I "design"
your own package of formatting macros or
perform other actions beyond the capabilities of existing tools;
{3} is a prerequisite,
and familiarity with {4} is very helpful,
as is an experienced advisor.
It takes a great deal of effort to write a good package of
macros for general use.
Don't reinvent what you can borrow from an existing package
(such as \s-2PWB/MM\s0).
.H 2 "NROFF/TROFF User's Manual ++"
Look at this in detail and try
modifying the examples.
If you are going to use the phototypesetter,
do the same for \fIA T\s-2ROFF\s0 Tutorial\fP ({4.3} above).
.H 2 "Things to Do"
It is fairly easy to use the text formatters for simple purposes.
A typical application is that of writing simple macros that print
standard headings in order to eliminate repetitive
keying of such headings.
It is extremely difficult to set up general-purpose
macro packages for use by large numbers of people.
If possible, try to use an existing package or modify one as needed.
Look at existing packages first\*dsee
.I "tmac.name\^" "(VII)."
.H 2 "Manual Pages to Be Studied"
All pages mentioned in {3} and {4}.
.H 1 "COMMAND LANGUAGE (SHELL) PROGRAMMING"
The Shell provides a powerful programming language
for combining existing commands.
This section should be especially useful to those
who want to automate manual procedures
and build data bases.
.H 2 "The UNIX Time-Sharing System ++"
.H 2 "PWB/UNIX Shell Tutorial ++"
.H 2 "Things to Do"
If you want to create your own library of commands, create a \*`\*ppath\*'
file in your login directory, as described in
.I "sh\^" "(I)."
.H 2 "Manual Pages to Be Studied"
Read
.I "sh\^" "(I)"
first;
the following pages give further details on commands that are
most frequently used within command language programs:
.VL 21 \na 1
.LI "echo(I)"
echo arguments (typically to terminal).
.LI "equals(I)"
Shell assignment command (for variables).
.LI "exit(I)"
terminate command file.
.LI "expr(I)"
evaluate an algebraic expression.
.LI "fd2(I)"
redirect diagnostic output.
.LI "if(I)"
conditional command.
.LI "next(I)"
read command input from named file.
.LI "nohup(I)"
run a command immune to communications line hang-up.
.LI "onintr(I)"
handle interrupts in Shell files.
.LI "pump(I)"
Shell data transfer command.
.LI "sh(I)"
Shell (command interpreter).
.LI "shift(I)"
adjust Shell arguments.
.LI "switch(I)"
Shell multi-way branch command.
.LI "while(I)"
Shell iteration command.
.LE 1
.if t .bp
.H 1 "FILE MANIPULATION"
In addition to the basic commands of {2},
many \s-2UNIX\s0 commands exist to perform various kinds
of file manipulation.
Small data bases can often be managed quite simply,
by combining text processing (from {5}),
command language programming {6},
and commands listed below in {7.2}.
.H 2 "Things to Do"
This \*`roadmap\*' notes only the most frequently used commands.
It is wise to scan Section I of the \fIP\s-2WB/UNIX\s0 User's Manual\fP periodically\*dyou
will often discover new uses for commands.
.H 2 "Manual Pages to Be Studied"
The following are used to search or edit files in a single pass:
.VL 21 \na 1
.LI "grep(I)"
search a file for a pattern;
more powerful and specialized versions include
.I "egrep\^" "(I),"
.I "fgrep\^" "(I),"
and
.I "rgrep\^" "(I)."
.LI "sed(I)"
stream editor.
.LI "tr(I)"
transliterate (substitute or delete specified characters).
.LE 1
The following compare files in different ways:
.VL 21 \na 1
.LI "cmp(I)"
compare files (byte by byte).
.LI "comm(I)"
print lines common to two files, or lines that appear in only
one of the two files.
.LI "diff(I)"
differential file comparator (minimal editing for conversion).
.LE 1
The following combine files and/or split them apart:
.VL 21 \na 1
.LI "ar(I)"
archiver and library maintainer.
.LI "cpio(I)"
general file copying and archiving.
.LI "csplit(I)"
split file by context.
.LI "split(I)"
split file into chunks of specified size.
.LE 1
.in 0
These commands interrogate files and print information about them:
.VL 21 \na 1
.LI "file(I)"
determine file type (best guess).
.LI "od(I)"
octal dump (and other kinds also).
.LI "wc(I)"
word (and line) count.
.LE 1
Miscellaneous commands:
.VL 21 \na 1
.LI "find(I)"
search directory structure for specified kinds of files.
.LI "gath(I)"
gather real and virtual files;
alias for
.I "send\^" "(I)."
.LI "help(I)"
ask for help about a specific error message.
.LI "reform(I)"
reformat \*`tabbed\*' files (often used to truncate lines).
.LI "sort(I)"
sort or merge files.
.LI "tee(I)"
copy single input to several output files.
.LI "uniq(I)"
report repeated lines in a file, or obtain unique ones.
.LE 1
.H 1 "C PROGRAMMING"
Try to use existing tools first,
before writing \s-1\fBC\fP\s0 programs at all.
.H 2 "Programming in C\*dA Tutorial ++"
Read; try the examples.
.H 2 "C Reference Manual ++"
Terse but complete reference manual.
.H 2 "A New Input-Output Package +"
Describes a new I/O
package that is superseding many of the
existing routines;
write any new code using this package.
.H 2 "UNIX Programming +"
.H 2 "YACC\*dYet Another Compiler Compiler"
.H 2 "LEX\*dLexical Analyzer Generator"
.H 2 "Make\*dA Program for Maintaining Computer Programs"
.H 2 "Things to Do"
The best way to learn \s-1\fBC\fP\s0 is to look at the source code of existing
programs,
especially ones whose functions are well known to you.
Much code can be found in directory \*`/sys/source\*'.
In particular, directories \*`s1\*' and \*`s2\*' contain the source
for most of the commands.
Also, investigate directory \*`/usr/include\*'.
.H 2 "Manual Pages to Be Studied"
.VL 21 \na 1
.LI "adb(I)"
\s-1\fBC\fP\s0 debugger; more powerful (but more complex) than the older \fIcdb\fP\^(I).
.LI "cc(I)"
\s-1\fBC\fP\s0 compiler.
.LI "cdb(I)"
\s-1\fBC\fP\s0 debugger (for post-mortem core dumps and other debugging).
.LI "ld(I)"
loader (you must know about some of its flags).
.LI "lex(I)"
generate lexical analyzers.
.LI "make(I)"
automate program regeneration procedures.
.LI "nm(I)"
print name (i.e., symbol) list.
.LI "prof(I)"
display profile data (used for program optimization).
.LI "regcmp(I)"
compile regular expression.
.LI "strip(I)"
remove symbols and relocation bits from executable file.
.LI "time(I)"
time a command.
.LI "yacc(I)"
parser generator.
.LE 1
.H 1 "IBM REMOTE JOB ENTRY (RJE)"
This section is for those who use \s-2PWB/UNIX\s0 to submit jobs to
remote computers.
.H 2 "Guide to IBM Remote Job Entry for PWB/UNIX Users +"
.H 2 "Manual Pages to Be Studied"
.VL 21 \na 1
.LI "bfs(I)"
big file scanner (scans \s-2RJE\s0 output).
.LI "csplit(I)"
split file by context (often used to split \s-2RJE\s0 output).
.LI "fspec(V)"
format specification in text files.
.LI "reform(I)"
reformat files (often used to convert source programs from
non-\s-2UNIX\s0 systems).
.LI "rjestat(I)"
\s-2RJE\s0 status and enquiries.
.LI "send(I)"
submit \s-2RJE\s0 job.
.LE 1
.H 1 "SOURCE CODE CONTROL SYSTEM (SCCS)"
S\s-2CCS\s0 can be used to maintain, control, and identify
files of text as they are modified and updated.
Its most common use is for maintaining source programs,
as well as for keeping track of successive versions of various documents;
in combination with
.I "diffmark\^" "(I),"
this allows one to automatically generate \*`revision bars\*'
in successive editions of such documents.
.H 2 "SCCS/PWB User's Manual ++"
.H 2 "Manual Pages to Be Studied"
Of the following,
.I "get\^" "(I),"
.I "delta\^" "(I),"
and
.I "prt\^" "(I)"
are most frequently used.
.VL 21 \na 1
.LI "admin(I)"
administer \s-2SCCS\s0 files (including creation thereof).
.LI "chghist(I)"
change the history entry of an \s-2SCCS\s0 delta.
.LI "comb(I)"
combine \s-2SCCS\s0 deltas.
.LI "delta(I)"
make an \s-2SCCS\s0 delta (a permanent record of editing changes).
.LI "get(I)"
get a version of an \s-2SCCS\s0 file.
.LI "prt(I)"
print \s-2SCCS\s0 file.
.LI "rmdel(I)"
remove a delta from an \s-2SCCS\s0 file.
.LI "sccsdiff(I)"
get the differences between two \s-2SCCS\s0 deltas.
.LI "what(I)"
find and print \s-2SCCS\s0 identifications in files.
.LE 1
.if n .bp
.H 1 "NUMERICAL COMPUTATION"
.H 2 "DC\*dAn Interactive Desk Calculator"
.H 2 "BC\*dAn Arbitrary Precision Desk Calculator Language"
.H 2 "RATFOR\*dA Preprocessor for a Rational Fortran"
.H 2 "Manual Pages to Be Studied"
.VL 21 \na 1
.LI "bas(I)"
\s-2BASIC\s0 interpreter.
.LI "bc(I)"
interactive language,
acts as front end for
.I "dc\^" "(I)"
.LI "dc(I)"
desk calculator.
.LI "fc(I)"
Fortran compiler/interpreter.
.LI "rc(I)"
\s-2RATFOR\s0 preprocessor.
.LE 1
