X-Git-Url: https://www.yuggoth.org/gitweb?p=weather.git;a=blobdiff_plain;f=INSTALL;h=17eac873d4f98333da9546b302866a2dc9151602;hp=da831b6dbd34bd424152fb79371d61c6c2a6ba6d;hb=676e13b0be2c514ade912957782d7b42f1d91b36;hpb=8349654b7c627448b1e56c2943234895724d7857

diff --git a/INSTALL b/INSTALL
index da831b6..17eac87 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,59 +1,68 @@
-BASIC UNIX INSTALLATION INSTRUCTIONS FOR THE WEATHER UTILITY
-
-Copyright (c) 2006-2008 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.
-
-
-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).
-
-
-RUNNING IN PLACE
-
+==============================================================
+ Basic Unix Installation Instructions for the Weather Utility
+==============================================================
+
+:Copyright: (c) 2006-2012 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. 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:
+resulting directory::
 
    tar xzf weather-*.tar.gz
-   cd weather
+   cd weather-*
    ./weather --version
    ./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.
-
-
-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:
-
-   python -c "import sys ; print sys.path"
-
-
-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.
-
-
-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/).
+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::
+
+   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 /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/).