.if n .pH scrn.chap3 @(#)chap3	40.2
.BK "Source Code Product Build Instructions"
.CH "Source Code Product Machine Readable Documentation" 3
.\"  Following source is directly from drp_mrd_rn/tape
.if n .pH drp_mrd_rn.tape @(#)tape	40.14 of 2/13/90
.\"  formerly drp_mrd_rn.chap2
.\" Copyright 1989 AT&T
.H 1 "Overview"
This chapter explains how to extract files containing documents and tools from the
Source Code Product Machine Readable Documentation
(SCP MRD) tape and install them on your system.
It begins by summarizing the contents of the SCP MRD tape
(``Contents of the SCP MRD Tape'') and
by listing stylistic infelicities
(``Style Exceptions'').
.P
Next, the section ``MRD Processing Instructions'' shows you how 
to take files off the tape and how to use the formatting tools.
The section ``Extracting Files From the Tape'' lists the documents included on this tape.
The section ``Installation Instructions'' explains how to install the DOCTOOLS software.
Special tips are given in the sections
``Memorandum Macros''
and
``PostScript\(rg Language and DOCTOOLS Software.''
The final section,
``Printing Books,''
explains how to print individual files and entire documents.
.H 2 "Contents of the SCP MRD Tape"
The source tape (6250 bpi) contains 23 documents in 23 directories:
.BL 
.LI
Source for the
.BT "Source Code Product Machine Readable Documentation Release Notes"
is in the \f4MRD\f1 directory.
.LI
Source for the
.BT "DOCTOOLS User's Guide"
is in the
.UI DOCTOOLS
directory,
which contains both software and documentation for DOCTOOLS.
.LI
Source for the remaining 21 documents are contained in 21 directories,
where each directory contains one document.
.LE
.P
Some manual pages appear in more than one document.
These pages are exact duplicates; they appear in more than one place
because they describe technology associated with more than one document.
For example, all manual pages for networking administration
appear in both the
.BT "System Administrator's Reference Manual"
and the
.BT "Network User's and Administrator's Guide" .
.P
The documents that have titles that end in
``(Manual Pages)''
have been extracted from guides,
as specified by the source code licensing agreement.
For information about obtaining the complete customer document set,
see the
.ST "Introduction"
of this document.
.P
Permuted indexes and tables of contents are not provided for these documents.
To learn where a manual page is located, see the
.CT "Master Permuted Index"
chapter in the
.BT "Product Overview and Master Index" .
To generate your own permuted indexes and tables of contents for these documents,
use the \f4-c\fP option to the \f4format\fP command as
described in the
.BT "DOCTOOLS User's Guide."
.H 2 "Style Exceptions"
The document set contains the following
stylistic inconsistencies, omissions, and quirks:
.BL
.LI
In Release 4, we converted the font used for literal I/O
to be a \f4constant-width\fP font.
(Literal I/O includes command and routine names, manual page names,
filenames, user input, computer output, and program examples.)
This font conversion was not completed for some documents.
.LI
Most manual pages can be \f4nroff\fPed with no loss of information.
The following pages require a terminal with graphical capabilities.
If you
.UI nroff
these pages, the illustrations do not print.
.BL
.LI
Some pages in the
.BT "Device Driver Interface/Driver\(enKernel Interface (DDI/DKI) Reference Manual"
contain pictures created using
.UI pic .
.LI
Most pages in the
.BT "Programmer's Guide:  OPEN LOOK\(tm Graphical User Interface"
contain PostScript\(rg language commands.
.LE
.LI
In some documents, the preface (``About This Document'')
contains a paragraph titled ``How to Comment on This Guide''
which refers to ``the card located after the title page.''
No comment card has been provided.
.LI
Some documents contain references to instructions for ordering documents,
but do not provide these instructions.
.LE
.H 1 "MRD Processing Instructions" 
The tape you have received contains source files for the SCP MRD for
UNIX System V Release 4.
.P
Instructions for preparing files for document production are given below.
These documents should be formatted only with DOCUMENTER'S WORKBENCH\*(Tm Software 
Release 2.0 and only with the macro packages which have been provided on the SCP MRD tape.
.AB N
Commands, options, files, and lines cited from either shell
procedures or document files described in these \f2Release Notes\fP
are given in a constant-width font.
Substitutable strings appear in \f2italics\fP.
(Substitutable strings are strings for which you are expected to provide a value,
such as \f2file\fP.)
.AC
.H 2 "Extracting Files from the Tape"
Some computer centers will read the tape into a directory you request.
Check with your center.
If it provides this service, find out what
information they need and let them copy the tape to your file system.
.AB N
If your computer center extracts the files for you,
advise them that in order to 
prevent a permissions problem with the directories being extracted,
before extracting the files
they should \f4su\fP to the login
of the person who will be doing steps 3 and on.
.AC
If it does not provide this service, the following procedure
explains how you can copy the MRD tape to your file system
after it has been mounted on your system's tape drive.
.AB N
This procedure tells how to copy the contents of
a magnetic tape
.I into
a UNIX system that you specify.
At most computer centers, tapes must be mounted by center personnel.
However, the transfer procedure (steps 3 to the end) can be executed
from your own terminal.
The contents of the tape are
transferred using the
.UI cpio
command.
.AC
.AL
.LI
Take
the tape to your computer center.
Tell them that you want to copy
\f2from\fP
the tape
\f2to\fP
the system you specify,
and that the tape was made using a density of 6250 bits per inch.
.sp.5
In the event of a delay before the tape can be
mounted, arrange to have them
call you when it is ready.
.LI
Ask for the device number of the tape drive they will be using.
.sp.5
Some typical device numbers are
.UI /dev/rmt0 ,
.UI /dev/rmt10 ,
and
.UI /dev/rmt11 .
The exact device number depends on your system's tape drive and
the tape density.
.LI
Log in to the system you specified.
.LI
You will need to know if there is enough free disk space on your
system to accommodate the MRD files.
.BL
.LI
Use the command
.UI pwd
to find out your file system name.
An example of a response to
.UI pwd
is
.UI /h1/d3775/mpf
and the part of this response that is the file system
name is
.UI /h1 .
.LI
Next, use the command
\f4df -f\fP \f2file_system_name\fP
to find out how many blocks of disk space are free.
Have someone who knows how many bytes are in each block for your system
convert this number into bytes.
.LE
.P
The MRD files need about 40 megabytes of disk space.
You can increase the amount of free disk space on your file
system by removing some unwanted files, and/or by ``packing''
infrequently used files
(see the
.BT "UNIX System V User's Reference Manual"
for details on the
.UI pack (1)
command).
.LI
Create a directory for the documentation set.
.LI
Change directory
to the directory just created.
.LI
Type
.DS I UI
cpio -icvmBd < \f2device_number\fP
.DE
For example, the actual command might be something like:
.DS I UI
cpio -icvmBd < /dev/rmt/0h
.DE
It may take from a few seconds to half an
hour to complete the transfer.
When all the files have been transferred, you will see the number of blocks
and your shell level prompt.
For example:
.DS I CO
234 blocks
$
.DE
.P
When \f4cpio\f1 has completed, you will find 
a \f4readme\f1 file and the directories 
.UI BSX ,
.UI CHAR ,
.UI DDRM ,
.UI DOCTOOLS ,
.UI FSTYPES ,
.UI KERNPORT ,
.UI MRD ,
.UI NI ,
.UI NUA ,
.UI OL ,
.UI POMI ,
.UI PRM ,
.UI SARM ,
.UI SCBI ,
.UI SN ,
.UI SS ,
.UI STRM ,
.UI TFMG ,
.UI URM ,
.UI X11 ,
.UI X11PORT ,
.UI XWIN ,
and
.UI XWINPORT
in your current directory.
.LE 
.H 3 "Verifying the Transferred Files"
To check that you have copied a complete set of files from the tape
to your file system, complete the following steps:
.AL
.LI
Type
the following command in the
directory into which you have copied the tape:
.DS I UI
find . -print > $HOME/\f2file1\fP
.DE
Where \f2file1\fP is a file that will be created by this command
in your login directory.
It will contain a list of all files in
the directory into which you copied the tape.
.LI
Type
.DS I UI
cpio -it < \f2device_number\fP > $HOME/\f2file2\fP
.DE
Where \f2file2\fP is a file that will be created by this command
in your login directory.
It will contain a list of all files on the MRD tape.
.LI
Type
.UI cd
to return to your login directory.
.LI
Edit
\f2file1\fP
and execute the following global substitution:
.DS I UI
1,$s/^\e.\e///
.DE
This removes the ``\f4./\fP'' prefixed
to all filenames by the
.UI find
command.
Save the file as changed, and exit your editor.
.LI
Type
.DS I UI
diff \f2file1\fP \f2file2\fP
.DE
There should be no differences between
the two files.
.P
If differences show up, you may have to have the files transferred again from
the tape.
.LI
After you have verified that all the files have successfully been
transferred from the tape,
call your computer center to tell them
you are done and that they can unmount your tape.
.LE
.H 3 "Directory Contents"
Table 2-1 below lists each directory extracted from the tape and the book it
contains.
See the chapter
.CT "Source Document Set Design"
for approximate page counts.
.TB "SCP Tape Directory Names by Book"
.TS H
expand ;
lf3w(0.75ii) lf3w(3.75i)
lf4 lf2.
Directory	Book
_	_
.sp .5
.TH
BSX	T{
BSD/XENIX\(rg Compatibility Guide (Manual Pages)
T}
.sp .5
CHAR	T{
Programmer's Guide:  Character User Interface (FMLI and ETI) (Manual Pages)
T}
.sp .5
DDRM	T{
Device Driver Interface / Driver\-Kernel Interface (DDI/DKI) Reference Manual
T}
.sp .5
DOCTOOLS	T{
\f1Source files for documentation tools and \f1DOCTOOLS User's Guide\f1
T}
.sp .5
FSTYPES	T{
Programmer's Guide:  Writing File System Types
T}
.sp .5
KERNPORT	T{
Programmer's Guide:  Porting the Kernel
T}
.sp .5
MRD	T{
Source Code Product Machine Readable Documentation Release Notes
T}
.sp .5
NI	T{
Programmer's Guide:  Networking Interfaces (Manual Pages)
T}
.sp .5
NUA	T{
Network User's and Administrator's Guide (Manual Pages)
T}
.sp .5
OL	T{
Programmer's Guide:  OPEN LOOK\(tm Graphical User Interface (Manual Pages)
T}
.sp .5
POMI	T{
Product Overview and Master Index
T}
.sp .5
PRM	T{
Programmer's Reference Manual
T}
.sp .5
SARM	T{
System Administrator's Reference Manual
T}
.sp .5
SCBI	T{
Source Code Build Instructions
T}
.sp .5
SN	T{
Software Notes
T}
.sp .5
SS	T{
Programmer's Guide:  System Services and Application Packaging Tools (Manual Pages)
T}
.sp .5
STRM	T{
Programmer's Guide:  STREAMS
T}
.sp .5
TFMG	T{
Technology/File Mapping Guide
T}
.sp .5
URM	T{
User's Reference Manual
T}
.sp .5
X11	T{
Programmer's Guide:  X11/NeWS\(rg Graphical Windowing System (Manual Pages)
T}
.sp .5
X11PORT	T{
Programmer's Guide:  Porting the X11/NeWS Server
T}
.sp .5
XWIN	T{
Programmer's Guide:  XWIN\*(Tm Graphical Windowing System (Manual Pages)
T}
.sp .5
XWINPORT	T{
Programmer's Guide:  Porting the XWIN Server
T}
.TE
.P 
Each directory contains a \f4COLFILE\f1 file.
\f4COLFILE\fP is a collection file that can be used to print an entire document.
(See the ``Printing Books'' section
at the end of this chapter for information on printing books from
these collection files.)
.H 2 "Installation Instructions"
To install this release of DOCTOOLS, follow the steps outlined
below.
.AL
.LI
Edit the 
.UI shells/defs.h.src
file to tell DOCTOOLS about your
local printers and other destinations.
Follow the examples in the file.
You will need to know how to send jobs to the printers
on your system to define the variables.  If you know
the command line syntax, such as:
.DS "" UI
tbl \f2file\fP | troff -Tpost -mm | dpost | lp -opost -dprinter1
.DE
you can edit
.UI defs.h.src.
If you do not know this information,
get the information from your system administrator.
.P
If you have a pre-1.0 release of DOCTOOLS, you can copy
your existing
.UI defs.h
to
.UI shells/defs.h.src.
Change any occurrences of
.UI MACH
to
.UI MACHINE .
Note, however, that some destinations included in
.UI defs.h.src
are meant to be location independent.
These are:
.VL 0.75i 0.5i
.LI proof UI
Proof files on a DMD terminal.
.LI null UI
Process files to check for errors or to generate tables of contents.
.LI post UI
Create PostScript language files.
.LI archive UI
Archive files with
.UI cpio .
.LE
You may need to make some minor adjustments to these
definitions to accommodate your local environment.
.LI
You may need to edit
.UI macros/macros.h.src .
This file contains the font specific information
and other tunable variables, like the print date that
appears at the bottom of manpages.
.AB N
Unlike
.UI defs.h.src ,
the
.UI macros.h.src
file is not compatible with
previous versions of DOCTOOLS.
.AC
The
.UI macros.h.src
file holds definitions, in the form
of
.UI troff
defined strings, for much of the typography
produced by DOCTOOLS.
You can change the definitions
to change the style created by the markup in the text
files, such as the fonts used for user input text,
computer output text, and program code text (see
the macros for
.UI \&.UI ,
.UI \&.CO ,
and
.UI \&.PC
in the user's guide).
Try using it as is.
If you have font related
errors, then edit
.UI macros.h.src
and reinstall.
.P
Follow the comments in the
.UI macros.h.src
file and make changes carefully.
.LI
You will need to set the variables described in
.UI Makefile .
.UI Makefile
contains the variables that set where the tools
are installed as well as set necessary variables
within some of the files themselves.
At a minimum, you need to name a bin directory
.UI (BINDIR)
where you want the executables kept, and a library directory
.UI (LIBDIR)
where you want the support files kept, such as the macro
files.
Follow the comments in
.UI Makefile .
.P
Once you have made these changes, type
.UI
make install
.SF
in this directory and watch for any error messages.
.LE
.H 3 "Memorandum Macros (MM)"
If you plan to print memoranda with DOCTOOLS,
copy or link your local memorandum macro file to
a file called
.UI mmt
in
.UI LIBDIR
(defined in
.UI Makefile ).
Make sure any sourced (\f4.so\f1) files in
.UI mmt
are also
in
.UI LIBDIR ,
or make sure that they can be successfully read
in from where they are kept.
.H 3 "PostScript\(rg Language and DOCTOOLS Software"
The Release 4 software tape includes a set of PostScript language tools
designed to work with DOCUMENTER'S WORKBENCH software,
including a
.UI troff
postprocessor called
.UI dpost .
Not only
is this a robust set of software that enhances
your PostScript language printing capabilities, but it includes
special features that DOCTOOLS takes advantage of.
One of these features allows you to use the
.UI \&.BP/.EP
macros described in Chapter 4 of the ``\%DOCTOOLS User's Guide.''
The 
.UI \&.BP
(Begin PostScript) and
.UI \&.EP
(End PostScript) macros
enable you to integrate PostScript language graphics files 
into your source text files.
Another feature allows DOCTOOLS to write PostScript language code to shade
the icons, screens, and hardkeys in your guide files.
.P
The PostScript language software is on your Release 4 
software tape in the
.UI /usr/src/cmd/lp/postscript
directory.
You will see references in some of the entries in the
.UI defs.h.src
file to 
.UI \-Tpost
and 
.UI dpost .
These entries
are designed to work with this PostScript language software.
.H 2 "Printing Books"
Once you have installed DOCTOOLS, you can print individual files by entering
.DS I UI
\f4format -d\f2printer\fP \f2file1\fP \f2file2\f1 . . .
.DE
To generate table-of-contents files, use the \f4-c\f1 option to \f4format\f1 and enter
.DS I UI
\f4format -c -d\f2printer\fP \f2file1\fP \f2file2\f1 . . .
.DE
The \f4-c\f1 option creates files in the form of
\f4C\f2file\f1.
These files include
table-of-contents information as well as indexing information.
.H 3 "Printing from Collection Files"
.AB C
Before you attempt to use a collection file, make sure you can
process more than a single file at a time, and that you really want to print
all the files listed in the provided collection file.  Where appropriate,
collection files include table-of-contents and indexes,
which list page numbers that may not be correct when you
format the guide files locally.
For page numbers to be accurate in your printing environment, you may need
to generate the table-of-contents files and index files locally.
This can be done as described above with the \f4-c\fP option.
See the
.BT "DOCTOOLS User's Guide"
for a complete description
of collection files and how to use them, as well as more information
on how to create table-of-contents files and index files.
.AC
Once you have verified that the tools for printing are functioning,
you can try to print an entire book in a single step.
This is done by using a collection file (named \f4COLFILE\fP)
to list all the files that make up a book
in printing order.
For example, here is the collection file for the
.BT "DOCTOOLS User's Guide" :
.DS I UI
\&.# This book ("DOCTOOLS User's Guide")
\&.# contains the following files,
\&.# listed in the order in which they are printed.
\&.# Next to each file name is its SCCS delta number.
\&.FT
MasterToc	1.2
Cchap1		1.2
chap1		1.6
Cchap2		1.2
chap2		1.6
Cchap3		1.2
chap3		1.6
Cchap4		1.2
chap4		1.6
Cchap5		1.2
chap5		1.6
Cchap6		1.2
chap6		1.2
Cindex		1.1
index		1.1
checkmacs.1	1.4
deltamacs.1	1.4
format.1	1.6
index.1		1.2
Crefcard	1.3
refcard		1.10
.DE
To use this collection file to print the entire
.BT "DOCTOOLS User's Guide,"
enter
.DS I UI
\f4cd DOCTOOLS/docs
format -d\f2printer\fP COLFILE
.DE
You may print individual files listed in \f4COLFILE\fP
by entering:
.DS I UI
format -d\f2printer file
.DE
.H 3 "Printing the MRD Release Notes"
The 
.BT "Source Code Product Machine Readable Documentation Release Notes"
describes the document set, tools, and each book in detail.
To print the
.BT "Release Notes,"
take the following steps:
.AL
.LI
Enter
.DS I UI
\f4cd MRD\fP
.DE
.LI
Now, either print the entire contents of \f4COLFILE\fP
by entering:
.DS I UI
format -d\f2printer\fP COLFILE
.DE
or print individual files listed in \f4COLFILE\fP
by entering:
.DS I UI
format -d\f2printer file
.DE
.LE
