txsig TxSig - Txoof's Signature Rotation Program Updated October 18, 2004 The latest version can be found at http://txsig.sourceforge.net Table of Contents: ================= 0) Introduction 1) Installation 1.1 Setup and Configuration 1.1.1 The Quick And Dirty First Time installation 1.1.2 The Quick and Dirty Upgrade 1.2 The Config File 1.2.1 Alternate Configuration Files 1.3 The Quotefile Directory 1.3.1 Alternate Quote File 1.4 Using txsig With Other Applications 1.4.1 Using txsig with Pine 1.4.2 Using txsig to Automatically Update ~/.signature 2) Specifics 2.1 Command Line Switches 2.2 Notes on Various Output 2.3 Errors 3) Changes 4) To Do 5) References 6) Known Bugs 7) Contact Information 0) Introduction: ================= Txsig is my own personal hack of the Unix fortune program written entirely in perl using standard modules available from CPAN. I wanted the ability to pick and choose quotes based on a rating value and fortune only supports the 'off' feature. This was a bit broad for my tastes. It's written more or less from scratch with ideas stolen from the man pages of fortune. As far as I know, it works and doesn't do anything too strange. See the 'Known Bugs' section for information on weirdness and ways to avoid it. Please read the license agreement for more information on the topic of weird operation and whose problem that might be. Remember, if your house burns down, your cat explodes, or the sun prematurely expires due to this program, it's your problem and not mine. Your mileage may vary. Feel free to contact me with any suggestions or problems or whatnot at . Please read the license agreement included in this distribution (LICENSE) before using this software. 1) Installation: ================= 1.1 Setup and Configuration 1.1.1 The Quick And Dirty First Time installation 1.1.2 The Quick and Dirty Upgrade 1.2 The Config File 1.2.1 Alternate Configuration Files 1.3 The Quotefile Directory 1.3.1 Alternate Quote File 1.4 Using txsig With Other Applications 1.4.1 Using txsig with Pine 1.4.2 Using txsig to Automatically Update ~/.signature 1.1 Setup and Configuration --------------------------- TxSig can be installed anywhere in your path. It does not need any special permissions, it only needs to be executable. TxSig can be installed for system wide use by root, or can be simply added per user. The fitness and security of TxSig have NOT been evaluated. Use at your own risk. 1.1.1 The Quick And Dirty First Time installation -------------------------------------------------- o Make sure that the first line of the script matches the location of your perl installation. Use 'which perl' to check your installation. o For an individual user, copy txsig to someplace in your home directory such as ~/scripts/. Use the command: cp txsig ~/scripts/ o Execute the following command: $] ~/scripts/txsig -i -q ~// -R o TxSig should now be ready to run o Be aware, the -R (rescan) opiton is not written to the configuraiton file. If you wish to have txsig rescan the quote directory every time it is run, you will need to manually add the line rescan=1 to the file ~/.txsig/txsigrc 1.1.2 The Quick and Dirty Upgrade ---------------------------------- o Make sure that the first line of the script matches the location of your perl installation. Use 'which perl' to check your installation. o Install txsig wherever the older version of txsig was located. o Run the command: $] /path/to/txsig -R -A o This should save your configuration files and make any updates necessary to the database file. 1.2 The Config File --------------------- By default, txsig looks for ~/.txsig/txsigrc for configuration; this file can be generated automatically by using the -i option (note, a valid quote directory or file must be specified with either -q or -f when using -i). An alternate configuration file can be created from the command line by issuing -c in conjunction with the -i option. Whitespace and comment lines (#) are ignored. Valid keys that can be used in the configuration file are as follows: datafile= - this is the location of the database file and the .cnt file. The default location and files are ~/.txsig/data and ~/.txsig/data.cnt exclude= - exclude is any file extension that you want txsig to ignore when finding quote files. This is especially useful when using files from BSD fortune. See Section 1.2 for more information. file= - a single file to draw quotes from - using this forces txsig to ignore any value for quotedir maxlines= - maximum length of quote in lines, not characters maxloops= - maximum number of attempts to choose a quote the default is 50 and appears to be adequate. Very low values here can cause txsig to bail out without choosing a quote. purgeall=0/1 - this option only works when using -R (rescan); this option causes txsig to purge all of its DB records. This is really only useful if the db becomes corrupt for some reason or when upgrading from an older version of txsig. quotedir= - location where your quotes are stored. See section 1.2 for more information rating= - maximum rating value - see section 1.2 for more information on rating rescan=0/1 - rescan the entire quote directory for changes - this is slow so txsig does not do it every time it runs. If you frequently make changes to your quotes and don't mind the delay, turn this on. I find it easier to simply run 'txsig -R' after I've made changes sigdash=0/1 - Use pine style sigdashes "--" at the beginning of the quote - 0 is off 1 is on sigfile= - file to append to quotes; this is useful if you wish to append your name and contact information to the quote when using txsig with an email client time=0/1 - turn on/off timing of execution. This is crude and inaccurate. It only measures the time from when the script is finished compiling to completion. This is annoying, you're welcome to it. 1.2.1 Alternate Configuration Files ------------------------------------ If you are using the Roles function of pine or simply wish to have a variety of configuration files available that choose from different quotes or use a different rating scale alternate configuration files can be used. At the command line specify -c . These files can be created by hand or can be generated automatically by using the -i option. When using the -i option, a valid quote directory or quote file must be specified. Any other command line options will be included in the configuration file that is specified. If you plan on using a variety of quote directories use the -d option to specify a different data file set for each directory. See the section 1.4.1 for more information regarding using multiple configurations for txsig. 1.3 The Quotefile Directory --------------------------- NOTE: The format for quote files has changed from version .12a. The index mark has moved from BEFORE the quote to AFTER the quote. See the samples in the samplefiles directory for properly formatted quotes. This change was made to make txsig 100% compatible with the files that fortune uses. Included in this release is a script called 'convert-files.pl' that will convert old style txsig quote files into the new format. Please see 'conversion.txt' for more information on using this script. IMPORTANT!!! Versions of txsig before 1.0 automatically updated their database of quotes each time the script was run. In order to speed up the process, this feature has been eliminated. In order for the quote database to be updated and to ensure that new quotes are used when added, txsig must be run with the -R option. This will rescan the entire quote base and update any files that have changed since the last time this was done. It is possible to add 'rescan=1' to the configuration file and force txsig to update its databases every time it runs, but this has a very negative impact on performance. Alternately, a cron entry can be made that updates the txsig database automatically. If the quotes are changed frequently, this is a good idea. In this example, the database is updated every day. Try man crontab for more help. 0 12 * * * /home/jsmith/scripts/txsig -R > /dev/null 2>&1 Txsig depends on having a directory full of quote files. these files are formatted much like the files that fortune uses. Each quote or fortune is followed by a '%' to mark the end. Txsig also supports an optional rating value. It is critical that txsig has permissions to read the directory that you specify as well as permissions to read everything within the directory. A sample quote file would look something like this: Stupid Flanders, you're a genius! -Homer Simpson % 3 Ohh! I bent my wookie! -Ralph Wiggum % Included in ./samplefiles are a few examples of properly formatted quote files. When creating or editing your files, make sure that there is no extra white- space at the head of the file as well as between the quotes. Whitespace is assumed to be part of the quote and is used accordingly. Notice that the first quote above has the marker '% 3'. This indicates that the quote has a rating of 3 or PG13 on a five-point scale. 0 or none - Not Rated 1 - G 2 - PG 3 - PG13 4 - R 5 - X This scale is not hard and fast, the rating value can be any positive whole number including zero (or none at all). This feature allows you to mark some quotes as more appropriate than others. Use the -r switch or the rating key word in the configuration to specify the largest (inclusive) rating value you wish txsig to use. Quotes without a rating are assumed to be NR (0). Because txsig uses the same basic format as fortune for its files, fortune files can be used with txsig. These files can be used directly by specifying the directory where fortune keeps its files (usually /usr/share/games/fortunes). Or this can be done by making symlinks in your local quote directory. Use the following command from within your quote directory to add a symlink: $] ln -s /usr/share/games/fortunes/magic ~/quotedir/magic Beware, fortune's files do not use the rating system; they will all be classified as having a rating of 0. The exclude option (-e, keyword exclude) indicates that txsig should ignore certain file extensions when creating its database. The .dat files that fortune uses most definitely should be excluded. Simply specify '-e dat' or 'exclude dat'. Do not use .dat the leading period will confuse txsig. 1.3.1 Alternate Quote File -------------------------- Alternately, a single file can be specified for txsig to draw quotes from. Use the command line switch -f or the keyword file= in your configuration file. Txsig will check these quotes for length and rating just like any other randomly chosen quote. 1.4 Using txsig With Other Applications --------------------------------------- TxSig can be used with any application that can receive data from a pipe. Some examples are listed below. If you successfully get txsig to work with a particular application, let me know. I would be happy to include the instructions in this document. 1.4.1 Using txsig with Pine --------------------------- Txsig has been tested and will work with V4.44 of pine from the University of Washington (http://www.washington.edu/pine/). Earlier versions of pine may not work with txsig as they do not support the Unix-pipe feature. To use txsig with pine, enter the setup screen (from the main menu in pine), then choose (C)onfig. Search for enable-unix-pipe-cmd and enable it with an X in the box. Now, set signature-file to the path where txsig is kept followed by a '|'. The entry should look something like this: /home/txoof/scripts/txsig | Now, any new email composed in pine should have a randomly chosen quote or an error if txsig isn't configured properly. Pine does *not* accept any command line arguments when specifying a program in the signature-file field in the configuration screen (see section 1.4.1). Creating a shell script such as the one below is a good way to work around this if you need multiple configuration files. #!/bin/bash ~/scripts/txsig -c ~/.txsig/professional_txsigrc 1.4.2 Using txsig to Automatically Update ~/.signature ------------------------------------------------------ Txsig can be used with cron to automatically update your ~/.signature file or any other file of your choice. Simply add the following entry into your crontab: # automatic update of ~/.signature every day at 1:00 AM 0 1 * * * /home/YourDir/scripts/txsig > /home/YourDir/.signature Launch crontab with: $] crontab -e For more information on crontab, see 'man crontab' and 'man 5 crontab'. 2) Specifics ============= 2.1 Command Line Switches 2.2 Notes on Various Output 2.3 Errors 2.1 Command Line Switches -------------------------- usage: txsig - [aAcCdefhilmpPqrRsStvV] -a append the source filename of the quote to the quote -A purge the database file; this option is only useful with the -R option. -c use an alternate config file - the default is ~/.txsig/txsigrc -C print current configuration to the screen -d use for the database and .cnt file - the default is ~/.txsig/data(.cnt) -e exclude when collecting quote files; this is useful when BSD fortune .dat files are present -f draw quotes only from -h this screen -i install the current configuration; -q or -f must be specified If -c is specified, the configuration will be installed in -l limit the number of attempts to choose a quote - default is 50 -m maximum number of lines for a quote -p print the DB to the screen -P print a list of all quote files and their probability of being chosen -q use as the path to the quote base -r maximum rating value for quotes. Larger numbers are potentially more offensive -R rescan the quote file directory and update the DB and .cnt file. This must be done after quote files have been updated. -s append to the end of the signature -S add sig-dashes like pine >> -- << have been changed or updated -t print the time that txsig took to run after being compiled -v set the verbosity of reporting to ~/txsig.log. Larger numbers result in more output -V show version and license information 2.2 Notes on Various Output ---------------------------- Txsig can produce copious amounts of output that is largely meaningless unless you are extremely bored. ** -C ** Using -C will cause txsig to spit out the configuration that it is using currently. See section 1.2 for information on configuration keys. Again this isn't terribly useful unless you're tracking down a problem. The only strange entry in this file may be the 'exclude' option. This is set to a more or less random value if no value is specified by the user: exclude = 1070940982 In fact, this value is actually set to the time in unix-epoch seconds at the moment that txsig was first configured; it's a sufficiently random number that won't get in the way where it might actually make a difference. Ignore this, change it to whatever you want or set it to something useful. See section 1.2 for help with this. ** -p ** The -p option will provide an output of the database file used by txsig. The output displays the path to each data file that has been scanned, the number of quotes, the mtime and the location in bits from the head where each quote ends. /home/txoof/signature/Sleater-Kinney - 4:1069786032:92,194,283,370, path - number of qutoes:mtime:offset1,offset2,offset3... This information isn't really all that valuable to the average user, but it is handy for debugging. Enjoy it. ** -P ** The -P option shows the percentage distribution of quotes. The more quotes a single file has in it, the greater probability it has of being chosen. Older versions of txsig randomly chose a file from the quote-directory and then randomly chose a quote from within that file. This meant that the quotes in small files --that is to say, files with very few quotes-- were given preference. Using the older method, if there were two files, a.txt containing 1 quote b.txt containing 99 quotes, a.txt would be chosen %50 of the time and its single quote would be displayed %50 of the time while the other 99 quotes would be shown the remainder of the time. The new weighted system used in later versions of txsig is much more fair and gives a much better distribution of quotes. The -P option simply shows the probability of one single file of being chosen. In the example below, quotes from Andrew_Bird will show up about %10 of the time. percentage distribution of quotes | | ------------------------------------------------------------- %3.23 | All | 1 ------------------------------------------------------------- %9.68 | Andrew_Bird | 3 ------------------------------------------------------------- %80.65 | Anime_Laws | 25 ------------------------------------------------------------- %6.45 | Badly_Drawn_Boy | 2 ------------------------------------------------------------- Total=100.00% There are 31 quotes to choose from. Now the drought is crippled by the rain/ that hammers on my pain/ we loose our selves again -Pissing in the Wind, Badly Drawn Boy Best regards, Aaron ** -t ** The -t option in txsig displays about how much time the script took to run *after* it was parsed and compiled. The parsing and interpreting and other fun stuff all take time and none of this is measured by the -t option. This was incorporated simply to aid in testing new versions against older ones. The output looks something like this: txsig took 0.020 CPU seconds to run This means that the script was executed in .02 seconds, this is not how much time elapsed from pressing the enter key to the final output. 2.3 Errors ----------- Details regarding errors will be reported to ~/txsig.log adding -v switch will increase txsig's verbosity and may give more hits as to why it failed. Larger numbers increase verbosity. If you receive this error: WHOA NELLY! Something is broken in your configuration! Try txsig -v 3 and then check ~/txsig.log for more information. It is most likely because the configuration is too strict; the rating and length requirements are not large enough to accommodate your quotes. When txsig draws a quote that is either rated too high or is too long, it will attempt to draw another quote; it will, by default, make 50 attempts. Try adjusting your maxlines (-m) and rating (-r) values. If all else fails, try using -v 5 and check the logs to see what txsig is doing. If you receive the error: Errors in txsig logged! Try txsig -h for help Something is very wrong with your configuration check ~/txsig.log for more information. Most likely this is due to missing files or missing configuration information. Add -v 3 if the errors logged in the log file aren't helpful enough. 3) Changes =========== See the ChangeLog for changes 4) To Do ========= o setup alternation from the command line for on/off commands such as sigdash, time, etc. 5) References ============== TxSig is based on the BSD fortune-mod version 9708 most recently hacked by Amy A Lewis . Stable versions of this can be found with most linux distributions. The fortune-mod can be used much like TxSig in the fact that a 'length' in characters can be specified on the command line. TxSig only offers 'length' with reference to the number of lines. The latest version of Pine can be found at the University of Washington http://www.washington.edu/pine/ Additional quote files can be found at www.freshmeat.net in the fortune cookies section. Search for 'fortune mod' 6) Known Bugs ============== First, a word about bugs: if you encounter a bug, please, please, please document it, try and reproduce it and most of all, send me your logs. Try -v 10 to make sure you get everything possible spewed out into your logs. Also, if you are motivated to try and fix a bug, please feel free. o In order to set the maxlines or rating value to '0' from the command line '-r 00' or '-m 00' must be used. This is due to the way perl evaluates variables; a value of '0' evaluates to false and throws off the configuration routine. Using a value of '00' solves this problem as it evaluates to true where it counts and to 0 everywhere else. I'm pretty happy with this hack for the moment. o The perl module Getopt::Std is greedy and this can cause some interesting problems if you aren't expecting it. If, for instance you used the options '-m -v 3' -m would gobble up '-v' because it is expecting any values that follow -m to be arguments. This isn't really a bug, but it is something you should be aware of. This is applicable to any command line switches that expect a value. o It is only possible to turn sigdashes on from the command line, it is not possible to turn it off if it is set as on in the config file. 7) Contact Information ======================= I would love to hear from anyone who finds this script useful or has any suggestions on how to make it better, faster, more delicious, etc. Please feel free to contact me. Aaron Ciuffo txoof@hotmail.com TxSig's Home page: http://txsig.sourceforge.net A note on Tx and what it means. I call it T - X sig. It's from a nick name that I've had for a better part of my life - Txoof. That's pronounced . That's all. Not very exciting, eh? Thanks for reading the documents, it makes everybody's life a little bit better.