2.9BSD/usr/contrib/notes/doc/2
.ch "Using Notesfiles"
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 character are terminated by a carriage
return.
.se "Invocation"
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 "termtype" 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.
.se "Notesfile Names and Wildcards"
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.
.se "The -f Option"
The "-f" option of the notesfile system
specifies a file of notesfile names to read.
The file consists of lines containing notesfile names:
.ne 4
.nf
nfgripes
net.unix-wizards
net.bob*
net.general
fa.telecom
ucbcad.*
!ucbcad.test
!net.bob
.fi
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":
.ne 6
.nf
-x
nfgripes
micronotes
bicycle
-s
net.*
!net.misc
.fi
.se "General"
Almost all notesfile commands require exactly one character
(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 command).
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.
.ss "Help"
Typing "?" anywhere will list the available options in
an abbreviated format.
.ss "Exiting"
Type "q" ("quit") to leave the current notesfile.
Capital "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 information).
The "k" and "K" keys function exactly as "q" and "Q".
The "z" key updates your sequencer table and exits the program.
.ss "Shells"
Fork a shell at any time by typing "!"
(just like many other Unix programs).
.ss "Comments and Suggestions"
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.
.se "The Index Page"
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:
.KS
.nf
.in +10
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
- - - - - - - - - - - - -
.in
.fi
.KE
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:
.br
.bx
.ix
Scroll the index forward or backward.
.ix
Read a note.
.ix
Write a note.
.ix
Go to the next unread note.
.ix
Search for notes or responses after a specific date/time.
.ix
Search for keywords within notes' titles.
.ix
Search for notes/responses by a specific author.
.ix
Go to another notesfile.
.ix
Read the policy note.
.ix
Register a complaint/suggestion about notesfiles.
.ix
Fork a shell.
.ix
Exit the notes program.
.ix
Invoke notesfile director options (if the user is a director).
.ix
Check whether the group is networked and if anonymous submissions can be made.
.ix
Unsubscribe from the notes group.
.ex
.ss "Scrolling the Index Page"
Scroll the index page by:
.nf
.ls 1
+ 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
.br
.ls
.fi
.ss "Choosing Notes and Responses"
While on the index page, choose a note to read by typing its number
followed by a carriage return.
(This is the only command 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.
.se "Notes and Responses"
.ss "Reading Notes"
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:
.KS
.nf
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
======================================
.fi
.KE
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 functions 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:
.br
.bx
.ix
Display the next page of the note.
.ix
Display the first page of the note.
.ix
Write a response to the displayed note.
.ix
Read next note or previous note.
.ix
Read next unread response or note.
.ix
Return to the index page.
.ix
Skip to a given response.
.ix
Delete the note (if you are its author or a file director).
.ix
Edit the note's title (if it is yours).
.ix
Edit the note (if it is yours and there are no responses).
.ix
Copy the note to another notesfile.
.ix
Save the note in your file space.
.ix
Mail the note to someone.
.ix
Talk ("write") to the author of the note.
.ix
Search for keywords in note titles.
.ix
Search for notes/responses by a particular author.
.ix
Toggle the director message (if privileged).
.ix
Fork a shell.
.ix
Go to another notesfile.
.ix
Make a comment or suggestion about notesfiles.
.ix
Exit the notesfile program.
.ix
Unsubscribe from the notes group.
.ex
.ss "Reading Responses"
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:
.KS
.nf
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...
======================================
.fi
.KE
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:
.bx
.ix
Display the next page of the response.
.ix
Display the first page of the response.
.ix
Go to a different response (usually the next one).
.ix
Go to the next unread note/response.
.ix
Reread the base note.
.ix
Reread the previous note.
.ix
Return to the index page.
.ix
Copy the response to another notesfile.
.ix
Mail the response to someone.
.ix
Save the response in your file space.
.ix
Talk to the response's author.
.ix
Write another response to the note.
.ix
Search for keywords in note titles.
.ix
Search for notes/responses by particular authors.
.ix
Delete the response (if you are its author or a file director).
.ix
Edit the response (if it is yours and there are no later responses).
.ix
Fork a shell
.ix
Go to another notesfile.
.ix
Register a suggestion or complaint about the notesfile program.
.ix
Exit the notesfile program.
.ix
Unsubscribe from the notes group.
.ex
.ss "Writing Notes and Responses"
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 various 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.
.ss "Mailing Notesfile Text"
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 anyone. 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 variable
MAILER. If this is not set, the standard mail program is used.
.ss "Forwarding Text To Other Notesfiles"
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 different 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.
.ss "Saving Text in Local Files"
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.
.ss "Piping Text through Commands"
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).
.ss "Deletion"
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.
.ss "Online Communication"
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.
.ss "Editing Note Titles"
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).
.ss "Editing Notes/Responses"
"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.
.se "Other Commands"
.ss "Returning to the Index Page"
Type "i" ("index") while reading notes or responses
to return to the index page.
.ss "Searching Titles for Keywords"
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.
.ss "Searching for Authors"
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 system is specified, local authorship is assumed.
Abort the search by hitting the RUBOUT (or DELETE) key.
.ss "Stacking Notesfiles"
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 notesfile.
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 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.
.ss "Policy Note"
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.
.se "The Sequencer"
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;
sometimes 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.
.ss "Seeing New Notes and Responses"
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 uninteresting,
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.
When no more new notes or responses exist, both the
"j" and "J" commands will take the user to the index page.
Two other commands useful with the sequencer are "l" and
"L". "l" works much like "j" in that only modified note strings
are displayed. However unlike "j", "l" will display all continuation
pages of the note before proceeding to the next note string.
Also, upon visiting the last page of the last modified note string,
"l" will cause an exit with update. "L", analogous to "J",
jumps to the next modified base note or exits if there are no
new notes.
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.
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).
Another possibility is to exit with "z". This
forces an immediate exit like control-D but in
addition updates the sequencing information.
.ss "Automatic Sequencing"
An alternate entry to the notes program
allows the user to invoke notes with the sequencer enabled and a list
of notesfiles to be scanned with a single,
simple
command.
The "autoseq" command is invoked by typing
autoseq
This is equivalent to typing "notes -s" or using the "-s" sequencing
mode; the user only enters notesfiles which have new text.
By typing "-x" or "-i" on the command line, the user can
specify other sequencing modes as well.
.se "Environment Variables"
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.
.bx
.ix
"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 environment variable "EDITOR" (which many other programs use).
If neither "NFED" nor "EDITOR" are defined, a default editor is
used (/bin/ed).
.ix
"PAGER" is the paging program ("more", "pg") which is used for scrolling
the help files.
The default paging program is /usr/ucb/more.
.ix
"MAILER" determines the mail program to use. If undefined, this defaults
to /usr/ucb/mail.
.ix
"WRITE" is used to specify the program for communication between users.
If undefined, the Unix program "write" is used.
.ix
"TERM" determines the type of terminal in use. This must be set
for notes to know what screen addressing conventions to use. In most
cases the value will be correctly initialized by the system at login
time.
.ix
"SHELL" specifies which shell the user is running.
This will almost always be set by the operating system.
.ex