CVS: phpweather/doc/src phpweather.texi,1.5,1.6
Brought to you by:
iridium
From: Martin G. <gim...@us...> - 2004-01-01 22:50:41
|
Update of /cvsroot/phpweather/phpweather/doc/src In directory sc8-pr-cvs1:/tmp/cvs-serv28989 Modified Files: phpweather.texi Log Message: Moved the Contributors chapter to contributors-body.texi, and expanded things like "it's" to "it is". Index: phpweather.texi =================================================================== RCS file: /cvsroot/phpweather/phpweather/doc/src/phpweather.texi,v retrieving revision 1.5 retrieving revision 1.6 diff -u -3 -r1.5 -r1.6 --- phpweather.texi 10 Oct 2003 23:33:27 -0000 1.5 +++ phpweather.texi 1 Jan 2004 22:50:31 -0000 1.6 @@ -6,13 +6,10 @@ @c @setchapternewpage odd @c %**end of header -@set VERSION #VERSION# -@set RELEASED #DATE# - @titlepage -@title PHP Weather Version @value{VERSION} -@subtitle Reference and Users Guide released on @value{RELEASED} +@title PHP Weather Version #VERSION# +@subtitle Reference and Users Guide released on #DATE# @author Martin Geisler @email{gimpster@@phpweather.net} @c The following two commands start the copyright page. @@ -35,12 +32,12 @@ @node Top @top PHP Weather - a @acronym{METAR} Decoder -@noindent This is the definitive guide to PHP Weather, or at least it -tries to be. PHP Weather is a script written in -@uref{http://www.php.net/, PHP} which makes it possible to display the -current weather on a webpage. The system is based on data from 4,500 -airports scattered all over the world, so there's a good chance that -you'll find a station near your place. +This is the definitive guide to PHP Weather, or at least it tries to +be. PHP Weather is a script written in @uref{http://www.php.net/, PHP} +which makes it possible to display the current weather on a +webpage. The system is based on data from 4,500 airports scattered all +over the world, so there is a good chance that you will find a station +near your place. @end ifnottex @contents @@ -73,7 +70,7 @@ Using PHP Weather * Output Modules:: The standard output modules -* The Raw Data:: It's yours to play with, if you want it +* The Raw Data:: It is yours to play with, if you want it Output Modules @@ -107,8 +104,8 @@ format which PHP Weather can decode. The METAR reports are made at about 4,500 airports from around the -world, so there's a good chance that you live near one of them. And -the airports make an report once or twice an hour, so you'll be able +world, so there is a good chance that you live near one of them. And +the airports make an report once or twice an hour, so you will be able to provide fresh reports on your website. The reports from all over the world are stored at the National Weather @@ -116,11 +113,11 @@ a department under the National Oceanic and Atmospheric Administration (@dfn{NOAA}, see @uref{http://www.noaa.gov/}) of the United States. The reports are available using both HTTP and FTP --- PHP Weather uses -HTTP because it's the fastest of the two protocols. +HTTP because it is the fastest of the two protocols. -Once you've got hold of a METAR, you'll want to display the weather -report contained within it. A textual display, known as a @dfn{pretty -print} looks like this: +Once you have got hold of a METAR, you will want to display the +weather report contained within it. A textual display, known as a +@dfn{pretty print} looks like this: @quotation @@ -151,7 +148,7 @@ @end quotation -Each station is uniquely identified by it's @dfn{ICAO} code. ICAO is +Each station is uniquely identified by it is @dfn{ICAO} code. ICAO is an abbreviation for the @uref{http://www.icao.org/, International Civil Aviation Organization}. @@ -169,7 +166,7 @@ @item You can change the language of the report. The report is built by combining many tiny strings which can be translated into other -languages. There's also support for more diverse translations, see +languages. There is also support for more diverse translations, see @ref{Diverse Translations}. @end itemize @@ -185,7 +182,7 @@ @noindent PHP Weather has been designed so that it is easy to install it. After -you've obtained PHP Weather, just unpack it somewhere on your +you have obtained PHP Weather, just unpack it somewhere on your webserver and load the file @file{index.php} in your favorite browser. The next section will give you more details. @@ -204,19 +201,19 @@ @noindent The first thing to do, is to get hold of PHP Weather. The official PHP Weather homepage can be reached at @uref{http://phpweather.net/} and -you'll be able to download the latest version of PHP Weather from the +you will be able to download the latest version of PHP Weather from the ``Downloads'' section. -After you've downloaded PHP Weather in your favorite format (we +After you have downloaded PHP Weather in your favorite format (we provide files in three formats: @file{tar.gz}, @file{tar.bz2}, and @file{zip}) you should unpack it in a temporary place. If the file you downloaded is called @file{phpweather-x.y.tar.gz}, then it will be unpacked in a directory called @file{phpweather-x.y}. Upload this -directory with all it's files to your webserver. +directory with all its files to your webserver. PHP Weather has now been installed! Use your browser to load the file @file{index.php} found in the root-directory of the PHP Weather -installation and see how it works. You'll be presented with a +installation and see how it works. You will be presented with a demonstration of PHP Weather. @node Configuration @@ -252,7 +249,7 @@ @item Next, the file @file{defaults.php} is read if it exists. This file -isn't part of the PHP Weather distribution, but should be created by +is not part of the PHP Weather distribution, but should be created by you if you want to change some of the defaults from @file{defaults-dist.php}. @@ -276,9 +273,9 @@ @end example @item -You can change some of the options after you've created the object. If -you want to change the current ICAO of a @code{phpweather} object, -then you'll use the @code{set_icao} method like this: +You can change some of the options after you have created the +object. If you want to change the current ICAO of a @code{phpweather} +object, then you will use the @code{set_icao} method like this: @example $weather->set_icao('EKYT'); @@ -287,28 +284,28 @@ @end enumerate The idea is, that you should create a @file{defaults.php} file with -the options that you'll always want to use --- things like database +the options that you will always want to use --- things like database and proxy settings. To create the file, you should use the supplied script @file{make_config.php} found in the @file{config} directory. Load the script in the browser and follow the instructions. In short, then you build the configuration file by repeatedly choosing/changing -options until the all say ``Input accepted''. You'll notice that all +options until the all say ``Input accepted''. You will notice that all options are at their default settings when you load the page initially ---- you'll have to change something and press the ``Update Options'' +--- you will have to change something and press the ``Update Options'' button before anything changes. When you press the button, the page will reload, and the configuration file found at the bottom is updated with your new selections. Also, your selection might give your more choices such as when you change the @code{use_proxy} option from ``No'' to ``Yes''. When you press the -update button you'll be presented with input fields for the +update button you will be presented with input fields for the @code{proxy_host} and the @code{proxy_port}. Because we cannot anticipate the name of your proxy, the @code{proxy_host} will be set -to nothing (the empty string ``'') initially. Since this isn't a valid -hostname, you'll see a text in red that says exactly this. +to nothing (the empty string ``'') initially. Since this is not a +valid hostname, you will see a text in red that says exactly this. -Continue to make changes to the options. When you're happy with the +Continue to make changes to the options. When you are happy with the configuration you should press the ``Download the Configuration'' button. Your browser should ask you where to same the downloaded file --- save it as @file{defaults.php} in the root of your PHP Weather @@ -328,8 +325,8 @@ @noindent PHP Weather works by retrieving weather reports called METARs. It -takes some time to get the METARs, so you'll be interested in using a -local database as a cache. All database backends support the same +takes some time to get the METARs, so you will be interested in using +a local database as a cache. All database backends support the same features (see @ref{Required Functions in a Backend} for details) but differ in speed. Your version of PHP might also lack support for some of the backends. PHP Weather supports the following databases @@ -338,17 +335,17 @@ @table @code @item null -This is the default ``database'' backend, but it isn't really a +This is the default ``database'' backend, but it is not really a database. It pretends to cache the METARs, but in reallity it just throws them away. This means that PHP Weather will have to fetch them from the NWS again each time. This makes the @code{null} backend the slowest backend if you repeadaly need the same METAR, e.g. if you show the current weather -for a fixed location on your homepage. But it's just as quick (or +for a fixed location on your homepage. But it is just as quick (or slow, depending on how you view things) as the other backends when it -comes to showing the weather for a random station. So if that's your -usage-pattern, then you might like this backend. +comes to showing the weather for a random station. So if that is your +typical usage-pattern, then you might like this backend. @item pw_mysql You can use the @uref{http://www.mysql.com/, MySQL} relational @@ -360,37 +357,36 @@ @item pw_dba This database backend uses normal files on the webserver to do the -caching. You'll have to ensure that the PHP process on the webserver +caching. You will have to ensure that the PHP process on the webserver can write to the @file{db/files} directory so that the necessary files can be created and maintained. @end table -After you've chosen a database backend, you'll have to initialize the -database. You should first generate the appropriate +After you have chosen a database backend, you will have to initialize +the database. You should first generate the appropriate @file{defaults.php} file, see @ref{The defaults.php file}. -After you've uploaded the file to the webserver, you can load the +After you have uploaded the file to the webserver, you can load the script @file{make_db.php} found in the @file{config} directory in your favorite browser. When you press the ``Create or Recreate Tables'' -button the database will be initialized. If you've selected a -SQL-based database, then the necessary tables will be -created. +button the database will be initialized. If you have selected a +SQL-based database, then the necessary tables will be created. -If you've selected a file-based database, then the script will attempt +If you have selected a file-based database, then the script will attempt to create the necessary files. This might very well fail: the script is run by the webserver, and the webserver will most likely @emph{not} have permission to create new files in the @file{db/files} directory under the PHP Weather root directory because the webserver runs as an unprivileged user. -So, you'll have to change the permission on the @file{db/files} -directory. I'll assume that the webserver is running some form of -Unix. If you have shell access to the machine, then you can execute -the following commands after you have logged into the webserver. If -you don't have that kind of access to the machine, then you should -still be able to change the permissions using your FTP -program. The relevant commands are: +So, you will have to change the permission on the @file{db/files} +directory. Assuming that the webserver is running some form of Unix +and that you have shell access to the machine, then you can execute +the following commands after you have logged into the webserver. If +you do not have that kind of access to the machine, then you should +still be able to change the permissions using your FTP program. The +relevant commands are: @example cd /root/directory/of/phpweather/installation @@ -411,8 +407,8 @@ @noindent All database backends have to support a common set of methods --- if PHP had support for @emph{interfaces}, then we would require them to -implement a database interface. Because of the lack of interfaces in -the PHP language we're left with this description of what a database +implement a database interface. Because of the lack of interfaces in +the PHP language we are left with this description of what a database backend has to satisfy. All database backends are defined in their own class which is a @@ -444,13 +440,13 @@ @cindex usage @noindent -Now that you've learned about how to install and configure PHP +Now that you have learned about how to install and configure PHP Weather, you might want to learn how you can use it on your own webpages. @menu * Output Modules:: The standard output modules -* The Raw Data:: It's yours to play with, if you want it +* The Raw Data:: It is yours to play with, if you want it @end menu @node Output Modules @@ -460,7 +456,7 @@ @cindex modules, output @noindent -The textual output you've seen on the @file{index.php} demonstration +The textual output you have seen on the @file{index.php} demonstration page is produces by an @dfn{output module} called @code{pw_text}. The images are selected by another module called @code{pw_images}. @@ -485,7 +481,7 @@ @cindex data, raw @noindent -It's easy for you to get hold of the raw data produced by the code in +It is easy for you to get hold of the raw data produced by the code in @file{phpweather.php}: @example @@ -498,9 +494,10 @@ was able to extract from the METAR. The different parts in the METAR is stored under specific keys in the array --- if the METAR lacks a given part, then the corresponding entry in the array will be left -out. This means, that you'll have to check each entry with -@code{empty} before you use it, otherwise you see warnings from PHP, -if you've set the error reporting level high enough. +out. This means that you will have to check each entry with the +built-in PHP function @code{empty} before you use it, otherwise you +see warnings from PHP, if you have set the error reporting level high +enough. You can have PHP show you the structure of the array by using the builtin @code{print_r} function like this: @@ -518,7 +515,7 @@ @item type This can either be @samp{METAR} or @samp{SPECI} and denotes the type -of the report. This isn't used for anything. +of the report. This is not used for anything. @item metar The raw METAR report. @@ -542,8 +539,8 @@ @item report_mod A report modifier which gives information about how the report was made: @samp{AUTO} for a fully automated report with no human -intervention or @samp{COR} for a corrected report. It's supposed to be -part of all METARs, but experience shows that it's not. +intervention or @samp{COR} for a corrected report. It is supposed to +be part of all METARs, but experience shows that it is not. @item wind This is an array with information about the wind. The @code{deg} entry @@ -571,7 +568,7 @@ The visibility itself is stored in the @code{meter}, @code{km}, @code{ft}, and @code{miles} entries. There is an optional entry -@code{dir} for a direction --- if there's no direction, then the +@code{dir} for a direction --- if there is no direction, then the visibility refers to the overall visibility. @item runway @@ -583,7 +580,7 @@ ``center'', or ``right'' respectively. The visibility information can either be a single value or a pair of -values in case of varying conditions. If there's only a single value, +values in case of varying conditions. If there is only a single value, then @code{meter} and @code{ft} holds the visibility, an optional @code{prefix} can be @samp{-1} if range is less than the lowest reportable value or @samp{1} if greater than the greatest reportable @@ -596,7 +593,7 @@ @item weather This holds the current weather phenomena and is one of the most -interesting groups. It's an array of weather groups which means that +interesting groups. It is an array of weather groups which means that the the first group will be @code{$data['weather'][0]}, the second group (if there is such a group) will be @code{$data['weather'][1]}, and so on. @@ -621,8 +618,8 @@ for ``few clouds'', @samp{SCT} for ``scattered clouds'', @samp{BKN} for ``broken clouds'', @samp{OVC} for ``overcast'', and @samp{SKC} and @samp{CLR} for ``clear sky''. The condition @samp{CAVOK} is a bit -special, because if it's present, then the @code{condition} entry will -be the only entry in the cloud group. +special, because if it is present, then the @code{condition} entry +will be the only entry in the cloud group. The other conditions will be part of a larger array with an optional @code{cumulus} entry denoting the presence of cumulonimbus (@samp{CB}) @@ -632,8 +629,8 @@ @samp{nil}. Theres an optional @code{prefix} with the usual meaning. @item temperature -This is the temperature group. It's an array with two or four entries: -@code{temp_c} and @code{temp_f} is always present and is the +This is the temperature group. It is an array with two or four +entries: @code{temp_c} and @code{temp_f} is always present and is the temperature in degrees Celsius and Fahrenheit respectively. If information about the dew-point is present, then @code{dew_c} and @code{dew_f} will be added to the array. @@ -655,7 +652,7 @@ timescales. The entries @code{mm} and @code{in} contains the precipitation during the last hour, entries @code{mm_h6} and @code{in_6h} store the amount of precipitation in the last 3--6 hours -and finally there's @code{mm_24h} and @code{in_24h} with the +and finally there is @code{mm_24h} and @code{in_24h} with the precipitation measured over the last 24 hours. If there has been snowfall, then that will be reported in the @code{snow_mm} and @code{snow_in} entries. @@ -664,7 +661,7 @@ that there was only a trace of precipitation. @item remarks -Anything which isn't recognized is added to this entry. +Anything which is not recognized is added to this entry. @end table @@ -687,6 +684,10 @@ @cindex diverse translations @cindex advanced translations +@noindent +PHP Weather has facilities ready that makes it possible to totally +redefine the generated text from within a translation. + @node Things To Do @chapter Things To Do @cindex TODO list @@ -708,7 +709,7 @@ contain @emph{forecasts} instead of just the current weather. This is of course much more interesting that the current weather conditions. -There's more information about how to decode TAF reports at this +There is more information about how to decode TAF reports at this website: @uref{http://www.awc-kc.noaa.gov/awc/help/taf-decode.html}. @item @@ -751,21 +752,21 @@ etc.) that could display the weather. I discovered that they got their data from the NWS who makes the data available at no cost. -The data is available off the Internet via either FTP or HTTP, so it's -easy to get hold of it with PHP. The only problem was that the data -has to be decoded because it's written in a compact fashion. The data +The data is available off the Internet via either FTP or HTTP, so it +is easy to get hold of it with PHP. The only problem was that the data +has to be decoded because it is written in a compact fashion. The data in question is a so-called METAR report that the airports issue once or twice an hour. I then discovered a script written in Perl that could take a METAR and -split it into it's components. The script was written by Jeremy +split it into its components. The script was written by Jeremy D. Zawodny @email{Jeremy@@Zawodny.com} and is licensed under the GPL just like PHP Weather. So there was no problem with me peeping at his code for PHP Weather. I took the logic from the Perl script and wrote a function in PHP that would decode a METAR. -But that wouldn't do it --- to be useful the decoded data has to be -displayed in a nice fashion, preferable so that it's easy to +But that would not do it --- to be useful the decoded data has to be +displayed in a nice fashion, preferable so that it is easy to customize. The script should also be able to fetch a METAR from the NWS and once that is done, the METAR should be cached so that the script would run faster after the METAR had been fetched once. The @@ -777,11 +778,10 @@ degrees Fahrenheit)''. That turned out very nice so I released the code to the public. -I didn't think about internationalization then, but after a while, I -received a Spanish translation made by Eduardo Guilenea -@email{eduardo@@guilenea.com}. Because the script wasn't ready for -internationalization, he had simply gone through the script and -translated all the English words into Spanish. +I did not think about internationalization then, but after a while, I +received a Spanish translation made by Eduardo Guilenea. Because the +script was not ready for internationalization, he had simply gone +through the script and translated all the English words into Spanish. That promped me to start thinking about how we could translate PHP Weater into other languages. I quickly found out, that it would work @@ -805,188 +805,12 @@ flexible structure. All locale-specific code has been moved out from the main parsing algorithms, so that PHP Weather can be truly localized. All access to the database is now done through a database -abstraction layer: each database is defined in it's own class, so it's +abstraction layer: each database is defined in its own class, so it is free to implement the various methods any way it wants. - - - @node Contributors @chapter Contributors - -@noindent -Everybody listed below has helped in some way with the creation of PHP -Weather. If, by some mistake, your name isn't listed below, then send -a mail to @email{gimpster@@gimpster.com} so that proper credit can -given. - -@table @asis - -@item Kristian Kristensen @email{zianet@@zianet.dk} - -He made the interface to PostgreSQL. - -@item Jeremy D. Zawodny @email{Jeremy@@Zawodny.com} - -He wrote @code{Geo::METAR}, which is a Perl module which can do some -of the things PHP Weather now does. @code{Geo::METAR} can be found -here: @uref{http://www.wcnet.org/jzawodn/perl/Geo-METAR/index.html}. - -@item Enrico Lodolo @email{e.lodolo@@bo.nettuno.it} - -For suggesting that I use http to get the METARs instead of the much -slower ftp. - -@item Stefan Wiesendanger @email{stefan.wiesendanger@@epfl.ch} - -For rewritting some large @code{case}- and @code{switch}-statements as -a couple of arrays. This speeds-up the parsing of the METARs. - -@item Mike @email{bvrtrimmer@@lycos.com} - -He noticed that the pressures was all wrong. I though the unit used in -the METAR was hPa, when it really was inHg. - -@item Jeffrey Y. Sue @email{jysue@@tiki.net} - -Suggested that I told people how to turn off the warnings, if you -don't establish a connection to MySQL. - -Later he made it possible to use PHP Weather with DBM databases. He -also added support for precipitation. Lots of other stuff, see the -@file{ChangeLog} for more details. - -@item Rutger Lubbers @email{rutger@@notenbomer.nl} - -Noticed that South/southeast was duplicated in the directions-array. - -@item Eduardo Guilenea @email{eduardo@@guilenea.com} - -Translated PHP Weather into Spanish, and thereby forced me to add -support for multiply languages. (Which was a Good Thing :-) - -@item Sven-Erik @email{sven_erik@@andersen.as} - -Translated PHP Weather into Norwegian. - -He also sat down and did the boring work, when he manually compiled -the complete list of all airports available from NWS. - -@item Maciek Uhlig @email{muhlig@@us.edu.pl} - -Noticed that I sometimes tried to access @code{$cloud_coverage_array} -with just @code{$cloud_coverage} --- which, of cause, didn't work. - -@item Ing. Vladimir Kotala @email{kotala@@ingema.net} - -Suggested that I changed the long text @samp{@dots{} degrees Celsius} -into the more compact @samp{@dots{} °C}, which is much -better. - -@item Gyulai Mih@'aly @uref{http://gyulai.freeyellow.com/} - -Made the Hungarian translation for PHP Weather. He has also corrected -tons of spelling errors. - -@item Johnny Funder @email{jhf@@slv.dk} - -Lots of explanations and suggestions. He also gave a much simpler -formula for calculating the relative humidity. - -@item Ray van Beek @email{r_vanbeek@@hotmail.com} - -Helped me spot a little error with the current weather. He has also -written code that displays the current weather as an image. - -@item David Kjellquist @email{dave@@kjellquist.com} - -Added support for windchill. - -@item Max Hammond @email{max@@flipstorm.net} - -Lots of different things: bugfixes, clever suggestions, and general -maintenance. - -@item Jes@'us Pe@=nas @email{jpc@@educaplus.org} - -Made the Spanish translation. - -@item Ondrej Jombik @email{nepto@@pobox.sk} - -Translated PHP Weather into Slovak and rewrote the navigation system -used in index.php. He also looked at the MySQL and PostgreSQL database -and found some security flaws. - -@item Reini Urban @email{rurban@@xarch.tu-graz.ac.at} - -Fixed some problems with using PHP Weather on a default installation -of PHP 4.2. - -@item Kari Salovaara @email{kari.salovaara@@pp1.inet.fi} and Tage Malmen - -Translated PHP Weater into Swedish and Finnish. - -@item Paul Kairis @email{Paul.Kairis@@sas.com} - -Wrote the code that handles connections through a proxy server. - -@item Bas Elshof @email{bas@@elshof.de} - -Translated PHP Weather into Dutch. - -@item V@'aclav R@'{@dotless{i}}kal @email{vaclavr@@physics.muni.cz} - -Made a Czech translation. - -@item Radoslava Fed@'akov@'a @email{mortischka@@pobox.sk} - -Czech translation. - -@item Guillaume Petit @email{gpetit@@fr.st} - -Translated PHP Weather into French. - -@item Rudy Boedts - -Updated the Dutch translation. - -@item Konrad Tadesse - -Finally, a working German translation. - -@item Andrew Simpson (andrewsimpson) - -Reported problems with the use of short open tags in a couple of -files. - -@item Jim Whitehead @email{jim@@twopalms.com} - -Fixed the rounding of hours and minutes in the pretty-printed report. - -@item Ferhat Bingol @email{s021183@@student.dtu.dk} - -Made a Turkish translation. - -@item Renato Gallmetzer @email{renatogl@@renatogl.com} - -Provided us with an Italian translation. - -@item Pablo Alcaraz (pabloa) - -Updated the Spanish translation and other bugfixes. - -@item Etienne Tourigny (etienne_t) - -Added a method that decodes TAF reports and made some of the database -backends archive the data instead of always replacing the old data -with new reports. - -@item Justin Heideman @email{justin_heideman@@mcad.edu} - -Drew a full set of beautiful icons for PHP Weather to display the -current weather conditions. - -@end table +@include contributors-body.texi @node Licenses @appendix Licenses @@ -997,10 +821,11 @@ Because we believe in @uref{http://www.opensource.org/, Open Source}, we have licensed the code in PHP Weather under the GNU General Public License and the manual under the GNU Free Documentation License. This -license is similar to the GPL, it's just aimed for documentation. +license is similar to the GPL, it is just aimed for documentation. This means that you are allowed to use PHP Weather on as many websites -as you like, and you're even allowed to use it on commercial websites. +as you like, and you are even allowed to use it on commercial +websites. @menu * GNU General Public License:: |