2.9BSD/usr/contrib/notes/doc/man
Technical report number UIUCDCS-R-82-1081
NOTESFILE REFERENCE MANUAL
Raymond B. Essick, IV
Rob Kolstad
June 17, 1982
Revised by
Rick L Spickelmier
UC Berkeley
Lou Salkind
NYU
ABSTRACT
The notesfile system coordinates discussion forums. It
stores, indexes, sorts, and searches individual remarks. This
manual describes the commands to install, invoke, and use the
system.
(C) 1982 University of Illinois Board of Trustees, All Rights Reserved
This work partially funded by NASA grant NAS-1-14472
directed by Roy H. Campbell, University of Illinois.
1 _I_n_t_r_o_d_u_c_t_i_o_n.
Notesfiles support computer managed discussion forums.
Discussions can have many different purposes and scopes: the
notesfile system has been designed to be flexible enough to han-
dle differing requirements.
Each notesfile discusses a single topic. The depth of
discussion within a notesfile is ideally held constant. While
some users may require a general discussion of personal worksta-
tions, a different group may desire detailed discussions about
the I/O bus structure of the WICAT 68000 (a particular worksta-
tion). These discussions might well be separated into two dif-
ferent notesfiles.
Each notesfile contains a list of logically independent
notes (called base notes). A note is a block of text with a com-
ment or question intended to be seen by members of the notesfile
community. The note display shows the text, its creation time,
its title, the notesfile's title, the author's name (some notes-
files allow anonymous notes), the number of "responses", and
optionally a "director message". Each base note can have a
number of "responses": replies, retorts, further comments, criti-
cism, or related questions concerning the base note. Thus, a
notesfile contains an ordered list of ordered lists. This
arrangement has historically been more convenient than other pro-
posals (e.g., trees were studied on the PLATO (trademark of CDC)
system).
The UNIX (trademark of Bell Labs) notesfile system was
designed and implemented by Ray Essick at the University of Illi-
nois, Urbana-Champaign. It provides users with the abilities to
read notes and responses, write notes and responses, forward note
text to other users (via mail) or other notesfiles, save note
text in their own files, and sequence through a set of notesfiles
seeing just new text. Each notesfile has a set of "directors"
who manage the notesfile: they delete old notes, compress the
file when needed, grant and restrict access to the notesfile, and
set different notesfile parameters (e.g., title, "director mes-
sage", policy note, whether notes' authors can be anonymous).
Some notesfiles contain correspondence from other computers.
Like the UNIX "USENET", notes and responses are exchanged (often
over phone lines) with remote machines. The notesfile system
provides automatic exchange and updating of notes in an arbi-
trarily connected network.
This document details the use of notesfiles from invoca-
tion through intersystem notes exchanges. The last chapter sum-
marizes the entire set of commands for easy reference.
2 _U_s_i_n_g _N_o_t_e_s_f_i_l_e_s.
The notesfile system is invoked with a single command
line. Most notesfile commands require only a single character
(like the vi editor). Those that do require more than one char-
acter are terminated by a carriage return.
Notesfile Reference Manual Page 2
2.1 _I_n_v_o_c_a_t_i_o_n.
Invoke the notesfile system with:
notes [ -sxi ] [ -t termtype ] [ -f nfile ] [ topic1 ] [
topic2 ... ]
The topic list (e.g., topic1) specifies the notesfiles to read.
Invoking the notes system with NO arguments causes the program to
look for a file called '.notesrc' in your home directory, and if
it exists, effectively does 'notes -f ~/.notesrc'. When more
than one topic is specified, the user encounters each topic
sequentially (i.e., topic2 is entered upon completion of topic1).
The -s switch activates the "notesfile sequencer" which
is discussed in section 2.7. Specify "-x" to use the extended
sequencer. The "-i" flag selects yet another sequencing mode.
The -t option directs the notesfile system to use "term-
type" as the user's terminal type, overriding the TERM shell
variable.
The -f option directs the notesfile system to read the
contents of the file "nfile" for a list of notesfiles to read.
See section 2.3 ("The -f Option") for more information on the
format of this file.
2.2 _N_o_t_e_s_f_i_l_e _N_a_m_e_s _a_n_d _W_i_l_d_c_a_r_d_s.
The notesfile system supports pattern matching for names
in the same manner as the shell. By using the shell meta-
characters "*", "?", "[" and "]", the user can specify a number
of notesfiles with a single entry. To read all the notesfiles
that pertain to unix, enter the following line (the quotes are
required to protect the asterisks from interpretation by the
shell):
notes "*unix*"
There are several ways to read the notesfiles test1,
test2, test3 and test4:
notes test1 test2 test3 test4
notes "test?"
notes "test[1234]"
This feature is available from the normal entry (notes)
and the automatic sequencer entry (see section 2.7); it is also
available to the network transmission and statistics programs.
2.3 _T_h_e -_f _O_p_t_i_o_n.
The "-f" option of the notesfile system specifies a file
of notesfile names to read. The file consists of lines contain-
ing notesfile names:
nfgripes
net.unix-wizards
net.bob*
net.general
Notesfile Reference Manual Page 3
fa.telecom
ucbcad.*
!ucbcad.test
!net.bob
The names start at the left margin; they are indented here for
readibility. The sequencer mode can be changed by inserting a
line of the form:
-s
Again, this starts at the left margin. The "s" can be
any of: "s", "x", "i", or "n". When a line of this form is read
from the file, the sequencer mode is set to the corresponding
mode: The normal "s"equencer, the e"x"tended sequencer, the
"i"ndex sequencer, and "n"o sequencer.
To always enter nfgripes, micronotes, and bicycle while
only entering the networked notesfiles "net.*" when new notes are
present, one might use "notes -f myfile" with the following
"myfile":
-x
nfgripes
micronotes
bicycle
-s
net.*
!net.misc
2.4 _G_e_n_e_r_a_l.
Almost all notesfile commands require exactly one charac-
ter (no carriage return). Only commands that are longer than one
character require a terminating carriage return (currently,
choosing a note to read is the only non-single character com-
mand).
The commands were chosen to be easy to remember. Upper
case forms of commands usually function like their lower case
counterparts but with some additional feature or power (i.e., "w"
writes a response, "W" includes the current displayed text in the
response).
Some commands are available almost everywhere in the
notesfile system. These include those for help, exiting, forking
a shell, and making a comment for the suggestion box.
2.4.1 _H_e_l_p.
Typing "?" anywhere will list the available options in an
abbreviated format.
2.4.2 _E_x_i_t_i_n_g.
Type "q" ("quit") to leave the current notesfile. Capi-
tal "Q" leaves the current notesfile and refrains from entering
your last entry time into the sequencer table (see section "The
Sequencer"). The notesfile system proceeds to the next topic in
the invocation list. Use control-D ("signoff") to leave the
notesfile system completely (without updating entry time informa-
tion).
Notesfile Reference Manual Page 4
The "k" and "K" keys function exactly as "q" and "Q".
The "z" key updates your sequencer table and exits the
program.
2.4.3 _S_h_e_l_l_s.
Fork a shell at any time by typing "!" (just like many
other Unix programs).
2.4.4 _C_o_m_m_e_n_t_s & _S_u_g_g_e_s_t_i_o_n_s.
Type capital "B" ("suggestion Box") while on the index
page or reading notes to make a comment or suggestion about the
notesfile program. Your suggestion will be stored in another
notesfile reviewed frequently by the notesfile system manager.
2.5 _T_h_e _I_n_d_e_x _P_a_g_e.
When the notes system is invoked without the -s option,
the user sees an index of the most recent notes. A sample page
is shown below:
Workstation Discussion 2:03 pm Jan 4, 1982
12/9/81 2 Stanford SUN 4 horton
3*WICAT 68000 kolstad
4 M68000 1 horton
5 Dolphin 3 duke!johnson
12/10 6 CDC Standalone 1 smith
8 IBM Personal Computer henry
9 Personal computers harmful? 8 Anonymous
10 Ethernet interfaces 3 mhz? 23 essick
11 Requirements for uiucdcs 10 botten
1/1/82 12 Happy New Year! 5 mjk
- - - - - - - - - - - - -
The upper left corner shows the notesfile's title. In
this example, the notesfile discusses personal workstations. The
current time and date are displayed in the upper right corner.
Ten note titles are displayed (if available). Each note is
displayed with its date (if different from the previous date),
note number, title, number of responses (if any), and author.
The first note above was written by user "horton" on December
9th. It is titled "Stanford SUN" and has four responses. Note 7
has been deleted for some reason (by either its author or a
notesfile director). Note 5 was written by user "johnson" whose
signon resides on the "duke" system. Note 9 was written by an
author who preferred to remain unidentified. Notes with director
messages (sometimes denoting importance) are displayed with a "*"
next to the note number (see note 3 above).
From the index page the user may:
o+ Scroll the index forward or backward.
o+ Read a note.
o+ Write a note.
o+ Go to the next unread note.
o+ Search for notes or responses after a specific date/time.
o+ Search for keywords within notes' titles.
o+ Search for notes/responses by a specific author.
Notesfile Reference Manual Page 5
o+ Go to another notesfile.
o+ Read the policy note.
o+ Register a complaint/suggestion about notesfiles.
o+ Fork a shell.
o+ Exit the notes program.
o+ Invoke notesfile director options (if the user is a
director).
o+ Check whether the group is networked and if anonymous
submissions can be made.
o+ Unsubscribe from the notes group.
2.5.1 _S_c_r_o_l_l_i_n_g _t_h_e _I_n_d_e_x _P_a_g_e.
Scroll the index page by:
+ forward one page
* forward to the most recent page (* is multiple +'s)
- backward one page
= backward all the way (= is multiple -'s)
<return> forward one page
<space> forward one page
2.5.2 _C_h_o_o_s_i_n_g _N_o_t_e_s & _R_e_s_p_o_n_s_e_s.
While on the index page, choose a note to read by typing
its number followed by a carriage return. (This is the only com-
mand that requires a carriage return after it.) Usually the space
bar is used to scan text. To skip to a special note or response,
use the features below.
While reading a note, ";" or "+" advances to the first
response of the note. The next note is displayed if there are no
responses. The number keys ("1", "2", ... , "9") advance that
many responses. If there are fewer responses, the last response
is displayed. The return key skips the responses and goes to the
next note. Press "-" or backspace to see the previous page of
the current note; if the page currently displayed is the first,
the notesfile program displays the first page of the previous
note.
While a response is on the screen, the ";" and "+" keys
display the next response. As with reading a note, if there are
no further responses these keys advance to the next note. The
number keys ("1", ... , "9") will advance the appropriate number
of responses. If there are fewer responses, the last response is
displayed. The "-" or backspace keys display the previous page
of the current response. If the current page is the first page of
the response, these keys display the first page of the previous
response. Enter "=" to see the base note of the current note
string. Press the return key to proceed to the next note.
2.6 _N_o_t_e_s & _R_e_s_p_o_n_s_e_s.
2.6.1 _R_e_a_d_i_n_g _N_o_t_e_s.
After selecting a note from the index page (or entering
the notesfile with your "sequencer" on), the note is displayed.
A sample display is shown below:
Notesfile Reference Manual Page 6
Note 15 Workstation Discussion 2 responses
horton WICAT 150 4:03 pm Dec 11, 1981
Wicat System 150
8 MHz 68000, Mem. mgmt, Multibus architecture, 256k to 1.5 Mb RAM
16/32/64Kbyte EPROM,
10 ms interval timer, 2 RS232 (19.6k async, 56k sync), 16 bit parallel
intelligent disk controller
10 Mbyte winchester (5.25", 3600 rpm, access: 3 ms trk-trk, 70 avg, 150 max),
960Kb floppy (5.25", 300 rpm, access 10 ms trk-trk, 267 avg, 583 max)
Options: battery backed clock, graphics with touch panel, video disk control,
High Speed Serial Network Interface
Unix/V7 avail, Pascal, C, APL, ADA, Cobol, Fortran, Lisp, Basic, Asm
======================================
This is note number 15 in the "Workstation Discussion"
file. User "horton" wrote this note at 4:03 pm on December 11th,
1981. Two responses have been written. The note's title is
"WICAT 150". If a director had written the note, the "director
message" might have been displayed beneath the note's title.
Director's notes sometimes contain important information or new
policies.
Notes and responses can be up to 65535 bytes long (2^32
bytes in 4.1c BSD), much more than can be displayed in a single
screen. The display routine pages text automatically. For all
but the last page of a long note or response, the lower right
corner of the display shows the percentage of the note that has
been shown. For all but the first page of long text, the message
"[Continued]" appears in the upper left portion of the display.
Use the space bar to see the next page of a long note or
response. When the last page is displayed, the space key func-
tions as the ";" key: it proceeds to the next response. The "-"
and backspace keys back up the display to the previous page.
Only the first 10 pages of text are managed this way; typing "-"
from the eleventh page on will return to the tenth page. The "r"
("replot") key goes back to the first page of the note.
While reading a note, it is possible to:
o+ Display the next page of the note.
o+ Display the first page of the note.
o+ Write a response to the displayed note.
o+ Read next note or previous note.
o+ Read next unread response or note.
o+ Return to the index page.
o+ Skip to a given response.
o+ Delete the note (if you are its author or a file direc-
tor).
o+ Edit the note's title (if it is yours).
o+ Edit the note (if it is yours and there are no
responses).
o+ Copy the note to another notesfile.
o+ Save the note in your file space.
o+ Mail the note to someone.
o+ Talk ("write") to the author of the note.
o+ Search for keywords in note titles.
o+ Search for notes/responses by a particular author.
Notesfile Reference Manual Page 7
o+ Toggle the director message (if privileged).
o+ Fork a shell.
o+ Go to another notesfile.
o+ Make a comment or suggestion about notesfiles.
o+ Exit the notesfile program.
o+ Unsubscribe from the notes group.
2.6.2 _R_e_a_d_i_n_g _R_e_s_p_o_n_s_e_s.
Response displays are similar to those of main notes with
the exception that "Response x of y" replaces the note's title.
The first response to note 15 is shown below:
Note 15 Workstation Discussion
koehler Response 1 of 2 11:53 pm Dec 11, 1981
Does anyone have any insight about the relative speeds of the Winchester
disks available on these systems? The previous disk seems to have
track to track response times commensurate with reasonably fast 8"
floppies. I wonder if some of the manufacturers are using disks that
will not meet reasonable specifications for response time for these
kinds of applications.
On the other hand, with intelligent layout of file sectors, the I/O system
could romp and stomp on often used files...
======================================
The commands for manipulating the text of a long response
are the same as those for looking at long notes. Typing space
will move to the next page. Typing "-" or backspace will display
the previous page, within the same limitations as for reading
notes (only 10 pages are kept). Press "r" ("replot") to go back
to the first page of the text.
The options available while reading responses include:
o+ Display the next page of the response.
o+ Display the first page of the response.
o+ Go to a different response (usually the next one).
o+ Go to the next unread note/response.
o+ Reread the base note.
o+ Reread the previous note.
o+ Return to the index page.
o+ Copy the response to another notesfile.
o+ Mail the response to someone.
o+ Save the response in your file space.
o+ Talk to the response's author.
o+ Write another response to the note.
o+ Search for keywords in note titles.
o+ Search for notes/responses by particular authors.
o+ Delete the response (if you are its author or a file
director).
o+ Edit the response (if it is yours and there are no later
responses).
o+ Fork a shell
o+ Go to another notesfile.
o+ Register a suggestion or complaint about the notesfile
program.
o+ Exit the notesfile program.
o+ Unsubscribe from the notes group.
Notesfile Reference Manual Page 8
2.6.3 _W_r_i_t_i_n_g _N_o_t_e_s & _R_e_s_p_o_n_s_e_s.
Write new base notes by hitting "w" while reading the
index page. The notesfile system will then invoke an editor (the
default editor is "ed", use either of the shell variables NFED or
EDITOR to change it). After the prompt, type the insert command
along with the text you wish to enter. Write the text to the
disk and leave the editor. The system will prompt you for vari-
ous options if they are available: anonymity, director message
status, and the note's title.
To write a response to a note type "w" while that note or
any of its responses is displayed. The same steps used to write a
base note should then be followed.
2.6.4 _M_a_i_l_i_n_g _N_o_t_e_s_f_i_l_e _T_e_x_t.
Both notes and responses can be mailed to other users
(with optional appended text). The capital "M" ("mail") command
gives you the opportunity to edit the text then send it to any-
one. Its inferior counterpart, "m", allows you to mail a message
to anyone. To mail to the author of the text, use capital "P"
("Personal comment") to send the text and your comments; use "p"
for a simple letter.
To use a specific mail program, set the environment vari-
able MAILER. If this is not set, the standard mail program is
used.
2.6.5 _F_o_r_w_a_r_d_i_n_g _T_e_x_t _T_o _O_t_h_e_r _N_o_t_e_s_f_i_l_e_s.
Capital "C" ("copy") prompts for a destination notesfile
then allows editing of the note text before it is copied to the
other notesfile. Lower case "c" sends a note without the current
displayed text (i.e., allows you to write a comment in a dif-
ferent notesfile). The forwarded text can be entered as either a
new note or as a response to an existing note. In the latter
case, an index page is given to the user so that he may choose
the appropriate note to which he wishes to respond.
2.6.6 _S_a_v_i_n_g _T_e_x_t _i_n _L_o_c_a_l _F_i_l_e_s.
The "s" ("save") command appends the current displayed
text to a file of your choice (which is created if not present).
Notesfiles prompts for the file name; typing only a carriage
return aborts the command -- no text is saved. Capital "S"
appends the base note and all its responses.
2.6.7 _P_i_p_i_n_g _T_e_x_t _t_h_r_o_u_g_h _C_o_m_m_a_n_d_s.
The "|" command pipes the current text through a command.
The "^" command pipes the base note and all of its responses
through a command. The "%" command pipes the current text
through a decrypter (rotation 13).
2.6.8 _D_e_l_e_t_i_o_n.
Capital "D" ("delete") deletes a note or response if it
is yours and has no subsequent responses. Notes already sent to
the network can not be deleted by non-directors. Directors can
delete any note or response with the "Z" ("zap") command.
Notesfile Reference Manual Page 9
2.6.9 _O_n_l_i_n_e _C_o_m_m_u_n_i_c_a_t_i_o_n.
Typing "t" ("talk") attempts to page the author of the
current displayed text. The Unix "write" command to him/her is
issued if the author is local and non-anonymous.
If the environment variable WRITE is defined, the program
it specifies is used to write to the author.
2.6.10 _E_d_i_t_i_n_g _N_o_t_e _T_i_t_l_e_s.
While reading a base note, type "e" ("edit") to change
the note's title (provided you are the author of the note or a
notesfile director).
2.6.11 _E_d_i_t_i_n_g _N_o_t_e_s/_R_e_s_p_o_n_s_e_s.
"E" allows editing of the text of a note or response. It
is impossible to edit an article if it has subsequent responses
or if it has been sent to the network. If the "later responses"
are deleted, it is possible to edit the original text.
2.7 _O_t_h_e_r _C_o_m_m_a_n_d_s.
2.7.1 _R_e_t_u_r_n_i_n_g _t_o _t_h_e _I_n_d_e_x _P_a_g_e.
Type "i" ("index") while reading notes or responses to
return to the index page.
2.7.2 _S_e_a_r_c_h_i_n_g _T_i_t_l_e_s _f_o_r _K_e_y_w_o_r_d_s.
Notesfiles can search backwards for keywords appearing in
note titles. Typing "x" ("x is the unknown title") prompts for
the substring to be found. Searching begins at the current note
(or from the last note shown on the index page) and proceeds
towards note 1. Upper/lower case information is ignored in the
search. Use upper case "X" to continue the search. The search
can be aborted by hitting the RUBOUT (or DELETE) key.
2.7.3 _S_e_a_r_c_h_i_n_g _f_o_r _A_u_t_h_o_r_s.
The "a" command searches backwards for notes or responses
written by a specific author. Notesfiles prompts for the authors
name. The "A" command continues the search backwards. The
author name may be preceded by an optional `system!'. If no sys-
tem is specified, local authorship is assumed. Abort the search
by hitting the RUBOUT (or DELETE) key.
2.7.4 _S_t_a_c_k_i_n_g _N_o_t_e_s_f_i_l_e_s.
Sometimes it is useful to be able to glance at another
notesfile while reading notes. Using "n", the user can save
(stack) his current place and peruse another notesfile.
When on the index page or while reading notes/responses,
type "n" ("nest") to read another notesfile. Notesfiles prompts
for the notesfile to read. If the notesfile exists, the place is
marked in the old notesfile and the new one's index is displayed.
Type any of the standard keys to leave the nested notes-
file. Both "q" and "Q" leave the nested notesfile and return to
the previously stacked notesfile. Control-d ("signoff") and "z"
causes the notesfile program to exit regardless of the depth of
Notesfile Reference Manual Page 10
nesting.
Sequencing is turned off in the new notesfile regardless
of its state in the old notesfile. The depth of the stack of
notesfiles is limited only by the amount of memory available to
the user.
2.7.5 _P_o_l_i_c_y _N_o_t_e.
A notesfile director can write an optional policy note to
describe the purpose of a notesfile. Read the policy note by
typing "p" ("policy") from the index page.
2.8 _T_h_e _S_e_q_u_e_n_c_e_r.
Most users prefer to scan notesfiles and see only those
notes written since their last reading. The notesfile
"sequencer" provides this capability. It is activated by the "-
s" option ("sequencer") on the command line. When the sequencer
is activated, the notesfile system automatically remembers the
last time the user read notes in each notesfile. Subsequent
entries to the notesfile can use the "last time" information to
show only new notes and responses. If there is nothing new in a
notesfile, the sequencer proceeds to the next notesfile specified
in the command line.
The normal sequencer does not give the user a chance to
read the notesfile if there are no new notes or responses; some-
times it is desirable to be able to do so. Use the "-x" option
to enable the sequencer and enter the notesfile even if there
are no new notes.
No keys need be pressed if there are no new notes in the
entire list and the normal ("-s") sequencer mode is selected.
With the extended ("-x") sequencer, the user must type "q", "Q",
or control-d for each notesfile regardless of whether there are
new notes.
The "-i" mode of sequencing is similar to the "-s" mode.
Using the "-i" mode, notesfiles with no new entries are passed
over. The user is placed on the index page of notesfiles which
contain new notesfiles.
2.8.1 _S_e_e_i_n_g _N_e_w _N_o_t_e_s _a_n_d _R_e_s_p_o_n_s_e_s.
The sequencer always shows the base note of a modified
note string, whether or not is has been shown before, in order to
establish the context of the new response(s). The "j" command
skips to the next modified text (note or response).
If the rest of a particular note string seems uninterest-
ing, skip to the next modified note string with the "J" ("big
Jump") command. This skips any new responses on the current note
string. It is common to follow in detail only a few note strings
and skip others with the "J" command.
To modify the "last entry" time (used for searches), use
the "o" ("oldest notes to read") command. This command modifies
the "last entry" time for the current notesfile. The "o", "j",
and "J" commands function whether the sequencer is on or off but
never change the sequencer's memory of the last entry time. When
the sequencer is off, the "last entry" time is set to January 1,
1970.
Notesfile Reference Manual Page 11
When no more new notes or responses exist, both the "j"
and "J" commands will take the user to the index page. To exit
the notesfile, use the "q" command. Exiting with "q" will update
the user's "last entry" time. Exiting with capital "Q" will NOT
modify the "last entry" time (neither will control-D).
2.8.2 _A_u_t_o_m_a_t_i_c _S_e_q_u_e_n_c_i_n_g.
An alternate entry to the notes program allows the user
to invoke notes with the sequencer enabled and a list of notes-
files to be scanned with a single, simple command. The "autoseq"
command is invoked by typing
autoseq
The automatic sequencer uses the "-s" mode of sequencing,
the user does not enter notesfiles which have no new text. By
specifying "-x" or "-i" on the command line, the user can use the
appropriate sequencer mode.
2.9 _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s.
The notesfile program reads several environment variables
to tailor the system to the user's preferences. Below is a list
of the variables, their purpose, and their default values.
o+ "NFED" specifies which editor will be invoked when the
user writes a note or response. If this variable is not
specified, the notesfile system looks for the environ-
ment variable "EDITOR" (which many other programs use).
If neither "NFED" nor "EDITOR" are defined, a default
editor is used (/bin/ed).
o+ "PAGER" is the paging program ("more", "pg") which is
used for scrolling the help files. The default paging
program is /usr/ucb/more.
o+ "MAILER" determines the mail program to use. If unde-
fined, this defaults to /usr/ucb/mail.
o+ "WRITE" is used to specify the program for communication
between users. If undefined, the Unix program "write"
is used.
o+ "TERM" determines the type of terminal in use. This must
be set for notes to know what screen addressing conven-
tions to use. In most cases the value will be correctly
initialized by the system at login time.
o+ "SHELL" specifies which shell the user is running. This
will almost always be set by the operating system.
3 _M_a_n_a_g_i_n_g _N_o_t_e_s_f_i_l_e_s.
The notesfile system is installed by a user who is known
as the "owner" of the notesfiles (UIUCDCS uses user "notes").
This user can create, delete, rename, and initiate networking of
notesfiles. Each notesfile is assigned a set of "directors" (who
may or may not be associated with owner of notesfiles). The
directors have special privileges for managing the notesfile (see
below). The "owner" 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.
Notesfile Reference Manual Page 12
3.1 _D_i_r_e_c_t_o_r _O_p_t_i_o_n_s.
The director can:
o+ Change the access permissions.
o+ Write the policy note.
o+ Change the notesfile title and director message.
o+ Open or close the notesfile.
o+ Allow the notesfile to be networked.
o+ Permit or restrict anonymous notes.
o+ Compress the notesfile.
o+ Delete notes and responses.
o+ Toggle director message on any note or response.
The director can delete notes or toggle the director mes-
sage above them while reading the notes. Access other options by
typing "d" on the index page. A display like this results:
Workstation Discussion
*** Your Director Message Here ***
Anonymous: ON Notefile: OPEN Networked: YES
Option:
= = = = = = = = = = = = = = = = = =
Options available on this page include: access lists,
policy note writing, title & director messages, open/close notes-
file, network enabling, anonymous notes, notesfile compress, and
delete a list of notes.
3.1.1 _A_c_c_e_s_s _L_i_s_t_s.
The notesfile system allows directors to allow or res-
trict 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 extant 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.
Notesfile Reference Manual Page 13
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).
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.
3.1.2 _P_o_l_i_c_y _N_o_t_e.
Type "w" ("write policy") on the director option page to
write a policy note (just like writing any other note though lim-
ited to a single page).
3.1.3 _T_i_t_l_e & _D_i_r_e_c_t_o_r _M_e_s_s_a_g_e_s.
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.
3.1.4 _O_p_e_n/_C_l_o_s_e.
Type "o" ("open") to toggle the availability of the
notesfile (subject to the access list). Closed notesfiles are
unavailable to non-directors.
3.1.5 _N_e_t_w_o_r_k _O_p_t_i_o_n_s.
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.
3.1.6 _A_n_o_n_y_m_o_u_s _N_o_t_e_s.
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).
3.1.7 _C_o_m_p_r_e_s_s_i_o_n.
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.
Notesfile Reference Manual Page 14
3.1.8 _M_a_s_s_i_v_e _D_e_l_e_t_i_o_n_s.
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.
3.1.9 _D_i_r_e_c_t_o_r _O_p_t_i_o_n_s _f_o_r _N_o_t_e_s.
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 Fas-
cist 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 read-
ing the text of the note or response by typing "Z" ("zap this
one") and confirming with "y".
3.2 _C_r_e_a_t_i_o_n & _D_e_l_e_t_i_o_n _o_f _N_o_t_e_s_f_i_l_e_s.
Only the "owner" of the notesfile system can create
notesfiles. Create notesfiles with the mknf command:
mknf [ -aon ] topic1 [ ... ]
The created notesfiles have default status of closed,
non-networked, and no anonymous notes permitted. Specify -a to
permit anonymous notes in the new notesfiles. Use -o to have the
notesfiles marked open for general use and the -n option to
enable the notesfiles' network availability. These status flags
can all be modified from the directors page at later times.
Delete notesfiles with rmnf:
rmnf [-f] topic1 [ ... ]
Each notesfile to be removed must be verified with "y" after a
prompt -- anything else will leave that notesfile intact. The -f
option forces the removal, similar to 'rm -f'.
The file /usr/spool/notes/.utilities/avail.notes contains
a list of the public notesfiles. The notesfile owner should
update this file when he creates new notesfiles. The contents of
the file are up to the discretion of the notesfile system owner.
3.3 _I_n_t_e_r_s_y_s_t_e_m _N_o_t_e_s_f_i_l_e_s.
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 (UIUCDCS uses uucp). Notesfiles to be
shared must have their "network status" enabled (see director
options).
Duplication of notes and responses is prevented by the
use of unique identifiers. Each note and response in a notesfile
Notesfile Reference Manual Page 15
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.
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).
3.3.1 _T_r_a_n_s_m_i_t_t_i_n_g _N_o_t_e_s_f_i_l_e _U_p_d_a_t_e_s.
The nfxmit program gathers the new notes and responses in
specified notesfiles and sends them to a specified site. The
notesfile "owner" must occasionally enter the following command
(or have it entered for him by cron) to update remote notesfiles
with new notes and receive new remote notes:
nfxmit -dsitename [-tmmddyy] [-r] [-a] [-f file] topic1
[...]
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. For remote notesfiles with
different names, see the section below on Name Mapping.
The optional -t specifies that all notes and responses
since that date should be sent (normally -t is omitted and the
notesfile system sends only new notes and responses).
The -r option specifies that the remote notes system
should not only receive the current changes but also reply in
kind. This is useful if the remote system does not automatically
run the nfxmit program.
The -a option specifies that articles inserted from the
news(I) system are to be sent also. Normally these articles are
not sent because the receiver probably has them; the primary use
of this switch is for sites that do not run news(I).
Using the -f switch tells nfxmit to read the file speci-
fied for a list of notesfiles to transmit; multiple -f parameters
are permitted and can be freely intermixed with `topic' parame-
ters. Notesfile name pattern matching is performed on both
`topic' parameters and the entries in a file specified by the -f
option.
3.3.2 _N_e_t_w_o_r_k _T_r_a_n_s_a_c_t_i_o_n _L_o_g.
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 the notesfile utility directory (by default:
/usr/spool/notes/.utilities).
Notesfile Reference Manual Page 16
3.3.3 _N_o_n-_S_t_a_n_d_a_r_d _L_i_n_k_s.
Some systems will be unable to keep the notesfile network
software in a public directory (such as /usr/bin). Other sites
will have non-uucp links. The `net.how' file is for these cases.
`Net.how' is kept in the notesfile utility directory
(/usr/spool/notes/.utilities) and contains information on linking
to remote systems. Entries in the file are made for systems with
non-standard links and have the following format:
system:direction:::command string
The system field is self explanatory. The direction
field contains either an `x' or `r' (no quotes) and specifies the
direction that the line is for. An `x' specifies that the command
string is for sending notes to the remote site; an `r' specifies
that the command string is used in coercing the remote system to
send its new notes and responses back.
The command string is a printf control string (without
quotes) with two `%s' entries. The first is for filling in the
name of the notesfile, the second is for the local system name.
Many entries in the `net.how' file will be to place different
paths on the `nfrcv' and `nfxmit' commands. The default command
line is:
uux -z - system\!nfrcv %s %s
for the `x' entry and for the `r' entry:
uux system\!nfxmit %s -d%s
A sample from the uiucdcs net.how file:
uicsovax:x:::uux - uicsovax!/mnt/dcs/essick/.commands/nfrcv %s %s
uicsovax:r:::uux uicsovax!/mnt/dcs/essick/.commands/nfxmit %s -d%s
A sample from the ucbcad net.how file (4.1c BSD, ethernet
transmission):
ucbmonet:x:::rsh ucbmonet -l ricks /usr/local/lib/notes/nfrcv %s %s
ucbmonet:r:::rsh ucbmonet -l ricks /usr/local/lib/notes/nfxmit %s -d%s
3.3.4 _N_o_t_e_s_f_i_l_e _N_a_m_e _M_a_p_p_i_n_g.
To provide flexibility in the naming of notesfile across
systems, the network software looks in the directory
/usr/spool/notes/.utilities/net.aliases for mappings of local
notesfile names to remote notesfile names. Each file in the
directory is named after a system (e.g., pur-ee or uicsovax).
Each of these files contains lines which specify the mapping of
local notesfiles to the particular systems notesfiles. Lines in
the files look like:
local_nf:remote_nf
If there is no entry for a particular notesfile or the
file for that system is missing, the local name is used.
Notesfile Reference Manual Page 17
3.4 _I_n_i_t_i_a_l _I_n_s_t_a_l_l_a_t_i_o_n & _P_a_r_a_m_e_t_e_r_s.
Installation of the notesfile system requires the follow-
ing:
o+ A working familiarity with version 7 UNIX (and UUCP for
intersystem transfers).
o+ The notesfile distribution tape.
o+ A signon for the notesfile owner. This should be a
member of the same group as the uucp signons.
o+ The ability to write into the directories where the
notesfile binaries and data base are to live.
Appendix A ("Notesfile Installation Checklist") is a
helpful guide for installing the notesfile system.
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 sys-
tem 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 Sample 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.
After the tape has been read in, select the appropriate
parameters.
3.4.1 _S_e_l_e_c_t_i_n_g _A_p_p_r_o_p_r_i_a_t_e _C_o_n_s_t_a_n_t_s.
Go to the src directory and edit the file `parms.h'. The
parameters should be modified as follows:
o+ "Sysname" should be the local system name. For compati-
bility with the rest of the world, this should be 9 or
fewer characters. (e.g., uiucdcs)
o+ "MSTDIR" should be the directory where the notesfiles
will be kept. We use /usr/spool/notes.
o+ "ARCHDIR" is where the archived notes are sent. Placing
ARCHDIR and MSTDIR on the same file system is not
recommended unless you have lots of disk space.
o+ "NOTESRC" is the default ".notesrc" file name.
o+ "ARCHTIME" is the default number of days that a note is
allowed to go unmodified before it is eligible for
archival. Nfarchive allows this to be overridden on
its command line.
o+ "NOTESUID" is the uid of the notesfile "owner". On our
system we have a user "notes" which owns the notes-
files.
o+ "ANONUID" is the uid used for anonymous notes. This uid
is not allowed to run notesfiles. We made a dummy user
in our password file whose uid we set this constant
equal to. If you are on a PDP-11 and have no free uid
slots, pick your worst enemy.
o+ "DFLTSH" is the default shell for forking. /bin/sh will
usually suffice. The environment variable SHELL will
override this for any user.
o+ "DFLTED" is the editor that notesfiles uses for writing
notes. Each user can specify his preference by the NFED
or EDITOR environment variables.
o+ "AUTOSEQ" is the pseudonym (a la the Unix program `ln')
of the notes program used for automatic sequencing. We
use "autoseq".
Notesfile Reference Manual Page 18
o+ "MAILER" defines the mail program used by notesfiles.
Because the notesfile system does not maintain the full
pathname to remote authors, it is recommended that the
'uumail' program which is included in the distribution
be used.
o+ "OLDGROUP" is the number of days to wait before expiring
a group.
o+ "AUTOCREATE" should be defined if you wish notes groups
to be created automatically by newsinput.
o+ "NEWS" should be defined if your machine runs news.
o+ "DEMANDNEWS" should be defined if you wish "newsoutput"
to be forked immediately on a submission.
If you are running on a PDP-11 or other machine with 8
bit user ids, then the following line should be added to the
`parms.h' file:
#define PDP11 1 /* running on PDP-11 */
If you wish the notesfile system to use a prompt, you
should define the string PROMPT as follows (use any string you
prefer):
#define PROMPT "? " /* command prompt */
There are several other definitions that might need to be
changed. See appendix A ("Notesfile Installation Checklist") for
a list of these.
Once these changes have been made, the next step is to
update the Makefile. The values which should be checked are:
o+ "DESTDIR" is where the programs notes, nfprint, nfstats,
and nfpipe are installed. We use /usr/local.
o+ "MSTDIR" must match the value given in `parms.h'.
o+ "ARCHDIR" must also match the value given in `parms.h'.
o+ "NET" is the extant directory where the notesfile net-
working software is kept. This must be somewhere along
the default search rule for uucp. We use
/usr/local/lib/notes.
o+ "AUTOSEQ" is the name of the link to the notes program
used for automatic sequencing. This must match the
value given in `parms.h'.
o+ "NOTES" is the user name of the notesfile system "owner".
This should match the NOTESUID in `parms.h'. (e.g.,
NOTESUID=144, NOTES=notes)
o+ "NOTESGRP" is the group of the notesfile "owner". This
should be the same group as the uucp signon.
3.4.2 _C_o_m_p_i_l_i_n_g _t_h_e _N_o_t_e_s_f_i_l_e _S_y_s_t_e_m.
After all the appropriate parameters are set up, the next
step is to generate the notesfile system. First, the requisite
directories and files in /usr/local (or wherever) should be
manufactured. This procedure should be run exactly once and will
probably have to be run by the superuser. To make these files
type:
make base
The next phase should be run while signed in as the
notesfile "owner". Type:
make boot
Notesfile Reference Manual Page 19
If all goes well, this should end with a message to the
effect that the notesfile system has been installed (Less than 10
minutes on a VAX-11/780, less than 50 minutes on an 11/60). 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.
To replace the notesfile software any time after these
two steps have been run, type:
make install
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.
3.4.3 _U_s_e_r _S_u_b_r_o_u_t_i_n_e_s.
The user subroutine "nfcomment" (which is described
later) is found in the file src/nfcomment.c. For users to take
advantage of this routine, it should be compiled and placed in
/usr/lib (or the appropriate place on your system).
To generate the user subroutine, type:
make subs
The resulting file (libnfcom.a) should then be moved to
the appropriate library (usually /usr/lib). Users can then load
this routine by specifying `-lnfcom' on the `cc' or `ld' command
lines.
3.5 _I_n_s_t_a_l_l_i_n_g _t_h_e _m_a_n(_1) _D_o_c_u_m_e_n_t_a_t_i_o_n.
Install the man(1) pages for the notesfile with the fol-
lowing commands. They are best done as su.
cd Page
make install
The nroff sources for the documentation will be installed in the
directory /usr/man in subdirectories man1, man3, and man8.
3.6 _I_n_t_e_r_f_a_c_i_n_g _t_o _N_e_w_s(_I).
The notesfile system interfaces to the news(I) program.
The newsinput program parses the A news protocol and inserts
articles in the appropriate notesfiles. The bnewsinput program
parses the B news protocol. The newsoutput program moves notes
from the notesfile system to the news system. Neither program
will move text between the two systems if the notesfile is not
enabled for networking (see section 3.1.5). Newsoutput will not
retransmit articles inserted by newsinput. Sites sharing notes-
files can all run newsinput; only one of the sites should run
newsoutput for any given notesfile.
Before interfacing to news, check the file `newsgate.h'
to guarantee that the correct calling sequence to insert news
articles is used.
Notesfile Reference Manual Page 20
3.6.1 _C_o_p_y_i_n_g _N_e_w_s _t_o _N_o_t_e_s_f_i_l_e_s.
To have news automatically forward the articles it
receives to the newsinput program, an entry similar to this
should be made to the /usr/spool/news/.sys file:
nf_system:newsgroup_list::/usr/spool/notes/.utilities/newsinput
Where "newsgroup_list" is a news(I) subscription list of
the newsgroups which have parallel notesfiles. The above entry
assumes that you are running A news; B news users should run
bnewsinput.
3.6.2 _C_o_p_y_i_n_g _N_o_t_e_s_f_i_l_e_s _t_o _N_e_w_s.
The newsoutput program accepts a list of notesfiles as
parameters and scans them looking for new notes/responses to
place into the news(I) system. Newsoutput accepts two optional
parameters in addition to the list of notesfiles to send to news.
newsoutput [ -a ] [ -f file ] topic [ ... ]
The -a parameter specifies that notes and responses from
any system are to be sent to news. The default is for local text
only.
The -f parameter specifies a file containing a list of
notesfiles to send to the news system. The preferred method of
running newsoutput is with cron. Only the "notesfile owner" is
permitted to run newsoutput, so the cron entry should have an su
to the correct uid.
Since most notesfile users will form small subnets of the
larger news network, some care must be taken as to who uses the
-a option of newsoutput. One solution is to have a single site
running news and then sharing notesfiles with the other sites.
If more than one site runs news, things are trickier. If all the
sites run news, then they can each run both newsinput and
newsoutput without the -a option.
In any case, if a notesfile generated article finds its
way to news through two different sites, a duplication in the
news system will occur which will not cancel itself when the two
meet on the same system. Newer versions of news (release 2.7 and
later) should be flexible enough to eliminate this problem once
the news/notes gateways are modified accordingly.
3.6.3 _N_a_m_i_n_g _N_o_t_e_s_f_i_l_e_s _a_n_d _N_e_w_s_g_r_o_u_p_s.
Newsgroup names may be longer than the fourteen charac-
ters allowed for file names by UNIX, although the first fourteen
characters must be unique. Notesfile names are limited to four-
teen characters. An aliasing facility is included to convert
between notesfiles and newsgroups. The file
`/usr/spool/notes/.utilities/newsgroups' contains the relation-
ships of notesfiles and newsgroups. If the file does not exist or
there is no entry for the desired notesfile/newsgroup the routine
which scans that file returns the original argument as if it had
matched itself. A typical line in the file looks like:
notesfile_name:newsgroup
Entries in this file need be made for only a few reasons:
(1) The newsgroup which matches the notesfile is longer than
Notesfile Reference Manual Page 21
fourteen characters, (2) the notesfile and the newsgroup are dif-
ferent names (e.g. the notesfile `Bnews' can be linked to the
newsgroup `net.news.b' with an entry of `Bnews:net.news.b'), and
(3) you want several newsgroups linked to a single notesfile.
You can not link a single newsgroup to several notesfiles. The
file is scanned from the start until EOF or a match is found.
Several newsgroups can spool into the same notesfile:
somenotesfile:newsgroup1
somenotesfile:newsgroup2
If you want newsoutput to send the notesfile-generated
notes in `somenotesfile' to both `newsgroup1' and `newsgroup2',
add the following entry BEFORE the above two entries:
somenotesfile:newsgroup1,newsgroup2
3.6.4 _S_p_a_c_e _U_t_i_l_i_z_a_t_i_o_n.
Since the notes system stores the entire text of a single
notesfile in a single file, a notesfile system uses less space
than the same scale news system. The notesfile system is gen-
erally more space efficient than B news.
3.7 _H_o_u_s_e_k_e_e_p_i_n_g.
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
on 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.
3.7.1 _A_u_t_o_m_a_t_i_c _R_e_m_o_v_a_l _o_f _N_o_t_e_s.
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:
nfarchive [-d] [-m+ or -m-] [-n] [-f file] topic
The -d option specifies that no archiving is to take
place; the notes eligible are to be deleted.
The -m option specifies whether to check the director
message status before archiving notes. Use "-m+" to archive
notes which meet the age requirement and have the director mes-
sage on. The "-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.
The -n option specifies the age of eligible notes. The
increment is days. The default is determined by the value of
ARCHTIME in `parms.h' and is distributed as fourteen days. The
Notesfile Reference Manual Page 22
value of OLDGROUP specifies the group expiration time.
The -f option specifies a file containing a list of
notesfiles to be archived. Multiple -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 -f option.
3.7.2 _A_d_d_i_t_i_o_n_s _t_o _S_y_s_t_e_m _B_o_o_t.
Since the notesfile system maintains several lock files
to ensure mutual exclusion of each notesfile, a line similar to
the following should be added to the /etc/rc file.
rm -f /usr/spool/notes/.locks/*
Make sure `/usr/spool/notes' matches the MSTDIR parameter
in the Makefile and the `parms.h' file. This line will remove any
dangling locks left if the system has crashed.
4 _O_t_h_e_r _N_o_t_e_s_f_i_l_e _U_t_i_l_i_t_i_e_s.
The notesfile distribution includes utility programs to
provide hard copy output, additional interfaces to user programs,
and statistics. They are described below.
4.1 _H_a_r_d _C_o_p_y _O_u_t_p_u_t.
The program "nfprint" sends to standard output a nicely
formatted listing of the notesfile in its command line. Its for-
mat is:
nfprint [-lnn] [-p] topic [ note# ] [ note#-note# ] [ ...
]
The "-l" option specifies an alternate page size (the default is
66). The optional note number list specifies that only certain
notes of the notesfile are to be printed. The list can specify
individual notes and ranges. The notes are printed in the order
specified.
4.2 _P_i_p_e_d _I_n_s_e_r_t_i_o_n _o_f _N_o_t_e_s.
The nfpipe program enters text from the standard input
into a notesfile:
nfpipe topic [-t title] [ -d ] [ -a ]
The -t option allows specification of a title. The -d and -a
options specify the director and anonymous flags respectively (if
available). If no title is specified, one is manufactured from
the first line of the note.
4.3 _U_s_e_r _S_u_b_r_o_u_t_i_n_e_s.
The nfcomment subroutine is callable from a user's C pro-
gram. It allows any user program to enter text into a notesfile:
nfcomment (nfname, text, title, DIRFLAG, ANONFLAG)
Notesfile Reference Manual Page 23
The parameters are:
char *nfname; /* name of notesfile */
char *text; /* null terminated text to be entered */
char *title; /* if non-null, title of note */
int DIRFLAG; /* != 0 -> director flag on (if allowed) */
int ANONFLAG; /* != 0 -> anonymous note (if allowed) */
If the *text pointer is NULL, the text of the note will
be read from standard input. If no title is specified the sub-
routine will manufacture a title from the first line of the note.
This routine is useful for error reports, user comments about
programs, and automatic logging of statistics or internal states.
This routine can be loaded with a C program by specifying
`-lnfcom' on the `cc' command line.
4.4 _S_t_a_t_i_s_t_i_c_s.
The notesfile system keeps statistics on where notes and
responses originate, the number of network accesses, duplications
and orphaned responses. Combined with the use of the log main-
tained by the notesfile networking software, monitoring notesfile
traffic is quite easy.
The -s option specifies that only a summary is to be pro-
duced, skipping the individual reports. Wildcard constructs with
'*', '?', '[', and ']' are recognized by nfstats. Invoke the
statistics program with:
nfstats [ -s ] topic1 [ ... ]
Typical output is:
rbenotes on uiucdcs at 6:24 pm May 7, 1982
NOTES RESPS TOTALS
Local Reads 359 115 474
Local Written 53 55 108
Networked in 0 0 0
Networked out 0 0 0
Network Dropped 0 0 0
Network Transmissions: 0 Network Receptions: 0
Orphaned Responses Received: 0 Entries into notefile: 109
Total time in notefile: 66.57 minutes Average Time/entry: 0.61 minutes
Created at 10:04 pm May 5, 1982, Used on 3 days
A combined set of statistics is produced at the end of
listings of more than one notesfile. The statistics are largely
self explanatory.
4.5 _C_h_e_c_k_i_n_g _f_o_r _n_e_w _n_o_t_e_s.
The checknotes program checks if there are new notes.
The exit code is arranged to make the program useful in shell
scripts: 0 (TRUE) is there are new notes, 1 (FALSE) otherwise.
Use the "-q" option to receive a message
There are new notes
if one or more of the notesfiles have notes/responses written
Notesfile Reference Manual Page 24
since the user's last entry time into that notesfile.
The "-n" option is similar to the "-q" option, with the
exception that it yields output when there are no new notes. The
output of checknotes with the "-n" option is:
There are no new notes
Use "-v" to print the name of each notesfile with new
notes/responses. The "-s" option is suited for use conditional
expressions in shell scripts; no output is generated by this
option.
Notesfile Reference Manual Page 25
5 _S_u_m_m_a_r_y.
notes [-sxi] [-t type] topic1 [...] ; Next text
+ Next text
Everywhere: ret Next note
7 Forward 7 responses
? help 15 = 8 + 7
q,k quit i Index page
Q,K Quit w/out save m Mail to anyone
|^D Leave NOW w/out sequencer M Mail w/text
! Fork Shell n Nest notesfiles
B Register suggestion p Personal note to author
z Leave NOW with sequencer P To author w/text
u Unsubscribe from a group t Talk to author
w Write response
Index Page: s Save text
S Save entire note string
+ Forward | Pipe text through a command
* Last page ^ Pipe entire note string through a command
- Backward % Pipe text through a decrypter (rotation 13)
= First page C Copy text to notesfile
13 Read note 13 e Edit title
(requires RETURN) E Edit text
o Oldest date for sequencing D Delete (if yours)
O Set sequencer for today's notes d Toggle director msg.
x,X Search for title = Base note
a,A Search for author x,X Search backwards (title)
w Write a note a,A Search backwards (author)
n Nest notesfiles Z Delete (directors only!)
j,J Jump to first unread note
p Read policy note Director Options:
r Replot the screen
d Director options o Toggle open status
c Compress notesfile
Reading anything: w Write policy
a Toggle anonymous
spc Next page of current text n Toggle network avail.
- Previous page of text z Zap lots of notes
r First page of current text p Access (permission) List:
j Next unread text i insert
J Next unread base note d delete
l Acts like spc in current note, acts m modify
u user
g group
s system
r read access
a answer access
d director options
w write access
n null access
A-1
APPENDIX A
Notesfile Installation Checklist
____ vi parms.h
____ select Sysname [ucbcad, cmcl2]
____ MSTDIR [/usr/spool/notes]
____ ARCHDIR [/usr/spool/oldnotes]
____ ARCHTIME [14 - number of days before removing articles]
____ NOTESUID [user id of the notes maintainer]
____ ANONUID [unused user id]
____ define PROMPT [if you wish the system to give a command
prompt]
____ define CNTRLZ [if your system supports control-Z job control
processing]
____ define DUMPCORE [this determines whether core is dumped when
an internal error is detected. You might want this for testing,
but not for production]
____ define the OS (4.1cBSD, V6,..... - defaults to 4bsd)
____ define AUTOCREATE [if you wish for notes to automatically
create new groups]
____ OLDGROUP [amount of time before groups expire]
____ NOTESUMASK [umask for files created by notes]
____ define NEWS [if you wish to submit notes to news]
____ define DEMANDNEWS [this forces articles to be submitted to
news at the time of submission]
____ define BNEWS [if running B release of news for gateways. If
not running news locally, this does not matter. If running A
news, the notesfile owner will collect lots of mail because A
news does not allow overriding of the authors name.]
____ define TONEWS [again, dependent on running notes/news gate-
ways locally. The defaults here are probably adequate in either
case]
____ [finished editing] parms.h
____ vi Makefile
____ DESTDIR [same as BIN in parms.h]
____ MSTDIR [make sure it matches that used in parms.h]
____ ARCHDIR [again, make sure it matches that used in parms.h]
____ NET [This directory must already exist - where networking
programs are kept (nfxmit, nfrcv)]
____ NOTES [this must match the NOTESUID used is parms.h]
____ NOTESGRP
____ AUTOSEQ
____ [finished editing] Makefile
____ [may have to become super-user at this point]
____ make base [and assess its completion. It will tell you if
all went well]
____ [Signon as notesfile "owner"]
____ make boot [This is the final step, it should complete with a
message that the system is installed]
#
TABLE OF CONTENTS
1 Introduction......................................................1
2 Using Notesfiles..................................................1
2.1 Invocation...................................................2
2.2 Notesfile Names and Wildcards................................2
2.3 The -f Option................................................2
2.4 General......................................................3
2.4.1 Help.................................................3
2.4.2 Exiting..............................................3
2.4.3 Shells...............................................4
2.4.4 Comments & Suggestions...............................4
2.5 The Index Page...............................................4
2.5.1 Scrolling the Index Page.............................5
2.5.2 Choosing Notes & Responses...........................5
2.6 Notes & Responses............................................5
2.6.1 Reading Notes........................................5
2.6.2 Reading Responses....................................7
2.6.3 Writing Notes & Responses............................8
2.6.4 Mailing Notesfile Text...............................8
2.6.5 Forwarding Text To Other Notesfiles..................8
2.6.6 Saving Text in Local Files...........................8
2.6.7 Piping Text through Commands.........................8
2.6.8 Deletion.............................................8
2.6.9 Online Communication.................................9
2.6.10 Editing Note Titles..................................9
2.6.11 Editing Notes/Responses..............................9
2.7 Other Commands...............................................9
2.7.1 Returning to the Index Page..........................9
2.7.2 Searching Titles for Keywords........................9
2.7.3 Searching for Authors................................9
2.7.4 Stacking Notesfiles..................................9
2.7.5 Policy Note.........................................10
2.8 The Sequencer...............................................10
2.8.1 Seeing New Notes and Responses......................10
2.8.2 Automatic Sequencing................................11
2.9 Environment Variables.......................................11
3 Managing Notesfiles..............................................11
3.1 Director Options............................................12
3.1.1 Access Lists........................................12
3.1.2 Policy Note.........................................13
3.1.3 Title & Director Messages...........................13
3.1.4 Open/Close..........................................13
3.1.5 Network Options.....................................13
3.1.6 Anonymous Notes.....................................13
3.1.7 Compression.........................................13
3.1.8 Massive Deletions...................................14
3.1.9 Director Options for Notes..........................14
3.2 Creation & Deletion of Notesfiles...........................14
3.3 Intersystem Notesfiles......................................14
3.3.1 Transmitting Notesfile Updates......................15
3.3.2 Network Transaction Log.............................15
3.3.3 Non-Standard Links..................................16
3.3.4 Notesfile Name Mapping..............................16
3.4 Initial Installation & Parameters...........................17
3.4.1 Selecting Appropriate Constants.....................17
3.4.2 Compiling the Notesfile System......................18
3.4.3 User Subroutines....................................19
3.5 Installing the man(1) Documentation.........................19
3.6 Interfacing to News(I)......................................19
3.6.1 Copying News to Notesfiles..........................20
3.6.2 Copying Notesfiles to News..........................20
3.6.3 Naming Notesfiles and Newsgroups....................20
3.6.4 Space Utilization...................................21
3.7 Housekeeping................................................21
3.7.1 Automatic Removal of Notes..........................21
3.7.2 Additions to System Boot............................22
4 Other Notesfile Utilities........................................22
4.1 Hard Copy Output............................................22
4.2 Piped Insertion of Notes....................................22
4.3 User Subroutines............................................22
4.4 Statistics..................................................23
4.5 Checking for new notes......................................23
5 Summary..........................................................25
APPENDICES
A Notesfile Installation Checklist