TWLOG HELP FILE

DESCRIPTION
  This program uses a simple data entry form to perform basic log operations.
  It records ten pieces of information, and six of them can be entered with
  a button press.  The ten pieces of data are the Date and Start Time of the
  QSO, Call sign of the station worked, Band, Mode, Power, signal reports
  exchanged and End Time.  A Notes field is also available for any comments
  you may wish to record.  

  The Band, Mode, and Power menus, along with other properties of the program
  can be configured to meet your operating needs.  You do NOT need to
  recompile to do this.  See RESOURCE FILES below for more information.


WINDOWS - The application consists of four windows:
               Main window
               Edit dialog
               About dialog
               Help dialog
   

MAIN WINDOW

   The main window consists of a menu bar and the log entry form.


   Menu Bar - The menu bar has two buttons, File and Help.  Pressing either
      of these buttons will produce the pulldown menu items described below.

      File - The menu bar's "File" button displays the following five choices:

         Append
            Clicking on this button will cause all of the data from the
            right cloumn of the log entry form to be collected, appended
            to your logfile, and clears the form.  Two lines of text are
            written to the logfile.  The first line contains all of the
            data except the Notes field, which is written on a second
            line.
               
         Edit Log
            Pressing this button creates the Edit dialog window and displays
            the contents of your logfile.  Besides allowing you to modify
            your log, this window has a Search function to find a specified
            text string.  See EDIT DIALOG below for more information.

         Print Log
            This button queues the logfile for printing.  You will be able
            to log more contacts while it prints.  Some field length will
            produce a cleaner looking printout.  See LIMITS below for more
            information.

         New Log
            Selecting this option will rename your current logfile
            and create a new, empty logfile.  The old log's file name
            will be in the form:

            log.yyyy.ddd.hhmmss - where:

            yyyy   = the year
            ddd    = the day of the year (1 Jan = 001, 31 Dec = 365 or 366)  
            hhmmss = hour, minute, and second when the file was created.

            This naming convention will allow you to do something like
            "cat log.* >biglog" and everything will be in the correct
            order, even after the year 2000.

         QRT
            Exit the program.
            

      Help - The menu bar's "Help" button displays the following choices:
   
         About
            This pops up the About Dialog which displays a little bit about
            who wrote this thing. 

         Help 
            This opens the Help Dialog which displays this file.  See
            HELP WINDOW below for more information.



   Log Entry Form

      The log entry form in the main window consists of ten rows of two 
      columns.  The left column has push buttons and labels, and the
      right column contains text fields or option menus.
      
      The right column contains the values that will be written to the
      logfile.  Nothing is written to the logfile until you press the
      Append button, so you may edit these columns at any time.  

      The maximum length for any of the text fields is huge!  However, the
      logfile will display and print better if you stay within some defined
      limits.  See LIMITS below for more information.

      Date:
         This row consists of a push button on the left and a text field on
         the right.  Pushing this button will fill the text field with the
         current date.
 
      Start Time:
         Push this button to fill the Start Time text field.  It also fills
         the Date text field with the current date, so both the Date and
         Start Time can be entered with this one button press. 

      Call:
         Click the box on the right hand side.  A border will be placed around
         the text field and a cursor will be displayed.   Now type in the call
         sign of the station you are working.  NOTE: All letters are changed
         to upper case automatically, so no need for the shift key.

      Band:
         The right column of the Band row is an option menu.  Clicking on
         the menu will display a list of bands or frequencies you have selected.
         Then click on the desired band/frequency.  The menu will show the
         selected frequency or band.

      Mode:
         This is another option menu.  Click on the menu and select your mode,
         just like the Band menu above.

      Power:
         Click on this option menu to select your power, just like the Band
         menu above.

      His RST:
         Click on the text field in the right column and type his signal report.

      My RST:
         Click on the text field in the right column and type your signal report.

      Notes:
         Click the box in the right column and enter any notes or comments.
         This field is one long line of text.  The Return key is ignored.  As
         you type, the text will scroll to the left, making room for more text.

      End Time:
         Push this button to fill in the current time, just like the Start Time
         button.


EDIT DIALOG

   The EDIT window allows you to modify and search your logfile.  This window
   has a scrolled text area, a textfield and three pushbuttons.

   NOTE:  While this window is open, you will NOT be able to use the MAIN
   window.  You must click on the OK button to close this window before
   you can use the MAIN window.   

   Editing - With the textfield you can cut, paste, add and delete text.
   The editor will act much like a WYSIWYG editor.  To save the changes you
   make, push the Save pushbutton.  NOTE:  Nothing is written to logfile until
   you push the Save button.  So, you may exit at anytime WITHOUT saving the
   changes by pressing the OK button
   
   Searching  - Click in the box labeled "Search Text:" and enter the
   text you want to find (calls, dates, etc).   Next, press the Search
   pushbutton or hit the Enter key.
   
   NOTE: The search text is CASE SENSITIVE.   
   
   The search starts at the beginning of the logfile and searches forward for
   a match.  When a match is found, the text is highlighted and displayed
   on the top line.  Pressing the Search push button again, or hitting Enter,
   will continue the search and highlight the next match.  When the end of the
   file is reached without finding a match, the search text field will clear,
   indicating no match was found.


ABOUT DIALOG 

   The About Dialog displays a little bit about who wrote this thing.  Press
   the OK button to close this window.


HELP DIALOG 

   This window displays this Help file.  It can be moved and resized.  The MAIN
   window will still be active when this window opened, so you can refer to
   the help file while entering data in the MAIN window.

   If you close or iconify the MAIN window, the HELP window will close or
   iconify too.  Pressing the OK button will close the Help window.
   

RESOURCE FILE

   The resource file, Twlog, is an important part of this program.  It allows
   you to customize the program to meet your needs WITHOUT recompiling.  After
   making any changes to the resource file, you must restart the program to 
   have the changes take affect.

   A quick look at the file will tell you that a line beginning with an
   exclamation point (!) is a comment.  Lines in a resource file can become
   quite complex, but here we will look at just the basic rules.

   A line in the file contains two columns.  The left column is the name
   of a widget and one of its properties, like height or width.  The name is
   followed by a colon (:) and any number of spaces or tabs.  The right column
   is the value to be assigned to the property.  It is important that no spaces
   follow the value!  For example, if the right hand value were tan followed by
   a space, you would get an error message like this: 

      Warning: Color name "tan " is not defined

   The dumb computer is looking for a four letter word.  Notice it says it can't
   find "tan " - that's t, a, n, and a space - not just "tan".  

   If you want to create your own color scheme, change one of the colors to
   red and restart the program.  Now you can see the parts of the interface
   controled by that property.  Be sure to look at the Edit and Help windows
   to see if your change affected these windows. You can then change this 
   property to any color or rgb value (#rrggbb) you want, and then repeat this
   process for the other color properties.   
   
   This resource file is pretty straight forward.  The file is divided into ten
   sections.


   PROPERTIES - This section lets you define some basic properties for the 
   windows.  The lines with "twlog.x:  0" and "twlog.y:  0" allow you to
   position the upper, left hand corner of the MAIN window.  Change the 0's to
   the position you want the window to appear when the program starts.
   NOTE: When moving a window, some window managers display the current
   x-y position and you can use these to determine the x-y values. 

   The next two lines are for the foreground and background colors for most of
   the windows.  You can pick a common color name, or use a name in the file
   /usr/X11R6/lib/X11/rgb.txt.  There are over 750 colors in there.  These are
   set to black and tan.  Later in the file, some parts of the interface have
   there colors set to a green and off-white. I was going for the old Heath
   Kit colors. See the COLORS AND OSF CONTROLKEYS section below for more. 

   The next line determines the font that will be used in all the window
   of the interface.  Check /usr/lib/X11/fonts/misc for other fonts.
   
   The next two entries are for highlight color and thickness.  If you change
   the foreground color, you may want to change the highlight color also.
   The highlight thickness is set to three.  You can comment (!) this line and
   it will use the default of two.  I like three, but much bigger gets ugly!

   The next line:
   
       twlog.form1.rc1.XmTextField.cursorPositionVisible: False
   
   is best left alone.  It turns off the cursor in all of the textfields.  I
   get tired looking at them.  The program will turn them on when the textfield
   is selected and off when you leave it.  Yes, you can change it to True, but
   the program will eventually win.   
      

   LOGFILE - The property twlog.dirpath must be set to the complete pathname
   of the directory where you want to keep your logs.  For example:

       twlog.dirpath:         /home/ted/logfiles
   
   Don't put any spaces behind the path.
    
   
   TIME ZONE CHOICE - You can choose to record QSO times in local or GMT.
   Setting the property to 0 will record local time and 1 will record in GMT.
   Any other value will be detected as an error and the program will exit.


   BANDS DATA - This property lets you select which bands or frequencies
   you want as options in the BANDS menu.  The right-hand value is a list of
   bands or frequencies, separated by commas. For example,
         twlog.bands:    80,40,30,20,15,10

   DEFAULT BAND - This property allows you to select which band you want
   displayed when the program starts.  The right-hand column is a digit that 
   represents the default button in the BANDS DATA above.  NOTE: The numbering
   starts from zero.  So, if twlog.bands is 80,40,30,20 and your favorite band
   is 30 meters, you would make the DEFAULT BAND entry look like this:

   twlog.default_band:  2


   MODES DATA - This value is set using the same rules as BANDS above.  Putting
   your favorite mode first in the list will make it the default value for
   the menu, or you can put then in the order you like and use the next 
   property to select the start up value.


   DEFAULT MODE - This one works the same as DEFAULT BAND. See DEFAULT BAND
   above.


   POWER DATA - This is another comma separated list just like BANDS and MODES.
   Again, make the first entry your most used power to get the proper default,
   or put them in order and use the next property to select the default.


   DEFAULT POWER - This one works the same as DEFAULT BAND. See DEFAULT BAND
   above.


   COLORS AND OSF CONTROLKEYS - In the PROPERTIES section above, the foreground
   and background colors were set to black and tan.  In this section some parts
   of the interface are set to other colors - a green (#00768d) and antiquewhite.
   These definitions override the earlier ones because they are more specific.
   They specify a widget (rc1) or a type of widget (XmLabel) instead of using 
   an "*" to match any widget.  The rule here is a more specific definition 
   wins.
   
   The last part of this section makes the control and function keys work as 
   I expect them too.  You may be able to comment them all out.  It depends a 
   lot on what window manager you are using and how the keys are defined for
   your window manager. 
   
   Finally, see the Twlog and README files for more information.


LIMITS
   
   The number of characters that can be entered in a textfield is virtually
   unlimited.  However for economy and a better looking output, the program
   does set limits.  When the log is written, all of the textfields are
   truncated to 20 characters, except for the Notes field, which allows for
   80 characters.  Those are the maximum lengths that will be written to the
   log.  But, for a better looking output with the columns aligned, try to keep
   the fields below these maximum number of characters.

   Date    11
   Start   10
   Call    10
   Band     6
   Mode     6
   Power    6
   His RST  6
   My RST   6
   End     10
   Notes   80
     

KEYBOARD CONTROL

   If you prefer, all operations can be done using the keyboard instead of the
   mouse.  This can be very efficient, since you don't have to move your hand
   between the keyboard and the mouse.

   When the program starts, the Date pushbutton is selected, as indicated by
   the border around it.  Pressing the Tab key will move the border and select
   another widget.  Shift Tab will move backwards through the widgets.  Hit tab
   several times and notice the sequence in which the widgets are selected.  The
   program will overide this sequence in some cases.  See below.

   If a button is selected, pressing the space bar is the same as clicking on it
   with the mouse.  If the Band, Mode, or Power menu is selected, pushing the
   space bar will display the options.  Use the up and down arrows to select
   the option you want, and press the space bar.  Then the Tab or Enter Key
   will move you to the next widget.

   When a textfield is selected, enter the data and press the Tab or Enter
   key to move to the next widget.

   The program overrides the normal sequence of the Tab key.  For example, if
   the Date button is selected and you press the space bar, the date textfield
   is filled in, and the program skips the Date textfield and goes to the Start
   Time pushbutton.  Right where you want to be anyway!

   The menu bar can also be used via the keyboard.  If your window manager is
   behaving right, pressing F10 will display a 3D border around the File button
   in the menu bar.  You can then use the left and right arrows to select a
   button in the menu bar.  Press the space bar to display the options and use
   the up and down arrows to select an option and press the space bar.  

   There are also some shortcut keystrokes available.  Notice that some of the
   buttons in the menu bar and pulldown menus have an underlined character.  
   These buttons can be pushed by typing the underlined character, however the
   button must be displayed before this will work.  For example entering
   F10 H A will select the menu-bar (F10), then the Help button (H), and finally
   the About button (A).

   Another form of shortcuts is also available.  This kind does NOT require
   that the menu be displayed.  Click on the File button on the menu bar and
   notice the text strings on the right side of the pulldown menu.  Next to
   the Append button, is the text Ctrl-A.  This means that this option may
   be selected by a Control A keystroke.  Therefore, after you have filled
   in all of the info for a QSO, pressing Control A will append the info
   to your logfile.