  makeSIGN documentation
  Christian Garbs - mitch@uni.de
  v1.33.1 99-08-23

  makeSIGN is a flexible email/news signature generator. It works both
  under DOS and Linux and is licensed under the GNU GPL.  If you like
  makeSIGN, then please send me the mottoes that you use!
  ______________________________________________________________________

  Table of Contents


  1. General

     1.1 Purpose
     1.2 Requirements
     1.3 Installation
        1.3.1 Linux
        1.3.2 DOS
        1.3.3 Windows
     1.4 Copyright

  2. Using makeSIGN

  3. The commandline options

  4. Configuration files

  5. Motto files

     5.1 Header
     5.2 Mottoes
     5.3 An example

  6. Examples

     6.1 A simple call
     6.2 The simple call in more complex ways
     6.3 Using the standard output
     6.4 A standard call
     6.5 Compatibility with v1.30
     6.6 Using the header of a motto file
     6.7 Using multiple mottoes in one signature

  7. Working together with your Mail & Newsreader

     7.1 mutt
     7.2 tin
     7.3 Your software isn't listed here?

  8. Frequently Asked Questions

     8.1 Where can I find good signatures?
     8.2 How can I insert blank lines between the header/footer and the motto?
     8.3 How does the STRICT filter work exactly?
     8.4 With which return codes does makeSIGN exit?

  9. Development

     9.1 Contacts
     9.2 A look into the future
     9.3 Thanks
     9.4 History



  ______________________________________________________________________

  1.  General

  1.1.  Purpose

  The program generates a text file everytime it is run. This file may
  contain your name, your eMail-address, perhaps an URL and a random
  motto of the day.  Most eMail/News-clients can add such a signature
  automatically to each eMail or News article you send.


  1.2.  Requirements

  makeSIGN runs under Linux, plain DOS, in a Win95-DOS-box and perhaps
  under Win NT or OS/2 (If you can test it on one of these systems,
  please mail me!). You should edit the related files under the same
  environment that your eMail-client uses in order to avoid problems
  with different charsets and strange characters.


  1.3.  Installation

  Unpack the archive to a directory of your favor. If you can read this
  documentation, everything should already be fine :-) Documentation is
  found under doc/ and some example configuration are placed under
  doc/examples/.


  1.3.1.  Linux

  Take a look at global.h and edit it to your needs. Then compile
  makeSIGN with "make" and install it by "make install" (you might have
  to be root to install). The executable "makesign" will be installed
  under /usr/local/bin. The documentation will be installed at
  /usr/doc/packages.


  1.3.2.  DOS

  Due to the 8+3 limited filenames you will get problems with the HTML
  documentation. When you unzip the archive you will be prompted several
  times that the file makesign.htm already exists. You can overwrite the
  file. Be sure to use the plain text documentation (makesign.txt).

  You will find the precompiled file makesign.exe. Run it - that's all,
  no compiler is needed.

  The source code (makeSIGN is written in C) is also included. If you
  want makeSIGN to support another language than English, you have to
  compile it yourself using an different message file.


  1.3.3.  Windows

  On a VFAT system, you will not encounter the problems with the long
  file names when you use a proper extraction tool. Everything else
  corresponds to the DOS installation.


  1.4.  Copyright





  ______________________________________________________________________
  makeSIGN version 1.33beta  99-08-15  a signature generator for DOS/Linux

  Copyright (C) 1999  Christian Garbs   <mitch@uni.de>

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  ______________________________________________________________________




  2.  Using makeSIGN

  A simple call of makeSIGN looks like this:


       makesign sig.txt quotes.txt


  This will cause makeSIGN to read the file quotes.txt, pick a random
  motto from there and then write this motto to sig.txt. This file can
  then be automatically attached to your eMails (consult the manual of
  your eMail-Client on how this is done).

  It's best (especially when you're using commandline parameters) to
  call makeSIGN from within a batch file, your startup folder, your
  ~/.profile, your crontab or your autoexec.bat.


  3.  The commandline options

  makeSIGN understands quite a few commandline options. The complete set
  looks like this:


       makesign [-?SVeoqsv] [-f FOOTERFILE] [-h HEADERFILE] [--help]
       [--strict] [--version] [--equal] [--override] [--quiet] [--separator]
       [--verbose] [--footer FOOTERFILE] [--header HEADERFILE] outfile
       infile_1 [infile_2 ... infile_20]


  All of the long commandline switches can be abbreviated. The
  abbreviations look like this:











  -?   --help
  -S   --strict
  -V   --version
  -e   --equal
  -o   --override
  -q   --quiet
  -s   --separator
  -v   --verbose
  -f   --footer
  -h   --header




  (To all you Linux users out there: The case of the long commandline
  options is not important.)



     --help
        A short help with all commandline options is printed. No
        signature is generated.


     --strict
        makeSIGN will produce no signature longer than 4 lines. The
        common length of a signature is 4 lines and some people might be
        bothered if you use longer ones. The --strict option cannot be
        used when --header or --footer are set to standard input.


     --version
        makeSIGN will print its version number and exit.


     --equal
        All mottoes will be considered equal: The control lines in the
        ``motto files'' are ignored, there are neither "better" nor
        "worse" mottoes.


     --override
        makeSIGN will use the footer and header given by --footer and
        --header and will ignore the footer and header given in the
        ``motto files''.


     --quiet
        makeSIGN doesn't print any error messages. This might be useful
        if you want to pipe the signature to another program.


     --separator
        The signature is prepended by the line "-- ". This is the common
        delimiter of a signature in eMails or News articles.


     --verbose
        makeSIGN will print all status and error messages. It's mainly
        for debugging and makes the program look very busy :-)


     --footer FOOTERFILE
        The given file FOOTERFILE is appended to the random motto. If
        you set the footer file to - it will be read from standard
        input.
     --header HEADERFILE
        The given file HEADERFILE is prepended to the random motto. If
        you set the header file to - it will be read from standard
        input.


     outfile
        This is the file to where the signature is written. This
        argument must be given. If you set the output file to - the
        signature will be written to standard output.


     infile
        In these files the mottoes are stored. You can use up to 20
        files at once. At least one file must be given. The format of
        these files is described at the ``motto files'' section.



  4.  Configuration files

  To avoid long and complex commandlines you can use a configuration
  file instead. (This is mainly for DOS because it can't handle very
  long commandlines and just truncates them. If you run into this
  problem, then you must use a configuration file.)

  To use a configuration file, you must start makeSIGN like this:


       makesign configurationfile


  This will cause makeSIGN to read the given configuration file instead
  of the commandline parameters. If you set the configuration file to -
  it will be read from standard input.

  The configuration file is a simple text file. You can set the
  following options (one per line):

  (To all you Linux users out there: The case of the configuration
  options is not important.)



     STRICT=TRUE
        makeSIGN will produce no signature longer than 4 lines. The
        common length of a signature is 4 lines and some people might be
        bothered if you use longer ones. The STRICT= option cannot be
        used when FOOTER= or HEADER= are set to standard input.


     EQUAL=TRUE
        All mottoes will be considered equal: The control lines in the
        ``motto files'' are ignored, there are neither "better" nor
        "worse" mottoes.


     OVERRIDE=TRUE
        makeSIGN will use the footer and header given by FOOTER= and
        HEADER= and will ignore the footer and header given in the
        ``motto files''.


     QUIET=TRUE
        makeSIGN doesn't print any error messages. This might be useful
        if you want to pipe the signature to another program.
     SEPARATOR=TRUE
        The signature is prepended by the line "-- ". This is the common
        delimiter of a signature in eMails or News articles.


     VERBOSE=TRUE
        makeSIGN will print all status and error messages. It's mainly
        for debugging and makes the program look very busy :-)


     FOOTER=footerfile
        The given file footerfile is appended to the random motto. If
        you set the footer file to - it will be read from standard
        input.


     HEADER=headerfile
        The given file headerfile is prepended to the random motto. If
        you set the header file to - it will be read from standard
        input.


     OUTFILE=outfile
        This is the file to where the signature is written. This
        argument must be given. If you set the output file to - the
        signature will be written to standard output.


     INFILE=infile
        In these files the mottoes are stored. You can use up to 20
        files at once. At least one file must be given. The format of
        these files is described at the ``motto files'' section.


  (You can use YES instead of TRUE in all cases.)

  All in all not pretty much of a difference to the commandline
  parameters. If makeSIGN can't parse a line it will print an error. If
  you want to write a comment into the file then the line must begin
  with a '#'. Blank lines are not allowed. If you set options that
  antagonize each other (like QUIET=TRUE and VERBOSE=TRUE or multiple
  OUTFILE= lines) then the last line becomes active.

  If you want to see an example for a configuration file, then have a
  look at the ``examples'' section.


  5.  Motto files

  These files contain the quotes or mottoes that are randomly picked.
  They are simple text files that consist of a header and the mottoes.


  5.1.  Header

  A motto file starts with a header. This header must be followed by a
  blank line. If you don't want to use the header, you must still begin
  the file with a blank line. Otherwise the first motto will never be
  used.

  In the header you can give the following options:



     FOOTER=footerfile
        If a motto is picked from this particular motto file then the
        file footerfile will be used as a footer instead of the one
        given on the commandline or in the configuration file. This can
        be overriden with the OVERRIDE option. If you set the footer
        file to - it will be read from standard input.


     HEADER=headerfile
        If a motto is picked from this particular motto file then the
        file headerfile will be used as a header instead of the one
        given on the commandline or in the configuration file. This can
        be overriden with the OVERRIDE option. If you set the header
        file to - it will be read from standard input.



  5.2.  Mottoes

  Next there are the mottoes:

  Any motto may be up to 255 lines long and must be followed by a blank
  line.  The mottoes may be preceded by a control line. This control
  line can make the motto "better" or "worse" so that it is used more or
  less often as a signature.

  The control line looks like this:


  ______________________________________________________________________
   [++++]  take this motto very very often
    [+++]  take this motto very often
    . . .
    [---]  take this motto very seldom
   [----]  take this motto very very seldom
  ______________________________________________________________________




  5.3.  An example

  So, a motto file might look like this:


  ______________________________________________________________________
  #   <->  mottoes for makeSIGN  <-->  see documentation for details  <->  #
  # This is still the header. The next line is a kewl ruler.
  ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----
  # We want to use myheader.txt as the header file when a motto is picked
  # from here:
  HEADER=myheader.txt
  # The next line is blank and marks the end of the header.

  line 1 of a normal motto
  line 2 of a normal motto

  [++]
  line 1 of the next motto. This one is taken more often than the above one.
  line 2 of the second motto
  line 3 of the second motto
  line 4 of the second motto

  [----]
  line 1 of a motto that I don't like very much
  . . .
  ______________________________________________________________________

  6.  Examples



  6.1.  A simple call


  A simple call of makeSIGN looks like this:


       makesign sig.txt quotes.txt



  6.2.  The simple call in more complex ways

  The following configuration file foo.cfg does the same as the simple
  call above:


  ______________________________________________________________________
  # This is a makeSIGN configuration file named foo.cfg
  INFILE=quotes.txt
  OUTFILE=sig.txt
  ______________________________________________________________________



  To use this configuration file, you have to call makeSIGN this way:


       makesign foo.cfg


  You can also pass the configuration file to makeSIGN via standard
  input:


       makesign - < foo.cfg



       cat foo.cfg | makesign -


  DOS users would use "type" instead of "cat":


       type foo.cfg | makesign -


  The cat or type command writes the contents of the file foo.bar to
  standard output. This standard output is then piped to standard input
  of makeSIGN. To make makeSIGN read the standard input you set the name
  of the configuration file to -.


  6.3.  Using the standard output

  If you want to write the signature to stantard output, you have to set
  the signature file to -:


       makesign - quotes.txt


  The configuration file:


  ______________________________________________________________________
  #This is a configuration file for makeSIGN named foo_2.cfg
  OUTFILE=-
  INFILE=quotes.txt
  ______________________________________________________________________



  You can also redirect the standard output to a file. The following
  example does exactly the same as the simple example from above:


       makesign - quotes.txt > sig.txt



  6.4.  A standard call

  Let's have a look at the following example:


       makesign --header myheader.txt --separator sig.txt foo.txt foobar.txt
       barfoo.txt


  This will cause makeSIGN to write a separator, the file myheader.txt
  and a random motto from one of the files foo.txt, foobar.txt or
  barfoo.txt. The signature will be written to the file sig.txt.  If you
  want to use short commandline switches you would write:


       makesign -H myheader.txt -SEP sig.txt foo.txt foobar.txt barfoo.txt


  Using a configuration file it would be:


  ______________________________________________________________________
  # This is a makeSIGN configuration file named foo_3.cfg
  HEADER=myheader.txt
  SEPARATOR=TRUE
  OUTFILE=sig.txt
  INFILE=foo.txt
  INFILE=foobar.txt
  INFILE=barfoo.txt
  ______________________________________________________________________




  6.5.  Compatibility with v1.30


  If you want makeSIGN to behave like the old version 1.30 then you have
  to use these parameters:


       makesign --header personal.txt sig.txt quotes.txt


  The is equal to this configuration file:


  ______________________________________________________________________
  # This is a makeSIGN configuration file (compatibility to v1.30) named foo_4.cfg
  OUTFILE=sig.txt
  INFILE=quotes.txt
  HEADER=personal.txt
  ______________________________________________________________________




  6.6.  Using the header of a motto file

  Let's say you have two motto files, one with English mottoes
  (english.txt) and one with German mottoes (german.txt). You want to
  have a footer that fits the language of your motto (foot-eng.txt and
  foot-de.txt.

  Edit the header of the the first motto file:


  ______________________________________________________________________
  #This is the header of english.txt
  FOOTER=foot-eng.txt

  line 1 of motto 1
  line 2 of motto 1

  line 1 of motto 2
  . . .
  ______________________________________________________________________



  And edit the header of the second motto file:


  ______________________________________________________________________
  #This is the header of german.txt
  FOOTER=foot-de.txt

  line 1 of motto 1
  line 2 of motto 1

  line 1 of motto 2
  . . .
  ______________________________________________________________________



  This time you would call makeSIGN like this:


       makesign sig.txt english.txt german.txt


  You don't have to give the FOOTER option because makeSIGN chooses the
  footer file from the motto file. The equivalent configuration file:


  ______________________________________________________________________
  #This is a configuration file for makeSIGN named foo_5.cfg
  INFILE=english.txt
  INFILE=german.txt
  OUTFILE=sig.txt
  ______________________________________________________________________

  6.7.  Using multiple mottoes in one signature


  This is fun:


       makesign - quotes.txt | makesign -h -e - foobar.txt barfoo.txt >
       sig.txt


  So what have we got here... These are two makeSIGNs chained together.
  The first makeSIGN will write a random motto from quotes.txt to
  standard output. This is equal to:


  ______________________________________________________________________
  #This is the configuration file for the first makeSIGN named foo_6_1.cfg
  OUTFILE=-
  INFILE=quotes.txt
  ______________________________________________________________________



  The picked motto is then used as a header by the second makeSIGN. It
  adds a second motto from one of the files foobar.txt or barfoo.txt to
  the first one and writes everything to standard output. The standard
  output is then written to the file sig.txt.


  ______________________________________________________________________
  #This is the configuration file for the second makeSIGN named foo_6_2.cfg
  HEADER=-
  OUTFILE=-
  INFILE=foobar.txt
  INFILE=barfoo.txt
  ______________________________________________________________________



  Unfortunately, there is a problem here: A random number is always
  based on the current system time. So if you use two makeSIGNs with the
  same motto file, you are very likely to get the same motto both times.
  Try it:


       makesign - quotes.txt | makesign -h - - quotes.txt



  7.  Working together with your Mail & Newsreader


  There are two ways of attaching a signature to your Mails & News:


  o  The simple method is to attach a text file. Nearly every program
     supports this. This means that the signature will only change when
     you run makeSIGN - add either by yourself or from some kind of
     batch file (your autoexec.bat, your STARTUP-Folder or your crontab
     perhaps). Most of the Linux software looks for a signature in
     ~/.Sig by default.

  o  Some Mail & News software is able to launch an external application
     for every signature. The output of this application is then used as
     the signature. This is why makeSIGN can be configured to write to
     stdout. This allows great flexibility and a fresh signature for
     every Mail or News.


  7.1.  mutt

  mutt allows text files and external applications to be used. Just edit
  your ~/.muttrc and add the following line to it:


       set signature=SOME_FILE


  SOME_FILE might be a text file (e.g. ~/.Sig) or an application (e.g.
  makesign myconfig_file). If it is an application, the line has to end
  with a pipe symbol (|).


  7.2.  tin

  tin allows text files and external applications to be used. Start tin
  and press M to enter the setup menu. Select option 61. Create
  signature from path/command.


  To use a text file as signature, simply enter the name of the
  signature file (e. g. ~/.Sig). To use a signature generated by an
  application, enter the name of the application prepended by an
  exclamation mark (e. g.  ! ~/signature-gen.sh). To use no signature at
  all, enter --none.


  If you set option 62. Prepend signature with "-- " to ON you don't
  need to call makeSIGN with the option --separator.


  You can edit the keys default_sigfile and sigdashes in the file
  ~/.tin/tinrc respectively.


  NOTE: If you call an application to generate the signature tin adds
  the current newsgroup as an extra commandline argument. This will
  confuse makeSIGN because it looks for a signature file with the name
  of the newsgroup. To avoid this, you have to write a small shell
  skript that "eats" this extra argument and give the name of this
  script to tin.


  ______________________________________________________________________
  #!/bin/sh
  makeSIGN [your arguments]
  ______________________________________________________________________



  This provides extra flexibility. You can generate different signatures
  depending on the current newsgroup that you are posting to. Take a
  look at this script:









  ______________________________________________________________________
  #!/bin/sh

  NEWSGROUP=$1

  case $NEWSGROUP in
      de.comp.os.linux*)  SIGNATURE="sig-linux";;
      de.talk.jokes*)     SIGNATURE="sig-dtj";;
      *)                  SIGNATURE="sig-generic";;
  esac
  makesign ~/$SIGNATURE.cfg
  ______________________________________________________________________



  It uses different configuration files (~/sig-linux.cfg, ~/sig-dtj.cfg,
  ~/sig-generic.cfg) depending in the newsgroup that you are posting to.


  7.3.  Your software isn't listed here?

  Then please mail a description of how to add a signature to your
  software to mitch@uni.de

  I plan support for at least pine, knews, kmail, Netscape Messenger and
  Microsoft Outlook Express.


  8.  Frequently Asked Questions

  8.1.  Where can I find good signatures?


  I've got plenty of them, but because of political correctness I won't
  give them to you. Get your own collection started!

  If you know a short funny joke: save it. If you know a play on words:
  add it.  If you find a good signature in an eMail to you or in a News
  article: copy it.  If you run fortune and it has something good to
  say: take that, too.  Within some weeks, you will own quite a bunch of
  good signatures.


  8.2.  How can I insert blank lines between the header/footer and the
  motto?


  Add one or more blank lines to your header file. In your footer file,
  you have to leave the first line(s) blank.


  8.3.  How does the STRICT filter work exactly?


  The filter will try to match one of the following criteria (in this
  order):


  1. Quote and header are shorter than 5 lines (both are used)

  2. The quote is shorter than 5 lines (only the quote is used)

  3. The header is shorter than 5 lines (only the header is used)

  4. Neither quote nor header are shorter than 5 lines (makeSIGN will
     print an error)
  If there are enough lines left the filter will also add the footer.


  8.4.  With which return codes does makeSIGN exit?


  makeSIGN returns the following codes:


  o  01 - Not enough memory to complete operation

  o  02 - A file could not be read

  o  03 - A file could not be written

  o  04 - A file could not be closed

  o  05 - Unknown commandline parameter

  o  06 - Unknown command in configuration file

  o  07 - Header and footer can't be set to <STDIN> simultaneously

  o  08 - No inputfile given in config file

  o  09 - Too many motto files

  o  10 - There are no quotes with 4 or less lines (when using --strict)

  o  11 - --strict cannot be used together with header set to <STDIN>

  o  12 - --strict cannot be used together with footer set to <STDIN>

  0 means that everything was ok.


  9.  Development

  9.1.  Contacts

  Suggestions, bug-reports, questions, comments:


       mitch@uni.de


  Flames and the like:


       dev/null@mitch.h.shuttle.de


  My web-page is here:


       <http://www.h.shuttle.de/mitch/>


  The up-to-date version of this program can be found here:


       <http://www.h.shuttle.de/mitch/download.html#makeSIGN>




  9.2.  A look into the future



  o  So far there is nothing to add, I think. If YOU want something to
     be added, just mail me!

  o  The documentation on using makeSIGN with popular mail and news
     software will be extended.


  9.3.  Thanks


  Thanks go out to the beta-testers:


     Florian Dennert

     o  The fastest beta-tester in town!


     Blasius "Crazie Eddie" Puchala

     o  eMail: pucholski@okay.net

     o  homepage:  <http://members.aol.com/pucholski/index.htm>


     Florian "Mr. Coffee" Paetz

     o  eMail: FlorianPaetz@usa.net


     Dennis Schoen

     o  He has seen the early 1.2* versions.


  If you want to become a beta-tester then tell me.


  9.4.  History




     99-08-23  v1.33.1

     o  Added a Linux Software Map entry and submitted makeSIGN to
        MetaLab.unc.edu

     o  Fixed a bug with commandline arguments

     o  Description on how to use makeSIGN together with tin is added.


     99-08-15  v1.33beta

     o  I added the --equal option.

     o  I added the --version option.

     o  makeSIGN is now nearly concurring with POSIX 1003.2. It also
        supports long GNU-style options.

     o  makeSIGN now exits with proper exit codes.


     99-07-04  v1.33alpha2

     o  Fixed some nasty bugs.


     99-04-13  v1.33alpha

     o  I added the ``Working together with your Mail & Newsreader''
        section to this document.

     o  I added some points to the ``Frequently Asked Questions''
        section.

     o  makeSIGN is completely rewritten in C.


     99-02-04  v1.32

     o  It seems to be time for a new official release since no errors
        occured during the last weeks.

     o  I added the ``A look into the future'' section to this document.

     o  I added a file_id.diz file to the archive.


     99-01-17  v1.32beta2

     o  Bugfix: STRICT didn't work at all

     o  The compatibility mode to version 1.30 has been removed.

     o  The source code was missing in the .ZIP


     99-01-10  v1.32beta

     o  Bugfix: The short commandline parameters didn't work at all.

     o  makeSIGN is available for Linux now.

     o  You can use the standard input for footer files, header files
        and configuration files.

     o  You can use the standard output for your signature file.

     o  You can specifiy footers and headers on a per-motto-file base
        (this makes the undocumented commandline switch obsolete).

     o  You can tell makeSIGN to work quiet or verbose.

     o  Bugfix: An error is printed when using more than 20 motto files.


     99-01-02  v1.31

     o  It seems to run stable, so here's the official release.


     98-12-28  v1.31beta

     o  The documentation is now based on SGML. It can be converted to
        TXT, HTML, PS, ...
     o  Support of more than one motto-file

     o  Enhanced memory management

     o  Support of commandline parameters and configuration files

     o  The files don't have to be in one directory any more

     o  Lots of small changes...


     98-10-18  v1.30

     o  The location of makeSIGN has changed to
        <http://www.h.shuttle.de/mitch/stuff/makesign.zip>


     98-08-08  v1.29

     o  Now this documentation is available both in HTML and ASCII


     98-06-16  v1.28

     o  Now you can set "good" mottoes that appear very often and "bad"
        ones that don't (based on an idea by Florian Dennert)

     o  Bugfix: the first motto in a file was not read


     98-05-25  v1.27

     o  first official release


     08-04-25  v1.26beta

     o  now the fourth line of a motto should work


     98-04-23  v1.25beta

     o  first complete beta release including this documentation























