fcs.mex

操作系统SunOS 4.1.3版本的源码

.PL RIGHT
.sp 5
.UH M "Printing Man Pages Procedures Outline"
.UH S "TERMS"
.LP
Some definitions to make life easier:
.UH S "Freeze date"
The last day engineers (and other random hackers) can make changes to
man pages.  We set this date based on the time we'll require to do our work.
Since engineers are responsible for making changes to pages they 
affect, they need warning of this cut-off.  Traditionally, they
procrastinate when it comes to man pages, this puts a fire under them.
.UH S "Build"
The compiling and configuring of a system, for our purposes this term
will refer to the entire operating system, which is "built" by the
release engineers. This is done immediately prior to making release tapes.
.UH S "Code fork"
This process of cloning all the release machine sources onto another
machine can take anywhere from 2 days to 3 weeks.  Sources are
cloned to make builds, or to begin work on the next release (yup, even
though work on this release isn't nearly finished, somebody's already
onto the next one \(em it never ends!)
.UH S "Thaw date"
Man pages are again available for changes.  Like the freeze date, we
set this date.  It generally coincides with the end of the build.  
.UH S "PREPARATION"
.LP
.UH S "8 Weeks Out"
.LP
Announce man page freeze date to the mail alias for the
current release.  Also make this announcement on the
subsequent release machine, if the code fork
for that release has already taken place.  It's not very wise
to be completely inflexible about this date, recognize that
some engineers will not be able to meet this deadline.
Offer early on to negotiate, then you'll have a good idea
of what to expect.  Below is an example of the mail announcement.
.BS GRAY
.LS 2
%  mail 4-0@argon, 4-1@argon
Subject: man pages are FROZEN for both 4.0 and 4.1
Cc: syspubs@gottlieb

Man pages will remain FROZEN for final edits,
merges of ECD material, administratrivia, and FCS
printing, until at least March 7.  If you haven't
contacted me already about changes, they'll have to
wait until after the thaw (e.g., 4.1).

Unless I've given you specific permission, do not
check in any man page updates on larry, argon, or
any 4.x release machine until I've announced the thaw.

Questions and/or flames to me.

-bob
.LE
.BE
.LP
Start catching up on evaluated bugs.  All bugs evaluated
for the current release must be fixed in source and
released on elmer.  Evaluate all new bugs for the next release.
.UH S "4 Weeks Out"
.LP
Freeze man pages, this includes putting a warning in
.L /etc/motd
on release machine, and sending mail.  Again, this should also be done
on the subsequent release machine, if necessary.
.UH S "3 Weeks Out"
.LP
Hard freeze.  When the freeze has been in effect for a week,
it is then considered a "hard freeze" and absolutely no changes
will be accepted.
.LP
The following files can be updated once the hard freeze is
set.  The updates must be done by hand, but should not be 
extensive, each is already a good working file.
.LS 2
/usr/src/bin/manpages	
/usr/src/bin/spell.ok
.LE
.LP
At some point
.L /usr/src/bin/titles
should be created and added to
this list.  These files will be used by make during the
checks process.
.LP
When all merges and bug fixes have been made, and all pages are
present and checked in, you can begin the final
checks and fixes.
.UH S "DOCUMENT CONTROL"
.LP
cover.mex is a standard file that needs to be edited for each
release.  Roger will provide the partnum, revision, and date line.  It
is important that these are changed which each release.  The date
and release appear on the title page, and the release also appears
in the footer of each page.
.LP
Edit line 2 of
.L /usr/doctools/tmac/sunman ,
.L /usr/doctools/tmac/an
and
.L /usr/lib/tmac/tmac.an
on all doctools hosts, and
.L /usr/src/usr.lib/tmac/tmac.an
and
.L /usr/lib/tmac/tmac.an
on all affected release machines:
.LS 2
\&.\"     @(#)tmac.sunman 1.36    88/03/05
\&.ds ]W Sun Release \f(LB4.0\fP
.LE
.LP
The permission modes on
.L /usr/lib
may make it necessary to apply some force to edit these files. 
.LP
You also have to do this at alpha and beta stages:
.TS
lfL l.
4.1\e(*a  4.1\(*a
4.1\e(*b  4.1\(*b
.TE
.LP
The copyright statement should also be reviewed at this time.
Every non-Sun product mentioned in the pages should be covered
by a trademark statement.  Examples of trademarked products
include:  Ethernet,
VAX, MicroSoft, and PostScript.  References to these products should
only been used when absolutely necessary, and when referring to
that specific product, otherwise generic references are sufficient.
.UH S "FINAL CHECKS"
.LP
To run the final checks on all the printed man pages, cd to
.L /usr/src/man
on the release machine and type:
.BS GRAY
.LS 2
% make prep
.LE
.BE
.LP
This will invoke the following targets:
.IP "files" 
Extract the current version of all man
pages listed in
.L $(FILES)
of
.L man?/Printfile .
.IP "update"
Append to
.L man?/Printfile
and
.L man?/Makefile
the list of man pages to be added to or deleted from
.L $(FILES) .
These pages must be inserted alphabetically in
.L $(FILES) ,
as well as in
.L man?/List.? ,
or deleted in both places. 
.L $(FILES)
must be
maintained by hand, in both the Makefile and Printfile
file.  They should be updated as changes occur during the release,
this target should merely be a final test of
that maintenance.
.IP "pagelist"
Create
.L /usr/src/tmp/man?.pagelist ,
a list of all printed man pages for each section.
Also \(lqtouch\(rq pagelist in the current
directory so that this target is only made
once.
.IP "bin/hier"
Create
.L /bin/hier
using find in
.L /proto .	
.IP "badpgrefs"
Create
.L /usr/src/tmp/man?.badpgrefs ,
a list of all man pages and any bad references they
may contain.  Also \(lqtouch\(rq badpgrefs in the
current directory so that this target is only
made once.
.br
.ne 8
.IP "titles"
Create
.L /usr/src/tmp/man?.titles ,
a list of all man pages and any title references they
may contain.  Title references are defined
as any line containing more than one word
beginning with a capital letter, or lines
beginning with .I[RB] followed by a capitalized
word[s].  TX macros are excluded.  Also
\(lqtouch\(rq titles in the current directory so
that this target is only made once.
.IP "no.ix"
Create
.L /usr/src/tmp/man?.no.ix ,
a list of all man pages with no index
entries.  Also \(lqtouch\(rq no.ix in the
current directory so that this target is only
made once.
.IP "badnames"
Create
.L /usr/src/tmp/man?.badnames ,
a list of all man pages and NAME lines that contain
point size or font changes, or line breaks.
Also \(lqtouch\(rq badnames in the current directory
so that this target is only made once.
.IP "badhf"
Create
.L /usr/src/tmp/man?.badhf ,
a list of all man pages that have the TH macro
arguments in the wrong order.  Also \(lqtouch\(rq
badhf in the current directory so that this
target is only made once.
.IP "spell"
Create
.L /usr/src/tmp/man?.spell ,
a list of all man pages and any incorrect spellings they
may contain.
Also \(lqtouch\(rq spell in the
current directory so that this target is only
made once.
.IP "badtroff"
Create
.L /usr/src/tmp/man?.badtroff ,
a list of all man pages and any bad troff usage they
may contain.  Also \(lqtouch\(rq badtroff in the
current directory so that this target is only
made once.
.LP
Then, using the files generated by
.L "make prep" ,
edit the man pages requiring fixes.  Allow
approximately one man week for these fixes,
depending on the number of pages that have been
changed or added.
.LP
Once the 
.L $(FILES)
lists have been updated, they need to be
collated before quitting the file.  The last comment inserted by
.L "make update"
will tell you whether you should use:
.LS 2
1G/FILES
!}make collate
.LE
.LP
or
.LS 2
1G/FILES
!}make FILES
.LE
.LP
to collate the 
.L $(FILES)
lists.
.L "make collate"
is used if you are editing the Printfile,
.L "make FILES"
is used to collate the Makefile.
.LP
Each of these will replace the existing FILES list with a new one
that is complete and correctly collated.  In the Printfile,
the 
.L $(FILES)
will only include the printed man pages; in
Makefile, the printed pages as well as
.L \&.so 's
will be included.  Invoking
.L make
from within
.L vi
may seem a bit confusing, so below is a
review brief of what happens when you follow the example above.
.LP
First, understand that the exclamation point in the above
command is a shell escape, so it is actually the shell calling
.L make ,
and not
.L vi .
In its logical fashion,
.L make
then searches the current directory
(\fL/man/man?\fP)
for a file called
.L Makefile ,
finding it, make reads
.L Makefile .
.L Makefile
includes the file
.L ../Makefile.master .
.L make
knows then to read
.L ../Makefile.master
to find a rule for
.L collate .
Indeed we find the target
.L collate
and its rule:
.LS 2
collate:
	-@ $(MAKE) -f Printfile collate
.LE
The rule being nothing but a nested make command, we still
don't know what
.L collate
does.  To discover that we must
follow the nested make command to
.L Printfile
(remember that we are still in the
.L man/man?
directory, so the file we are discussing is
.L man/man?/Printfile ).
In this file
.L make
finds the macro definition for
.L $(FILES)
and includes
.L ../Printfile.master .
Finally, after reading four makefiles
.L make
finds the definitive rule for
.L collate :
.BS
.LS 2
.ps -2
collate: 
	-@if test `pwd | sed 's/.*\e///'` = man3 ; \e
	then \e
		echo 3.FILES= $(3.FILES) | tr ' ' '\e012' | sort -u | fmt | \e
			sed -e 's/$$/ \e\e/' -e '$$s/\e\e//' ; echo "" ; \e
		echo 3l.FILES= $(3l.FILES) | tr ' ' '\e012' | sort -u | fmt | \e
			sed -e 's/$$/ \e\e/' -e '$$s/\e\e//' ; echo "" ; \e
		echo 3m.FILES= $(3m.FILES) | tr ' ' '\e012' | sort -u | fmt | \e
			sed -e 's/$$/ \e\e/' -e '$$s/\e\e//' ; echo "" ; \e
		echo 3r.FILES= $(3r.FILES) | tr ' ' '\e012' | sort -u | fmt | \e
			sed -e 's/$$/ \e\e/' -e '$$s/\e\e//' ; echo "" ; \e
		echo 3v.FILES= $(3v.FILES) | tr ' ' '\e012' | sort -u | fmt | \e
			sed -e 's/$$/ \e\e/' -e '$$s/\e\e//' ; \e
	else \e
		echo FILES= $(FILES) | tr ' ' '\e012' | sort -u | fmt | \e
			sed -e 's/$$/ \e\e/' -e '$$s/\e\e//' ; \e
	fi
.ps +2
.LE
.BE
The rule itself is not really important, what is
important is the ordering of the steps
.L make
took to find the rule.  The definition of 
.L $(FILES)
found in
.L man?/Printfile
will be used for $(FILES)
in the above rule.  We are still in the nested
.L make ,
the output of
.L collate
will be passed to the original
.L make
which will then pass it to
.L vi ,
where the new collated
.L $(FILES)
list replaces the original definition.
.UH S "INDEXING"
.LP
The following procedure is relies on the
.L awk -based
pix indexing script which is not yet working.  It is therefore
subject to changes, and obviously, should NOT be run
until a working script exists.
.BS GRAY
.LS 2
% pix
.LE
.BE
.LP
Run script, this will create the indexing scripts for
each page.
.LP
Fake a trial index and print it for editing.  Duplicate
and kludgy entries and primary entries that should be
secondary should be obvious.  These can be fixed
by editing the pix generated scripts.   Cosmetic
fixes to the index should also be done at this
point.
.LP
Once satisfied with the scripts, apply them to the pages.
At some point (not necessarily now) the scripts need to be
archived somewhere, so that the next run of pix can access
them for comparison.
.UH S "CODE FORK"
.LP
By this time the code fork for the subsequent
release will have been completed.  When the man
pages thaw, all work on the current release
machine must be included on the subsequent
release machine.  This would be an ideal time to
duplicate changes onto that machine.
.LP
You can generate a list of all pages that have
been changed since the last build by repeating the
following commands for each subdirectory.  
.BS GRAY
.LS 2
% cd /usr/src/man/man?/SCCS
% ls \-lt > /tmp/?.list
% vi /tmp/?.list
.LE
.BE
.LP
Remove lines with obviously old dates, using:
.BS GRAY
.LS 2
	\fIRemember, this is done while still in vi\fR
	
/Feb
:.,$d

	\fIFeb is used as an example, substitute the appropriate string\fR

.LE
.BE
.LP
Then strip off all but the filename part of each line, using:
.BS GRAY
.LS 2
:%s/.* s\.//
.LE
.BE
.UH S "CLONING SOURCES"
.LP
You are now ready to clone source.  This is a two
step process.
.LP
First,
.BS GRAY
.LS 2
% make \-f Printfile clone
.LE
.BE
.LP
This duplicates the
.L /usr/src/man
hierarchy in 
.L $(DESTDIR) ,