''' Hey EMACS, I'm an -*-Nroff-*- file.
.bp
.NH 1
Managing Notesfiles
.XS
\*(SN Managing Notesfiles
.XE
.PP
The notesfile system is installed by the user "notes" who is known as the
\fIowner\fP of the notesfiles.
This user can create, delete, rename, and initiate networking of notesfiles.
Each notesfile can be assigned a set of \fIdirectors\fP.  
A director has special privileges
for managing that particular notesfile (see below).
The \fIowner\fP rarely manages the day to day aspects of a notesfile,
although he has director, read, write and response privileges to
all notesfiles for
handling emergencies and failures.
.NH 2
Configuration Files, Utilities, and Permissions
.XS
\*(SN Configuration Files, Utilities, and Permissions
.XE
.PP
All configuration files and utilities live in the home directory of
the notesfile "owner".  In the rest of this document, we will refer to
this directory as LIBDIR.  If the notes administrator uses the
C-shell, it is a very good idea to always use "~notes" to refer to
this directory.  This guarantees that you will get the same directory
as the Notesfile system, and avoids blunders like changing things in
"/usr/lib/notes", when LIBDIR is really "/usr/local/lib/notes".
.PP
The notesfile system owner should be user "notes", and is generally a
special login for the notes system, like "bin" and "uucp".  It is
possible to change the notesfile "owner" to be a login other than
"notes", but there is little point in it, and some of the scripts may
not like it.  When we wish to talk about a real person who manages the
Notes system, as opposed to the notes "owner" login, we will say
"notes administrator."
.PP
All the programs in the Notes system run setgid to the login group of
the notesfile "owner".  All directories and files in the system must
be accessible to that group.  Simply being owned by "notes" makes no
difference.  The most common cause of problems in the Notefile system
is improper file and directory permissions.
.PP
Much of the material in this section is also available in the form of
Unix manual pages.  Those pages are in the subdirectory "man" in the
notes distribution.  References like "notesrc(5)" refer to the man
pages.
.NH 2
Director Options
.XS
\*(SN Director Options
.XE
.PP
The director can:
.RS
.nf
\(bu Change the access permissions.
\(bu Write the policy note.
\(bu Change the notesfile title and director message.
\(bu Open or close the notesfile.
\(bu Allow the notesfile to be networked.
\(bu Force all submissions to the notesfile to be mailed to a moderator.
\(bu Permit or restrict anonymous notes.
\(bu Compress the notesfile.
\(bu Delete notes and responses.
\(bu Toggle director message on any note or response.
.fi
.RE
.PP
The director can delete notes or toggle the director message
above them while reading the notes.
Access other options
by typing "d" on the index page.  A display like this results:
.DS
.TS
center;
c s s
c s s
c c c.
Workstation Discussion
*** Your Director Message Here ***
Anonymous: ON	Notefile: OPEN	Networked: YES
.sp 4
.T&
l c c.
Option:
.TE
.DE
.LP
Options available on this page include:  access lists, policy
note writing, title and director messages, open/close notesfile,
network enabling, anonymous notes, notesfile compress, and delete
a list of notes.
.NH 3
Access Lists
.XS
\*(SN Access Lists
.XE
.PP
The notesfile system allows directors to allow or restrict access
to each notesfile.
The access list can allow or deny read, write, respond, and director
options to any user, group, or system.
Type "p" ("permissions") on the director options page to enter the access list editor.
The system prompts for an option:  "m" to modify an existing entry, "d" to delete
an entry, "i" to insert a new entry, "r" to replot the list,
"q" to quit editing the access list, and capital "Q" to quit editing the
access list and IGNORE ANY CHANGES MADE.
Delete or modify entries by entry number.  Scroll the entries using "+" and
"\-".
[As distributed, the list is configured for a single page of entries]
After typing "i" to insert a new entry, the system prompts for a user type
("u" for user, "g" for group, "s" for system).
The system then prompts for the name of the user, group, or system.
(Users and groups must be valid names)
The default access options
are then displayed: read, write, answer (for responses).  Use the keys
"r", "w", "a", and "d" to toggle the read, write, answer, and director
privileges respectively.  Some options automatically
enable others (e.g., "w" for writing automatically enables "a" for answering).
It is not possible to remove answer access while write access is enabled.
The "n" key will remove all privileges ("no access").
Type return (or "q") when the correct options have been entered.
The system prompts for another user.  Press return at the prompt to exercise
other access list options.
.PP
The access machinery checks user names before checking
group names.  If user "john" explicitly has no
access but his group does, he will nevertheless be denied access to the file.
The current implementation of system access enforcement is naive.
The network software will send to a system only if it has read permission.
Reception allows intermediaries
to pass on notes even if they are not allowed write access to the notesfile;
the access permission is determined from the originating system of each note
or response.
The name "Other" (capital "O") matches any name in the class not
mentioned explicitly
(N.B.:  if you include a user named "Other", that user's access will override
all group access checks since it is checked first).
.PP
On systems where a user may be in several groups at once, like 4.2
BSD, the access list will checked against all the user's groups.
.PP
Many notesfiles allow several users and groups to have
read/write access,
a single user to have director access, and all other users no access.
.PP
For system names, the permissions may include wildcards.  For example,
you may specify "hp*" to match all system names beginning with "hp",
or "*.HP.COM" for systems with domain names.  The match is case-sensitive.
.NH 3
Policy Note
.XS
\*(SN Policy Note
.XE
.PP
Type "w" ("write policy") on the director option page to write a policy
note (just like writing any other note though limited to a single
page).
.NH 3
Title and Director Messages
.XS
\*(SN Title and Director Messages
.XE
.PP
Change the notesfile title with "t", the director message with "m".
The system prompts for a new message.
Typing only a carriage return will not change the old message.
.NH 3
Open/Close
.XS
\*(SN Open/Close
.XE
.PP
Type "o" ("open") to toggle the availability of the notesfile (subject to
the access list).
Closed notesfiles are unavailable to non-directors.
.NH 3
Network Options
.XS
\*(SN Network Options
.XE
.PP
Type "n" ("network") to toggle the availability of the notesfile
for networking.
Arrangements must be made with the notesfile system "owner" to do the network
transfers.
.NH 3
Moderated Groups
.XS
\*(SN Moderated Groups
.XE
.PP
Certain USENET groups are moderated.  They are listed in a periodic posting
to news.lists called "List of Moderators".  If a group is moderated, a note
that a user tries to post to it will automatically be mailed to the
moderator, who will post it (or reject it).
.PP
Use "m" to toggle the moderated/unmoderated state of the group.  If you
make a group moderated without providing a submission address, the previous
submission address is used.  If there was no previous submission address,
the default submission address is picked up from LIBDIR/config; if that
address contains a question mark, the question mark is replaced with the
name of the group, except a hyphen is substituted for each dot.  For
example, if the default address is "?@hub.ourdomain.edu" and the group's
name is "local.classes.math", then the default submission address is
"local-classes-math@hub.ourdomain.edu" (which, presumably, is a valid
mailbox or alias for the group's moderator).
.NH 3
Anonymous Notes
.XS
\*(SN Anonymous Notes
.XE
.PP
Type "a" ("anonymous") to toggle the availability of
anonymous notes in the notesfile.
The availability of the anonymous option may provoke slanderous
attacks from users
(whose anonymity is completely protected).
.NH 3
Compression
.XS
\*(SN Compression
.XE
.PP
Type "c" ("compress") to compress the notesfile.  As notes
are deleted, their text and index space is not reclaimed.  This command
reclaims the space.  The notesfile must be closed.  On a VAX 11/780,
20 seconds of real time (on a slightly loaded system) is required to
reclaim the space of a notesfile with 50 remaining notes
(compression time is dependent on remaining notes).
Notesfiles should be compressed whenever many of their notes have been
deleted.
The notesfile archiver and cron(8) can be used to automate this
process.
.NH 3
Massive Deletions
.XS
\*(SN Massive Deletions
.XE
.PP
Type "z" ("zap") to delete many notes (and their
responses) quickly.
Enter a list of note numbers or note ranges (aa-bb) separated by spaces.
Confirm with "y".  It is economical and prudent to compress the notesfile
shortly thereafter.
Note that deleting notes in a networked notesfile makes those notes
unavailable to those who poll your system for new notes and responses.
.NH 3
Director Options for Notes
.XS
\*(SN Director Options for Notes
.XE
.PP
Directors may put a "director message" above any note they write.
There is one single line director message for each notesfile.  Typical
director messages are: "New Policy", "*** This problem fixed or ignored ***",
or "-- Eat Flaming Death Fascist Pigs --".
Directors can also toggle the director message on a note being read ("d" for
"director message").  A director can delete a note (and all its
responses) or any response while reading the text of the note or response
by typing "Z" ("zap this one") and confirming with "y".
.NH 2
Doing It All from Command Line
.XS
\*(SN Doing It All from Command Line
.XE
.PP
All of the above options can be set without entering notes at all, using
the `nfdirect' command.  This is most useful when the same operation needs
to be applied to a whole group of notes.  For example, to make all "local"
groups unmoderated, you can simply do

	nfdirect -m 'local.*'

which is much easier than going into the director's menu in each of those
groups and hitting the "m" key.
.PP
The `nfdirect' command is described in detail in its manual page, nfdirect(8).
.NH 2
Creation and Deletion of Notesfiles
.XS
\*(SN Creation and Deletion of Notesfiles
.XE
.PP
Only the "owner" of the notesfile system can create notesfiles.
Create notesfiles with the mknf command:
.DS
mknf [ \-aonqu ] topic1 [ ... ]
.DE
The created notesfiles have default status of
closed, non-networked, and
no anonymous notes permitted.
Specify
.B \-a
to permit anonymous notes in the new notesfiles.
Use
.B \-o
to have the notesfiles marked open for general use and
the
.B \-n
option to enable the notesfiles' network availability.
These status flags can all be modified from the directors page at later
times.
.PP
The
.B \-q
flag (quick) avoids rebuilding the active list (LIBDIR/Active).  This
flag is only useful when you will be creating a group of notesfiles
(each with different options), and want to wait until the last one to
rebuild the active list (takes a minute or two).  Notes uses the
active list to expand wildcards, so the list must be rebuilt so that
notes and newsoutput can work normally.
.PP
The
.B \-u
flag (update) is the complement of
.BR \-q.
It forces an update of the active list.
.PP
Delete notesfiles with rmnf:
.DS
rmnf [\-fq] topic1 [ ... ]
.DE
Each notesfile to be removed must be verified with "y" after a
prompt -- anything else will leave that notesfile intact.
The
.B \-f
option forces the removal, similar to 'rm \-f'.  The
.B \-q
option is the same as for mknf, above.
.PP
The file LIBDIR/help/avail.help contains
an introductory notes message.
The contents of the file are up to the discretion of the
notesfile system owner.
.NH 2
Setting Up USENET Moderated Groups
.XS
\*(SN Setting Up USENET Moderated Groups
.XE
.PP
This handy little script can be used to process the whole monthly "List of
Moderators" posting in USENET group news.lists:
.nf

	#!/bin/sh -
	cd LIBDIR
	sed -e '1,/^:/d' -e '/^--/,$d' \
	| awk '{system("./nfdirect +v +n +pg:Other=nrw +m" $2 " " $1);}'
	exit 0

.fi
(change "LIBDIR" to the actual directory name).  The nfdirect command makes
sure that the file is networked and that the default permissions are
Read/Write, and sets the submission address (found in column 2) for each
group (found in column 1).
.PP
This script can be simply piped into (with the "|" command) while you're
reading the "List of Moderators" note.
.NH 2
Intersystem Notesfiles
.XS
\*(SN Intersystem Notesfiles
.XE
.PP
The notesfile system provides for intersystem notesfiles
in an arbitrary connected network.
Copies of a shared notesfile must exist on each
of the systems wishing to read notes for that notesfile.
The contents are kept in synchrony through occasional exchanges
over a network such as uucp.
Notesfiles to be shared must have their "network status" enabled (see
director options).
.PP
Duplication of notes and responses is prevented by the use of
unique identifiers.
Each note and response in a notesfile is assigned a unique number.
The networking software checks each note as it arrives to
see if a copy already exists.
In the event of duplication, the extra copy is discarded and
the fact is logged in the statistics and the network log.
.PP
If notes are exchanged both in News format and in Notes format,
it will not be possible to catch all duplicates.  In some cases,
nearly every note will be duplicated.  Future version of Notes
may include an additional index which will partially fix this problem.
The only real solution is to only communicate with site running
News or a current version of Notes.
'''.PP
'''In the (hopefully) rare event that a response arrives at a 
'''system before the base note does, the network reception program will
'''generate a "foster parent" for the orphaned response.
'''When the true parent arrives,
'''the foster parent will be overwritten.
'''A count of orphaned responses received is kept and available 
'''through use of the nfstats program (see section 4.4).
.NH 3
Transmitting Notesfile Updates
.XS
\*(SN Transmitting Notesfile Updates
.XE
.PP
Three programs are supplied for sending notes to another system.  The
newsoutput program does the actual work, but is rarely used by itself.
It must be used if you wish to send articles in to an old notes site
(not running "Notes 2.6" or later versions).  The other two programs
are sendbatch and newbatch.  These are simple scripts which automate
"news batching" for transmission to NetNews sites or up-to-date Notes
sites.
.PP
Newsoutput finds new notes in each specified notesfile and gathers
them into a "news batch" which is sent to standard output.  "New
notes" are articles that have been received since the time recorded in
that system's sequencer.  A "news batch" is the standard format for
sending groups of articles between NetNews sites (see RFC-850).
Newsoutput can only be run by the notesfile "owner".
.DS
newsoutput \-o \-t sitename [\-f file] [\-s maxsize] topic1 [...]
.DE
The "sitename" is the name of the remote site
to receive the new notes.
The remote site should have notesfiles matching those specified
by the topic1 parameter.
The "\-o" flag tells newsoutput to send the articles in the "old" Notes
format.
Using the
.B \-f
switch tells newsoutput to read the file specified for a list
of notesfiles to transmit;
multiple
.B \-f
parameters are permitted and can be freely intermixed
with `topic' parameters.
Notesfile name pattern matching is performed on both `topic' parameters and
the entries in a file specified by the
.B \-f
option.  The pattern matching is the same as for the .notesrc file
(see the Unix manual page for notesrc(5)).
.PP
The
.B \-s
option tells limits the total number of bytes generated by any one
invocation of newsoutput (this is referred to as the batch size).
This option is particularly useful in the uucp environment, where
transmissions should not be too long in length.  In practice, 50000
bytes seems to be a good batch size (see UUCP Connections, below).
.PP
The standard output of newsoutput should be fed
to a program that actually accomplishes the network transmission.
For many sites this will be uucp.  So a typical command might be:
.DS
newsoutput \-t remotehost "comp.*" | uux \- \-z acf4!rnews
.DE
This will send a news batch containing all new articles in the net
groups to acf4's notes receiving program on the other end.  Both Notes
and NetNews use the rnews program to receive articles.
.PP
Using newsoutput as shown above will usually create very large news
batches which may require many tries to transmit with uucp (the chance
of a datacomm error is quite likely in a one megabyte file).  To send
more reasonably-sized batches, use the sendbatch or newbatch scripts.
.PP
If you need to send articles to a site still running an older version of
Notes, you must use newsoutput with the "\-o" flag.  In this case, the
notes are not sent to standard output.  Newsoutput calls a script to
generate the remote command.  This script (LIBDIR/nfxmitsh) will tranfer the
notes with a command like:
.DS
uux \- \-z remote_system!nfrcv topic local_system
.DE
To use a different command to transfer notes, edit the script.  There are
examples and explanatory comments in the script.  If you do edit the
script, be careful to change the copy in the source directory, since
a "make install" will overwrite nfxmitsh.
.PP
Exchanging articles with an old Notes site can cause very serious
problems.  The old notes format holds much less information than the B
News format.  Articles sent out in that format may reappear as
duplicate notes.  The Notes system makes valiant attempts to avoid
duplicates, but some will still occur.  The only real solution is for
the remote site to upgrade to a current version of Notes.  See the the
section on "Trouble-shooting Notes" for more information.
.PP
The sendbatch program is a simple shell script that calls newsoutput.
It is intended to be invoked from cron with a list of system names
as arguments.  Then, for each system, it checks to see which notesfiles
to transmit and what command to use to transmit them.
.PP
Newbatch is a modified sendbatch that takes one system name and a
list of topics.  It is used for speedier delivery of local notesfiles.
Typically, a site will use sendbatch at night to all sites, and newbatch
during the day to send a few notesfiles to a few sites each hour.
.PP
Sendbatch and newbatch use three files in the directory "LIBDIR/sys".
They are the sequencer file (.seq), the topic list (.out), and the
command to transfer notes (.cmd).  Newbatch ignores the topic list.
.PP
On systems with fourteen character filenames, system names must be
twelve characters or shorter.  If you need to communicate with a
system that has a longer name, use a short nickname for sendbatch and
the filenames, and spell out the longer name in a command in the .cmd
file.
.PP
The sequencer file is maintained by newsoutput and is in the same
ASCII format as the user's sequencer (see nfseq(5)).  This file
contains the sequencing information for the remote system (date of
last newsoutput for each notesfile).  The seqset command (see below)
is provided to reset the sequencer times when necessary.
.PP
The notesfiles to be transmitted for a system are kept in the file
"LIBDIR/sys/system.out" (using the -f option of newsoutput).  If
the (command) file "LIBDIR/sys/system.cmd" exists, the output of
newsoutput is made the standard input of system.cmd.  Otherwise, the
command "uux \- \-r \-z remote!rnews" is executed.
.PP
As an example, suppose acf4 wants to send all new articles in
notesfiles news.* and nyu.* to the rnews program on cmcl2.
Then /usr/lib/notes/sys/cmcl2.out would contain the lines
.DS
news.*
nyu.*
.DE
Then from crontab every few hours the command
.DS
sendbatch cmcl2
.DE
is executed.  The file /usr/lib/notes/sys/cmcl2.cmd would be empty,
since the default transmission command (uux \- \-r \-z cmcl2!rnews)
is used here.
.PP
If you do not have a sequencer file for a particular system,
newsoutput will only send the previous two days worth of articles.  To
set a sequencer, use the "seqset" command.  The "\-w" flag sets "when".
Seqset takes the same flags as newsoutput, such as "\-f".
.PP
The time specification is parsed by getdate(3), and may be a reasonably
free-form English phrase.  The notesfiles may be specified by the same
methods accepted by newsoutput.  Examples:
.DS
seqset \-t newsvax \-w "now"  "*"
seqset \-t newsvax \-w "may 3 1986"  "local.*" "news.*" "!*.sources"
seqset \-t newsvax \-w "yesterday"  "*"
seqset \-t newsvax \-w "3:00 pm apr 24"  "comp.*"
seqset \-t newsvax \-w "last week"  \-f sys/newsvax.out
.DE
The last example shows the most common usage.  That command sets
the sequencers for all notesfiles that we transmit to newsvax.
This is how you would initialize a sequencer for a new connection.
.NH 3
Transmitting New Notes through NNTP
.XS
\*(SN Transmitting New Notes through NNTP
.XE
.PP
When two Notes (or News) neighbors are connected with TCP/IP, a more
interactive method for transmitting new notes can be used.  It is called
NNTP, "Network News Transfer Protocol" (see RFC-977).  Fully implemented
NNTP supports 
both the transfer of articles between two systems, and reading/writing
articles from a remote system.  Notes 2.9 only uses NNTP for transfer.
.PP
Transmitting notes through NNTP is a two-step process.  As before,
newsoutput is first run in order to extract new notes from the notes
database.  It uses the same options as were discussed above, but an
additional option, '-N' for "NNTP" is used.  The output of 'newsoutput \-N'
is
.I not
piped to a transfer command \- the articles are automatically placed in
individual files, named

	NNTP-OUT-DIR/\fIneighbor's-name\fP/\fImessage-id\fP

where NNTP-OUT-DIR is a spool directory specified in LIBDIR/config.
.PP
(Note that since Message-id's tend to be longer than 14 characters, this
implementation of Notes NNTP will not work on systems with 14-character
limit on file names.)
.PP
A neighbor may have an internet (domain-based) name that is different from
its name in the "Path:".  For example, the UUCP name for EECS.NWU.Edu is
"nucsrl", and the UUCP name for Oddjob.UChicago.Edu is "oddjob", and both
sites put their UUCP name into the path rather than their internet name.
In such cases, the name given to newsoutput is the one that goes in the
path, and "name-in-path internet-name" pairs are placed in file
LIBDIR/nntpmap.  The LIBDIR/nntpmap file may look like this:
.nf

	oddjob		oddjob.uchicago.edu
	nucsrl		eecs.nwu.edu

.fi
.PP
The NNTP equivalent of the 'sendbatch' script is called 'spoolnntp'.  Just
like 'sendbatch', it uses LIBDIR/sys/neighbor.out and
LIBDIR/sys/neighbor.seq to keep track of what groups are sent out to
"neighbor" and when.  Again, "neighbor" is the name that occurs in paths.
File LIBDIR/sys/neighbor.cmd is not applicable to NNTP transmissions.
.PP
Once the notes are spooled, the (almost) standard 'nntpxmit' program is
used to send them to the other system.  The version of nntpxmit supplied
with Notes 2.9 has an additional flag, '-z', that tells it to delete each
article file as soon as it is transmitted.
.PP
The script 'sendnntp' can be used to go through all subdirectories of
NNTP-OUT-DIR (thus for each NNTP neighbor) and run nntpxmit on files in
each of them.
.NH 3
Receiving New Notes through NNTP
.XS
\*(SN Receiving New Notes through NNTP
.XE
.PP
Incomming NNTP connections are accepted by the NNTP daemon, 'nntpd'.  Its
job is to talk to the nntpxmit program on the sending machine, accept
articles offered to it, and pipe them through 'rnews' (which has been
discussed earlier, when newsoutput was introduced).
.PP
The nntpd that is supplied with Notes 2.9 is a very limited version of the
News nntpd.  Unlike the News version, it will accept all articles offered
to it, rather than checking first if they are on this system already, and it
will not accept interactive reading or posting commands from users.  Its
only function is to act as the receiving end of an NNTP transfer of
(possibly) new notes.
.NH 3
Crontab and Cron Scripts
.XS
\*(SN Crontab and Cron Scripts
.XE
.PP
Since many of the Notes utilities must be run by the notesfile "owner"
(user "notes"), the scripts run by cron should be run as that user.
If you are using the System V cron, simply install them in the crontab
for the proper user.  With a V7 cron (also used in Berkeley Unix prior to
4.3BSD), you will need something like:
.DS
0 2,23 * * * su notes -c /usr/lib/notes/cron.nightly >> /usr/lib/notes/net.log 2>&1
.DE
The file "cron.nightly" must be executable, of course.  With System V
cron, you will also need to add the notesfile owner to the
"cron.allow" file.
.PP
The scripts that cron runs can be very simple, thanks to the sendbatch
and newbatch commands.  Here are a couple of examples:
.DS
--------------
# Hourly cron script
#   sends local notesfiles to machines on our LAN
#   all these groups are also sent at night
#
newbatch hpcesea "hp.*" "hpf.*"
newbatch hpcerb  "hp.*" "hpf.*" "hpl.*"
newbatch hpcerc  "hp.*" "hpf.*" "hpl.*"
--------------
# Nightly cron script
#   handles high-volume groups and distant sites
#
sendbatch hpcesea hpcerb hpcerc
sendbatch newsvax long-distance-vax backbone-machine
--------------
.DE
.PP
If you are careful to only use newbatch to send notesfiles that are
also listed in the ".out" file, then it will be easy to answer the
question, "What do we send to site X?"  A future version of Notes will
probably use the data in the sys directory to answer the NetNews
sendsys control message.
.PP
Once a week, you will need to run nfarchive to delete old articles and
reclaim space (see Housekeeping, below).
.NH 3
UUCP Connections
.XS
\*(SN UUCP Connections
.XE
.PP
It is not possible to give exact instructions for setting up UUCP
connections, since there are several different versions of UUCP in
common use.  It \fIis\fR possible to give some advice and point out
possible problems.  This discussion may give short shrift to
nfrcv/nfxmit transfers, since those are considered obsolete.
.PP
News batches are received with the rnews program or the unbatch
program.  In Notes 2.7 (and above) systems, rnews and unbatch are
implemented with 
the same program, newsinput.  Newsinput automatically identifies an
individual article (rnews) or a batch (unbatch), and does the right thing.
.PP
Rnews and unbatch should be put in a directory where uuxqt can find
them.  Typically, this means /bin or /usr/bin.  The names "rnews" and
"unbatch" should also be added to the permitted commands for uuxqt.
Normally this means adding them to the file /usr/lib/uucp/L.cmds, but
older version may require editing the source and recompiling uuxqt.
.PP
Rnews and unbatch may be shell scripts which exec LIBDIR/newsinput
(beware the /bin/sh if you use a '~'), or may be copies of the binary.
If they are copies of the binary, you may want to modify the Makefile
to also install newsinput as /bin/rnews and /bin/unbatch.  Shell
scripts need to be changed if you change the home directory for the
notesfile system owner.  Shell scripts make it easer to add debugging
if you are having problems (see the section on Trouble-shooting Notes).
.PP
It is good practice to have a separate login name and userid for each
system that calls you for UUCP.  This makes it much easier to track
the operation of UUCP.  It also gives you a place to record the name
and phone number of a human contact at each site (highly recommended).
Put the info in the fullname field (really the "gecos" field) of
/etc/passwd.
.NH 3
Network Transaction Log
.XS
\*(SN Network Transaction Log
.XE
.PP
The network software maintains a log of all transactions,
including time, date, number of notes and responses transferred, direction
of transfer,
and number of notes replicated by transfer.
This log is placed in a file called "net.log" and resides in LIBDIR
(the home directory of user "notes").
.NH 2
Initial Installation and Parameters
.XS
\*(SN Initial Installation and Parameters
.XE
.PP
Installation of the notesfile system requires
the following:
.RS
.IP \(bu
A working familiarity with
.UX
(and UUCP for intersystem transfers).
.IP \(bu
The notesfile distribution tape (or other means of distribution).
.IP \(bu
A signon for the notesfile owner.
.IP \(bu
The ability to write into the directories where the notesfile
binaries and data base are to live.
.IP \(bu
The
.B -ms
macros (to format the manual with troff).
.IP \(bu
The GNU make program ("gmake").
.IP \(bu
Reading the file INSTALL, which is more up to date than this manual.
.RE
.PP
In fact, \fByou should probably skip this whole section and follow
instructions in INSTALL instead\fP.
.PP
Appendix A ("Notesfile Installation Checklist") is a helpful
guide for installing the notesfile system.
.PP
First: read in the distribution tape.
The tape is a TAR format tape. 
This will read in several directories worth of data. 
The src directory contains all source code for the notesfile
system and the internal help files.
The doc directory contains the nroff sources for the user manual and
the macros that were used to generate it, along with the man pages.
The samples directory is a collection of various system files from our
machine; they are included to provide examples in setting the matching
files on your system.
.PP
After the tape has been read in, set up the notesfile owner (next section),
and get ready to compile (later sections).
.NH 3
Setting Up the Notes Owner
.XS
\*(SN Setting Up the Notes Owner
.XE
.PP
Every program and most shell scripts in the notesfiles system reads
/etc/passwd to find the home directory for the notesfile owner and the
group of that user.  That entry must be set up correctly before
installation (scripts run by the Makefile also read /etc/passwd).
.PP
The notesfile system owner should be user "notes".  If you choose
a different user name, you may have to modify parms.h and a lot
of scripts.
'''.PP
'''You will also need an entry for the Anonymous user.  Even if you do
'''not have any notesfiles with Anonymous allowed, notes still needs the
'''ID.
.PP
Here is a sample passwd entry for notes:
.DS
'''anon:*:21:5:Anonymous ID for Notesfiles::/bin/sync
notes:*:23:5:Notesfiles owner (W. Underwood):/usr/lib/notes:/bin/sync
.DE
In this case, "/usr/lib/notes" is where the config file and utilites
must live.
.NH 3
Parameters in the Config File
.XS
\*(SN Parameters in the Config File
.XE
.PP
Most current detailed information about the config file is in the manual
pages notes-config(5).  It provides some other examples of config files,
and reading it in addition to (or even instead of) this section is very
advisable. 
.PP
Most of the parameters in the notesfile system may be changed
by editing "LIBDIR/config".  This is read by each program at startup.
If you change something in "LIBDIR/config", you \fIdo not\fR need
to recompile notes.
.PP
The config file is set up like a mail header.  Here is a sample file:
.TS
center;
l l.
Domain:	.UUCP
Organization:	Hunga Dunga U.
Spool-Directory:	/usr/spool/notes
Archive-Directory:	/usr/spool/oldnotes
Editor:	/usr/bin/vi
Pager:	/usr/bin/more
Shell:	/bin/sh
Archive-Days:	7
Allow-Old:	No
.TE
The sample shows the default values for these fields.  White space
(blanks and tabs) after the colon is ignored.  Case is ignored in the
field name (thus "shELL" works as well as "Shell").  For the yes/no
fields, either "yes", "no", "true", or "false" may be used.  Case is
ignored.
.PP
When you execute "make setup", a default config file will be made for you.
You will need to edit that, since it some of the defaults (particularly for
"Organization:") are sure to be wrong.
.PP
If you have not yet done a "make setup", skip this and look at the next section.
.LP
Spool-Directory:
.IP
Normally /usr/spool/notes, this is the directory where the
notesfiles articles are kept.  Each notesfile is a subdirectory
of spooldir.  If you plan on receiving
all the network newsgroups (net.*), expect The spool directory to use at
least 20Mbytes of space.  To move the all of your notes to a new directory
(perhaps a bigger disk), simply copy the directory tree over there, then
change this field.
.LP
Archive-Directory:
.IP
Normally /usr/spool/oldnotes.  This is where nfarchive places
old articles.  These articles can later be retrieved using the
nfrcv program.  This may be changed, just like "Spool-Directory:" above.
.LP
Archive-Days:
.IP
This is the number of days before notes are expired by the nfarchive
program.  Newsoutput will not send out any articles whose "Date:" line
identifies them as older this period.  Default is 7 (seven) days.
.LP
Allow-old:
.IP
If set to "yes" this turns off defeats the check for articles that are
older than "Archive-Days" in both newsinput and newsoutput.  Default
is "No".
.LP
Group-timeout:
.IP
Number of days of inactivity before deleting a group.  Activity includes
deletions due to archiving.  Only empty notesfiles are automitically 
deleted.  If group-timout is set to "60", and a group is archived at
14 days, then the group will be deleted if no notes arrive in 74 days.
Default is to never delete a notesfile.
.LP
Manul-rmgroup:
.IP
When set to "yes", rmgroup control messages will not automatically
remove a notesfile.  Instead, a notice will be posted to the nfmaint
notesfile.  An administrator can then manually remove the notesfile.
This protects against rogue control messges that can remove net.sources.
Default is "no".
.LP
Verbose:
.IP
When set to "yes", this causes notes to complain about things that may
not be a problem, and to print additional information about problems.
Used for debugging.
.LP
Verbose-log:
.IP
Normally, nfrcv and newsinput only record summaries in net.log.  If
this is set to "yes", each incoming message will be logged.  Also,
each ill-formed Message-ID will be logged (in the notesfile as well as
in the incoming batches).
.LP
Shell:
.IP
Put your favorite shell here.  By default /bin/sh.  Users may override
this with the environment variable SHELL.
.LP
Editor:
.IP
The default editor to call for article submissions.
By default /usr/bin/vi.  Users may override this with the
environment variable EDITOR, which in turn will be overridden
by the environment variable NFED.
.LP
Pager:
.IP
The default pager used by the help command in notes.
By default /usr/bin/more.  Users may override this with the eniviroment
varible PAGER.
.LP
Write:
.IP
The command to use for inter-user communication.  Normally
either /bin/write or /usr/ucb/talk.  Users may override this
with the environment variable WRITE.
.LP
Mailposter:
.IP
The program used to post mail.  By default it is the shell script
"LIBDIR/notesmail".  Users may override this with the environment
variable MAILPOSTER.
.LP
Prompt:
.IP
A prompt string if you would like to be prompted for commands in
notes.  Defined to a null string (no prompt) by default.
.LP
Organization:
.IP
The name of your organization.  This should be some reasonably short
(less than 40 characters) string such as "University of Illinois" or
"AT&T Bell Laboratories, Murray Hill."  Try to include organization
name, city and state, like "HP Farm Tractor Division, Omaha, NB."  You
must use the American spelling of organisation for notes to recognise
this line.
.LP
Domain:
.IP
The name of your network domain.  Unless you know better, this
should be ".UUCP".  If you are in Hewlett-Packard, use ".HP.COM".
.NH 3
Changing Parameters in the Source
.XS
\*(SN Changing Parameters in the Source
.XE
.PP
Go to the src directory and edit the file "parms.h".
The parameters should be modified as follows:
.LP
SYSV
.IP
Define this symbol if you are running a System V (or System III)
system.
.LP
BSD4.2
.IP
Define this symbol if you are running Berkeley 4.2BSD.
.LP
VFORK
.IP
Define this symbol if you have the vfork() system call for a performance
speedup.
.LP
NOTESUID
.IP
This is the user id of the notesfile owner.  You probably do not want
to change this to be anything other than "notes".
.LP
TMPDIR
.IP
Normally /tmp.  This is where the notesfile systems creates its
temporary files.
.LP
AUTOCREATE
.IP
Automatically create new newsgroups if they do not exist.
.LP
OLDGROUP
.IP
Automatically delete inactive newsgroups after this many days
of inactivity.
.LP
PATHALIAS
.IP
If defined, this is the full pathname of a file that contains
path aliases for various hosts.  This file is in the format
.DS
host	printf-string
.DE
where the first column gives the name of the host, and the
second column gives a printf-string to which the user name is
passed.  So, for example, a file might have lines of the form:
.DS
x	s!%s
y	%s@y.ARPA
z	x!z!%s
.DE
This file can be generated by Steve Bellovin's pathalias program,
available through mod.sources on USENET.  The default value for this
is "/usr/lib/notes/notes-map".
.LP
TRANSLATE
.IP
This is the default shell command that is executed when a joke
translation is requested.  Normally this is a "rot13."
.PP
Next, you should edit the variables in Makefile:
.LP
BINDIR
.IP
This is where the user programs for the notesfile system reside.
By default this is /usr/contrib/bin.
.LP
NOTES
.IP
The login name of the notes user; it should correspond to the uid you used
above.
.PP
Also, if you changed SPOOLDIR, LIBDIR, or ARCHDIR, make sure to edit
those strings in the Makefile.
.NH 3
Compiling the Notesfile System
.XS
\*(SN Compiling the Notesfile System
.XE
.PP
Before you do any makes, the /etc/passwd entry for the notesfile owner
\fImust\fR be added.  Several scripts in the installation process get
information from /etc/passwd.  If you have changed the notesfile owner
to something other then "notes", you will need to edit nearly every
script in the notesfile system (notesmail.sh and nfxmit.sh are not
affected).
.PP
Now that you have set up /etc/passwd and parms.h, the next step is to
generate the notesfile system.  The "make setup" does a lot of mkdirs,
chowns, and chmods, and will probably need to be done as "root".  The
remaining steps can be done as user "notes"
.PP
To install notes, read over the following, then turn to Appendix A,
"Notesfile Insallation Checklist."  The checklist is easier to follow
than the text below, which is why it exists, of course.
.PP
To make the notes binaries, type:
.DS
make all
.DE
This should take thirty minutes to an hour for machines in the same
approximate class as the VAX-11/780.
.PP
To make the notes directories, install some help files, etc., type:
.DS
make setup
.DE
Assuming all went well, you should type:
.DS
make install
.DE
This will install the binaries in BINDIR and in LIBDIR.
.PP
This should end with a message to the effect
that the notesfile system has been installed.
If anything goes wrong, perusal of the terminal dialogue should
point out the offending steps.
The most likely cause of errors will be a missing directory, or
incorrect permissions.
.PP
To replace the notesfile software
any time after these two steps have been run, type:
.DS
make install
.DE
.PP
If at some time you are must change some of the internal constants of
the notesfile package (such as string lengths and blocking factors),
all the existing notesfiles on your system will be incompatible with
the new instantiation of the program.  These constants are all in the
file "structs.h".
.NH 2
Installing the man(1) Documentation
.XS
\*(SN Installing the man(1) Documentation
.XE
.PP
Install the \fIman\fP(1) pages for the notesfile with the following
commands. They are best done as su.
.DS
cd man
make install
.DE
The nroff sources for the documentation will be installed in the
directory /usr/man in subdirectories man1, man3, and man8.
.NH 2
Differences from B News
.XS
\*(SN Differences from B News
.XE
.PP
Notes is fully compatible with B News, but some News features are
ignored, and Notes has a few special features.
.PP
Neither newsinput nor newsoutput will move text between the two
systems if the notesfile is not enabled for networking (see the
section on the access list).
.PP
Control messages are recognized, but nearly all of them are ignored.
Newgroup messages are acted upon.  All control messages are stored
in the "control" notesfile.  \fBIf you feed downstream News sites, make
sure the "control" group is fed to them,\fP or they will not be able to get
USENET control messages.  It is advisable to pass "control" to Notes 2.7
(and up) sites, too.
.NH 3
Fourteen Character Filenames
.XS
\*(SN Fourteen Character Filenames
.XE
.PP
If you are using an OS that limits filenames to fourteen characters,
there are a few restrictions.
.PP
Newsgroup names may be longer than fourteen characters, but are
limited to fourteen characters between dots.
.PP
Names which are not unique in the first thirteen characters will
share the same lockfile on a system with short filenames.  This will
not cause notes to fail, but it can cause notes to run more slowly.
.PP
The system names given as arguments to newsoutput and sendbatch will
be limited to twelve characters (see the section on Transmitting
Notesfile Updates).
.PP
NNTP cannot be used for transmitting notes to other systems (it can still
be used for receiving them).
.NH 2
Housekeeping
.XS
\*(SN Housekeeping
.XE
.PP
When a note or response is deleted, a hole is left in
that notesfile.  This makes for quick deletion but tends to leave
disk space wasted.  The compress option on the director page is
one way that this space is reclaimed.
The nfarchive program (see section 3.6.2) also returns unused space.
Have cron run the nfarchive program weekly to automate
space reclamation.
.NH 3
Automatic Removal of Notes
.XS
\*(SN Automatic Removal of Notes
.XE
.PP
The nfarchive program archives notes and groups untouched for more than
a specified number of days.
The notes and their responses are archived in "generic" notesfile
format in the archive directory specified in "parms.h".
Each notesfile has a subdirectory in the archive directory and each time
nfarchive is run it generates a unique file
for each notesfile archived.
The notes are deleted after they have been archived. 
After the archival, a compression of the notesfile is performed to
recover the space formerly occupied by the archived notes.
Nfarchive assumes that all months have 30 days and all years have 12 months.
The format of the nfarchive command line is:
.DS
nfarchive [\-d] [\-m+ or \-m\-] [\-n] [\-f file] topic
.DE
The
.B \-d
option specifies that no archiving is to take place;
the notes eligible are to be deleted.
.PP
The
.B \-m
option specifies whether to check the director message
status before archiving notes.
Use
.B \-m+
to archive notes which meet the age requirement and have
the director message on.
The
.B \-m\-
option archives notes of sufficient age with the director
message turned off.
If this option is omitted, notes are archived on the basis of age only.
.PP
The
.BI \- n
option specifies the age of eligible notes. The increment is days.
To specify 21 days, use \-21, and so on.
The default is determined by the value of Archive-Days: in
"LIBDIR/config" and is defaults to seven days.  The value of
OLDGROUP in parms.h specifies the group expiration time (default is 60
days).
.PP
The
.B \-f
option specifies a file containing a list of notesfiles
to be archived.
Multiple
.B \-f
parameters are permitted and can be intermixed with
"topic" parameters.
Notesfile name pattern matching is performed on both "topic" parameters
and the entries in a file specified by the
.B \-f
option.
