Help Text for RISC OS MoonTool

RISC OS MoonTool, Version 3.26.
Last modified: 29.09.99

Contents

      * Introduction
      * Using MoonTool
      * Moon phases
      * Gamma correction
      * Saving the window positions, etc.
      * Selecting a different time/date
      * Test Mode
      * Quitting
      * Options
      * Accuracy
      * Differences between the RISC OS version and the original
      * Technical details
      * History (of my versions)
      * Credits
      * Copyright
      * Disclaimer
      * Contact details

----------------------------------------------------------------------

Introduction
````````````
MoonTool is a desktop application that calculates and displays the current
phase of the moon and other related information.

The original version of the program was called "A Moon For The Sun" since
it was written for Sun workstations. Sometime around 1993 Eduoard Poor
ported MoonTool to RISC OS 3.

Later, in early 1999, I saw a request for the moon to appear the right way
up in the program (Eduoard was based in New Zealand so naturally the moon
drawn by his version was the wrong way up for those of us in the Northern
hemisphere). Also requested was the ability to calculate the moon
phase/information for times other than the current date/time. Since both
these things had been on my list of "Things to get around to one day" I
decided I'd finally get on and do them.

Note that for MoonTool to work correctly the clock in your computer must
be set correctly and your TimeZone/DST must also be correct. See your RISC
OS user guide for more information.

MoonTool is compatible with RISC OS 3.1 and later.


Using MoonTool
``````````````
MoonTool is run in the normal RISC OS fashion (ie. double-click on its
icon in a filer directory display). There's no reason why you shouldn't
include MoonTool in a boot sequence (eg. in !Boot.Choices.Boot.Tasks on
RiscPCs) if you're the sort of person who likes having the moon on your
desktop to keep you company. I know that I do.

Initially a small window will open that displays a picture of the moon as
it appears in the sky (although it is always shown upright). Clicking on
the moon in this small 'icon' window will open the main window which
contains various pieces of information about the date and relative
positions of the sun, moon and earth. Closing the window, or clicking
Select on the Moon graphic, will cause the smaller 'icon' window to be re-
opened.


Moon phases
```````````
Selecting "Moon phases..." from the menu will open a window containing the
dates and times of the quarters of the moon surrounding the currently
selected date/time. The dates/times shown are all in UTC (Universal Time
Coordinated), ie. GMT.

You can also open/close the Moon phases window by clicking with Adjust on
the Moon icon or the Moon in the main MoonTool window.


Gamma correction
````````````````
If you find that the Moon graphics are too bright or dark on your monitor,
you can adjust their 'brightness' using the Gamma Correction option from
the main menu.

In the Gamma Correction window, there is a small image showing two
grey-scales and the Moon at both full and new phases. Between the grey-scales
is a line of alternate blocks of solid grey and 'dithered' grey.
Ideally, these blocks should look as close to each other in 'brightness' as
possible.

To save the gamma correction setting, use Save choices from the main menu. 


Saving the window positions
```````````````````````````
You can save the current positions of the various windows that MoonTool
uses by selecting Save Positions from the main menu.

When MoonTool is next reloaded it will initially open the windows in the
same place they were when the positions were saved.


Selecting a different time/date
```````````````````````````````
If you select "Choose time..." from the menu a window will open that
allows you to select the date and time of day that you want MoonTool to
use for its calculations.

Note that whilst test-mode is active the Choose Time window will not work
as expected. Rather than following the time selected test mode will simply
'step' each time a change is made. It's probably best not to mix the two.

The window contains a number of icons:

Current
    When this option is selected, MoonTool will use the current date
    and time (as obtained from your computer's clock) and update its
    display(s) in real time.
    The time adjustment icons will be shaded and un-selectable whilst
    this option is selected.
    Note that this option doesn't have an immediate effect. You must
    click on the "Use" button to cause MoonTool to effect it.

Update
    This option, when selected, causes MoonTool to update its displays in
    line with the time showing in the time selection window.
    It can sometimes be useful (especially on older/slower machines) to
    turn this option off when selecting a time as the calculations
    MoonTool performs are relatively time consuming and so slow things
    down.
    Note that this option takes immediate effect - you don't need to click
    on "Use".

Bump arrows
    Use these arrows to select the date and time of day you're interested
    in. If you've ticked "Update" then MoonTool's various displays will be
    updated as the values are changed.

Now
    Clicking this button causes the current date and time to be entered
    into the time selection window.

Cancel
    Resets whatever options were in force when the time selection window
    was opened. If the button is clicked with Select then the window will
    also be closed. Clicking with Adjust keeps the window open.

Use
    Causes MoonTool to use the options (or time/date) in the window. As
    with "Cancel", clicking with Adjust rather than Select will cause the
    window to  stay open on the screen.


Test Mode
`````````
The original MoonTool had a 'test mode' that rapidly stepped through time.
Later versions (for the Sun/X11) added a button to (dis)engage this
feature at any time. I've added this feature to my RISC OS version as a
menu option and extended it to allow three different test speeds.

If you select "Test mode" from the menu then test mode will be engaged at
the last selected speed ('Slow' initially). When test mode is engaged it
can be cancelled either by reselecting it from the menu, or by selecting
"Off" from the Test Mode submenu.

You can simultaneously engage test mode and select a speed by selecting
one from the Test Mode submenu. The three speeds are (very approximately):

      * Slow, 1-2 hours per second, normal speed update.
      * Fast, about 3 days per second, updated quickly.
      * Ludicrous, about a week per second, updated quickly.



Quitting
````````
The original RISC OS version of MoonTool was quit by closing its main
window. This version should be quit by selecting "Quit" from its menu (or
by quitting it from the Task Manager's Tasks display, etc).


Options
```````
There are a few user selectable options that can be set by editing the
application's !Run file.

The options are:

Start up 'iconified': -i
    This is set as standard. If for some reason you want MoonTool to open
    its main window at startup (rather than the little 'icon' window) then
    removing the -i from the !Run file will make this happen.
    Conversely, replacing the -i will cause MoonTool to open the small
    'icon' window rather than the main window at startup.

Hemisphere: -n or -s
    You can select either Northern or Southern hemisphere in the !Run file
    by including the flags -n or -s as appropriate.
    By default, MoonTool assumes Northern hemisphere.

Open phases window at startup: -p
    This flag will cause MoonTool to open the moon phases window at
    start-up.

Start in test mode: -t
    This flag causes MoonTool to start up in test mode (at the default,
    ie. slow, speed).

Use outline fonts in the windows: -o
    This flag causes MoonTool to use outline fonts in its windows.
    Depending on  the machine and monitor/screen-mode combination you are
    using you may find that outline fonts improve/reduce readability.

Brighten text in the windows: -b
    You may find, especially at large screen sizes, that the grey-on-black
    text in the MoonTool windows is too hard to read. The -b option causes
    MoonTool to display all text (that has a black background) in white
    rather than grey.




Accuracy
````````
To the best of my knowledge the dates and times given by MoonTool are
reasonably accurate. The original documentation (which is included
verbatim as !MoonTool.!HelpOrig) says that the times should be accurate to
within 10 minutes.

If you feel like checking up on MoonTool there are tables of moon phases,
etc. available on the 'net, for example:

      * Moon Phase times for 1990 - 2005:
      http://aa.usno.navy.mil/AA/data/docs/MoonPhase.html
      * Virtual Reality Moon Phase pictures:
      http://tycho.usno.navy.mil/vphase.html



Differences between the RISC OS version and the original
````````````````````````````````````````````````````````
I've substantially changed the part of MoonTool that determines the times
of the new moons surrounding a given date (and from these the times of the
quarters in between). This was necessary since the original method could
produce incorrect results, especially when using the time selection window.

The "ghost moon" drawing is my own interpretation of how this should be
done. I believe that the Sun/X11 versions have an option to use colour or
monochrome when drawing the moon and show the dark area of the moon in
blue. I haven't bothered with the monochrome option (it doesn't really
seem worth it...) and chosen to make the dark moon look dark. If you
really do want it to be blue, this is possible (see below in the "techie"
section).

The Moon sprites used were obtained by scaling down a rather nice picture
of the full moon I obtained from a PD source some years ago.


Technical details
`````````````````
The full source code is available as a separate archive. It should be
available from the same place as MoonTool itself, or failing that from my
web pages, or failing that drop me an e-mail.

It's possible to change the way that the dark moon is drawn by editing
MoonTool's Messages (and possibly Sprites) files. Specifically, the
Messages file contains the definition of the pixel translation table used
to darken pixels in the sprite.

It should also now be possible to create a version of MoonTool for a
different language without having to re-compile. The Messages and
Templates files should now contain all the language specific words/phrases.


History (of my versions)
````````````````````````
3.26 (27 Sep 1999)

    * Added the Gamma Correction facility.
    * Toggling the size of the 'icon' window now switches between the small
      and large versions.
    * Test mode now updates the window(s) more quickly for fast/ludicrous
      speed.
    * Gamma and big/small 'icon' window state is now saved along with the
      window positions (hence Save positions => Save choices).
    * There is no longer any need to delete the WinPosns file if you change
      which of the small/large 'icon' windows you use.
    * Now tested (and confirmed working) under RISC OS 4.

3.25 (28 Apr 1999)

    * Added a workaround for a problem with the RISC OS 3.1 Wimp
      which caused the text in the windows not to update properly.
    * Corrected the spelling of kilometres.

3.24 (05 Apr 1999)

    * Redesigned the windows to give a much cleaner and more elegant
      layout.  This was prompted by the much larger Moon sprite (twice the
      size of the original).
    * Month names are now displayed abbreviated in all windows but the
      User time window and years are displayed in two-digit year format.
    * Tweaked the moon-drawing to pre-calculate some of the trig. stuff it
      uses. This gives a significant improvement to the speed of updating
      the moon-phase sprite (with a 132 pixel high sprite the old code was
      much too slow).
    * The moon-icon sprite is now created on-the-fly from the large
      sprite. This looks much better than just letting the Wimp plot the
      large one at half-size.
    * Added large icon option. This causes the full-size moon-phase sprite
      to be used rather than the half-size one.
    * Removed the hemisphere specific sprites - the northern hemisphere
      sprites are now rotated at load time if need be. In addition the
      sprites that are created on the fly are now blank in the sprite file
      to make the archive smaller :)
    * Added code to open/close the Phases window when the Moon icon
      is clicked with Adjust.
    * Added interactive help.
    * Workaround for a problem with the Moon: the string of 'itty-bitty'
      craters that runs in a vertical line through the middle of the
      sprite looked a mite nasty (they don't exactly look good on the real
      Moon, to be honest) so have been de-emphasised to counter the
      effects of the scaling, etc. that the Moon sprite has gone through.
    * Added the -b (brighten) and -o (outline fonts) options.

3.11 (16 Mar 1999)

    * Fixed the Julian date as displayed in the main MoonTool window (it
      was 0.5 too high).
    * Fixed a small problem that could cause the moon-phases window not
      to update properly when 'Current' is re-enabled in the user time
      window.
    * Added a menu option to save the positions of the windows.
    * Changed the layout of the moon phases window to make it the same
      height as the main MoonTool window and less 'fussy'.
    * Tweaked the ghost-moon/earth light pixel translation table to look
      better, especially in 256+ colour modes.

3.10 (24 Feb 1999)

    * Updated the core algorithms to the latest ones available in the
      Sun/X11 versions.
    * Re-wrote the Desktop specific code to suit my tastes and fit the
      DeskLib style better.
    * Improved the handling of the time selection window considerably and
      made it into a proper dialog window rather than a menu.
    * Added the main menu and Info window.
    * Split the moon phases into an independent window. Added code to
      open this window at startup if requested.
    * Closing the main window now "iconifies" the program (ie. acts as if
      the moon button had been clicked).
    * Added code to give (pinboard) iconised windows sensible titles.
    * Added Test Speed menu.
    * Re-worked the phase-hunting function to (hopefully!) work correctly.

2.00 (19 Feb 1999)

    * My initial release with Northern/Southern hemisphere correction,
      user selectable time and high-resolution moon graphics. Still
      substantially based on Eduoard's original port (ie. the version 2.0
      referred to in the original help text)




Credits
```````
Designed and implemented by John Walker in December 1987. Revised and
updated in February of 1988. Revised and updated again in June of 1988 by
Ron Hitchens. Revised and updated yet again in July/August of 1989 by Ron
Hitchens.

Original RISC OS port by Edouard Poor, circa 1993. This RISC OS port by
Musus Umbra, 1999.

RISC OS MoonTool was built using DeskLib (the freeware desktop C library
for RISC OS machines).

I'd like to thank the following people for variously suggesting
improvements, offering advice and prompting me to update the program in
the first place: Alan Gray, Reg Hemms, Raymond Ling, Michael Rozdoba,
Graham Jenkins, Fionn Taylor & Matthew Somerville.


Copyright
`````````
This program is in the public domain: "Do what thou wilt shall be the
whole of the law".

Please leave the original attribution information intact so that credit
and blame may be properly apportioned.


Disclaimer
``````````
The authors cannot and will not be held responsible for any loss or damage
arising from the use of, misuse of, or inability to use this software.

I am, however, interested in bug reports and feedback and will do my best
to help if you do have problems.


Contact details
```````````````
Musus Umbra, aka Adny:
e-mail: musus@argonet.co.uk
   web: http://www.argonet.co.uk/users/musus/
 snail: c/o 23 Baronsway, Whitkirk, Leeds 15, LS15 7AW, ENGLAND

