beta.mex

操作系统SunOS 4.1.3版本的源码

.LS 4
cd /usr/src/man
vi Printfile
.LE
Redefine
.L DESTHOST
to be the name of your doctools host.
Redefine
.L DESTDIR
to be the name of the directory in which you want to put the sources.
.LP
Do the remote copy:
.LS 4
make pinstall
.LE
This should have worked,
but just to be sure,
perform one more sanity check.
On the release machine:
.LS 4
cd CLONEDIR
du
.LE
On your doctools host:
.LS 4
cd DESTDIR
du
.LE
Do the sources in both directories occupy the same amount of storage?
.LP
There's one last check you need to make before you pring the manual.
You need to run
.L checknr
on all the source files:
.LS 4
make checknr
.LE
This will give warnings about dubious
.L troff
instructions.
Most of the source files should generate relatively few warnings,
and many of the warnings will not,
in fact,
indicate errors.
You should soon get a feel for which warnings need to be investigated.
Keep a list of files to investigate,
and make any necessary fixes.
When you're satified with these fixes,
you're finally ready to start printing the manual!
.H C "Printing the Manual"
.H 2 "Preparation"
.LP
Start by making each section of the manual a single document
by concatenating the pages in each section:
.LS 4
cd DESTDIR
make man
.LE
This target will generate files called
.L .man . \fIsection\fP
.LP
Generate PostScript images of these files:
.LS 4
make PS
.LE
This target will generate files called
.L .PS . \fIsection\fP
These are the files that will actually be printed.
The
.L PS
target will also generate the pagination file
.L pag.PS .
.H 2 "Verify the Pagination"
.LP
The pagination sheets consist of diagrams of each page of the manual.
Each sheet contains eighty to ninety small page diagrams.
A page number appears on each diagram,
and man page names appear on diagrams
that mark the beginnings of man pages.
.LP
Print
.L pag.PS :
.LS 4
lpr pag.PS
.LE
Review the printed copy very, very carefully!
Check for pages out of order (especially in section 3),
missing and duplicate pages,
and bad page numbering.
Make sure,
too,
that when a section ends on an odd page number,
there is a blank,
even-numbered page immediately following it.
.LP
Draw a diagonal slash through the page diagrams corresponding
to blank pages.
Circle the page numbers on the diagrams of pages
on which no page number should be printed.
.LP
Note:
There will be more than enough page diagrams at the end of the
pagination sheet to account for the index.
After you print the index,
and decide that it's correct,
go through and mark the page numbers on all the index page diagrams.
This is tiring,
but important.
You can then cross out the remaining page diagrams at the end.
.LP
If you find pagination problems,
you're going to have to fix them and 
backtrack enough steps to recover the errors.
This is frustrating and thoroughly unpleasant,
especially if you have to reprint entire sections.
.H 2 "Print Manual Sections"
.LP
Once you've ironed out the pagination problems,
you're at last ready to start printing.
A good strategy is to print the smaller sections first,
so that major errors can be caught before much printing has
been done:
.LS 4
lpr -s -P\fIprinter\fP \fIsection\fP.PS
.LE
Leaf through the printed copy and put yellow stickies
on pages which contain errors.
Especially important are errors which affect pagination,
such as bad page breaks,
bad size changes which alter vertical spacing
and incomplete pages.
Note any other technical or formatting errors as well.
.LP
Fix errors which affect pagination first,
and then make any other fixes you think necessary.
.LP
Note:
Edit the clones when you make fixes!
Do not work on the release machine!
.LP
If you've found pagination problems,
you'll have to redo some steps.
.LP
Note:
A pagination botch in one section will affect all subsequent sections.
In this case,
a major reprint is unavoidable.
.H 2 "Make Patches"
.LP
In the case of errors which don't affect pagination,
it's possible to replace the bad pages with patches,
instead of reprinting the whole manual.
After you've made all the fixes you find necessary,
you can write shell scripts to generate the patch pages
for each section and to number them correctly:
.LS 4
cd DESTDIR
vi \fIsection\fP.sh
.LE
Use this template to write your script:
.LS 4
#! /bin/sh
t() {
tbl $1 | troff -msunman -rC1 -rD1 -rP$2
}
t \fIpatchpage\fP \fIpagenumber\fP
.LE
.I patchpage
is the name of the source file for the man page you want
to reprint and
.I pagenumber
is the number given to the first page of
.I patchpage .
Include an invocation of the shell function
.L t
for each of the man pages in
.I section
you want to reprint.
Now run the script:
.LS 4
cd man\fIsection\fP
sh ../\fIsection\fP.sh
.LE
Write and run this script for each of the sections
in which you have pages to patch.
.H 2 "Fold in the Patch Pages"
.LP
Once you've printed all your patch pages,
you'll need to fold them into the manual.
Replace the stickied pages with their patches.
Double-check to make sure the page numbering is correct!
Watch for errors.
(You may have to patch the patches!)
Remember to insert blank sheets at the ends of sections
which end on odd-numbered pages.
Write page numbers in blue pencil on these blank sheets,
and insert colored sheets where tabs will go in the finished manual.
.LP
Don't forget to print the index!
.LS 4
lpr -s -P\fIprinter\fP index.PS
.LE
Review the printed copy of the index and sticky any unnacceptable
errors.
.H 2 "A Final Review"
.LP
By now,
you should be looking at an enormous pile of paper.
You need to one last major sanity check.
Yes,
you guessed it.
Leaf through the entire manual.
Verify that the page numbering correlates with the pagination
sheet.
Check page ordering and completeness.
Keep an eye out for greivous errors,
and put stickies on them.
.H 2 "More Patches"
.LP
When you've gone through the entire document,
print any final patches you think necessary,
and fold them in.
Again,
be careful about page numbering.
.H 2 "Print the Cover Sheet"
.LP
Now all your manual needs is a cover sheet.
.LS 4
cd DESTDIR
vi cover.mex
.LE
You need to update the part number and dash level,
the revision level and the revision date.
The dash level is 01 for an alpha release,
greater than 01 and less than 10 for a beta release
and 10 for an
.SM FCS
release.
.LP
Nobody knows why.
.LP
The revision level is 1 for an alpha release,
51 for a beta release
and A for an
.SM FCS
release.
.LP
Nobody knows why.
.LP
Print the cover sheet:
.LS 4
troff -Tlw -mex cover.mex
.LE
.H 2 "Deliver the Document"
.LP
You are now ready to send the hellish thing out the door.
Stack the manual neatly in a box,
section by section.
Check the page numbers at the beginnings and ends of sections
against the pagination sheet.
Review the pagination sheet itself for completeness and order.
Do the printer a favor:
Number the pages of the pagination sheet,
put a paper clip on them,
and put them in the box on top of the document.
.LP
Deliver it to the production department.
Now it's their problem!
.LP
.H C "Final Housekeeping"
.LP
I hate to tell you this,
but you're not finished yet.
Yes,
there's some final housekeeping still left to do.
.H 2 "Move Changed Pages Back to the Release Machine"
.LP
You've undoubtedly made changes to some of the pages since
you cloned the sources.
Now you have to move them back to the release machine.
.H 2 "Make Lists of Pages Changed Since the Clone"
.LP
The first step in this is to make lists of pages changed
since the clone and put them in files called
.L Mutantclones \fIsection\fP:
.LS 4
cd man\fIsection\fP
ls -lt > Mutantclones\fIsection\fP
vi Mutantclones\fIsection\fP
.LE
Delete
.L Mutantclones \fIsection\fP
itself from the list.
Find the start of that part of
the list bearing the date of the clone.
Delete these and all entries below it:
.LS 4
dG
.LE
Now,
in order to strip away all but
the desired filename from the file,
type
.LS 4
:%s/.*[0-9][0-9] //
.LE
Sort the list.
position the cursor on the first line of the file and
type:
.LS 4
!G
.LE
At the prompt,
type
.LS 4
sort
.LE
followed by
.SM RETURN .
Review the list visually to make sure there are no spurious entries.
.LP
Generate such a list for each section.
.H 2 "Copy the Lists to the Release Machine"
.LP
Now you need to copy these lists to the release machine:
.LS 4
cd DESTDIR
foreach i (1 2 3 4 5 6 7 8)
cd man$i
rcp Mutantclones$i \fIrelease-machine\fP:/tmp
cd ..
end
.LE
.H 2 "\fLsid\fP"
.LP
Now use
.L sid
to fix the
.SM SCCS
id lines:
.LS 4
foreach i (1 2 3 4 5 6 7 8)
cd man$i
sid `cat Mutantclones$i`
cd ..
end
.LE
Verify this process:
.LS 4
foreach i (1 2 3 4 5 6 7 8)
cd man$i
grep 'SMI' * | more
cd ..
end
.LE
If you still see any bad
.SM SCCS
id lines,
.L vi
the offending files and fix them.
.H 2 "Check out the Files Modified Since the Clone"
.LP
Now you need to go to the release machine
and check out all the files that have been modified since the
clone:
.LS 4
cd /usr/src/man
foreach i (1 2 3 4 5 6 7 8)
cd man$i
sccs edit -s `cat /tmp/Mutantclones$i`
cd ..
end
.LE
.H 2 "Copy the Files from Your Doctools Host"
.LP
Now you're ready to copy the files back.
Return to your doctools host:
.LS 4
foreach i (1 2 3 4 5 6 7 8)
cd man$i
rcp * \fIrelease-machine\fP:/usr/src/man/man$i
cd ..
end
.LE
After a remote copy of that magnitude
you need to do a sanity check.
Go back to the release machine.
For each of the files you copied,
display the number of lines of difference between
your modified copy of a file and the version of the file
which you originally cloned:
.LS 4
foreach i ( 1 2 3 4 5 6 7 8 )
cd man$i
foreach j (`cat /tmp/Mutantclones$i`)
echo -n "$j   " >>! /tmp/diffs.list
sccs diffs $j | wc -l >>! /tmp/diffs.list
end
cd ..
end
.LE
If there are less than five lines of difference,
you should investigate.
It's possible that the changes you made didn't get copied correctly.
If there are more than one hundred lines of difference,
you're probably missing something.
Investigate in this case, too.
You may have to try copying a file again,
or you may have to reconstruct your changes.
.H 2 "Check the Files In"
.LP
If you're satisfied that the copy was successful,
you're ready to check the files in:
.LS 4
cd /usr/src/man
foreach i (1 2 3 4 5 6 7 8)
cd man$i
sccs delget -s -y"\fIcomment\fP" `cat /tmp/Mutantclones$i`
cd ..
end
.LE
.I comment
should probably indicate that the modifications you made were
last-minute changes for the build.
.LP
One more sanity check:
.LS 4
cd man\fIsection\fP
sccs tell
.LE
If there's anything left checked out,
investigate and fix it.
Do this in each section.
.H 2 "Test \fLcatman\fP"
.LP
There's one final test you have to do.
You need to run some tests to assure that
.L catman
will work properly.
.LP
.L catman
produces formatted versions of the man pages
("cat files")
that take up space.
During testing,
though,
there's no need to do that time-consuming formatting.
You can trick catman into generating dummy cat files
that won't take up much space and will be easy to clean up.
.H 2 "Create \fLcat\fP\fIsection\fP Directories"
.LP
Create
.L cat \fIsection\fP
directories in
.L /usr/src/man ,
create a test directory,
and make symbolic links from the
.L cat \fIsection\fP
directories to your test directory:
.LS 4
cd /usr/src/man
mkdir cat1 cat2 cat3 cat4 cat5 cat6 cat7 cat8 
mkdir /tmp/cat
foreach i (1 2 3 4 5 6 7 8)
ln -s /tmp/cat cat$i
end
.LE
.H 2 "\fLNroff\fP"
.LP
There should be a file called
.L Nroff
in
.L /usr/src/man/bin.
It should consist of one line:
.LS 4
head -1 $2
.LE
.H 2 "Run \fLcatman\fP"
.LP
You can trick
.L catman
into using this
script instead of the usual
.L nroff :
.LS 4
cd /usr/src/man/bin
mv Nroff nroff
catman
.LE
Note:
You may have to adjust the argument number
.L $2 ) (
if you get this error message:
.LS 4
Bad number format
.LE
If you get errors from
.L catman ,
.L "sccs get"
the offending files,
and try again.
.LP
.L catman
should in all likelihood give error messages only about bad
.L .so
references.
These are usually references to files the names of which have
been changed.
These should be easy to fix.
Other,
more cryptical error messages may take some investigating.
.H 2 "Test \fLwhatis\fP"
.LP
You still need to run
.L catman
once more,
to test the
.L whatis
database:
.LS 4
catman -w
more /usr/man/whatis
.LE
The bad entries should appear at the top.
They indicate problems with the
.SM NAME
lines of certain pages.
It should usually be apparent which files are the sources of the dreck.
.L vi
these files and fix those 
.SM NAME
lines!
.H 2 "Cleanup"
.LP
When you're finally satisfied that
.L catman
will work properly,
clean up after yourself:
.LS 4
cd /usr/src/man/bin
mv nroff Nroff
cd ..
rm cat?
rm -r /tmp/cat
.LE
.H 2 "Recover"
.LP
Now,
you are well and truly finished with the build.
.LP
Follow these final instructions very carefully:
.LP
.SM "LEAVE THE OFFICE" !
Go out and indulge wholeheartedly in your favorite vice.
Sleep late tomorrow.
Repeat for a week.