updating POD information

INSTALL

@@ -13,7 +13,8 @@ Example first time:
 
 Autogenerated files and directories:
 
-1) ./.vee :: stores all entries in here 2) ./vee.html :: entry index; the name
+1) ./.vee :: stores all entries in here 
+2) ./vee.html :: entry index; the name
 can be controlled with "-i custom.html" or "-I" which is equivalent to "-i
 index.html"
 

bin/vee

@@ -3,7 +3,7 @@
 # PLEASE SUBMIT BUGS AND REQUESTS AT:
 # 	https://github.com/estrabd/vee/issues
 
-VERSION=0.9.9-zeta
+VERSION=1.00
 
 if [ ! ${EDITOR} ]; then
   EDITOR=vi
@@ -23,7 +23,7 @@ HEADERTXT=  # text or `cat some.header.txt`
 FOOTERTXT="Powered by <a href=\"http://www.0x743.com/vee\">vee</a><br/>Copyright &copy; 2006-${YEAR}"  
 TOP_TPL=./vee-top.tpl
 BOT_TPL=./vee-bottom.tpl
-PREFORMAT_HOOK=./my-pre-hook.sh # the hook is assumed to be executable, else it is ignored
+PREFORMAT_HOOK=./vee-pre # the hook is assumed to be executable, else it is ignored
 USE_EDITOR=1
 LISTENSTDIN=0
 SORT_NEWEST="sort -t. -nr"        # sorts all new to old 
@@ -76,7 +76,6 @@ CUSTOM_SETUP=default_setup
 #
 # Contact (bugs, patches, suggestions)
 #  estrabd+vee 'at' gmail
-#  AIM: bz743
 # 
 # Instructions:
 #  1. put in directory accessible via PATH
@@ -103,7 +102,6 @@ CUSTOM_SETUP=default_setup
 #  arun   @ chat.taucher.net #bsd
 #  J65nko @ bsdforums.com
 
-# ideas:
  default_set_format_func()
 { case "$1" in
     default) FORMAT_FUNC=format_with_groff
@@ -162,7 +160,7 @@ CUSTOM_SETUP=default_setup
   echo "  -t  'title'       specify title at commandline and avoid annoying default prompt" 
   echo "  -T  file          define top template; default is ./vee-top.tpl             " 
   echo "  -v                version and exit                                          " 
-  echo "  -x  hook        defines hook if not using default "./vee-pre"; hook   "
+  echo "  -x  hook          defines hook if not using default "./vee-pre"; hook       "
   echo "                    must be executable, i.e., chmod 755 vee-pre               "
   echo "                                                                              " 
   echo "Examples:                                                                     "

pod/vee-hooks.5.pod

@@ -1,41 +1,64 @@
 =head1 NAME
 
-vee hooks
+I<vee-pre>
+
+B<There is currently no post-format hook enabled>.
+
+=head1 REQUIREMENTS
+
+A vee hook is an executable file that accepts STDIN, a single argument
+($FORMAT_FUNC), and must output to STDOUT.
 
 =head1 SYNOPSIS
 
-vee hooks
+The following is an example hook.
+
+    #!/bin/sh
 
-=head1 DESCRIPTION
+    # this filter is a null filter; meaning it spits out
+    # exactly what was passed in
 
-C<veels> is a 
+    FORMAT_FUNC=$1 # the name of the format function used is passed in
 
-=head1 COMMANDS
+    IFS=""                     # ensures that leading spaces are retained
+    while read -r IN <&0 ; do  # break after 1 sec of no stdin
+     echo "${IN}"              # echo's stdin back out so user can see 
+    done
 
-=over 4
+It be be written in anything as long as it meets the aforementioned
+L<REQUIREMENTS>:
 
-=item -x     
+    #!/bin/env perl
 
-=back
+    use strict;
+    use warnings;
 
-=head1 FILES
+    # toy filter that replaces AUBURN with an img tag
 
-none
+    my $FORMAT_FUNC = $ARGV[0]; # name of format function is passed in
+
+    while(<STDIN>) {
+      chomp;
+      if ($_ =~ s/AUBURN/<img src=http:\/\/www.emaspro.com\/Portals\/0\/images\/Logo\%20-\%20Auburn.jpg>/g ) {
+      # argv[0] is the name of the formatting function
+        if ($FORMAT_FUNC =~ m/groff/) {
+          printf("'nf\n%s\n'fi\n",$_); 
+        } else {
+          printf("%s\n",$_); 
+        } 
+      } else {
+        printf("%s\n",$_); 
+      }
+    }
 
 =head1 ENVIRONMENT
 
-=head1 DIAGNOSTICS
+Must accept a single argument, which is passed to it by I<vee>. And that is
+$FORMAT_FUNC.
 
-=head1 BUGS
+The default value of the pre-format hook is I<vee-pre>, but to change this one
+must define PREFORMAT_HOOK in I<.veerc>.
 
 =head1 AUTHOR
 
 B. Estrade L<estrabd@gmail.com>
-
-=head1 SEE ALSO
-
-I<veels>(1) 
-I<veecat>(1) 
-I<vee-rebuild>(1) 
-I<veerc>(5) 
-I<veeindex>(5) 

pod/vee.1.pod

@@ -2,24 +2,26 @@
 
 =head1 NAME
 
-vee
+    vee
 
 =head1 VERSION
 
 =head1 USAGE 
 
-vee [-b] [-t "my first post"] [-m "whooo hoo" ]
+    vee -t "my post title" [-m "check this out f00 bar herp derp" ]
+
+=head2 Batch mode
+
+    cat some_file.txt | vee -b -t "my post title"
 
 =head1 REQUIRED ARGUMENTS
 
+It is recommend to use the I<-t> flag to set the title.
+
 =head1 OPTIONS 
 
 =over 4
 
-=item -b
-
-clears the terminal screen when securerun is executed
-
 =item -b     
 
 Puts vee into batch mode, allowing it to  accept  I<STDIN>  as  the
@@ -47,7 +49,7 @@ and I<none> are supported out of the box.
 
 prints help message, then quits.
 
-=item -i custom
+=item -i I<custom.html>
 
 specifies a custom index file to use.
 
@@ -131,60 +133,116 @@ There are minimal flags and no set up is required.
 
 =over 4
 
-=item .veerc
+=item EDITOR
+
+If set in the environment, this is the editor that I<vee> will attempt to use.
+The default it I<vi> found in PATH.
+
+=item PREFORMAT_HOOK 
+
+If C<PREFORMAT_HOOK> is defined and points to an executable file that accepts
+STDIN and prints to STOUT. It is run immediately before the main formatting
+takes place.
+
+This variable must be set directly in I<vee> or in I<.veerc>.
+
+=item POSTFORMAT_HOOK 
+
+B<NOTE: This hook is currently disabled.>
+
+If C<POSTFORMAT_HOOK> is defined and points to an executable file that accepts
+STDIN and prints to STOUT. It is run immediately before the main formatting
+takes place.
+
+This variable must be set directly in I<vee> or in I<.veerc>.
+
+=item I<.veerc>
 
-Primary configuration file, see I<veerc>(5).
+Primary configuration file, read after all options are read. Settins
+overridable via commandline options.  Use I<-d> to specify a directory in which
+to look for I<.veerc>. By default, it looks in `pwd`.
 
-=item vee-top.tpl
+=item I<vee-top.tpl>
 
-=item vee-bottom.tpl
+If this file exists, it is prepended to the post. Use the I<-T> flag to define
+a top template at runtime.
 
-=item vee-pre
+=item I<vee-bottom.tpl>
 
-=item vee.index
+If this file exists, it is appended to the post. Use the I<-B> flag to define a
+top template at runtime.
+
+=item I<vee.index>
+
+The main index. It is kept properly sorted through the use of line numbers
+embedded inside of HTML comments. It may be customized, but each line must
+contain a number based on the ordering one wishes to maintain during the
+addition of a new post link. 
 
 =item .vee/*.raw
 
+These are the main record files of each post; they contain header information
+and the original unformatted text.
+
+The utilities I<veecat> is used to query these fields and I<veels> is used to
+iterate over them.
+
 =back
 
 =head1 DEPENDENCIES
 
+The idea is that I<vee> can deployed on any minimal Unix-like environment
+without the overhead of any additional 3rd-party software tools or libraries.
+
+Certainly these can enhance I<vee>, but the goal is to still have it useful and
+functional on bare systems.
+
 =head1 INCOMPATIBILITIES
 
 =head1 BUGS AND LIMITATIONS
 
+The I<sort> tool on OS X is funky and causes some weirdness in some cases.
+
 =head1 AUTHOR
 
 B. Estrade L<estrabd@gmail.com>
 
 =head1 LICENSE AND COPYRIGHT
 
+This has been released under a variety of licenses, but the one that applies
+most directly is the C<Do What the F*** You Want>.
+
 =head1 EXAMPLES
 
-=head2 Basic using $EDITOR
+=head2 Basic using EDITOR
 
     $ vee -t "title of my post"
 
-=head2 Basic no $EDITOR
+=head2 Basic no EDITOR
+
+In this example, the message body is being specified at the commandline using
+I<-m>.
 
     $ vee -t "title of my post" -m "this is the body of my message"
 
-=head2 Basic batch (no $EDITOR)
+=head2 Basic batch (no EDITOR)
 
     $ echo "this is the body of my message" | vee -b -t "title of my post"
 
-This is really useful if you want to log the output of cronjobs.
+This is really useful if you want to log the output of cronjobs or other batch
+processes.
+
+=head1 SEE ALSO
 
-=head1 FREQUENTLY ASKED QUESTIONS
+I<veels>(1)  - used to iterate over I<*.raw> files
 
-=head1 COMMON USAGE MISTAKES
+I<veecat>(1)  - used to query specific parts of a I<*.raw> file
 
-=head1 SEE ALSO
+I<vee-rebuild>(1)  - rebuilds the I<veeindex> based on the existing I<*.raw>
+files.
+
+I<veerc>(5) - the primary method of customizing the environment 
 
-I<veels>(1) 
-I<veecat>(1) 
-I<vee-rebuild>(1) 
-I<veerc>(5) 
-I<veeindex>(5) 
+I<veeindex>(5) - the HTML-based listing of posts
 
 =cut