Basic Unix Installation Instructions for the Weather Utility
==============================================================
-:Copyright: (c) 2006-2010 Jeremy Stanley <fungi@yuggoth.org>. Permission to
- use, copy, modify, and distribute this software is granted under
- terms provided in the LICENSE file distributed with this software.
+:Copyright: (c) 2006-2014 Jeremy Stanley <fungi@yuggoth.org>. Permission
+ to use, copy, modify, and distribute this software is
+ granted under terms provided in the LICENSE file distributed
+ with this software.
.. contents::
Prerequisites
-------------
-You need the Python interpreter installed somewhere in your path (most modern
-UNIX derivatives come with one already). If you need to get Python, it can be
-obtained from http://www.python.org/ (but chances are your operating system at
-least provides some sort of native package for it, which you should probably
-install in whatever means is recommended by your OS vendor/distributor).
+You need the Python interpreter installed somewhere in your path (most
+modern UNIX derivatives come with one already). If you need to get
+Python, it can be obtained from http://www.python.org/ but chances are
+your operating system at least provides some sort of native package for
+it, which you should probably install in whatever means is recommended
+by your OS vendor/distributor. The script is tested with recent 2.x and
+3.x Python versions, attempting to maintain forward/backward
+compatability with the interpreter, so bug reports or patches to ensure
+this continues to be the case are most welcome.
Running in Place
----------------
-An easy way to try it out is to unpack the tarball and change to the resulting
-directory::
+An easy way to try it out is to unpack the tarball and change to the
+resulting directory::
tar xzf weather-*.tar.gz
cd weather-*
./weather --help
man ./weather.1
man ./weatherrc.5
- ./weather --forecast --no-conditions --city=charlotte --st=nc
- ./weather ord sea
+ ./weather --forecast rdu
+ ./weather clt gso
-...and so on. The weather utility, included Python module and documentation are
-all fully functional when kept together in one directory, if somewhat
-inconvenient.
+...and so on. The weather utility, included Python module and
+documentation are all fully functional when kept together in one
+directory, without needing to install these components to other
+locations within the filesystem hierarchy.
Installing the Utility
----------------------
-The file named weather should be made executable and put somewhere in your path
-(/usr/local/bin/ or ~/bin/ for example). Similarly, weather.py needs to be
-somewhere in Python's include path. You can see your Python interpreter's
-default include path by running::
+The file named weather should be made executable and put somewhere in
+your path (/usr/local/bin/ or ~/bin/ for example). Similarly, weather.py
+needs to be somewhere in Python's include path. You can see your Python
+interpreter's default include path by running::
- python -c "import sys ; print sys.path"
+ python -c 'import sys ; print(sys.path)'
+
+If the correlation data files are to be used (airports, places,
+stations, zctas, zones), they need to be in your current working
+directory or a directory mentioned within the "default" section's
+"datapath" option of the weatherrc file.
Configuration
-------------
-The weatherrc file should go in /etc/ or you can save it in your home directory
-as a dotfile (~/.weatherrc) to support user-specific alias configuration and
-overrides of the global /etc/weatherrc file.
+The weatherrc file should go in /etc/ or /etc/weather/ for global
+configuration. You can save it in your home directory as a dotfile
+(~/.weather/weatherrc or ~/.weatherrc) to support user-specific alias
+configuration and overrides of the global weatherrc file.
Manuals
-------
-Optionally, the weather.1 and weatherrc.5 files can be placed in sane locations
-for TROFF/NROFF manual files on your system (for example, /usr/local/share/man/
-or ~/man/).
+Optionally, the weather.1 and weatherrc.5 files can be placed in sane
+locations for TROFF/NROFF manual files on your system (for example,
+/usr/local/share/man/ or ~/man/).
+
+Updating Correlation Sets
+-------------------------
+The version control repository and tarballs are occasionally updated
+with refreshed correlation sets (the files which track what the nearest
+stations and weather zones are to various places). If you find you need
+to generate updated correlation sets yourself, however, it can be done.
+
+You'll need to retrieve the most recent source databases from the
+different sites mentioned in the comments at the top of a recent
+correlation data file--each one includes a comment block with a list of
+the origins and checksums of the data files used along with the date and
+time they were built. You'll also want to generate recent slist and
+zlist files (look at the comments at the top of each for the shell
+commands used to generate them). You probably also need the most recent
+overrides.conf from the weather source repository or tarball, since that
+contains known corrections for errors in the original data. Put all of
+these files in your current working directory and then call::
+
+ weather --build-sets
+
+Then wait, and wait, and wait some more. After loading and analyzing the
+source data, it will guess an upper-bound for the number of great-arc
+distance calculations it may have to perform and attempt to give you a
+progress bar indicating percent completion. If you're lucky, it will
+finish successfully also generate some automated quality assurance
+analysis of the results (mostly checking for obviously bad airports,
+stations, zones). If you are UNlucky, it will break, which is not
+terribly uncommon because the government-provided source data is often
+misformatted or gets sudden schema changes requiring updates to the
+parsing routines in weather.
+
+If you're using a system-wide (for example, distribution packaged) copy
+of weather and its data, you may want to place the new airports,
+stations, places, zctas and zones files into your ~/.weather directory
+and make use of the setpath configuration or command-line options to
+override where weather looks for them. See the weather(1) and
+weatherrc(5) manpages for details.
projects / weather.git / blobdiff