This is work in progress. Please let me finish before editing it. This message will disappear when I have.

1. Htag HOWTO

This is a howto for the program [http://www.earth.li/projectpurple/progs/htag.html htag] which should describe in some detail how to go about setting it up along with how it works.

1.1. How htag works

Before going into the depths of configuring htag, it is useful first to understand what it is doing. Hopefully this will make configuring it easier.

1.1.1. How htag is structured

htag is divided into three main parts:

1. htag.pl
   • This is the program itself which uses the other parts

2. HtagPlugin.pm

   • This is the library which holds many useful functions shared between plugins and htag.pl
3. plugins
   • These are the main meat of the program. They are run to perform actions which lead to eventual creation of the sig.

If this sounds like overkill then it is. This is the sledgehammer solution to signature generation. It's not fast but I like it and it does quite a few cool things for me with just a little extra Perl.

1.1.2. htag.pl

These are the steps htag.pl goes through in order to generate a sig. Some of this may not make sense just yet. You may want to skim this and then come back to this section later.

1. It prints a banner announcing its version.
2. It reads the command line switches and sets up various variables. If you've not given it enough parameters it will complain at this point.
3. It runs the configfile (see later for more information)

4. It checks to see if changeheaders is set.

   1. If it is, then it checks to see if any of the regular expressions match any of the headers. If they do it runs the extra config file specified.

5. If at this stage (after having run all the chosen config files) you haven't got the plugindir option defined then it dies

6. Otherwise it will run all the plugins in the plugindir. (see the next section for how)

1.1.3. plugins

The plugins are run from plugindir once htag.pl has checked all the settings from the configfiles. Here are some points about plugins.

• Plugins MUST be named to match the Perl regular expression \d\d.+ which means two digits followed by something else.

• The digits at the start are a sort of priority similar but not identical to SysV init script directories.
  • htag.pl runs plugins starting with the lowest priority and moving to the highest in order.

  • If two or more plugins have the same priority then one of them will be randomly picked and run before moving onto plugins of a higher number.

Plugins may return special values:

• 255 means that the script wants to terminate htag.pl completely without waiting for anything. This should normally only be used by plugins that have asked the user to quit and the user has said yes.
• 254 means that the script has reached a fatal condition and needs to die but wants to allow htag.pl to ask for a keypress through nicedie. Mostly unused since the scripts can just call htagdie themselves but hey TMTOWTDI.
• Any other value means that htag.pl should set the priority to that number and go back and start from there again. This allows plugins to go backwards.

An example of this last value is probably a good idea. In the default plugin layout there are a number of plugins which each carry out their own specialised function. One picks a random tag, one picks a signature, one calculates uptime, one generates random digits and numbers and one merges all these parts together. Then we have a plugin (called asktag) which asks the user if the choice of tag is ok and if the user says no, then it returns the priority corresponding to picking a random tag and the process starts back from there. It will then reappear back at the asktag plugin and ask the user if the new tagline is suitable and so on and so forth until the user says yes, quits or heat death occurs.

1.2. Config file options

If what has come before has confused you then you probably don't need to worry about it too much. Just keep going and once you look at configuring htag you'll see it's not all that evil.

1.2.1. Prerequisites

You require:

• htag (well duh) ideally from the tarball or the debian package but other sources should be fine too.

• perl - I have a feeling you need 5.005 or higher but since even Debian stable is shipping 5.005 that shouldn't be a problem

• Imagination to create new signatures and taglines

The .htrc is where you should start configuring htag. You should really download the ["SampleHtagRC"] first (though you should have one in /usr/share/doc/htag/examples/sample.htrc.gz in Debian or in docs/sample-config/sample.htrc in the tarball.

1.2.2. Format of htrc

The .htrc file is actually parsed as Perl. Now if this scares you, please don't run away screaming just yet. You can get by without knowing Perl but with judicious use of cut and paste. If you do know Perl you can do cool stuff of your own invention in the .htrc without having to change htag.pl.

Basically the .htrc consists of lines which set up a hash called cfg. Most of the values are simple straightforward scalars (just normal variables if you don't know what a scalar is) some are array references (don't worry if you don't know what this means).

htag options may use ~ which will be expanded to /home/username.

1.2.3. Global configuration

There a few important global configuration options that are required by the default plugins:

$cfg{'plugindir'}  = "~/perl/huggietag/current/plugins";
$cfg{'debug'}      = 1;
$cfg{'tmpdir'}     = "~/.htag/";
$cfg{'tmpsigfile'} = "~/.htag/sig";
$cfg{'tmptagfile'} = "~/.htag/tag";

$cfg{'nicedie'}    = 1;  # Wait until return pressed if going to die from
                         # htag.pl

The single most important option ever is plugindir. It should be set to the directory containing the plugins from the htag tarball or package. In the Debian package the plugins are in /usr/share/htag/plugins otherwise if you're installing them locally you could just leave them wherever you unpacked the tarball say ~/htag-0.0.19/plugins for the sake of argument.

debug is useful in order to get some form of trace of what htag is doing but once htag is well configured you may grow tired of seeing this output so you can set debug back to 0.

tmpdir, tmpsigfile and tmptagfile are all related. They refer to options which are used by many of the default plugins. Basically each plugin is run separately and doesn't communicate with the others except by the files it creates, modifies or deletes. tmpdir should be a directory that is private to you and which is used exclusively by htag. tmpsigfile and tmptagfile should point at distinct files. It is easiest to just leave this as it is unless you change the directory component.

nicedie does exactly what the comment says it does. It requires the user to press a key if a plugin requests death or if any fatal error occurs. This is very useful for debugging purposes.

If you are following the sample configfile you'll notice that it next talks about Multiple Config File support. I'm going to skip over this and return to it later on.

1.2.4. catsig plugin options

$cfg{'asksig'}     = 1;
$cfg{'sigdir'}     = "~/.sigs/";
# AND/OR
$cfg['sigs'}       = [ "~/.sigone", "/home/coolguy/funny/sig" ];

# sigmatch allows you to restrict the sigs in sigdir to all those in the dir
# that match sigmatch
# e.g.
# $cfg{'sigdir'}   = "~/.sigs/";
# $cfg{'sigmatch'} = '^/home/huggie/\.sigs/(bc-.*|blackcat.*)$';
# matches all the sigs in /home/huggie/.sigs/ which start with bc- or
# blackcat.

asksig tells catsig to ask if you want to use a particular signature file at run time. This way you get to choose which signature you want. Otherwise it picks one at random for you.

sigdir specifies a directory full of signatures that you wish to use.

sigs is an array reference (i.e. you need to use the funny square brackets if you don't know Perl) of signature files. This is useful if you want to specify signature files which aren't all in one directory.

Personally I prefer to put them all in one directory. But, you say, I have lots of signature files and I don't want certain people to see my bizarre ones, so how can I pick certain ones out? Ah, well you can use sigmatch. If you just want a basic htag setup then you can ignore this. sigmatch is a Perl regular expression which is applied to all the files in turn in sigdir. Only the ones that match it are allowed through and added to the signature list.

If you specify both sigdir and sigs then first all of sigs gets added to the list then any signatures in sigdir that match sigmatch. If sigmatch isn't defined then the whole of sigdir gets added.

If you are following the sample htrc then you will see sections for grep and dadadodo plugins which can safely be ignored.

1.2.5. marknlard plugin options

Inspired by the UK's BBC Radio 1 show by Mark and Lard who kept repeating "Is it foo, Mark? Sounds just like them.". You only have to define this if you want to add such quotes to your sig (as well as taglines)

$cfg{'attributions'} = "~/perl/huggietag/current/attributions";

Defines the path to the file of attributions. The file should be in the following format:

The Famous Five:them
Buzz Lightyear:him
Woody:him

that is name of person/band/thing and then pronoun that should be used in "Sounds just like them/him/it". Yes, this is a silly plugin. Er, what you thought taglines were serious?

1.2.6. uptime plugin options

$cfg{'uptime_time'} = 1;

This option cuts down the output from full uptime output to just "up 365 days, 23:59". Again only define it if you want to add uptimes to your sigfiles.

1.2.7. date plugin options

$cfg{'date_format'} = "%d/%m/%Y";

This option tells the date plugin what format to use. It's in the form strftime would use so see the strftime manpage.

1.2.8. simple plugin options

$cfg{'tagline_comment_char'} = '#';
$cfg{'tagfile'} = "~/taglines.tag";
#$cfg{'tagfiles'} = ["~/taglines.tag","~/others"];

# You can also use tagdir to specify a directory of taglines, and tagmatch
# to restrict the tagfiles to those that match.
# The example below includes all files in /home/huggie/.tags/ except
# /home/huggie/.tags/tech

$cfg{'tagmatch'} = '^/home/huggie/.tags/(?!tech$)';
$cfg{'tagdir'} = "~/.tags";

$cfg{'fortune'} = '/usr/games/fortune';
# Probability 0 -> 1 of using fortune instead of tagline
$cfg{'fortuneval'} = 0.3;
$cfg{'fortuneargs'} = '/home/huggie/Scratch/fortunes/matrixfortunes-0.1.0/matrix';

tagline_comment_char defines the comment character used in tagfiles. i.e. if it's set to # then lines starting with # in tagfiles will be ignored.

tagfile specifies a single tagfile. It's deprecated since you can use tagfiles to do the same thing but it's there for backwards compatibility.

tagfiles, tagdir and tagmatch work in exactly the same way as sigs, sigdir and sigmatch (see [#head-e00333a76482aa64e58c1617a080567a46ae2c25 catsig options] above)

The simple plugin can also run fortune. It can either only pick taglines if the fortune options are undefined, only pick fortunes if the tagfile options are undefined or pick one or the other at random.

fortuneval specifies the probability that it will pick a fortune rather than a tagline.

fortune specifies the path to the fortune executable

fortuneargs is optional and specifies any extra arguments you want passed to fortune for instance a different fortune file.

1.2.9. merge plugin options

The merge plugin deals mostly with signature files that are not templated that is, have no @68C@ style macros in them. In this case, the tagline is merely appended to the sigfile after having been wrapped according to the following parameters.

$cfg{'maxlinelen'} = 76;
$cfg{'first'}  = "... ";
$cfg{'leader'} = "    ";
$cfg{'newline'} = 1;

maxlinelen is the maximum line length (including leader or first) that is allowed before the tagline is wrapped.

first is the leader for the first line.

leader is the leader for second and subsequent lines.

What this means is that for a tagline wrapped with first equal to "****" and leader equal to "----" you get something like:

****Foo bar foo bar foo bar foo bar
----bar foo bar foo bar foo bar foo
----bar foo bar foo bar foo bar foo

Hopefully that makes sense now.

newline is how many newline characters to insert between the sigfile and the wrapped tagline. This really does depend on what you end your sigfile with. Play and then tune it.

Again, just a reminder that any of these parameters only apply to non-templated sigfiles.

1.2.10. asktag plugin options

$cfg{'asktag'}    = 1;

asktag set to one means asktag will show you the currently merged signature with tagline and ask you if it is ok. You can quit, say yes or get a new tag. This option is recommended if you're running interactively.

1.2.11. tearline plugin options

Tearlines are a Fidonet thing really. Still they were cute and perhaps some people are nostalgic. Basically they consist of a user defined leader, the text "Htag.pl" and its version, and an optional user defined random trailer.

$cfg{'tearline'} = "OFF";
$cfg{'pretear'}  = "[+]";
$cfg{'randtear'} = [ "I'm a tree!",
                        "Boink!",
                        "Chocolate!",
                        "Fear not the penguins.",
                        "Huggable.",
                        "Kick the baby!",
                        ];

tearline can be OFF, LONG or SHORT. It's actually case insensitive anyway but hey. LONG includes the random trailer, SHORT does not, OFF omits altogether.

pretear is the leader

randtear is an array reference of random trailers.

So it goes: "PRETEAR Htag.pl 0.0.19 - RANDTEAR" for LONG and "PRETEAR Htag.pl 0.0.19" for SHORT.

Well I thought it was a nice idea at the time, ok?

1.2.12. header plugin options

$cfg{'randhead'} = [ "Hi \@F,\@B",
                     "Hiya \@F,\@B",
                     "Look! It's \@F!\@B",
                     "'ello \@F\@B",
                     "Salut \@F!\@B",
                   ];

The header plugin prints up customized headers if it can get at enough information to do so. It normally does it by parsing the To: header. It can make some annoying mistakes and there is no exception file but it works well in normal cases.

randhead specifies the headers, one of which will be chosen and placed at the top of the message but below any lines that look like message headers.

If you're wondering, the @F is replaced by the first name and @B by a carriage return. But we'll get to that later in the section of macros.

1.2.13. The Last Line

In spite of comments in the config file saying that the last line has to be "1;" it doesn't any more. Oops. I should fix this in the tarball.

1.3. Running htag

So you should now have enough knowledge to amend the htag config file but how do you run it?

1.3.1. From an editor script

The most common way to run htag is from the following script:

~/path/to/htag.pl -m $1 
#2>&1 |tee ~/.htaglog
vim $1

The commented out line enables debugging information to be saved to a file called .htaglog which can be very useful for debugging purposes.

Basically you should run htag and then your editor or your editor and then htag depending on your point of view.

1.3.2. How to test your config

If you wish to test your config however you should probably just run it from the command line so create a test message file with the following contents:

To: Simon Huggins <huggie-spam-me-harder@earth.li>

> This is a test message.  Yadda yadda yadda.

Look here's my reply!  And with a bit of luck htag will add my sig below!

Then run htag as follows and see what happens:

~/path/to/htag.pl -m ~/path/to/messagefile

If all went well then it will magically work so read on about how to create signatures, best use macros and use different config files for different people.

Otherwise:

• If it complains that "Can't locate HtagPlugin.pm in @INC" OR

• If it complains that "HtagPlugin version 0.5 required--this is only version 0.4" or similar

  • try adding a line that reads "use lib '/path/to/htag/HtagPlugin';" to htag.pl before the "use HtagPlugin 0.5;" line.

• If it complains that it "couldn't do /home/huggie/.htrc" then check that you have created this file and that it is readable to you.

• If it complains that it "Cannot open /home/huggie/htag/plugins/: No such file or directory" then you have specified the wrong plugindir in your config file.

Other error messages come from the plugins. Common problems are:

• "htag.pl: Cannot open foo: No such file or directory" i.e. your message file doesn't exist.

• "No tagfile defined! I'm good but I'm not psychic. Did you configure me at all? Look at the sample.htrc" which means what it says really. No tagfile, tagfiles, tagdir or fortune options were defined.

When you run with $cfg{'debug'}=1; in your config file you will get a trace that looks a bit like what follows which may help you identify more specifically where the problem lies:

[snip]
Running "/home/huggie/perl/huggietag/current/plugins/06marknlard"
Running "/home/huggie/perl/huggietag/current/plugins/07sesame"
Running "/home/huggie/perl/huggietag/current/plugins/08uptime"
Running "/home/huggie/perl/huggietag/current/plugins/09date"
Running "/home/huggie/perl/huggietag/current/plugins/10simple"
Running "/home/huggie/perl/huggietag/current/plugins/13substtag"
[snip]

Other output is interpersed with this.

If you are still having problems then feel free to mail me: huggie-htag@earth.li

1.4. Making signature files

Signature files are easy to make once you get a hang of the syntax. There are two types:

1. Trivial signature files have no special markup and htag just appends the tagline it chose to the end wrapping it according to [#head-34ae98839985130ac84a36e14b6c879b35c738eb merge plugin options]
2. Normal signature files are templates which say where the various pieces should be slotted in.

1.4.1. Placement of signature files

This depends entirely on your [#head-e00333a76482aa64e58c1617a080567a46ae2c25 catsig plugin options] but I would recommend creating a separate directory for signatures and using it as the sigdir option.

If you name your signatures intelligently you can use sigmatch to good effect later when we examine how to change the configuration based on the headers of the message.

1.4.2. Trivial signature files

There really isn't a lot to say about them. A trivial signature file would be:

Simon

-- 

Producing:

Simon

-- 
... "The good thing about Unix is that it's very easy to create a child on
    the fly to tell you things like that (although it's not quite as much
    fun as in real life)." - Malcolm Beattie (linux-kernel)

To configure the first line leader (the "... ") and the second and subsequent leaders see the [#head-34ae98839985130ac84a36e14b6c879b35c738eb merge plugin options]

1.4.3. Basic macros

Both types of signatures may contain basic macros:

1.4.4. Templated signatures

Templated signatures come from the basic idea that you should be able to exactly specify where to put your tagline. Essentially you create a signature file but instead of leaving a gap at the end for your signature you can have it split over as many or as few gaps as you like.

Indeed you don't even need to limit this to taglines as some of the htag plugins provide their own template macros. So let's see how they work.

1.4.4.1. Basic principles of template macros

Template macros consist of:

• an initial @ symbol
• an optional letter - no letter means reformat the tagline, the other letters correspond to a plugin
• a number representing the width of the field
• an optional alignment character which can be L for left, R for right or C for centered. If not supplied then left is assumed.
• a final @ symbol

Here are the letters that are currently defined:

When the replacement is made, any unused characters are padded with spaces. If a replacement doesn't fit then it will try to find one that does and failing that will fail and tell you.

Here are some examples:

Multiple occurrences of macros are allowed and each plugin is run however many times a macro referencing it is found. i.e. having "@D20@ || @D20R@" would when substituted in result in the date twice once left aligned over 20 characters and once right aligned, split in the middle by " || ".

Tagline macros behave differently. There is only one tagline per sig and multiple tagline macros are interpreted as meaning split the tagline up over all of these different spaces.

1.4.4.2. Example sig files

Simon.

-- 
@76R@
@76R@
htag.pl @M68R@

This is a very simple layout and it means:

• Replace the @76R@ with right aligned portions of the tagline
• Replace the @M68R@ with a right aligned Mark 'n Lard style quote

It results in the following look:

Simon.

-- 
    "Bizarre, right?  That's what you get for knowing just enough Lisp to be
                       dangerous"  -- The Camel Book (description of select)
htag.pl                            Is it Woody, Mark?  Sounds just like him.

Here is a more interesting one:

Simon.

-- 
Just another wannabie | @30C@ |  Just another fool
----------------------+ @30C@ +-------------------
This message was brought to you by @S30@.
htag.pl @V -- http://www.earth.li/projectpurple/progs/htag.html

This means:

• Replace the @30C@ with centered portions of the tagline
• Replace the @S30@ with left aligned bits from the sesame plugin
• Replace the @V with the version of the running htag.pl

Simon.

-- 
Just another wannabie | "Cardinal Fang!  Fetch... the  |  Just another fool
----------------------+  comfy chair!" - Monty Python  +-------------------
This message was brought to you by the letter J and the number 21.
htag.pl 0.0.19 -- http://www.earth.li/projectpurple/progs/htag.html

You can of course be much more creative than I am

1.4.4.3. Special option for creating sigs

If you run htag -f sigfile htag will fill the sigfile with spaces where it would normally have filled it with a tagline or plugin text. This allows you to test the sigfile quickly without going through all the questions that htag may normally ask you. It is especially helpful to you when you want to line up some complex ASCII art.