HuggieTag 0.8 BUILD 3						22/04/1999
Author: Simon Huggins <huggie@dial.pipex.com> or <huggie@earth.li>
Web:    http://ds.dial.pipex.com/huggie/progs/huggietag/
Part of Project Purple. (http://www.noodles.force9.co.uk)

1. Introduction

  HuggieTag is a random tagline, .sig and header adder.
  It is designed to work with most mail and news clients. It should compile
  for most UNIXs and DOS.

1.1 Home page

  All the latest news, documentation and versions of HuggieTag will be made
  available from:

  http://www.earth.li/~huggie/huggietag/
  http://ds.dial.pipex.com/huggie/progs/huggietag/

  HuggieTag is also available from all sunsite mirrors in the
   /pub/Linux/system/mail/misc directory.


2. Quick Start

  HuggieTag requires a configuration file (normally .htrc but this may be
  overridden on the command line).

  There is a sample provided in sample.htrc. If you want to get started
  quickly (and why else would you be reading this section?) then copy it to
  ~/.htrc, edit the RANDSIG line to point at your current signature and
  put your tagfile in /usr/local/share/huggietag/taglines.tag

  HuggieTag is too long a name for a program like this and so the program
  name has been shortened to just `tags'.

  You will need to run tags --build to build the index file which is vital
  to the operation of the program. (See Index Files later)

  The best way to use HuggieTag is probably by running it from a script
  which your mail client calls as its editor. (See Setting an External
  Editor later)

  I use the following script which I created in /usr/local/bin/msg
  #!/bin/sh
  tags $1
  joe $1

  It's as simple as that. Please consider reading the manual in full in
  order to understand all the functions of HuggieTag. If you have *any*
  problems then please read the relevant section in the manual.

2.1 Setting an External Editor

  Please read the previous section for the script to use.

2.1.1 PINE

  To set PINE to use an external editor:

  - Run pine
  - Go to setup (S), config (C)
  - In the feature list select:
    - [X]  enable-alternate-editor-cmd
    - [X]  enable-alternate-editor-implicitly
  - Then towards the bottom change "editor" to point to your script:
    - editor                   = /usr/local/bin/msg
  - Exit and save the new configuration.
  - Send yourself a test mail to see if it works.

2.1.2 Mutt

  To set Mutt to use an external editor:

  - Edit your muttrc
  - Add (or modify if it already exists) a line which reads:
    set editor="/usr/local/bin/msg"
  (You may want to change where mutt stores its temporary files for security
  reasons. I use set tmpdir="~/tmp" where ~/tmp is only readable by me.)

2.1.3 Tin

  To set tin to use an external editor:

  - Run tin
  - Hit M to access the configuration screen.
  - Go down to the "Invocation of your editor" option
  - Change it to point to your script with a %F afterwards:
     -> 100. Invocation of your editor          :  /usr/local/bin/msg %F
  - Save this configuration


3. Configuration

3.1 Command line options

  The message HuggieTag itself gives when invoked as tags --help is:

  Usage: tags [options] message_file
  Options:
   -s, --steal message_file     - Steal tag(s) from message_file
   -b, --build                  - Build index file
   -c, --config configfile      - Use configfile instead of ht.cfg
   -t, --tag tagfile            - Use tagfile as the tag file overriding
				  default
   -h, --help                   - This help

3.1.1 Build Option

  This builds the index file. Please see the section on Index Files later.

3.1.2 Config Option

  This allows you to specify a different config file than the usual one.
  The config file is read at the time the option is encountered. Options are
  parsed left to right and so care must be taken if combining a alternate
  config file with an alternate tagline file that the tagline file comes
  *after* the config file.

3.1.3 Steal Option

  "Stealing" other people's taglines is an art which comes from Fidonet. It
  involves identifying lines which are taglines (lines starting with "...")
  and then adding them to the tagline file.
  The index file is *not* updated and must be rebuilt before the taglines
  will become available to HuggieTag. Please see the section on Index Files
  later.


3.2 Config File (htrc)

  The normal configuration file is called .htrc and would normally live in
  the users home directory.

  If HuggieTag is invoked without arguments it looks for a variable defined
  called HOME and then checks $HOME/.htrc to see if it exists.

  If you want to use a config file somewhere else, use the -c option. (see
  above)

  The options are specified by:

	OPTION		VALUE

  Some options require quotation marks around parameters.

3.2.1 FIRST Option

  FIRST defines the characters copied immediately in front of the first line
  of the tagline, if you are using the conventional signature type. (See the
  section on Signature Types later)

  It must be exactly one character less than LEADER and must be enclosed in
  quotation marks.

  FIRST 		"..."

3.2.2 LEADER Option

  LEADER defines the characters copied immediately in front of second and
  subsequent lines of the tagline, assuming you are using the conventional
  signature type. (See the section on Signature Types later)

  It must be one character more than FIRST and must be enclosed in quotation
  marks.

  LEADER		"    "

  If FIRST were "..." and LEADER "    " then a two line tag would look like
  this:

  ... Now, Mr. Simpson... Simpson, Simpson... French, is it?
      --Monty Python

3.2.3 TEARLINE Option

  A tearline is what comes after your signature and tagline. There are three
  settings for the TEARLINE option: OFF, SHORT or LONG.

  OFF    prints no tearline at all. Useful if you are using a signature with
         an embedded tagline (See the section on Signature Types later)

  SHORT  prints a tearline with just the PRETEAR, HuggieTag and the version.

  LONG   prints a tearline with the PRETEAR, HuggieTag, version, and a
         random RANDTEAR.

3.2.4 PRETEAR Option

  Printed immediately before the "HuggieTag" in the tearline. This option
  must be surrounded by quotation marks and can only be three characters
  long.

  PRETEAR	"***"

3.2.5 RANDTEAR Option

  Printed after the HuggieTag and version. These are selected randomly from
  the number available. Putting only one in the config file forces that one
  to be the only choice. This option must be surrounded by quotation marks
  and can may not exceed 56 characters long.

  RANDTEAR	"the best tagline adder ever"

3.2.6 MAXLINELEN Option		[default 76]

  Surprisingly enough the MAXLINELEN option defines the maximum line length
  you would like imposed on the reformatting of taglines. This is normally
  your screen width in characters minus a few. (I use 76 for an 80 character
  screen)

3.2.7 TAGFILE Option

  The TAGFILE option specifies the location of the tagfile you would like to
  use when one is not specified on the command line.

  This option (like the other options concerning files) does not need
  quotation marks.

3.2.8 TAGTEMP Option

  The TAGTEMP option specifies which file to use as a temporary file. $HOME
  will be expanded to the value of the HOME variable in the environment.

  HuggieTag will copy your mail into this file.

  IF YOU DON'T WANT OTHER PEOPLE TO BE ABLE TO READ YOUR MAIL, MAKE SURE
  THAT THIS FILE DOES *NOT* END UP IN /tmp

3.2.9 NEWLINE Option		[default 1]

  The NEWLINE option specifies how many CRs to add after the signature but
  before the tagline. (assuming as usual that you are using the standard
  signatures not combined signature and tagline)

3.3.0 RANDHEAD Option

  The RANDHEAD option defines random headers to be inserted at the top of
  the message. Any macros will be expanded (see Macro Expansion later)
  These options need quotation marks around them like the other text based
  options.

  RANDHEAD	"@N wrote to Huggie.@BHi @F,@B"

3.3.1 RANDSIG Option

  The RANDSIG option defines random signature files. Expansion of $HOME is
  performed as for TAGTEMP. HuggieTag chooses a random signature or, if only
  one is given, it will use that one.
  There is a limit of 50 signature files including any specified with
  SIGDIR. (This is a random number, if there is a need to increase please
  mail me)

3.3.2 SIGDIR Option

  This is an easier way of specifying many signature files, instead of
  many RANDSIG options. Simply make a directory and put all your
  signature files in it, then use SIGDIR to point HuggieTag at this
  directory. Expansion of $HOME is performed as for TAGTEMP.
  There is a limit of 50 signature files including any RANDSIG lines.
  You do not have to specify either SIGDIR or RANDSIG

  SIGDIR	$HOME/.htsigs/

NB You do not have to specify either SIGDIR or RANDSIG but you *may* specify
   both or even more than one SIGDIR. The world is your oyster? (well not
   unless you live in a bivalve mollusc)

3.3.3 FILLALLSPACES Option	[default OFF]

  This option defines the behaviour of HuggieTag when it is combining
  signatures and taglines (See the section Combined Signature and Tagline
  later).

  It can take two values either YES or NO (case sensitive). If set to YES
  then it forces HuggieTag to only choose taglines which would place
  characters in all the spaces left by the placeholders. Otherwise HuggieTag
  can choose any tagline and may leave placeholders at the end just blank.

  This option needs to be used with care. If taglines do not fit in the
  spaces provided they may never be seen and this will reduce the scope of
  your tagline file.

  You may also receive errors about too much recursion if you use this
  option and HuggieTag cannot find a tagline within the first 300 chosen
  which fits the signature.

3.3.4 PAUSEONERROR Option	[default YES]

  When HuggieTag is run from a script it is useful to be able to stop the
  script and look at the output of HuggieTag before your editor is invoked.
  This option takes either YES or NO and defaults to YES. (because no one
  reads documentation and so people would just mail me if it flashed up an
  error message and then the editor)
  Because this defaults to YES, in order to turn it off you have to place it
  at the *start* of the config file. (Otherwise the lines with errors come
  first). If there is an error in a line starting with PAUSEONERROR, it will
  keep its default value of YES. Confused yet?

4. Details

4.1 Index Files

  The very first versions of HuggieTag used to choose a random tagline by
  merely choosing a random number between 0 and the size of the tagfile,
  seeking in the tagline file, reading up to the next CR and then taking the
  next line as the "random" tagline. This led to a certain bias being
  displayed - taglines after long taglines were favoured.

  In order to avoid any bias, a new method was required. The method
  currently employed creates a file containing the locations of all the
  taglines. It also contains the number of taglines in the tagline file.
  When HuggieTag needs to pick a random tagline, it picks a number from 0 to
  the number of taglines in the file minus one and then scans through the
  index file until it finds the location of the tagline selected. Then it
  uses that number to perform just one fseek(3) on the tagline file, before
  reading in the tagline.

  This method allows HuggieTag to deal with large tagline files (over
  several megabytes) in a more efficient manner, but it means that every
  time the tagfile is modified, the index file must also be updated.

  Rebuilding the index file is very easy. You just have to give HuggieTag
  the --build (or -b) switch.

4.2 Macro Expansion

  Taglines and RANDHEAD can take advantage of the expansion of certain
  macros.

  When HuggieTag looks at a message file, it first of all checks for headers
  it recognises. These are of the form:

  To: John Smith <johnsmith@example.com>

  or PINE's:

  On Tue, 26 Jan 1999, John Smith wrote:

  When it encounters such a header it parses the first, and last names out
  of the line and stores them. They can then be accessed by using the macros
  assigned to them:

  Abbreviation   |  Meaning
       @F        |  First name
       @L        |  Last name
       @N        |  Full name
       @B        |  CR

  The last one, @B, can be used to insert a CR in a tagline or header. Be
  warned though that HuggieTag will always honour your CRs in taglines
  irrespective of whether that would "look good" or not after the
  reformatting.

4.3 Reformatting

  Both headers and taglines are reformatted by the same algorithm. How this
  happens depends on the value of MAXLINELEN. For a tagline, LEADER is
  copied into a buffer, FIRST is copied over the top of that (LEADER is one
  character longer than FIRST so the last character of LEADER remains).
  The tagline is then appended. If the tagline is longer than MAXLINELEN
  that line is terminated at the last space in the line (so that words are
  not split over lines). If there are no spaces in the line, then the line
  is just split at MAXLINELEN. This may cause problems for small values of
  MAXLINELEN.

4.4 Signature Types

  HuggieTag can be used in two different ways and this depends on the format
  of the signature file used with it.

4.4.1 Standard Use

  Normally HuggieTag adds a signature to a message file and then adds a
  tagline and then finally adds a tearline.

  This leads to results like this:

  Simon.
  ... Hey, don't call my brother a dildo! - Kyle
  [+] HuggieTag 0.7 - Fear not the penguins.

4.4.2 Combined Signature and Tagline

  When the signature contains @xx@ sequences (where x is a number),
  HuggieTag will interpret them as placeholders for a tagline. This means
  you can construct a signature which contains a tagline. This should allow
  plenty of options for people with more imagination than me.

  For instance a signature like this:

*********************************** 
*@33@* Use HuggieTag - Signature and tagline adder
*@33@* huggie@dial.pipex.com
*********************************** http://ds.dial.pipex.com/huggie

  Generates results like this:

***********************************
*"Go on, have a guess." - Holly.  * Use HuggieTag - Signature and tagline adder
*                                 * huggie@dial.pipex.com
*********************************** http://ds.dial.pipex.com/huggie

  As you can see, any placeholders which aren't used up are blanked so you
  can guarantee that there will be 33 characters in between the @ symbols.

  You can have more than one placeholder on a line and HuggieTag will start
  again, where it left off.

  You can also specify the justification used in these placeholders:

  @xx@		Align left
  @xxR@		Align right
  @xxC@		Align center (biased to the left - if there's an odd number
		of spaces to be split the extra one ends up on the right)

  This option is new in this release and so may still hold some bugs. Please
  let me know.

4.5 Fidonet Compatibility

  In order to help make HuggieTag ready for use with Fidonet, if it finds a
  Fidonet tearline of the form "---" it will add any signature, tagline and
  tearline before that so as not to invalidate the message.

  It also means that if you forward a message using PINE then the tagline
  ends up at the bottom of your comments, not the bottom of the message.


5. Problems, Bugs, and Comments

  If you have any comments, suggestions, or bug reports, please email me.

  The email address I currently use is huggie@dial.pipex.com

  I don't foresee changing this in the near future. However, in the event
  that this does change then please search for Simon Huggins or huggietag on
  the web in order to obtain my new address.

  I am interested in any feedback in order to improve HuggieTag.

6. Security

  HuggieTag deals with mail which can be a very personal matter and not
  something you want a random user to be able to see.

  To that end here are a few tips:
  - Always set TAGTEMP to be a file which is in a directory which only you
    can read (chmod 700 dir). I recommend creating a ~/tmp and setting its
    permissions to 700 and using ~/tmp/tagtemp.tmp as your setting for
    TAGTEMP.

  - Also ensure your htrc file is only writeable by you since otherwise
    people could change your signature or RANDTEAR lines leaving to a
    potentially embarrassing problem.

  - *NEVER* run HuggieTag as root. This program does lots of string
    manipulation and this is the area where buffer overflows are mostly
    likely to occur. We have done all we can to try to ensure there are no
    potential bugs of any kind but this program should not be thought of as
    "secure".

7. License

  HuggieTag is distributed under the GNU Public License a copy of which is
  included in this archive as LICENSE.



1. Introduction
  1.1 Home page
2. Quick Start
  2.1 Setting an External Editor
3. Configuration
  3.1 Command line options
    3.1.1 Build Option
    3.1.2 Config Option
    3.1.3 Steal Option
  3.2 Config File (htrc)
    3.2.1 FIRST Option
    3.2.2 LEADER Option
    3.2.3 TEARLINE Option
    3.2.4 PRETEAR Option
    3.2.5 RANDTEAR Option
    3.2.6 MAXLINELEN Option
    3.2.7 TAGFILE Option
    3.2.8 TAGTEMP Option
    3.2.9 NEWLINE Option
    3.3.0 RANDHEAD Option
    3.3.1 RANDSIG Option
    3.3.2 SIGDIR Option
    3.3.3 FILLALLSPACES Option
    3.3.4 PAUSEONERROR Option
4. Details
  4.1 Index Files
  4.2 Macro Expansion
  4.3 Reformatting
  4.4 Signature Types
    4.4.1 Standard Use
    4.4.2 Combined Signature and Tagline
  4.5 Fidonet Compatibility
5. Problems, Bugs, and Comments
6. Security
7. License
