Shareware Supreme Volume 6 #1/swsii.zip/swsii/151/ANNEX10E.ZIP/ANNEX.DOC

Text File | 1993-03-03 | 29KB | 610 lines

                                                                     3/3/93
                                Annex 1.0e

                         Written by Jason Bassford



                             - Introduction -

   Annex will interpret the message header information produced by OLX and
any other compatible mail reader (not that I know of any - if you do I'd
appreciate knowing about it) and manipulate it in just about any way that
you wish.  Such information is further broken down into such specific
things as the 24 and 12 hour time, whether it is "am" or "pm", just what
century it is (something that will come in handy should a variation of
Annex still be in use 8 years from now...) and even the proper "suffix" to
use with the day of the month (1st, 2nd, 3rd, etc.).  This manipulation
will allow you to configure whatever header and footers you might want to
appear in your messages.
   You will be able to determine how Annex will interpret a person's name
in the header that it uses.  You may want it to be all in Caps or only the
first letter, or you may even want to change it completely so that
whenever a certain name appears the header reads, "My friend was talking
to me about..." instead of "Michael Smith was talking to Jason Bassford
about..."  Every time Annex encounters a name that its not familiar with
it will stop and prompt you to enter what you would like it to use in
place of it.  Once it knows what you want it to use it will then use that
"association" automatically.
   In addition to the standard forms of headers, Annex also supports
special Internet headers that are sometimes required by BBSs in order to
properly send Internet mail.  In this way you can Reply to a message in
OLX and never worry about having to enter their Internet address before
writing your message to them.  (Lord knows, before I wrote Annex I more
than once had Internet mail bounced back to me because I'd forgotten to
include the recipient's Internet address in the body of a message...)
   (Note that both normal and Internet headers will not be available if the
message you are writing is *new*.  Headers are only possible if you are
replying to an existing message for which OLX has the necessary
information to pass on to Annex.  Footers, on the other hand, are always
available.)
   The footer section of Annex lets you control the format that you wish
to use for your taglines, and any other additional "footer" messages you
might wish to include, such as placing your signature before the tearline
in the actual message itself.  The one thing to be aware of about Annex's
tagline manipulation is that the taglines it uses are selected at random
by the program.  If you want to get a *specific* tagline to be used with
your message there is a fairly simple method to do so (which is described
at the end of this document) but it is not as simple as it would be with a
program designed solely to manage your taglines.  If what you are
interested in is simply a tagline manager then Annex 1.0 probably isn't
going to be what you're looking for.



                              - Background -

   This is an OLX/SLMR header and footer utility that I have been working
with, on and off, since the Summer of '92.  It all started with a friend
of mine who innocently suggested that I create a small header utility for
him to use with his OLX messages.  Once I started he kept suggesting more
features he'd like to see it have, and I also came up with some of my own
ideas.  When the header portion of Annex was finished I put the project
aside for a while as I was busy with other things and the reason it had
been created in the first place was solely as a header utility.
   Then I happened to order OLX 3.0 along with the new Qmodem Pro from
Mustang Software.  While I'm quite happy with both products, I was
dismayed to realize that the tagline signature OLX used was "QMPro 1.0
41-4932".  Not only did I not want the serial number in my taglines (as it
takes up too much space for my actual tags to comfortably fit) but I also
wanted it to instead display "OLX" - which program is the real reason I'd
ordered the upgrade package in the first place.  So after trying
unsuccessfully to sway the MSI staff to send me a "patch" of some sort to
address these problems, I decided to just go ahead and write my own
footer/tagline utility that would let me do what I wanted.  In short, I
picked up my earlier work on Annex once more.



                               - Licensing -

   There are several things that you should note about this utility. First
of all, and probably most important right now, is that I am distributing
this as Shareware.  Yet, is not crippled in any way and, contrary to the
normal concept of Shareware it isn't in any way different from the
registered version.  In fact, there *is* no "registered" version per se -
the program that exists here is exactly what I am currently working with
on my own machine.  Why then do I call it Shareware?  Simply because I
will put "registered users" on a list for the purposes of any future
releases that I might distribute.  I will take note of any registered
user's comments and suggestions for future versions, and offer any support
that is necessary in order to get it running smoothly.  If it becomes
apparent that there is a bug in the program that requires me to distribute
a maintenance release (while I've tested it extensively myself there is
always this possibility with different machines) I will mail this directly
to everyone on my list as soon as possible.  Anyone wishing to register
Annex need only send me a note informing me of this.  Other than the cost
of the postage stamp <grin> this process is free.
   Also, I do *not* distribute this along with my permission for the
program to be rewritten or altered in any way.  It is to be used *as is*,
and any changes to it have to come through me.  Additionally, if this is
distributed to a BBS (and I *do* encourage this) it should contain all of
the files that are listed later in the "Installation" section.  In other
words, it must be uploaded just as you downloaded it.  I'm not familiar
with the legalities involved here, however I can tell you that at the very
least I would be considerably "upset" if I find these conditions of use to
be ignored by someone.  I'm not sure just what action I would take,
although it would most likely not be pleasant. <grin>



                                - History -

Annex1.0a:

   This is a maintenance release for Annex 1.0 which I discovered, much to
my horror after I had uploaded it to various BBSs, contained some out of
date code, resulting in some program bugs.  Please accept my apologies.


Annex1.0b:

   This release allows for the configurable placement of footer text
before as well as after the message's tearline.  This will allow you to
place custom signatures in the body of your message, followed by a
tearline and then whatever tagline you want.


Annex1.0c:

   Now allows you to bypass a given name in the To: or From: field if it
is not found on file.  This allows you to reply to someone that you think
you might only correspond with once or twice, or quote messages from
bounced email, without unnecessarily increasing the size of your name
association file.  Also it now incorportates the proper stripping of *all*
footer text when a message is re-edited, rather than just the tearline and
everthing following it, and it will recognize "PACKET:" as well as "BBS:"
in the OLX field.


Annex1.0d:

   Corrects a specific problem with storing newly discovered names to file
that appeared in the previous version.


Annex1.0e:

   Fixes the incorrect handling of the weekday name during the month of
February.  This error was not spotted until that month just recently came
around and somebody pointed it out to me.



                             - Installation -

   The following files should be included in annex10.zip:

annex.doc   -  Annex documentation.  You're reading it.  (I always thought
               that this entry was pretty self-evident. <grin>)
annex.bat   -  A sample batch file showing how to implement Annex.  It
               will have to be modified to suit your text editor and other
               setup parameters.
header.exe  -  The program that produces header text in your messages.
header.txt  -  The text file controlling what the header text will look
               like.
header.net  -  The text file determining the format of any Internet header
               message.
footer.exe  -  The program that controls footer text.
footer.txt  -  The text file controlling what the footer text will look
               like.

   Copy all of these files to your OLX directory (although the program
will work just fine without annex.doc, you might want to keep it for
reference anyway).  To get Annex to work you have to tell OLX to run a
batch file in the Editor section of the Options (or Configuration) menu.
This batch file will first run the header program, then whatever text
editor you use, and finally the footer program.  I have called the batch
file that I use "annex.bat", although you can always name yours something
else if you wish.  This is what my OLX setup looks like:

Editor command line    c:\olx\annex

Quoted original message file REPLY.MSG
File to take reply text from REPLY.MSG

   And the following is what my included "annex.bat" file contains in order
to run Annex with OLX 3.0:

@echo off
cls
cd \olx
header %1
b %1
footer tagline.olx %1

   Note a couple of things here.  First of all the batch file changes
directories to the main OLX directory (in which the Annex files are to be
found).  If the directory in use is not the OLX directory Annex will not
work properly.  Secondly, make sure that you edit the OLX pathnames
appropriately, as according to your own setup.  The "b %1" line simply runs
my text editor - you should replace this with whatever commands are
necessary to run your own editor.  Lastly, this should work as-is with
earlier version of OLX also.  The only difference I would make if I
weren't using 3.0 is that I would add a line to run an external spell
checker (mine used to be "spell %1") after the last line.



                - Additional Installation Checklist -

   1. Configure OLX to include its own header information in its quoted
      replies.  Refer to the Replies section of the Options (Configuration)
      menu.

   2. Turn OLX's own taglining off by setting the Enable Taglines to "Off"
      in the same section as above.

   3. Make sure that the date format that OLX uses is MM-DD-YY.  If you
      don't, Annex will not properly interpret the information.

   4. If you are using an editor like Qedit which can place an end-of-file
      character (normally appearing as a "" or "" character) in the
      document, Annex will not properly create its footer text.  You must
      disable this function on your text editor.  If this is not possible
      than your text editor will not be fully compatible with Annex.



                              - Using Annex -

   As the program runs it will create a file called "header.inf" which
contains a list of names and the associations that you assign to them.  At
first, Annex will keep interrupting itself before writing the header
information and prompt you to enter how you want all of the new names not
found in this file to appear in your replies.  As your list of names grows
though this will happen less often, as it finds fewer new names, and it
will quickly be mostly invisible.



                          - The Header Program -

   If it finds a name that is not in the "header.inf" file, it will tell
you this and ask you how it should be handled.  There are several options
here.  One of these is to simply use a format of the name in which the
first letter of each "word" is in Capital and all others are in small
case.  Another allows you to enter a different format than this "default"
if you so wish.  Say that the name it is looking at is "MICHAEL SMITH".
You would see the following:


   Name not found in data file.  Please choose from the following
header formats for future use.


┌───────────────────┐
│ 1 - Michael Smith │
└───────────────────┘
     (2 - Do Not Save)

┌─────────────────────────────────────┐
│ 3 - Custom Format / Internet Header │
└─────────────────────────────────────┘
     (4 - Do Not Save)


   Enter choice:


   The first option is self-explanatory and what I use almost all the
time. However, say that Michael prefers being referred to as "Mike".  If
you wanted it to automatically put "This message was from Mike..." then
you would select "3".  You will now see a screen that looks like this:


The original name is 'MICHAEL SMITH'.


  Enter the new name:

    Internet address:


   (The cursor will be right after the "Enter the new name:" line.) You
would enter "Mike Smith" on the first line.  When you reached the second
line it would change to read:

    Internet address: [None]

   At this point you would simply hit <Return>, as we are not dealing with
Internet E-Mail in this example.  From then on whenever Annex encountered
the name "Michael Smith", it would replace it with "Mike Smith" in the
body of your header text.  If you later decided that you wanted to change
the association (Michael decides he wants to be more formal) you'd only
have to load the "header.inf" file into your text editor and edit it
manually - it is sorted alphabetically by first name.  If you have to edit
an "Internet" name, be sure to follow the format that the file uses for
those (you will see it when you look).



                          - Not Saving Name Entries -

   You will note of course that there are two other options that you can
use if Annex doesn't know what to do with a given name: both of these read
"Do Not Save".  These options simply allow you to use a given name in the
header of your reply to that person, but to *not* add an entry for it to
Annex's list of known names.  This can be very useful if you want to quote
a message from someone you know you'll never correspond with and send the
quote to someone else.  Say I come across a message in my mail packet from
"The Australian Outback Co." describing the equipment it offers and how
much everything costs.  I want to quote this message to a friend of mine
because I know she's interested in that sort of thing, but I don't want to
add an entry for the company into my header.inf file because I'm pretty
sure I'll never have to use it again, and I want to keep that file's size
as small as possible.  So, if I wanted to use the "default" format for the
name (without also permanently saving it), I would select "2" rather than
"1".  Similarly, if I wanted to change the "Co." to "Company" I would
select "4" rather than "3".
   As a point of interest, if you *do* select "4" then the "Custom Format/
Internet Header" screen will look just like it does in the explanation
example except that it will now appear with an additional line of text:


    Internet address:


   ┌───────────────────────────────┐
   │ This entry will not be saved. │
   └───────────────────────────────┘


   This only serves to reassure you that Annex is indeed only going to use
the header name temporarily as you had instructed it to do.



                      - Internet E-Mail and Headers -

   I don't know if you have dealt with this before or not.  It's private
mail that you send to people at certain "Internet addresses".  For
instance, my own Internet address is "[e-mail]".  If I were
to send you Internet E-Mail, OLX would display it as being "From:
[e-mail]".  This, obviously, is not what you want put in
the header line.  So, when prompted, you would select the second option
and make my new name "Jason Bassford".  However, if you wanted to send
Internet E-Mail back to me (as you probably would) the procedure for this
is a bit more complex.  What I have to do on *my* BBS (and I think it's
similar for other bulletin boards) is to make the To: line in OLX read
"USENET GATEWAY".  Then, in the body of the message, my first line is
"To: " followed immediately by the person's Internet address, and then a
blank line.  On the third line the actual message can start.
   So, if you want to send me Internet E-Mail, rather than just hitting
<Return> to go past the "Internet address: [None]" line, you would enter
my address ("[e-mail]").  Header will then create *two*
headers.  One for Internet and the other for the normal message.  In this
case it would read something like this:


To: [e-mail]

The following was said by Jason Bassford...


   Just as you may alter the header text by changing the file "header.txt"
you may alter the Internet header text (I wasn't sure if it always
followed the "To: address" format so I allowed for it to be changed too)
by modifying the file "header.net".
   Note that you may have more than one entry for the same person in
certain circumstances.  For instance, I have a friend who writes to me
both via Internet and on some network Conferences.  Hence, I have an
association for "GLEN CAMPBELL" as well as for "GLEN.CAMPBELL@ROSE.
COM".  Remember, it's the *name* not the person that the program
recognizes.

   (Special note:  Due to a programming "glitch" that I'm aware of there
is a potential problem with editing the Internet address.  You cannot
change the *first* character of the address directly.  Say, for example,
that I had meant to type "glen" but instead typed "flen".  In order to
correct such a mistake, you have to delete everything after the first
character (in this case only the "f" would remain) and then hit <Enter>
*as if* this were correct.  The program will return to it's previous state
and prompt you again for the correct address.)



                    - Creating Header and Footer Text -

   Header and footer text is generated by editing text files (header.txt
for headers, header.inf for Internet headers, and footer.txt for footers).
The text in these files will be read and placed in your messages at the
appropriate places. Things like the name of the person the message is
from, the date it was sent, or, as in the case of a footer, the date the
reply was written, are represented by "variables", as explained below.
Right now header text will word-wrap at 70 characters.  I haven't yet set
this up to allow the user to change this value.  (If any interest is
expressed in having this value changed, I will send a "patch" to any
*registered* user that requests it.)  So, if a word goes past 70
characters it will jump down to the next line.  I set it at 70 (as I have
my text editor for all E-Mail messages) so that it is easily quotable, not
going past the right 80 column margin.  Footer text will *not* word wrap.
Due to it's nature this would not be advantageous in my opinion (although
I'd be happy to hear any comments if you feel otherwise).  So it is up to
you to monitor the length of individual footer lines.



                      - Header and Footer Variables -

   Even though the text may appear on separate lines in the text files it
will *not* be treated as being as such when read in as a header or footer.
For instance the following

On
three
lines.

would appear on one line only: "On three lines."  To make it appear on
three separate lines you must explicitly put in carriage returns.  To tell
Annex to put in a carriage return you would put a carriage return
"variable" into the text.  All variables are enclosed by "|" characters
(located above the "\" key).  So, to get the above on three separate lines
our text file would look like this:

On|CR|
three|CR|
lines.

   And, if this is header text, to get the actual message to appear
following it and a blank line, you would need to add a "|CR|" both to the
end of the last line as well as another one after that. (Also note that I
could have just as easily written all of the above on one line
(On|CR|three|CR|lines.) and it still would have come out as three lines in
the end. It's purely for the sake of readability that I would choose the
first format.)
   If for some reason you wish to actually include a "|" character in the
text of the message you can do so by using two in a row ("||").  Also, if
you do not use a "legal" variable it will appear as text (if you made a
typing mistake and used "|C|", forgetting the "R", it would not issue a
carriage return but, for example, print "three|C|lines.").

   Here are the variables that you can use:

|FROM|        Header text only.
|TO|          Header text only.
|SUBJECT|     Header text only.
|MONTH|       Numerical value (December is "1").
|MONTH2|      As above but two digits (December is "01").
|LMONTH|      The full month name ("December").
|SMONTH|      The shortened month name ("Dec").
|DAY|         Numerical value (January "21"st).
|DAY2|        As above but two digits ("9" becomes "09").
|SUFFIX|      Appropriate termination for the numeric day ("21" "st").
|LDAY|        The full day name ("Wednesday").
|SDAY|        The shortened day name ("Wed").
|CENTURY|     The "first part" of the year (1992 is "19").
|YEAR|        The "second part" of the year (1992 is "92").
|TIME24|      The 24 hour time.
|TIME12|      The 12 hour time ("13:03" becomes "1:03").
|TIME12A|     As above but "13:03" would become "01:03").
|HOUR|        The time "period" (13:03 is "pm").
|BBS|         The name of *your* BBS.  Header text only.
|CONFERENCE|  Header text only.
|NUMBER|      The number of the message.  Header text only.
|REFERENCE|   (These OLX variables are both included although I believe
|RECEIVED|    they will always read something to the affect of "None"
              or "No", and I haven't figured out if they are worthwhile
              yet or not!  Also, only useable in header text.)

|CR|          Carriage return.
||            Pipe ("|") character.

|ADDRESS|     Internet header text only.  Note that "header.net" can only
              use this variable and the two special ones above.  All of the
              rest have no special meaning for it.
|TEARLINE|    Footer text only.
|TAGLINE|     Footer text only.


   Note: In the case of header text, time and date variables pertain to
         when the quoted message was sent.  If used in footer text, then
         they will refer to when *your* message was written.


   One last point.  The header.txt, header.net, and footer.txt files may
be of any length.  The program interprets each text character one at a
time and then moves on to the next.  You could include a header that was a
copy of "War And Peace", or compose a similarly long "farewell" speech for
your footer/tagline, if you wished.  But I certainly wouldn't recommend
it. <grin>



                       - Footer Text and Tearlines -

   Any lines of text that are written to you message *before* a tearline
will be just as they appear in the footer.txt file, however this is not
precisely true of text *following* a tearline.  Each line of such text
will be automatically indented one space by the program so that it lines
up properly with all other Net taglines that will be later appended.  This
is not just for aesthetic reasons, but to guarantee that there are no Net
"hiccouphs" due to improperly formatted tagline text.
   The placement of a tearline in your message is not automatic. Wherever
you want it to contain a tearline you must explicity enter a "|TEARLINE|"
variable in the footer.txt file - make sure to also issue a carriage
return ("|CR|") after that variable as well so that it will function
properly as a tearline.  If you don't use the "|TEARLINE|" variable but
instead decide to simply use "---", Annex will not interpret this properly
as anything other than "meaningless" text for the purposes of indenting
text afterwards as explained in the above paragraph. Multiple tearlines
*are* allowed by Annex if you write your footer.txt file to so indicate
them, but they will serve no special function other than to most likely
confuse the Net and some other users upset.  So I would recommend against
using them.
   Finally, if you *don't* include a tearline somewhere in your footer
text (if you have any such text) Annex will not remove your footers when
you re-edit any existing message (see below).  To remind you of this fact,
Annex will issue a warning message if it ever comes across such a
"misbehaved" footer.



                          - Footer Text Warning -

   Annex will try to remove any footer information in a message whenever
you re-edit a message that you've already entered.  This is to ensure that
you don't keep getting additional footer text "tacked on" to the end of
existing text that has become part of the message itself.  Because of the
way Annex works, the amount of text that it will remove is based on the
current contents of the footer.txt file.  Therefore, if you change this
file while you are in the middle of an OLX session, Annex may or may not
delete, in confusion, parts of any actual message's text when you attempt
to re-edit it.  As a rule of thumb: Wait until you are done with a mail
packet before altering your footer.txt file.



             - Alternate Tagline Files and Specific Taglines -

   If you look at the command syntax for running footer.exe in the batch
file you will note that it is different from that used with header.exe.
The latter requires only that you specify the name of the message text
file.  Footer.exe however, *also* requires the name of the text file that
contains your taglines.  Because of this it is possible to set it to a
tagline file other than "taglines.olx".  There may be some reason that you
*don't* want to use that filename and I thought it was silly to have Annex
assume that you did.  To use a different tagline file just edit the
"footer" line in the batch file controlling your message replies to
reflect this change.
   Similarly, it is possible to "force" Annex to append a specific
tagline, even though it is not written to do so.  All you have to do is
make sure that the tagline file that footer.exe is assigned contains only
one tagline - the one you want.  Even given it's randomness, it would be
hard pressed to come up with a number between 1 and 1 that didn't
correspond to that tagline. <grin>  This requires shelling out to Dos from
your OLX session.  Either copy your current tagline file to somewhere
else, and then edit the original, or create a new file with only the
tagline you want and edit your batch file so that footer.exe works with
that one instead.  Both methods require some work, but it's not that big a
hassle if you don't use specific taglines often.  (Just remember to later
change your setup back to what it was originally...)



                             - General Notes -

   There are a couple of things about the way Annex works that you might
like to know - although I doubt you will ever come across them.  First of
all, make sure that the *first* tagline in your tagline file is *not*
simply a number.  Because OLX places a number at the beginning of its
tagline file, I've had to make Annex ignore any such numbers if they exist
so it doesn't think that *it* is one of your taglines.
   Secondly, all text after a line containing *only* "---" at the left
margin will be deleted.  This is the only way I could have Annex handle
tear-lines and footers.  If you enter a message and then re-edit it, Annex
has to first delete the existing tear-line and footer information.  If it
didn't, you'd end up with increasing numbers of tear- and taglines
appended to the bottom of your re-edited messages.
   However, I find it *very* unlikely that either of these specific
conditions would be fulfilled in such a way as to cause you difficulties
with your messages! <grin>  If not something to be "warned" about, then
they are at least something you might find interesting to know, in terms
of how the program functions internally.



                              - Conclusion -

   I hope that I have explained the various workings of the program
satisfactorily.  As I say, this is still an "early" version - but, after
getting several requests for it recently, I decided to go ahead and
distribute it anyway.  Any comments or questions are welcome.  My mailing
address until May 1992 is:

59 Glenforest Rd.
Toronto, Ontario
Canada  M4N 1Z7

After that date I will be moving somewhere else when my lease expires
<grin>, but mail can always reach me at:

416 Keewatin Ave.
Toronto, Ontario
Canada M4P 2A5

My Internet address is "[e-mail]".

   Thank you for taking the time to read this, and I hope you find the
program useful!