This
Help file does not list every single feature of BORG. Anything that
BORG does that is not listed here is either something obvious, or
something that is mistakenly missing from this help.
The
Database Files
When
BORG
starts for
the first time, it prompts for the location to store its database
files. BORG
uses 3 files, borg.jdb for storing calendar appointments, mrdb.jdb
for
tasks, and addr.jdb for address/contact info. These files are in a
binary format. I
would suggest backing up these files every so often if you use BORG, in
case of disk failure (not because BORG is buggy :)
The
database
files are
not simple data stores. These files are formatted to be highly
resistant to corruption
from disk space overruns and computer crashes.
Internationalization
BORG
supports Locales (regional settings) as of release 1.3. The Locale can
be switched from the Options screen. Once a new Locale is chosen, a
restart is required before the new Locale is used. The date formats,
month names, and weekday names are supported for all Locales listed.
However, the majority of text strings in BORG come from a properties
file. As of release 1.3, a Spanish property file has been created. So,
except for this Help file and some README files, BORG supports Spanish.
Translations to other languages would only require a translated version
of the borg_resource.properties file that comes in the BORG jar file.
The Main Screen
The
BORG main screen shows a single month at a time. The Navigation buttons
appear
on the bottom of the screen and are intuitive (Let me define intuitive.
When I
say intuitive, it means that I am describing something that I haven’t
documented yet, and might not document, because it seems to be obvious
enough. For example the "next" button on the main month window).
If
the current month is being viewed, the current day will appear dark
pink.
Weekends are shaded slightly darker than weekdays. Days marked as
holidays
appear the same color as weekdays. Days can also be marked as vacation
days,
and if so, will appear green.
To add/remove/update
appointments for a given day, just click on the
button
containing the date.
Week
View
To the right of each week is a
button that will produce a "week view" when pressed. The week view is
not interactive. It is a grid view of the week that plots the scheduled
appointments for each day according to their start time and duration.
The start and end range of the grid is user tunable. The week view can
be sent to a printer via a menu option.
Categories
From the Categories menu on the
main screen, appointment categories can be created and filtered.
Each appointment can be assigned to a category. The program can
then filter appointments using a user-selected list of categories.
Appointments that are in a category that is being shown behave normally
and appear in the calendar, printouts, etc... Appointments that are in
a category that is hidden, will remain in your database, but will not
appear anywhere on any screen as long as their category is not being
shown. This provides a way to manage "virtual" calendars in one
database.
Editing appointments
When
the appointment editor first appears (after clicking a date button),
all of its fields are reset to
default
values and the text "*****
NEW APPT *****" appears in the upper
portion of the window. When this text appears, it means that
the window
is editing a new appointment that can be saved by choosing File/Add.
If the
day
being edited has existing appointments, they can be edited
by
clicking the Show Next button until the appointment you want to edit is
being
displayed.
Existing
appointments can be updated or deleted from the File menu.
Most of the fields in this window are intuitive and require no special
documentation. Some items bearing explanation are:
- If the "No
specific time" checkbox is selected, no time
string will appear in the main month
display or
print output and the appointment will be considered a non-scheduled
appointment or "note".
- The duration pulldown is new to Release 1.1 and affects the
week view.
- The color pulldown alters the
appointment color on the main month view, and in the color printout.
To Do's
If
the
To Do checkbox is selected, the appointment will be marked as a To Do.
It will appear
on the To Do list window, and can be marked as done from the To Do
window
also.
Repeating
Appointments
The
frequency pulldown allows you to set the frequency of an
appointment that
repeats. The times field should be set to the number of repeats desired.
When deleting repeated appointments, the File menu provides the choice
of
either deleting just the one occurrence of the repeat on the current
day being
edited, or all of the occurrences.
FYI -
repeats are only added to the calendar for 2 years from the present
date. So if you repeat something yearly for 1000 years and
try to look ahead to the year 3000, you will be disappointed.
Repeating
To
Do's
Repeating
To Do's will appear as
multiple times on the month view windows (as determined by the
frequency and
Times). However, they will only appear once on the To Do list -
starting with
occurrence number one. If a repeating To Do is marked as done on the To
Do
list, the NEXT occurrence of the To Do will then be placed on the To Do
list -
this is done until the last occurrence has been marked as done.
Vacation,
Half Day,
Holidays
The
vacation, half day, and holidays check boxes are used to mark the day
in a different color on the main month view.
BORG
currently can add
certain US and Canadian holidays. This is an option from the
preferences screen.
BORG will also "guess" as to whether or not a US holiday should be
marked using the holiday color or just normal day color. This is based
on whether or not the holiday usually causes a day off from work in the
US. So, for example, New Year's Day would be marked in weekend color,
but Valentine's Day is not.
Whether
or not you use the US holiday feature, if a certain day is a holiday
for
you, you can
add an appointment with the name of the holiday and mark the Holiday
checkbox.
Private
Appointments
Appointments
marked as private
using the private checkbox are processed differently from regular
appointments
in two ways:
1.
The
appointments only appear
in the main month view and print output if the Options/Show Private
checkbox is
selected from the Options menu. In this way, Private
appointments can be hidden when the calendar is used in a public
setting. Example uses for private appointments would be to record
certain doctor's appointments or to keep a log of your illnesses
or any other private non-work related items.
2.
Private
appointments are
encrypted in the borg.jdb file. Although anyone running BORG (WITH
ACCESS TO
YOUR FILES) can access even private appointments from a borg.jdb file,
a casual
snooper (like a sys-admin) who only gains access to the borg.jdb file
and scans
it for ascii text, will not be able to decode the private
appointments.
The To Do List
The To Do list is accessed from
the
Action/To Do
menu choice from the main Month screen. It also pops up upon start up.
This list shows all appointments marked as To Do's that have not been
marked as done. To
Do's can be
marked as done from the To Do window menu. There are 2 options to pick
from
when marking To Do's as done (from the Action menu). The "No Delete"
option, removes the appointment from the To Do list, but leaves it on
the
calendar. The Delete option removes it from the calendar also.
The To Do list can also be printed using its Action/Print List menu
choice.
Pop-Up Reminders
These appear 3 hours before
appointments (and 30 minutes afterwards if you start BORG up within 30
minutes after an appointment). If you are starting BORG up within 30
minutes after an appointment, BORG figures that you may have forgotten
about it.
Around 15 minutes before an appointment that has a pop-up displayed,
BORG will make an audible beep noise, and will try to bring the pop-up
window to the front to remind you about the appointment. This will
continue every 5 minutes until you dispose of the pop-up.
Email
Reminders
BORG can be set to send an email
reminder each day for the next day's appointments. The main options
menu is where you can enable email reminders. If this feature is turned
on, BORG will send out a single email reminder of the next days
appointments once per day.
The Task Tracker
The Task Tracker is used to keep
track of
various
tasks with defined start and end dates, different statuses,
descriptions, and
resolutions.
It is up to the user to decide if
something should be a task or regular appointment. Appointments can be
used to hold simple tasks that require no special tracking, such as
"pay mortgage" or "take out garbage". The task tracker is meant for
longer running, more complex tasks, such as "code new BORG feature",
"design new widget", or "re-floor bathroom" - things that have multiple
steps to check off, that require documentation of a resolution, and/or
have
"sliding" due dates.
The main Task Tracker window shows
a
scrollable list
of tasks. The Task Tracker Action menu can be used to add, update, and
delete
tasks. The radiobuttons on top can be used to show just open or closed
tasks, tasks that are done but have not been recorded for performance
review (PR), or all tasks.
A filter string can be typed in the
text
entry field. When the filter button is pressed, only tasks with text
containing the filter string will be shown.
Tasks can also be filtered
according to their category, using the category pull-down choice box.
Tasks with due dates will show on
your
calendar.
The task tracker is also designed
to keep track of tasks
done for
later recording on your list of accomplishments at work. This is called
performance review (PR). It is hoped that most BORG users
do not have to deal with this kind of hell. One of the
things that BORG can be used for is to figure out what you have done
during the year
at performance review time - and to make sure you can keep things that
you
have already claimed credit for apart from things that you have not.
Some users will not identify with this. Others may be groaning in
sympathy at this point.
Once added, tasks follow a set of states,
which
are user-configurable in BORG.
The different default task types are shown
below:
|
TASK
Type
|
Description
|
Allowable
States (in no special order)
|
|
TASK
|
Normal
task. Just something to do.
|
OPEN,
IN_PRG, CLOSED, DEF, PR
|
|
ISSUE
|
An
issue to be figured out
|
OPEN,
IN_PRG, CLOSED, DEF, PR
|
|
CODE
|
Coding
to be done
|
OPEN,
DEV, TEST, DEF, PR, CLOSED
|
|
DOC
|
Document
to write
|
OPEN,
IN_PRG, RVW, BL, CLOSED, DEF, PR
|
|
State
|
Meaning
|
|
OPEN
|
Not started yet
|
|
IN_PRG
|
In progress
|
|
DEV (for CODE)
|
Coding started
|
|
TEST (for CODE)
|
Coding done, testing started
|
|
PR
|
Task is done, but not yet
recorded in the next PR(or performance review, or whatever nonsense
your company does)
|
|
CLOSED
|
Task is complete
|
|
RVW (for DOC)
|
Document has been written.
Is out
for review.
|
|
BL (for DOC)
|
Document is “baselined”,
meaning
that is is approved. There still may be busy work required before the
document is official.
|
|
DEF
|
Deferred – to be worked on
at
some future time. Not being worked on now.
|
If you
don't
like the default task types and states, you can change them. Please see
the section below on Editing Task Types and States for more info. The
default task states are used by the author and provide a good example
of what can be done. There is no problem if you discard them all and
replace them with your own.
When
editing tasks, much of the functioning of the editor window is
obvious.
However:
- The PA (person assigned) and
Pri (priority fields) don’t really do anything except hold data. Use
them as
you like.
- The
standard BORG check
boxes (subtasks) for CODE and
DOC tasks might not apply to most users (especially those who aren’t
developers). Just as an FYI, here are what the CODE checkboxes were
created for:
- Delta = put code under
source
control
- Blue Print = a date
tracking
blue print has been filled out – see ISO 9000 for more info – see
Dilbert for
more info on ISO 9000
- MR = a modification request
has
been issued (or
change
request, or whatever your build system might require to relate code to
features/problems)
- Code
Insp =
code
inspection done.
- Here
are
the DOC checkboxes:
- DocNum = an
official
document
number has been established
- VGs – viewgraphs have been
prepared for
the
document presentation meeting
- Blueprint (see above)
- MR (see above)
- Library =
the document has been officially filed in some library.
- The
check
boxes don’t affect
any processing. However, the values are remembered on a per-task basis.
So use
them as you like.
Subtasks
For each task, 5 subtasks can be
defined by the user. These 5 check boxes can be used to keep track of
anything the user needs to take care of as part of the overall task.
For example, if a task is to refinance your home, subtasks might be
"get appraisal", "fax pay stubs", "mail application", "final closing",
"new payment book rcv'd". The subtasks just are there to be
checked-off. They do not affect any other processing.
Each task type can also have up to 5 type-specific subtasks that are
common
to all tasks of a particular type.. The type-specific subtasks can be
altered by the user (as of Release 1.0). See below.
Editing
Task Types and States
The default task tracker states defined above are probably adequate for
some users and inadequate for others. the user has the
capability to edit the list of task types and state transitions in the
task tracker. To edit the task types and states, first use the option
from the task tracker options menu that exports the task type
information to an XML file. Save this file in case you need to revert
back to it.
The format of this file is XML - but simplified XML. The simple XML
parser in BORG cannot handle comments, attributes, prologs - so the
file should just contain XML elements as described below.
The XML contains a root element. Under the root are elements for each
task type. To add a new task type, just add an element under the root.
Inside each task type element, the allowed state transitions are
described. For each allowed state, there is an element. This element
should contain an empty element for each state that can be reached from
that state. Up to 5 CB elements can be present per type. These are the
type-specific check boxes.
Here is the default subtree for the TASK type:
<root>
<TASK>
<OPEN>
<IN_PRG/>
<DEF/>
</OPEN>
<DEF>
<OPEN/>
<IN_PRG/>
</DEF>
<IN_PRG>
<DEF/>
<PR/>
<CLOSED/>
</IN_PRG>
<PR>
<CLOSED/>
</PR>
<CLOSED>
<IN_PRG/>
</CLOSED>
</TASK>
<ISS>
<OPEN>
<IN_PRG/>
<DEF/>
</OPEN>
<DEF>
<OPEN/>
<IN_PRG/>
</DEF>
<IN_PRG>
<DEF/>
<PR/>
<CLOSED/>
</IN_PRG>
<PR>
<CLOSED/>
</PR>
<CLOSED>
<IN_PRG/>
</CLOSED>
</ISS>
<CODE>
<OPEN>
<DEV/>
<DEF/>
</OPEN>
<DEF>
<OPEN/>
<DEV/>
</DEF>
<DEV>
<DEF/>
<TEST/>
</DEV>
<TEST>
<DEV/>
<PR/>
<CLOSED/>
</TEST>
<PR>
<CLOSED/>
</PR>
<CLOSED>
<DEV/>
</CLOSED>
<CB>Delta</CB>
<CB>Blueprint</CB>
<CB>MR</CB>
<CB>Code
Insp</CB>
</CODE>
<DOC>
<OPEN>
<IN_PRG/>
<DEF/>
</OPEN>
<DEF>
<OPEN/>
<IN_PRG/>
</DEF>
<IN_PRG>
<RVW/>
<DEF/>
</IN_PRG>
<RVW>
<BL/>
<IN_PRG/>
</RVW>
<BL>
<RVW/>
<PR/>
<CLOSED/>
</BL>
<PR>
<CLOSED/>
</PR>
<CLOSED>
<IN_PRG/>
</CLOSED>
<CB>DocNum</CB>
<CB>VGs</CB>
<CB>Blueprint</CB>
<CB>MR</CB>
<CB>Library</CB>
</DOC>
</root>
So, as you can see, there is a TASK type of "TASK". From state "OPEN",
you can transition to state "IN_PRG" or state "DEF", and so on...
All task types start in state
OPEN. This is hard-coded in BORG. All task types can be forced to
CLOSED state from the task tracker Action menu no matter what the XML
state information allows.
Once you have created the task type XML, it should be imported back
into the task tracker using the import option in the task tracker
Options menu.
BORG will not import invalid XML. If the XML is valid, but not correct,
you can fix the XML and import it again. No damage will be done by
logical errors in your XML, except that you might not be able to
transition your tasks correctly.
Options
Most of the options from the main options screen are self-explanatory -
except:
The font size increase/decrease currently only affects the appointment
text in the main month view. Hopefully, the size of all other text is
adequate. The users may want to change the appointment font size to
taste, depending on how much they want to fit in a single day box
versus how good their eyesight is.
Email - an email message is sent once a day only, and only for the next
day's appointments. Provide the name of an SMTP server and email
address to send to. BORG cannot send a user/password to the SMTP server
at this time.
Changing the database directory (where you keep BORG files), does not
affect the files. They are not moved. If you want to change
directories and keep your data, copy the files to the new directory,
change the dir in BORG, and then restart
BORG.
Logging - the log records provide a record of BORG activity (DB
adds/deletes). The Java version of BORG does not have any tools to take
action on the log records (i.e. view them nicely or play them back into
a DB).
Auto Update Check - this only causes BORG to compare the latest release
number from the BORG sourceforge web site to the release that you are
running. If the releases are different, a popup will inform you.
Nothing else is done. The feature is off by default. The check is done
once per day.
Look And Feel - the combo box will be populated only with the installed
look and feels in your JRE. The default is Metal. You can put new look
and feels in your classpath and type the full class name into the combo
box. BORG looks good with the default Metal L&F and also the
Kunststoff L&F, and the PlasticXP l&f from jgoodies.com,
which is recommended. The Liquid L&F looks ok
too. Some of the other L&Fs are not so appealing with BORG. No look
and feels are distributed with BORG.
Holidays - Most US and Canadian holidays can be shown (optionally).
Except for Christmas, religious/ethnic holidays are not yet included -
mainly because they are usually lunar based and much harder to
calculate - and because they aren't usually a day off from work. These
can be added manually through the appointment editor.
Word Wrap - this will cause text to wrap in the month view and print.
To take effect in the month view, the window must be destroyed and
recreated either be restarting BORG, or by killing the window and
re-opening from the systay icon (windows only).
Print Logo - A user defined print logo can be included on the month
print. The logo space will be the last
two empty boxes on the bottom right. This will have a size of
184x72 pixels. Any logo smaller than this will just be centered in this
space. Any logo larger will be scaled to fit - retaining its aspect
ratio. The logo can be GIF, JPG, or PNG. A color logo will print in
color, even if the color-print option in BORG is turned off.
Start in Background - Windows only. This will cause BORG to start only
as a systray icon. No other windows will be opened - except for
reminder popups and the auto version check if applicable. BORG will
still popup reminders and send email while running in the background.
The main month view can be started by double clicking the systray icon
or from the systray icon menu.
Printing
For some users, printing a month view may be the most important part of
BORG. Some users will print the next few months and use the printout as
a "daily planner" until they can get back to BORG to update it online.
There is ample room on the printout to jot new appointments.
The printing uses the Java print service to find a printer that can
print the month view. It may take a few seconds before Java scans the
printers on your system and pops up the printer selection box.
Systray Icon (Windows only)
Version 1.2 now supports a systray icon. See file
SYSTRAY.txt for information on how to set this up.
Import/Export to XML
BORG can export/import its data to/from XML. This is a fully functional
export/import with an improved XML format as of release 1.2. Importing
can only be done into empty databases. This is enforced (to prevent
really bad things from happening). The import/export actions can be
found on the month view Action menu. Import/Export provides a good way
to backup your data in human readable/editable form.
mdbtool.jar
A file called mdbtool.jar is distributed with the BORG binary .zip
file.
It is a tool that can be used to debug, turn
on logging, and do some other stuff for .jdb database files. It
is not vital to BORG and not fully documented yet. You shouldn't need
to use
it unless you playing with the database source code and need to do some
debugging.
In version 1.2 some options were added to mdbtool.jar:
The Repair option will scan through a database looking for bad rows.
Any bad rows will be marked as deleted, allowing the rest of the
database to be accessed. Database corruption usually only occurs when a
disk is bad, out of space, or during a computer crash. Usually, only 1
database row will be affected. In most cases, BORG will automatically
detect this and ignore bad rows. In rare cases, BORG will error and
appear to not fully fill in an entire screen of data. This is the case
where the repair tool can help. DO NOT RUN REPAIR UNLESS YOU HAVE A
PROBLEM.
The Convert Dates option is only to be used under rare circumstances.
Convert Dates will take a pre-1.2 BORG database and alter the date
information to a standard format. Databases created by version 1.2 and
later will be created using this standard format. THIS OPTION IS A BIT
EXPERIMENTAL - and should only be used if needed. One reason to need
this option is if you change locales (region setting) on your computer
to use a date format different from the one you have been using with
BORG 1.1 or earlier. Another reason would be if you try to copy a
pre-1.2 db file to a machine that uses a different date format. If this
happens, BORG will error trying to parse dates. If (AND ONLY IF) you
get these date errors, then backup your db files, and run the Convert
Dates option to make your DB files portable across locales. Do not run
this option if you have no problems.
RDBMS Support
BORG 1.3 contains experimental support for keeping its data in a
relational DB instead of normal files. Only a single user is supported
per DB in this release (with the intent of supporting multiple users in
a single DB in the future). However, multiple DBs can be created for
multiple users.
See file RDBMS.txt for more information.
AutoStart
The autostart feature provides a
way for a user to have BORG automatically start if an appointment is
coming due and the user has forgotten to start BORG.
Keep in mind that the best way to use BORG is to run it ALL the time.
It will keep popping up reminders and sending reminder emails. If it
can't be run ALL the time then have it always start when you first
start your windowing system. There are a number of ways to do this in
Windows - i.e. the startup menu or scheduled tasks. In UNIX, there are
also a few ways depending on the flavor of X-windows that you run.
GNOME on Linux has options to set startup programs by editing your
login session.
If this is not appropriate for you, there is the autostart feature.
Using this feature, you can have BORG try to start every so often (5/10
minutes? whatever you like) using the Windows task scheduler or cron
under UNIX. When started with the autostart option, BORG will only
start if an appoinment is approaching (<30 minutes away). Otherwise
BORG will quickly exit. BORG will also exit quietly if it detects that
another BORG process is already running. If you are not logged on, BORG
will also exit quietly.
To use autostart under
windows:
Create a .bat file that starts BORG in autostart mode. Here is an
example of the contents:
javaw -jar
c:\mbb\borgdir\borg.jar -autostart
Notice that javaw is used. Also notice the -autostart option. Use the
proper path to borg.jar on your machine. Use the full path to javaw if
it is not in your PATH already.
RIght click on the .bat file in explorer and set the following options
- run minimized and close on exit. This will make sure that each run of
BORG will not have MSDOS windows popping up or lying around.
Then set up a windows scheduled task item to run your .bat file as
often as you like. This will run BORG over and over without starting
the GUI until an appointment approaches.
The above example worked under Windows ME. Windows XP has not been
tried.
To use autostart under
UNIX:
Create an executable shell script that starts BORG in
autostart mode. The following example worked under Fedora Linux:
export DISPLAY=unix:0
/usr/java/j2sdk1.4.1/bin/java
-jar /home/mbb/sourceforge/borg_src/dist/borg.jar -autostart
>/dev/null 2>/dev/null
Use the appropriate path to java and your borg.jar file. cron jobs
don't have the same PATH set up as your login shell, so a full path is
probably needed. Also notice the -autostart option. With Fedora Linux
running the GNOME desktop, the DISPLAY variable needed to be set since
the cron environment did not have this and did not default to anything
usable. Each UNIX is different. You may have to experiment.
Removing the /dev/null stuff will cause cron to send BORG output to
your email. This will help you debug problems if BORG does not seem to
ever start correctly.
Then use crontab -e to add a cron job that runs your shell. See the man
page for crontab(5). Also, you may have to set up your UNIX machine to
give your login permission to use cron.
|