--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/conf/doc/bbl.rf	Mon Apr 18 23:46:02 2005 +0900
@@ -0,0 +1,201 @@
+.\"	@(MHWARNING)
+.\" @(#)$Id$
+.SC BBL 1
+.NA
+bbl \- manage a BBoard
+.SY
+bbl
+\%[+folder] 
+\%[\-shell\ program]
+\%[\-verbose] \%[\-noverbose]
+bboard
+\%[\-help]
+.DE
+\fIbbl\fR allows a \fIBBleader\fR to manage a BBoard.
+The process is relatively simple:  a \fIBBleader\fR
+invokes the \fIbbl\fR program to set\-up an environment in which the messages
+contained in the BBoard
+may be accessed as if they were messages in an \fIMH\fR folder.
+
+To do this, \fIbbl\fR, \fIincs\fR the \fIBBoard\fR
+to the folder \*(lq+bbl\*(rq, and \fIincs\fR the archives for the \fIBBoard\fR
+to the folder \*(lq+bbl/arc\*(rq.  The \fIBBleader\fR
+then gets a new shell in which \fIMH\fR
+commands (among others) may be executed.  When the \fIBBleader\fR
+is done, CTRL\-D is typed, which terminates the shell.  \fIbbl\fR then
+asks the \fIBBleader\fR
+as to how the BBoard
+should be reconstructed.
+Usually, this results in zeroing the existing \fIBBoard\fR
+file, and  \fIpack\fRing the \*(lq+bbl\*(rq folder into the \fIBBoard\fR
+file.  Similar actions are taken for the archive.
+
+The `\-shell' switch specifies what process that \fIbbl\fR should invoke
+as your command interpreter.  This need not be a rooted filename.
+If this switch is not specified,
+\fIbbl\fR looks at the envariable \fB$SHELL\fR for a value.
+If this envariable is not set, then \fIbbl\fR uses your login shell.
+
+The `\-verbose' switch directs \fIbbl\fR to type the shell commands that it
+executes to get the job done (e.g., \fIchmod\fR\0s, \fIinc\fR\0s, etc.)
+
+As \fIbbl\fR processing is most likely not intuitively obvious to most
+prospective BBoard\-leaders, a short diatribe is in order.  As pointed out in
+\fIBBleader\fR(1),
+a BBoard\-leader (of the fictitious BBoard \*(lqhacks\*(rq)
+has three primary maintenance functions: 
+.in +.5i
+
+.ti -.5i
+\fBRead the BBoard\fR
+.br
+You don't need \fIbbl\fR
+to do this, use \fIbbc\fR instead.
+
+.ti -.5i
+\fBRemove inappropriate material\fR
+.br
+Do this by running \fIbbl\fR.
+An example of this might be:
+.sp
+.nf
+\01 % bbl hacks
+\02 [ Working folder is +bbl, Archive folder is +bbl/arc ]
+\03 [ Type CTRL\-D to finish ]
+\04 % scan
+.ta \w'\05  'u +\w'20 'u +\w'10/14 'u +\w'1345-PDT 'u +\w'Reasonable Person 'u
+\05	20	10/14	1345-PDT	Silly User	Nonsensical message
+\06	21	10/14	1707-PDT	Silly User	Another one
+\07	22	10/14	2144-PDT	Reasonable Person	Legit message
+.re
+\09 % rmm 20 21
+\10 % \^D
+\11 Incorporate changes? y
+\12 Remove +bbl? y
+\13 Update archives? n
+\14 Remove +bbl/arc? y
+\15 [+inbox now current]
+\16 %
+.fi
+.sp
+In item 1, the BBoard\-Leader invokes \fIbbl\fR
+on the BBoard called \*(lqhacks\*(rq.  The \fIbbl\fR
+program responds by typing items 2 and 3 which tell the user what \fIMH\fR
+folders are being used and that a sub\-shell is now in use (respectively).
+The user does a scan of the +bbl folder
+(\fIbbl\fR sets the current\-folder to be the one with the BBoard in it.)
+and finds two messages that should be removed (numbers 20 and 21).
+The user then removes these using the \fIrmm\fR
+program (item 9) and then types a CTRL\-D to return to
+\fIbbl\fR (item 10).
+At this point,
+\fIbbl\fR
+asks how the BBoard should be reconstructed.  Item 11 asks if the contents of
+the +bbl folder should OVERWRITE the contents of the BBoard.  The user 
+responds `yes',
+that it should (hence the two \fIrmm\fR'd messages disappear).
+Next on item 12,
+the user is asked if the +bbl folder should be killed, since the BBoards
+have been successfully updated, the user answers `yes'.
+On item 13, the user is
+asked if the archives should be updated.  Since the user made no changes, the
+answer `no' is made.  (The user could have answered `yes' with no disastrous 
+effects, but knew that nothing had been updated).  Finally, on item 14, the
+user indicates that the +bbl/arc subfolder should be killed, by answering
+`yes'.
+
+.ti -.5i
+\fBArchive non\-recent material\fR
+.br
+Do this by running \fIbbl\fR.
+An example of this might be:
+.sp
+.nf
+\01 % bbl hacks
+\02 [ Working folder is +bbl, Archive folder is +bbl/arc ]
+\03 [ Type CTRL\-D to finish ]
+\04 % scan
+.ta \w'\05  'u +\w'20 'u +\w'10/14 'u +\w'1345-PDT 'u +\w'GFISHER@UCI-20B 'u
+\05	11	10/12	1905-PST	Marshall Rose	New MMail/BBck
+\06	12	10/12	1916-PST	Stephen Willson	PATH, nfinger, and ls
+\07	13	10/12	2329-PDT	G@UCI-20A	833-5122 hours
+\08	14	10/13	1045-PDT	MELLON@UCI-20B	Reporting line
+\09	15	10/13	1112-PST	Tim Shimeall	Re: 833-5122 hours
+\10	16	10/13	1045-PDT	MELLON@UCI-20B	Reporting line
+\11	17	10/13	2042-PST	Dana Roode	Ucifinger
+\12	18	10/13	2045-PST	Dana Roode	Files in /usr/restores
+\13	19	10/14	1028-PDT	WILLSON@UCI-20B	Re: term no pause
+\14	20	10/14	1345-PDT	Martin Katz	Re: term no pause
+\15	21	10/14	1707-PDT	SCRIBE@UCI-20A	Scribe Use
+\16	22	10/14	2144-PDT	GFISHER@UCI-20B	New Twemacs
+\17	23	10/15	1227-PDT	Rob Rittenhouse	Re: New Twemacs
+.re
+\18 % file +bbl/arc \-src +bbl 11\-12 17\-20 21
+\19 % ^D
+\20 Incorporate changes? y
+\21 Remove +bbl? y
+\22 Update archives? y
+\23 Remove +bbl/arc? y
+\24 [+inbox now current]
+\25 %
+.fi
+.sp
+The important command given is in item 18, in which the user \fIfiles\fR
+some messages from +bbl into +bbl/arc.  When CTRL\-D is typed, the user
+directs \fIbbl\fR
+to update both the BBoard and its archives, which does the proper action.
+As an alternate to this scenario,
+some creative \fIBBleaders\fR might use the \fIpick\fR command to do all of
+the work:
+
+.in +.5i
+.nf
+pick \-sequence select \-before \-12 \-datefield BB-Posted \-zero
+pick \-sequence select \-before \-20 \-nozero
+scan select
+refile select +bbl/arc
+.fi
+.in -.5i
+
+In order to facilitate the use of automation shell scripts,
+if the standard input for \fIbbl\fR is \fInot\fR a tty,
+then \fIbbl\fR will not ask any questions and will proceed as if
+the user's answer was \*(lqyes\*(rq for all questions.
+Hence, \fIbbl\fR may be run under \fIcron\fR\0(8) to provide for
+automatic archiving.
+.in -.5i
+.Fi
+^$HOME/\&.mh\(ruprofile~^The user profile
+.Pr
+^Path:~^To determine the user's MH directory
+.Ps
+^incproc:~^Program to incorporate a mail drop into a folder
+.Ps
+^packproc:~^Program to pack a folder into a msgbox
+.Ps
+^rmfproc:~^Program to remove a folder
+.Sa
+bbc(1), bbleader(1), bboards(1)
+.De
+`+folder' defaults to \*(lqbbl\*(rq
+.Ds
+`\-nofile'
+.Ds
+`\-shell' defaults to \fB$SHELL\fR or your login shell
+.Co
+None
+.Hi
+In the early days of the UCI BBoards facility,
+\fIBBleaders\fR actually used to run this program by hand.
+Now, this \fIbbl\fR is often run automatically by the system to perform
+automatic archiving.
+.Bu
+Note that \fIbbl\fR executes a lot of \fIMH\fR 
+commands, and as such, each of these commands can and will read
+your \fI\&.mh\(ruprofile\fR for defaults.
+Please read the \fBBUGS\fR section of \fImh\-profile\fR\0(5)
+for some hints to help you avoid many silly problems.
+
+Also, \fIbbl\fR is unforgiving in doing exactly what it is told,
+so take special care in answering \fIbbl\fR's questions.
+.En