|
Size: 21090
Comment:
|
Size: 209
Comment: 5
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| This is work in progress. Please let me finish before editing it. This message will disappear when I have. = 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. == 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. === How htag is structured === htag is divided into three main parts: 1. htag.pl * This is the program itself which uses the other parts 1. Htag''''''Plugin.pm * This is the library which holds many useful functions shared between plugins and htag.pl 1. 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. === 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. 1. 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. 1. It runs the configfile (see later for more information) 1. 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. 1. If at this stage (after having run all the chosen config files) you haven't got the '''plugindir''' option defined then it dies 1. Otherwise it will run all the plugins in the plugindir. (see the next section for how) === 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. == 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. === 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. === 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. === 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. === 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. === 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? === 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. === 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. === 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. === 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. === 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. === 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? === 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. === 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. == Running htag == So you should now have enough knowledge to amend the htag config file but how do you run it? === From an editor script === The most common way to run htag is from the following script: {{{ #!/bin/sh ~/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. === 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 == 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] 1. Normal signature files are templates which say where the various pieces should be slotted in. === 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. === 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] === Basic macros === Both types of signatures may contain basic macros: || Macro || Description || Output || || @F || First name || Simon || || @L || Last name || Huggins || || @N || Full name || Simon James Huggins || || @B || Line break |||| || @V || htag version || 0.0.19 || === 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. ==== 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 some examples: |
9xQdFR <a href="http://mfmfktxroejk.com/">mfmfktxroejk</a>, [url=http://jqnktqwsytcp.com/]jqnktqwsytcp[/url], [link=http://gfmzpwpoadqc.com/]gfmzpwpoadqc[/link], http://ttscppxrduth.com/ ---- CategoryRant |