beta.mex

操作系统SunOS 4.1.3版本的源码

may prove prohibitively cumbersome.
In this case,
just
.L vi
the file
to review your changes.
.LP
When you've finished,
and you're satisfied that you prefer the merged versions,
you need to move them onto the files in
.L index.pages:
.LS 4
cd \fIyour-home-directory\fP/index.pages
mv pages.merged/*.[1-8]* .
.LE
.H C "Updating the Index \(em Phase Two"
.H 2 "Using the \fL.IX\fP Macro"
.LP
The usage of the
.SM \fL.IX\fP
macro is as follows:
.LS 4
\&.IX "\fI1st-index-term\fP" "\fI2nd-index-term\fP" "\fIformat-of-1st\fP" "\fIformat-of-2nd\fP"
.LE
The first argument,
.I 1st-index-term ,
is the unformatted primary index term
and specifies where the entry will appear in the index.
The second argument,
.I 2nd-index-term ,
is the unformatted secondary index term and
will appear as a subentry in the index under
.I 1st-index-term .
The third argument,
.I format-of-first ,
specifies how
.I 1st-index-term
should be formatted in the index.
And the fourth argument,
.I format-of-second ,
specifies how
.I 2nd-index-term
should be formatted in the index.
.I format-of-first .
and
.I format-of-second
should be similar enough to
.I 1st-index-term
and
.I 2nd-index-term ,
respectively,
to ensure that the entries will appear in the right
places in the index!
.H 2 "Review \fLtrial.index\fP"
.LP
The next step in the indexing process is to
compare the trial index you have just generated
with the extant manual index.
Print out
.L trial.index :
.LS 4
lpr -n trial.index
.LE
Look over the printed copy and mark any ghastly
errors that you find.  Look specifically for
primary entries with only one secondary entry,
entries out of order,
formatting errors,
misleading or confusing entries and typos.
A primary entry that has only one secondary entry
in the trial index may well have several in the extant
index.
That is,
it may not be a problem.
Be sure to check for this.
.LP
It is sometimes difficult to determine the page on
which problem entries are indexed.
You may just have to make a few guesses until
you find the right pages.
.L grep "" (
is your friend.)
Usually,
though,
the name of the page in which a particular index entry occurs will appear
in the entry itself.
.H 2 "Fix the Bad Index Entries"
.LP
Now that you've identified the bad entries,
.L vi
the offending files and fix them.
Indexing can best be described as a black art,
and the best way to learn it is to learn by
example.
Look at the sources for the current release of the man pages
and see how indexing is done there,
and when in doubt,
ask someone about it.
.H 2 "Index the New Pages"
.LP
Once you've fixed the bad index entries,
you need to generate index entries for the
pages that have been added since the last release.
Many of these pages will not have been indexed at all,
and many others may have been indexed incorrectly.
Recall that
.L FILES.add
contains a list of added pages in each section:
.LS 4
cd /usr/src/man/man\fIsection\fP
vi `cat FILES.add`
.LE
In generating index entries,
try making each name listed in the
.SM NAME
line a primary entry,
checking frequently with the extant index for precedents,
rotating the NAME line to generate primary entries,
looking at
.SM "SEE ALSO"
entries to help indentify groups of related pages,
borrowing and modifying secondaries form other pages in such groups,
and converting new entries to secondaries when they belong logically
to some existing primary.
Remember,
it'll take some practice to get good at this.
.H 2 "Merge in the Indexing Changes"
.LP
Once you've satisfied yourself that the new pages are adequately
indexed,
you'll need to confirm the changes you've made and check the
new pages in on the release machine.
Use
.L filemerge
just as you did for the formatting fixes.
(See the chapter on reviewing page formatting.)
.LP
Now go to the release machine:
.LS 4
cd /usr/src/man
.LE
Check out the files in question:
.LS 4
foreach i (man[1-8])
cd$i
sccs edit `cat FILES.index`
cd ..
end
.LE
Copy the merged sources from your machine onto the sources on the
release machine:
.LS 4
foreach i (1 2 3 4 5 6 7 8)
cd man$i
rcp \fIyour-machine\fP:\fIyour-homedir\fP/index.pages/*.$i* .
cd ..
end
.LE
Check these copies in:
.LS 4
foreach i (man[1-8])
cd $i
sccs delget -y"indexing fixes for \fIrelease\fP" `cat FILES.index`
cd ..
end
.LE
.H C "Updating Makefiles and Printfiles"
.LP
You're now nearly ready to clone the sources and print the document,
but in order to do that,
you'll need to update the Makefiles and Printfiles.
The Makefiles will go on the release tape,
and the Printfiles will be used to generate the hard copy of the manual.
.H 2 "\fLmake update\fP"
.LP
Go to the release machine:
.LS 4
cd /usr/src/man
make update
.LE
This will append lists of pages deleted from and added to each section
to the Makefile and Printfile in each section.
.H 2 "Edit the Makefiles"
.LP
Now edit the Makefiles:
.LS 4
cd /usr/src/man/man\fIsection\fP
vi Makefile
.LE
Check the deletion and insertion lists for any obvious errors.
Delete all filenames ending with
.L .eqn
from these lists.
.L .eqn
files do not ship on the release tape.
Position the cursor on the first line of the
.L FILES
list definition.
You need to break the list out so that there's one filename per line:
.LS 4
!}
.LE
At the prompt,
type:
.LS 4
make show
.LE
Now go through the expanded
.L FILES
list and delete those filenames which appear
in the delete list.
You can do this by hand,
since the delete list won't ordinarily be large.
Be sure to keep a record of the deleted pages!
.LP
When you've made the deletes and noted them down,
delete the delete list and position the cursor on the first
line of the insert list.
Remove the comment characters and the extra spaces:
.LS 4
:.,$s/# //
.LE
Now you need to add the insert list to the
.L FILES
list.
Again position the cursor on the first line of the insert list.
Delete the list:
.LS 4
dG
.LE
Position the cursor on the line
.L "FILES= \e" ''. ``
.L "FILES= \e" '' (``
should be by itself on a line.)
Now get the list from the delete buffer and insert it at the top
of the
.L FILES
list:
.LS 4
p
.LE
Now position the cursor on the first line following the line
.L "FILES= \e" ''. ``
Sort and repack the
.L FILES
list and append a backslash
.L \e ) (
to each
line:
.LS 4
!}
.LE
At the prompt,
type:
.LS 4
sort -u | fmt | sed 's/$/ \e\e/'
.LE
There will be a backslash at the end of the last line.
Delete it.
.LP
Repeat the above in the Makefile for each section.
.H 2 "Review the Makefiles"
.LP
In each section,
review the changes you've made:
.LS 4
make show | more
.LE
Does the list look right?
.H 2 "Edit the Printfiles"
.LP
Now edit the Printfiles,
doing just as you did in the Makefiles,
with the following exceptions:
.LP
Do not delete the
.L .eqn
files from the list.
You'll need them to print the manual.
Instead,
delete all
.L . \fIsection\fP
files
that correspond to
.L .eqn
files.
.LP
Delete all the
files containing
.L .so
requests.
If you're not sure whether a file contains
.L .so
requests,
you'll just have to look at it to find out.
A little experience will make these identifications easier.
.LP
Finally,
when dealing with the Printfiles,
use
.LS 4
make showprint
.LE
instead of
.L "make show"
in all sections but Section 3.
In section 3, for each of the subsections (3, 3L, 3M, 3R and 3V):
.LS 4
!}
.LE
At the prompt,
type:
.LS 4
tr ' ' '\e012' | sed '/\e\e/d'
.LE
.LP
Note:
.L List. \fIsection\fP
does not appear in the
.L FILES
lists in the Printfiles.
This is as it should be.
.H 2 "Review the Printfiles"
.LP
When you've edited the Printfiles,
review them:
.LS 4
make showprint | more
.LE
.H 2 "Compare the Makefiles and Printfiles"
.LP
For a last sanity check,
compare the
.L FILES
lists in the Makefiles and Printfiles.
.LS 4
cd /usr/src/man/man\fIsection\fP
.LE
Create a file called
.L Print.list
containing
.L showprint
output:
.LS 4
make showprint > Print.list
.LE
Compare the contents of
.L Print.list
with the output of
.L "make show" :
.LS 4
make show | comm -3 Print.list - | more
.LE
All you should see is
.L .so
files in the right column
(pages in the
.L Makefile
list,
but not in the
.L Printfile
list).
and
.L .eqn
files in the left column
(pages in the
.L Printfile
list
but not in the
.L Makefile
list).
Investigate any other files that appear,
since they're either extraneous
or are missing from one of the lists.
.LP
Repeat this check for all sections.
.H 2 "Check in the Makefiles and Printfiles"
.LP
Once you've satisfied yourself that the Makefiles and Printfiles are
correct,
check them in on the release machine:
.LS 4
foreach i (man[1-8])
cd $i
sccs delget -y"updated FILES list for \fIrelease\fP" Makefile Printfile
cd ..
end
.LE
.H C "Cloning the Sources"
.LP
Now you're ready to clone the sources.
Check to see if there are any files still checked out:
.LS 4
cd /usr/src/man
ls man?/SCCS/p*
.LE
If you find any such file,
you'll have to force the owner off the file.
This is serious matter!
.LP
Go to the
.L man\fIsection\fP
directory that contains the errant file,
and save the file to the archive:
.LS 4
cd man\fIsection\fP
mv \fIerrant-file\fP ../arch/\fIerrant-file\fP.\fIowner\fP
.LE
Now you need to remove the
.L p.
file from the
.SM SCCS
directory:
.LS 4
rm SCCS/p.\fIerrant-file\fP
.LE
When you do this,
mail the release engineer and the owner of the file
that you have done so!
.H 2 "\fLmake clean\fP"
.LP
Once you're very sure that all the files are under
.SM SCCS
and are all checked in,
Remove all the extant versions of the files before
you extract just the printable versions from
.SM SCCS .
This is just to make verification easier.
.LS 4
cd /usr/src/man
make clean
.LE
Now examine all the sections.
.LS 4
cd man\fIsection\fP
.LE
Investigate any files you find still lying around,
as you may need to
.L "sccs create"
them.
.LP
There should be nothing left in the
.L man \fIsection\fP
directories but the
.SM SCCS
subdirectories.
.LP
Note:
When you find a file that's been sneaked in after the freeze date,
make sure that it's under
.SM SCCS
before you do a
.L "make clean" !
.H 2 "Retrieve Only the Printable Sources"
.LP
Now retrieve only the printable sources from
.SM SCCS :
.LS 4
cd /usr/src/man
make -f Printfile all
.LE
.H 2 "Make a Local Copy on the Release Machine"
.LP
The actual cloning of the sources will happen in two steps.
First,
make a local copy of the sources on the release machine.
.LS 4
cd /usr/src/man
.LE
Find out how much storage the sources require:
.LS 4
du
.LE
This command will display filesystem usage in k-bytes for the
current directory and its subdirectories.
.LP
Find a filesystem partition with enough free space to hold the sources
comfortably:
.LS 4
df
.LE
This command will display (among other things) available storage on each
mounted filesystem and the directories on which those filesystems
are mounted.
.LP
Find a directory with enough room in it,
and create a subdirectory there called
.L man :
.LS 4
cd \fIdirectorywithenoughroominit\fP
mkdir man
.LE
You now need to edit
.L Printfile
and redefine the
.L CLONEDIR
macro:
.LS 4
cd /usr/src/man
vi Printfile
.LE
Redefine
.L CLONEDIR
to be
.LS 4
\fIdirectorywithenoughroominit\fP/man
.LE
Next, execute the
.L clone
target in
.L Printfile .
Preview the actions of this target:
.LS 4
make -nf Printfile clone
.LE
This displays what the
.L clone
target will do.
Look it over carefully.
If it's correct,
execute
.L clone :
.LS 4
make -f Printfile clone
.LE
Verify this copy by looking through
.L CLONEDIR .
.LP
Once you're satisfied that the copy was successful,
restore the online sources 
.L .so "" (
files) so that people who mount the
man pages from the release machine won't get nasty messages when
they invoke
.L man :
.LS 4
cd /usr/src/man
make all
.LE
Before doing the second step,
make some general sanity checks:
.LS 4
cd CLONEDIR
.LE
Are all the Printfiles there?:
.LS 4
ls man?/Printfile
.LE
.H 2 "Make a Remote Copy to Your Doctools Host"
.LP
Now you're ready to copy the sources from
.L CLONEDIR
to your doctools host.
Edit the Printfile on the release machine and redefine the
.L DESTHOST
and
.L DESTDIR
macros: