.nh
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH PLOD 1 "2 November 1994" "PLOD"
.SH NAME
plod \- keep a log of your work
.SH SYNOPSIS
.B plod
\ [\ -s\ ]\ [\ -f \fIfile\fR\ ]\ [\ \fIone line message\fR\ ]
.br
.B plod
\ [\ -s\ ]\ [\ -f \fIfile\fR\ ]
\fB-C\fR|\fB-E\fR|\fB-P\fR|\fB-V\fR\ [\ \fIlogfile\fR\ [\ \fIkey\fR\ ]]
.br
.B plod
\ [\ -s\ ]\ [\ -f \fIfile\fR\ ]
\fB-g\fR|\fB-G\fR\ \fIpattern\fR\ [\ \fIlogfile\fR\ [\ \fIkey\fR\ ]]
.SH DESCRIPTION
\fBPLOD\fR
is a tool developed to help System/Network Administrators (and others)
keep track of the work that they do.  Good logs are useful both as a
personal reference and to show to your management on a regular basis
or around performance review time. By default, logs will be stored in
an encrypted format in the directory \fI$HOME/.logdir\fR, but this
behavior is completely customizable (see \fBENVIRONMENT\fR and 
\fBCUSTOMIZATION\fR below).

The first form of the command will enter a short message on the command
line into your log file.  If no message is present on the command line,
a date/time stamp will be printed and \fBPLOD\fR
will go into an interactive mode reminiscent of BSD mail.  Many tilde
escape sequences are supported (see \fBCOMMANDS\fR below or type 
\fI~h\fR or \fI~?\fR within interactive mode).  Enter a period on a
line by itself to end your log entry.

The second mode allows you to review or edit your old log files.  The
\fB-P\fR option invokes the default \fBPAGER\fR defined in the \fBPLOD\fR
source, or as defined in your environment, on the current log file.  The
\fB-E\fR and \fB-V\fR flags invoke \fBEDITOR\fR and \fBVISUAL\fR respectively.
The \fB-C\fR option will simply dump the current log file to the
standard output.  This is useful for piping your log file to other
commands, such as \fBlpr\fR.
Older log files may be accessed by specifying a file name and optional
encryption key on the command line.

The third mode allows you to search your logs for a particular pattern
but, unlike \fBgrep\fR(1), \fBPLOD\fR displays the entire log entry 
rather than just the line which matches the pattern.
The \fB-g\fR flag specifies a case-insensitive match, while \fB-G\fR
does a case sensitive search.  The \fIpattern\fR may be any valid Perl
regular expression.  Don't forget to quote the pattern to protect
any special characters from the shell.

In any mode, the \fB-f\fR flag allows the user to specify a different
startup file than the default (\fI$HOME/.plodrc\fR).  The \fB-s\fR
flag tells \fBPLOD\fR to prompt the user for their encryption key.
When making a one-line log entry, the \fB-f\fR and \fB-s\fR options must
appear first on the command line.

.SH ENVIRONMENT
\fBPLOD\fR supports a number of variables which can be modified to customize
its behavior.  The values of these variables may be changed by editing
\fBPLOD\fR directly, by assignment in a system-wide startup file, 
by creating an environment variable, or by assignment
in the user's startup file (see \fBCUSTOMIZATION\fR below).  \fBPLOD\fR
recognizes the following environment variables:
.Ip "\fBSEPARATOR\fR" 4
A string used to separate one entry from another in the log file.  This
string must be constant throughout the entire file or the \fB-g\fR and
\fB-G\fR command line options will not work correctly.  Default is
\fI-----\fR (five dashes).
.Ip "\fBSTAMP\fR" 4
The time/date stamp entered into every log entry.  Set this to null if you
do not wish to datestamp your logs.  Default is \fIMM/DD/YY, HH:MM --\fR.
.Sp
.Ip "\fBPREFIX\fR" 4
String to be prepended to each line of log entry as it goes into your log
file.  Default is the empty string.
.Sp
.Ip "\fBSUFFIX\fR" 4
String to be appended to each line of log entry as it goes into your log
file.  Default is the empty string.
.Sp
.Ip "\fBEDITOR\fR" 4
The user's preferred editor (used by the \fB-E\fR command line flag and the
\fB~e\fR, \fB~E\fR, and \fB~M\fR escape sequences).  Default is 
\fI/usr/local/bin/emacs\fR.
.Sp
.Ip "\fBVISUAL\fR" 4
The user's preferred visual editor (used by \fB-V\fR, \fB~v\fR, and \fB~V\fR).
Default is \fI/usr/local/bin/emacs\fR.
.Sp
.Ip "\fBPAGER\fR" 4
The user's preferred pager (used by \fB-P\fR, \fB~p\fR, and \fB~P\fR).
Default is \fI/usr/local/bin/less\fR.
.Sp
.Ip "\fBLINES\fR" 4
The number of lines on the current display.  Used to determine when the
\fBPAGER\fR needs to be invoked. Default is \fI24\fR.
.Sp
.Ip "\fBCRYPTCMD\fR" 4
The encryption command to be used.  If you do not wish to encrypt your
log files, set this to null.
Default is \fI/bin/crypt\fR (the standard UNIX \fBcrypt\fR command is
not in the least secure, but does provide protection from casual browsing).
.Sp
.Ip "\fBKEYVAL\fR" 4
The key to be used with \fBCRYPTCMD\fR.  Default is \fIpl<yr><mn>od\fR.
.Sp
.Ip "\fBPROMPT\fR" 4
Setting this variable to true (non-zero) causes \fBPLOD\fR to prompt
the user for their encryption key rather than using \fBKEYVAL\fR.
This is equivalent to using the \fB-s\fR flag
on the command line.  Default is \fIfalse\fR (zero).
.Sp
.Ip "\fBLOGDIR\fR" 4
Where log files are placed.  Default is \fI$HOME/.logdir\fR.
.Sp
.Ip "\fBLOGFILE\fR" 4
The name of the current log file.  \fBLOGDIR\fR will be prepended to this
value if \fBLOGFILE\fR is not an absolute path.  Default is
\fI<yr><mn>\fR.
.Sp
.Ip "\fBHOME\fR" 4
The user's home directory.  Default taken from user's password entry.
.Sp
.Ip "\fBPLODRC\fR" 4
The name of the user's startup file.  Can also be set with
the \fB-f\fR command line switch.  Obviously, there isn't a lot of
point in trying to set this in your \fI.plodrc\fR file.  \fBHOME\fR
will be prepended
to this value of \fBPLODRC\fR is not an absolute path.  Default
is \fI.plodrc\fR.
.Sp
.Ip "\fBBACKUP\fR" 4
The current \fBLOGFILE\fR is copied to \fBBACKUP\fR as the program begins
execution.  If, when the program terminates, the \fBLOGFILE\fR is gone or
zero-length, then it is replaced the the \fBBACKUP\fR copy and the current
log entry is dumped to \fBDEADLOG\fR.  Setting \fBBACKUP\fR to null disables
this feature.  The value of \fBHOME\fR is prepended if \fBBACKUP\fR is
not an absolute path.  Default is \fI.plod<pid>.bak\fR.
.Sp
.Ip "\fBDEADLOG\fR" 4
Where interrupted log entries are placed.  \fBHOME\fR will be prepended
to this value if \fBDEADLOG\fR is not an absolute path.  Default
is \fIdead.log\fR.
.Sp
.Ip "\fBTMPFILE\fR" 4
Scratch file used throughout execution of program.  Default is 
\fI/tmp/plodtmp<pid>\fR.
.Sp

.SH COMMANDS
Many tilde escape sequences are supported under \fBPLOD\fR's interactive
mode.  Users may also define their own escape sequences in \fBPLOD\fR's
initialization file (see \fBCUSTOMIZATION\fR below).  Currently defined
sequences are:
.Ip "~h, ~?" 8
Show a list of all escape sequences with a short usage message.
.Sp
.Ip "~= var[, ...]" 8
Display the current value of one or more variables.
.Ip ~e 8
Edit the current buffer with \fB$EDITOR\fR.
.Sp
.Ip ~v 8
Edit the current buffer with \fB$VISUAL\fR.
.Sp
.Ip ~p 8
Display the contents of the current buffer (using \fB$PAGER\fR if necessary).
.Sp
.Ip "~V [\ logfile\ [\ key\ ]]" 8
Call \fB$VISUAL\fR on the current log file, or on some other log file as
specified.  An additional encryption key may also be supplied.
.Sp
.Ip "~E, ~l [\ logfile\ [\ key\ ]]" 8
Similar to ~E except that \fB$EDITOR\fR is used.
.Sp
.Ip "~P, ~L [\ logfile\ [\ key\ ]]" 8
Same as ~E and ~V except that \fB$PAGER\fR is invoked.
.Sp
.Ip ~q 8
Quit \fBPLOD\fR, saving contents of buffer into \fB$DEADLOG\fR.
.Sp
.Ip ~x 8
Quit without attempting to save buffer.
.Sp
.Ip ~d 8
Append contents of \fB$DEADLOG\fR to current buffer.
.Sp
.Ip "~r somefile" 8
Append contents of file to current buffer.
.Sp
.Ip "~a somefile" 8
Append contents of current buffer to file.
.Sp
.Ip "~w somefile" 8
Overwrite file with contents of current buffer.
.Sp
.Ip "~X Perl-code" 8
Execute a line of Perl code.
.Sp
.Ip ~M 8
Invoke \fB$EDITOR\fR and execute resulting file as Perl code.  Each successive
invocation of this escape will edit the previously executed Perl code so as
to make it easier to go back and correct small errors.
.Sp
.Ip "~! command" 8
Execute a command in the shell and return.
.Sp
.Ip "~> command" 8
Append the output of a command to the current buffer.
.Sp
.Ip "~| command" 8
Pipe the current buffer through a command and replace the buffer with the
resulting output.
.Sp

.SH CUSTOMIZATION
Like most UNIX utilities, \fBPLOD\fR has an initialization file,
the \fI\.plodrc\fR,
which is read at startup.  Unlike most UNIX utilities,
this file is interpreted as Perl code.  Thus, if you wished to assign
a new value to a customization variable you would use the syntax
.RS
.PP
$LOGDIR = "$HOME/mylogs";
.RE
.PP
The location of the user startup file may changed with the \fB-f\fR
command line switch or by setting the \fBPLODRC\fR environment variable.

\fBPLOD\fR also looks for a system-wide customization file, \fI/etc/plodrc\fR.
The order of evaluation is: hard coded defaults in \fBPLOD\fR, then
the \fI/etc/plodrc\fR file, then the user's environment, and finally the
user's \fBPLODRC\fR file.

Beyond simple variable customization, the \fBPLODRC\fR file can be
used as an automatic pre-execution block and to define subroutines
that will be used during the execution of the program.  For
example, \fBPLOD\fR will attempt to execute
user-defined \fI&on_exit()\fR or \fI&on_error()\fR routines (if they
are defined) when the program terminates, depending upon whether the
program exits normally or abnormally.

Another application of this feature is to change the encryption
scheme used by \fBPLOD\fR to use some alternate (more secure) encryption
mechanism.  Encryption and decryption in \fBPLOD\fR are done
via \fI&encrypt()\fR and \fI&decrypt()\fR routines.  Both routines accept
the same three arguments:  a key value, an input file (either encrypted
or decrypted depending upon which routine is being called), and an output
file to place the result into.  The routines must return non-zero upon
success and zero on failure, and should prompt the user for an
encryption key if \fBPROMPT\fR is set.  As an example, here are the default
\fI&encrypt()\fR and \fI&decrypt()\fR routines from the \fBPLOD\fR source:
.RS
.PP
.nf
sub encrypt {
   local($key, $inputfl, $outputfl) = @_;
   local($safekey, $safeinp, $safeout);

   unlink($outputfl);

   if ($PROMPT) {	# Prompt for $KEYVAL if $PROMPT has been set
      print "File is $file.\n";
      print "Please enter encryption key: ";
      system 'stty', '-echo';
      chop($key = <STDIN>);
      system 'stty', 'echo';
      print "\n";
   }   

   ($safekey = $key) =~ s/(\W)/\\$1/g;
   ($safeinp = $inputfl) =~ s/(\W)/\\$1/g;
   ($safeout = $outputfl) =~ s/(\W)/\\$1/g;
   !(system("$CRYPTCMD $safekey < $safeinp >$safeout") >> 8);
}

sub decrypt {
   local($key, $inputfl, $outputfl) = @_;
   local($safekey, $safeinp, $safeout);

   unlink($outputfl);

   if ($PROMPT) {	# Prompt for $KEYVAL if $PROMPT has been set
      print "File is $file.\n";
      print "Please enter encryption key: ";
      system 'stty', '-echo';
      chop($key = <STDIN>);
      system 'stty', 'echo';
      print "\n";
   }   

   ($safekey = $key) =~ s/(\W)/\\$1/g;
   ($safeinp = $inputfl) =~ s/(\W)/\\$1/g;
   ($safeout = $outputfl) =~ s/(\W)/\\$1/g;
   !(system("$CRYPTCMD $safekey < $safeinp >$safeout") >> 8);
}
.fi
.RE
.PP
Note that any possible meta characters in the key or in filenames 
are protected from the shell with
backslashes before they are passed to \fIsystem()\fR.  An \fI&encrypt()\fR
or \fI&decrypt()\fR routine defined in the \fBPLODRC\fR will supercede the
default definitions in the \fBPLOD\fR source.

It is also possible for the user to create their own tilde escapes.  First,
create a subroutine which performs the desired function.  Then assign the
type glob which references that function to global array \fI%funcs\fR indexed
by the character of the escape sequence.  Any arguments that the user enters
after the tilde escape will be passed into the function as a single string
in \fI@_\fR.  The list \fI@lines\fR contains the current buffer.

As an example, here is the append to file function (~a) from the \fBPLOD\fR
source:
.RS
.PP
.nf
sub appendfl {
   local($file) = @_;
   if (!open(OUTP, ">> $file")) {
      warn "*** Could not append to file $file\\n";
      return;
   }
   print OUTP @lines;
   close(OUTP);
   print "Wrote ", scalar(@lines), " lines to file $file\\n";
   print "(continue composing note)\\n";
}
$appendfl = "file\\t\\tAppend contents of buffer to file";
$funcs{'a'} = *appendfl;
.fi
.RE
.PP
The scalar variable \fI$appendfl\fR is used by \fBPLOD\fR's help function
(~h or ~?) to provide a descriptive message about the escape sequence.
As a further example, here is \fBPLOD\fR's help function
.RS
.PP
.nf
sub helpuser {
   local($safename);
   $long = (scalar(keys %funcs) >= $LINES) && open(TMP, ">$TMPFILE");
   for (sort keys %funcs) {
      *info = $funcs{$_};
      if ($long) {
         print TMP "~$_ $info\n";
      }
      else { print "~$_ $info\n"; }
   }
   if ($long) {
      close(TMP);
      ($safename = $TMPFILE) =~ s/(\W)/\\$1/g;
      system("$PAGER $safename");
      unlink $TMPFILE;
   }
}
$helpuser = "\t\tPrint this message";
$funcs{'h'} = *helpuser;
$funcs{'?'} = *helpuser;
.fi
.RE
.PP
Note the use of various customization variables as well as the assignment
of the type glob to two different indices of the \fI%funcs\fR array.  Note
also that again we protect any meta characters from the shell.

Note that it is considered good form to \fIreturn()\fR from user defined
subroutines rather than terminating \fBPLOD\fR prematurely.  If you must
abort execution from within a routine, it is recommended that you
call \fI&PLODNormExit()\fR or \fI&PLODBadExit()\fR so that you get
both the \fBBACKUP\fR mechanism and the appropriate \fI&on_exit()\fR
or \fI&on_error()\fR call.

.SH FILES
.PP
.Ip $HOME/.plodrc 24
Default location for users' personal initialization files
.Sp
.Ip /etc/plodrc 24
System-wide initialization file
.Sp
.PP
Various other customizable file locations.

.SH SEE ALSO
.BR perl (1)

.SH AUTHORS
The original idea for \fBPLOD\fR comes from Bill Mendyka
(\fBmendyka@dg-rtp.dg.com\fR).

The current Perl implementation was developed by Hal Pomeranz
(\fBhal@deer-run.com\fR).

An Emacs mode for \fBPLOD\fR was developed by Paul Foley
(\fBpaul@ascent.com\fR), and another by Paul Hudson
(\fBpaulh@harlequin.com\fR).

Additional improvements have been suggested/developed by:
Bobby Billingsley (\fBbobby@dc.dk\fR),
David W Crabb (\fBcrabb@phoenix.Princeton.EDU\fR),
Michel Dignard (\fBdignard@ERE.UMontreal.CA\fR),
John Ellis (\fBellis@rtsg.mot.com\fR),
Bob Gibson (\fBrjg@sco.COM\fR),
Mike Lachowski (\fBmlachow@erenj.com\fR),
Eric Prestemon (\fBecprest@pocorvares.er.usgs.GOV\fR),
Erik E. Rantapaa (\fBrantapaa@math.umn.edu\fR),
Scot Schneebeli (\fBsls@tct.com\fR),
James Tizard (\fBjames@ringo.ssn.flinders.edu.au\fR),
and G. Paul Ziemba (\fBpaul@alantec.com\fR).

.SH BUGS
Any bug reports or suggestions for improvement should be submitted to
Hal Pomeranz via email at \fBhal@deer-run.com\fR.