beta.mex

操作系统SunOS 4.1.3版本的源码

.PL RIGHT
.UH M "Introduction"
.LP
This document outlines in detail the procedure for building a beta release
of the SunOS Reference Manual,
more commonly known as the
``man pages''.
It is intended to be followed step by step from beginning to end,
although it's a good idea to familiarize yourself somewhat with this
document before you start the build.
.LP
The procedure outlined here applies to a standard beta release of
the man pages.
Thus,
there may be problems specific to your build that
are not addressed in this document.
It's therefore a good idea to know someone whom you can consult
when problems arise.
Building the man pages is a long,
intricate,
tiring and often frustrating process,
which contains many potential pitfalls.
It's important,
therefore,
that you adhere strictly to the procedure
outlined here.
.UH S \fBOverview\fP
.LP
First, set up all the online sources (the
.L .so
files)
so that the
.L man
command will work as expected (chapter one).
Next,
update the
.L List
pages found at the end of the
.L Intro
page of each of the eight manual sections (chapter two).
Then,
update the index and review
formatting (chapters three, four and five).
After that,
you'll update the Makefiles,
used in setting up the online sources,
and the Printfiles,
used in printing the manual (chapter six),
after which,
you'll clone the manual sources from the release machine
to your doctools host (chapter seven),
and print the manual (chapter eight).
Finally,
there will be some housekeeping for you to do,
including moving back any sources that you've changed since
the clone,
and testing the
.L catman
command (chapter nine).
.LP
It may not sound difficult,
but it is.
Good luck.
.H C "Setting Up \fL.so\fP Files"
.LP
In order to set up the correct
.L .so
references and to update the List pages
for each of the manual sections,
you'll need to compile lists of man
pages that have been added and deleted
since the last release.
.H 2 "Get Lists of Pages as of the Last Release"
.LP
.L cd
to the
.L man
directory on the release machine
(typically
.L /usr/src/man ).
Once there, you'll need to reconstruct the list of old
entries from the Makefile used in the last release,
so you can compare it with a current list of
files under
.SM SCCS :
.LS 4
sccs prt Makefile | more
.LE
This displays a version history for
.L Makefile .
One of the history list entries should
be the version used in the last major release
or build.
Retrieve this version from
.SM SCCS
and put it
in
.L Makefile.old :
.LS 4
sccs get -GMakefile.old -r\fIversion\fP Makefile
.LE
You can now extract the list of files from
.L Makefile.old
and put it in
.L FILES.old :
.LS 4
make -fMakefile.old show | sort -u > FILES.old
vi FILES.old
.LE
Eliminate filenames
that aren't, in fact, man pages.
.H 2 "Get Current Lists of Pages"
.LP
Now generate and sort a list of new manual entries
and put it in
.L FILES.new :
.LS 4
ls SCCS/s.* | sed 's/SCCS\e/s\e.//' | sort -u > FILES.new
vi FILES.new
.LE
Again,
remove any entries that aren't man pages.
.H 2 "Get Lists of Pages Added and Deleted Since the Last Release"
.LP
You can now use:
.LS 4
comm -3 FILES.old FILES.new
.LE
which will display two columns on the screen.
The left hand column lists entries found in
.L FILES.old
but not in 
.L FILES.new
(deletions)
and the right hand column lists entries found in 
.L FILES.new
but not in 
.L FILES.old
(additions).
If there are entries in the left hand column,
put them in
.L FILES.delete :
.LS 4
comm -23 FILES.old FILES.new > FILES.delete
.LE
If there are entries in the right hand column,
put them in
.L FILES.add :
.LS 4
comm -13 FILES.old FILES.new > FILES.add
.LE
Repeat the above process for each of the
eight manual sections.
.H 2 "Generate \fL.so\fP Files"
.LP
Now that you have lists of added man pages in
.L FILES.add
in each section's source directory,
.L cd
to one of these directories and generate a list
of
.L .so
references:
.LS 4
\&../bin/getNAME -s `cat FILES.add`
.LE
This will display on the screen a shell script
for creating any new
.L .so
files that may be needed.
If a script does indeed appear on the screen,
you will want to run the command again and redirect
the output to
.L List.so :
.LS 4
\&../bin/getNAME -s `cat FILES.add` > List.so
vi List.so
.LE
Verify that the script is correct!
Specifically,
search for filenames which contain
`.' (dot) characters,
as
.L getNAME
does not treat these correctly.
Executing
.L List.so
will generate the
.L .so
files and echo their filenames to the standard
output.
Therefore,
you can create the
.L .so
files and put them under
.SM SCCS
with the command
.LS 4
sccs create `sh List.so`
.LE
.H C "Updating the \fLList\fP Pages"
.LP
It remains now to update the List pages of each
manual section.
You'll want to delete the List page entries
for man pages that have been deleted since the
last release and add entries for the new man pages:
.H 2 "Delete Entries of Pages Deleted Since the Last Release"
.LS 4
cp FILES.delete FILES.zap
vi FILES.zap
.LE
Remove the section suffixes from the filenames
listed there:
.LS 4
:%s/\e(.*\e)\e.[1-8].*/\e1/
.LE
Now,
.L FILES.zap
doesn't list filenames,
but rather lists names of commands or functions
that have been deleted since the last release.
.LP
Now generate the new List page entries for the section into
.L List.add :
.LS 4
\&../bin/getNAME -ip `cat FILES.add` > List.add
vi List.add
.LE
Verify that the entries are correct!
Again, search for filenames which contain
`.' (dot) characters.
.LP
Check out the current List file from
.SM SCCS :
.LS 4
sccs edit List.\fIsection\fP
.LE
Before deleting any lines of
.L List. "\fIsection\fP,"
make sure the right deletions will be performed.
Search
.L List. \fIsection\fP
for occurrences of names in
.L FILES.zap
and redirect the output to 
.L List.zap :
.LS 4
fgrep -f FILES.zap List.\fIsection\fP > List.zap
vi List.zap
.LE
Make sure that you want these lines deleted
from
.L List. \fIsection\fP!
If there are lines which you
don't
want to delete,
but they are comparatively few,
you'll want to make the deletions from
.L List. "\fIsection\fP ,"
and merge back in any mistakenly deleted lines afterwards.
It's therefore very important to preserve
.L List.zap !
.LP
To make the deletions,
.LS 4
vi List.\fIsection\fP
.LE
Type:
.LS 4
!G
.LE
At the prompt,
type:
.LS 4
fgrep -v -f FILES.delete %
.LE
followed by
.SM RETURN .
If the file doesn't look right,
you can always undo.
Now,
restore any mistakenly deleted lines from
.L List.zap
to
.L List. \fIsection\fP
and write the file.
In general it's a good idea to keep records of any deletions
you make,
so keep
.L List.zap
around,
just to be safe.
.H 2 "Add New Entries"
.LP
To generate the new entries,
position the cursor on the first line containing
.L .zZ .
Read in
.L List.add
at this point:
.LS 4
:r List.add
.LE
Sort the entries:
.LS 4
!G
.LE
At the prompt,
type:
.LS 4
sort
.LE
followed by
.SM RETURN .
The
.L .fi
request will be moved to beginning of the list.
Be sure to return it to the end of the list where it belongs.
If there are any capitalized entries,
sort will place them at the top of the list.
Move the capitalized entries to just after the
corresponding lower-case entries to restore the list to
dictionary order.
.LP
In sections 2 and 3,
make sure that function names are followed by
.L (\e|) ' `
(parentheses separated by a half-space).
To do this,
use the substitution command
.LS 4
:%s/\e\efR/(\e\e|)&/
.LE
The next steps in the process are updating
the index for each section, and running
a final check on the formatting of all
pages changed since the last release.
These processes should happen concurrently.
.H C "Updating the Index \(em Phase One"
.LP
In order to update the index,
you'll need to compile a list of man pages
changed since the last release.
Then, you'll want to run off a
trial index containing only references
to those man pages, in order to
check it for accuracy and completeness.
.H 2 "Get Lists of Pages Changed Since the Last Release"
.LP
.L cd
to the directory containing the 
sources for one of the sections.
List the
.L s.
files for the man pages in the
.SM SCCS
directory using the long form and by modification
time.
Redirect the output to
.L FILES.index :
.LS 4
ls -lt SCCS/s.* > FILES.index
vi FILES.index
.LE
Find the start of that part of
the list bearing the date of the last release.
Delete these and all entries below it
by typing:
.LS 4
dG
.LE
in command mode
(vi will not echo this).
Now,
in order to strip away all but
the desired filename from the file,
type:
.LS 4
:%s/.*\e/s\e.//
.LE
Sort the resulting list by positioning the
cursor on the first line of the file and
typing
.LS 4
!G
.LE
At the prompt,
type:
.LS 4
sort
.LE
followed by
.SM RETURN .
Write the file!
The success of the succeeding
steps depends on this!
.LP
At this point,
you want to make sure that current versions of the
files listed in
.L FILES.index
are extant.
To do this,
type
.SM CTRL-Z
to suspend
.L vi
and get a shell prompt.
Get the files from
.SM SCCS :
.LS 4
sccs get `cat FILES.index`
.LE
Go back into
.L vi :
.LS 4
fg
.LE
Since
.L .so
files do not contain indexing requests,
you'll want to eliminate them from the list.
Again position the cursor on the first line
of the file and type:
.LS 4
!G
.LE
At the prompt,
type:
.LS 4
grep -l NAME `cat %`
.LE
This will replace the
.L vi
buffer with the names of
those files in the list which contain
.SM NAME
lines.
.L % ' (`
stands for the name of the file currently being edited,
in this case,
.L FILES.index .)
.LP 
Write the file and quit
.L vi .
.LP 
You now have a list of man pages
for which the index entries must be checked.
.H 2 "Copy the Sources from the Release Machine"
.LP
Now you need to get copies of the sources from the release machine:
.LS 4
cd /usr/src/man/man\fIsection\fP
.LE
On your own machine:
.LS 4
cd \fIyour-home-directory\fP
mkdir index.pages
.LE
Go back to the release machine:
.LS 4
foreach i (man1 man2 man3 man4 man5 man6 man7 man8)
cd $i
rcp `cat FILES.index` \fIyour-machine\fP:\fIyour-home-directory\fP/index.pages
cd ..
end
.LE
You'll also need a copy of
.L FILES.index
on your own machine.
Rather than copying it from the release machine,
you can do it more easily:
.LS 4
cd \fIyour-home-directory\fP/index.pages
ls > FILES.index
vi FILES.index
.LE
Remove
.L FILES.index '' ``
itself from the list.
.H 2 "Generate a Trial Index"
.LP
Now generate a trial index:
.LS 4
make -f Printfile trial.index
.LE
This invokes the
.L trial.index
target in
.L Printfile ,
which generates the file
.L trial.index .
.LP
In order to preview this file,
you must copy it from the release machine
to your own machine:
.LS 4
rcp trial.index \fIyour-machine\fP:/tmp/trial.index.\fIsection\fP
.LE
Now for the fun part:
.LS 4
preview /tmp/trial.index.\fIsection\fP
.LE
This will display the formatted trial index
on the screen.
.H C "Reviewing Page Formatting"
.H 2 "Print Out the Pages Changed Since the Last Release"
.LP
Go back to the release machine and print out
the man pages listed in
.L FILES.index:
.LS 4
(troff -Tlw -msunman `cat FILES.index`) >& /dev/null &
.LE
.H 2 "Make Fixes"
.LP
Proofread them and make additional index
entries and corrections:
.LS 4
vi `cat FILES.index`
.LE
.H 2 "Merge in the Changes"
.LP
In order to this operation,
you must have the man pages mounted from the release machine
(typically on
.L /usr/src/man
or
.L /usr/man )
This is to ensure that you are comparing your versions of the pages
against the versions that you originally copied.
.LP
Create a destination directory where
.L filemerge
can store the merged versions of the files:
.LS 4
cd \fIyour-home-directory\fP/index.pages
mkdir pages.merged
.LE
Now extract from
.L FILES.index
separate lists for each section of pages changed since the last release:
.LS 4
foreach i (1 2 3 4 5 6 7 8)
grep "\.$i" FILES.index > FILES.index.$i
end
.LE
You're now ready to run
.L filemerge:
.LS 4
filemerge -b -l FILES.index.\fIsection\fP . /usr/src/man/man\fIsection\fP pages.merged
.LE
Repeat the process for each section.
.LP
Note:
If you've made many changes to a file,
.L filemerge