phpweather-checkins

[Martin G. <gim...@us...>]

Update of /cvsroot/phpweather/phpweather/docs/src/latex
In directory usw-pr-cvs1:/tmp/cvs-serv15376

Modified Files:
	apidoc.tex installation.tex main.tex phpweather-a4.tex 
	translation.tex 
Added Files:
	databases.tex history.tex 
Log Message:
Added some extra files to the documentation. The documentation needs a
lot of work right now, but if anybody wants to write something, feel
free. 

You shouldn't be intimidated by the fact that it's written in LaTeX,
as long as you're writing plain text, there shouldn't be any problems.


--- NEW FILE ---
% -*- mode: latex; tex-main-file: "phpweather-a4" -*-
\chapter{Database Backends}

As it takes about a second to retreive a \metar, \phpw supports
caching. \phpw supports several different database backends and it's
easy to write support for a new one.

\section{What's In a Database Backend?}

Each database backend is implemented through a separate class which
extends \class{pw\_db\_common}. This is convenient, as
\class{db\_common} has some properties needed by almost every back
end, most notably \variable{\$}{link\_id}.

It is up to the backend to decide how it will implement the functions
needed by \phpw, but it is required that each back-end has the
following methods:
\begin{description}

\item[\function{connect}] This will be called whenever the script
needs to make sure that we're connected. It must return true if a
connection is established, and false otherwise.

\item[\function{insert\_metar}] This is called when a new \metar should
be inserted into the cache.

\item[\function{update\_metar}] If the \metar is already in the cache,
this function will be called instead of \function{insert\_metar}.

\item[\function{get\_metar}] This function should return the \metar
report for a given \icao. If the \metar isn't found in the cache, it
should just return an empty string.

\item[\function{get\_countries}] This function returns a list of all
countries that have airports producing \metar reports.

\item[\function{get\_icaos}] Once you've selected a country, you'll
use this function to get a list of all airports in that country.

\end{description}

\section{Writing a New Back-end}

If you use \phpw on a system where you don't have access to one of the
databases already supported, you could write support for your own
database.

You should start by taking one of the existing back-ends, and use that
as a template. If your database understands SQL, then use a back-end
like \class{db\_mysql} as your template, as it also uses SQL.

Then go through the file, and adopt the functions to your database.
When you're done, send your file to
\email{php...@li...} so that it can be
included in the package.


--- NEW FILE ---
% -*- mode: latex; tex-main-file: "phpweather-a4" -*-

\chapter{History}

I began writing PHP Weather in June 2000. I had been talking with
Kristian Kristensen \email{zi...@zi...} about making such a
script for a project we were both working on. But it was only after
the project was finished, that I began investigating the possibilities
of making a script with PHP that could display the current weather.

I knew that it was possible to do such a thing, as I had seen a couple
of applets (small programs that serves only one purpose, such as
displaying the time or the amount of free space on the hard drive,
etc.) that could display the weather. I discovered that they got their
data from the National Weather Service (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
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 D.
Zawodny \email{Je...@Za...} 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
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
problem is, that it takes about a second to contact the NWS.

I started wrapping the actual data in English words to form sentences
like in 'The temperature is 5 degrees Celsius (x degrees Fahrenheit)'.



Index: apidoc.tex
===================================================================
RCS file: /cvsroot/phpweather/phpweather/docs/src/latex/apidoc.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -3 -r1.3 -r1.4
--- apidoc.tex	17 Jul 2001 12:25:13 -0000	1.3
+++ apidoc.tex	11 Mar 2002 16:50:07 -0000	1.4
@@ -27,7 +27,7 @@
 
 \item[Author] Martin Geisler \email{gim...@gi...}
 
-\item[Version] \variable{\$}{Id}: base\_object.php,v 1.10 2001/07/08 18:57:34 misibacsi Exp \$
+\item[Version] \variable{\$}{Id}: base\_object.php,v 1.11 2001/07/17 12:12:03 gimpster Exp \$
 
 \item[Filename] \filename{PHPWEATHER_BASE_DIR/base_object.php}
 
@@ -64,3167 +64,3365 @@
 
 
[...4787 lines suppressed...]
+of
+the output-object.
+
+\begin{funcdesc}
+
+\item[Definition] \functiondef{public string print\_table(void)}
+
+\item[Return value] \textbf{string}\hspace{\labelsep} The table-printed weather-report.
 
 \end{funcdesc}
 
-% End of function get_icaos()
+% End of function print_table()
 %%%%%%%%
 
 
-% End of class db_null.
+% End of class phpweather.
 %%%%%%%%%%%%%%%%
 

Index: installation.tex
===================================================================
RCS file: /cvsroot/phpweather/phpweather/docs/src/latex/installation.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- installation.tex	18 Jul 2001 10:38:22 -0000	1.1
+++ installation.tex	11 Mar 2002 16:50:08 -0000	1.2
@@ -1,22 +1,21 @@
 
 \chapter{Installation}
 
-It's quite easy to install \phpw. All you have to do, is to unpack the
-compressed file you've downloaded from
-\url{http://www.sourceforge.net/phpweather/} in a directory on the
-webserver. Once that is done you can load the file \filename{demo.php}
-in your favorite browser.
+It's quite easy to install \phpw. You have to start by going to
+\url{http://www.sourceforge.net/phpweather/} and downloading \phpw.
+Decompress the file in a directory on the webserver then load the file
+\filename{demo.php} in your favorite browser. That's it.
 
 You should see a page that lets you chose a country with an airport
-that makes a METAR. There is about 3,000 airports in 192 countries
-that make a METAR each hour so the chance of finding one near your is
+that makes a \metar. There is about 3,000 airports in 192 countries
+that make a \metar each hour so the chance of finding one near your is
 rather good.
 
 \section{Further Tweaking}
 
 What you've just seen is \phpw in it's default form. You can (and
 should) change a couple of things. You use the Configurator to do the
---- you've guessed it --- configuration. So load the file called
+configuration. So load the file called
 \filename{configurator.php} and see what happens.
 
 You should be presented with a page with a lot of drop-down boxed that

Index: main.tex
===================================================================
RCS file: /cvsroot/phpweather/phpweather/docs/src/latex/main.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -3 -r1.4 -r1.5
--- main.tex	18 Jul 2001 10:34:57 -0000	1.4
+++ main.tex	11 Mar 2002 16:50:08 -0000	1.5
@@ -1,63 +1,72 @@
-% The documentclass is defined in phpweather-x.php, where x is either a4 or letter.
+% -*- mode: latex; tex-main-file: "phpweather-a4" -*-
+% The documentclass is defined in phpweather-x.php, where x is either
+% a4 or letter.
+
+% This sets the font to Palatino.
+%\renewcommand{\rmdefault}{ppl}
 %\usepackage{palatcm}
-%\usepackage{palatino}
-\usepackage{xspace}
-\usepackage{graphicx}
+
+\usepackage{xspace,graphicx}
 \usepackage[bf]{caption2}
-\renewcommand{\rmdefault}{ppl}
 
 \usepackage{makeidx}
 \makeindex
 
-
 \usepackage{url}
 \newcommand{\Email}{\begingroup \urlstyle{rm}\Url}
 \newcommand{\email}[1]{\Email{<#1>}}
 
 \newcommand{\function}[1]{\textsf{#1(~)}%
-                          \index{#1@\textsf{#1()}}%
-                          \index{Functions!#1@\textsf{#1()}}
-}
-
-\newcommand{\functiondef}[1]{\textsf{#1}}
-\newcommand{\funcdesclabel}[1]{\emph{#1:}}
-\newenvironment{funcdesc}%
-  {\begin{list}{}{%
-                  \renewcommand{\makelabel}{\funcdesclabel}%
-                  \setlength{\itemsep}{0.25\baselineskip}%
+                          \index{#1@\textsf{#1(~)}}%
+                          \index{Functions!#1@\textsf{#1(~)}} }
+
+%\newcommand{\functiondef}[1]{\textsf{#1}}
+%\newcommand{\funcdesclabel}[1]{\emph{#1:}}
+%\newenvironment{funcdesc}%
+%  {\begin{list}{}{%
+%                  \renewcommand{\makelabel}{\funcdesclabel}%
+%                  \setlength{\itemsep}{0.25\baselineskip}%
 %                  \setlength{\topsep}{0pt}%
-                  \setlength{\partopsep}{0pt}%
-                  \setlength{\parsep}{0pt}%
-                 }%
-  }%
-  {\end{list}%
-}
+%                  \setlength{\partopsep}{0pt}%
+%                  \setlength{\parsep}{0pt}%
+%                 }%
+%  }%
+%  {\end{list}%
+%}
 
-\newcommand{\classdef}[1]{\textsf{#1}}
-\newcommand{\class}[1]{Class \textsf{#1}%
+%\newcommand{\classdef}[1]{\textsf{#1}}
+\newcommand{\class}[1]{\textsf{#1}%
             \index{#1@\textsf{#1}}%
             \index{Classes!#1@\textsf{#1}}}
 
+
 \newcommand{\variable}[2]{\textsf{\textbf{#1#2}}%
                           \index{#2@\textsf{\textbf{\protect\makebox[0cm][r]{#1}#2}}}%
                           \index{Variables!#2@\textsf{\textbf{\protect\makebox[0cm][r]{#1}#2}}}}
 
-\newcommand{\icao}[1]{\textsf{#1}}
-
+%\newcommand{\icao}[1]{\textsf{#1}}
 \newcommand{\code}[1]{\texttt{#1}}
-
 \newcommand{\filename}{\begingroup \urlstyle{tt}\Url}
-\urldef{\AUTHORS}\filename{AUTHORS}
 
-\newcommand{\phpw}{\emph{PHP Weather}\xspace}
-\usepackage[colorlinks,
-  linkcolor=blue,
-  pdftitle={PHP Weather Usage Guide},
-  pdfauthor={Martin Geisler, et al},
-  pdfsubject={Documentation for PHP Weather}
-]{hyperref}
+\newcommand{\phpw}{PHP Weather\xspace}
+\newcommand{\metar}{\textsc{metar}\xspace}
+\newcommand{\icao}{\textsc{icao}\xspace}
+
+%\usepackage[colorlinks,
+%  linkcolor=blue,
+%  pdftitle={PHP Weather Usage Guide},
+%  pdfauthor={Martin Geisler, et al},
+%  pdfsubject={Documentation for PHP Weather}
+%]{hyperref}
+
+\hyphenation{mail-ling-list pre-ci-pi-ta-ti-on sto-red}
+
 \title{\phpw Usage Guide}
-\author{Martin Geisler \email{gim...@gi...}\thanks{I would like to thank all the people who have helped me make \phpw. See the file \AUTHORS{} for a list.}}
+
+\author{Martin Geisler \email{gim...@gi...}\thanks{I would
+like to thank all the people who have helped me make \phpw. See the
+file \texttt{AUTHORS} for a list.}}
+
 \begin{document}
 
 \pagenumbering{roman}
@@ -78,7 +87,6 @@
 
 \end{quote}
 
-
 \tableofcontents
 
 \include{intro}
@@ -88,15 +96,13 @@
 
 \include{installation}
 
+\include{databases}
+
 \include{translation}
 
-%%%%%%%%%%
-%
-% API doc.
-%
-%%%%%%%%%%
+%\include{apidoc}
 
-\include{apidoc}
+\include{history}
 
 \include{fdl}
 

Index: phpweather-a4.tex
===================================================================
RCS file: /cvsroot/phpweather/phpweather/docs/src/latex/phpweather-a4.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- phpweather-a4.tex	12 Jul 2001 19:56:30 -0000	1.1
+++ phpweather-a4.tex	11 Mar 2002 16:50:08 -0000	1.2
@@ -1,2 +1,2 @@
-\documentclass[a4paper]{report}
+\documentclass[a4paper,draft]{report}
 \input{main}

Index: translation.tex
===================================================================
RCS file: /cvsroot/phpweather/phpweather/docs/src/latex/translation.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- translation.tex	18 Jul 2001 10:38:22 -0000	1.1
+++ translation.tex	11 Mar 2002 16:50:08 -0000	1.2
@@ -1,3 +1,4 @@
+% -*- mode: latex; tex-main-file: "phpweather-a4" -*-
 \chapter{Translation}
 
 It is quite easy to translate \phpw into another language. This chaper
@@ -7,9 +8,9 @@
 
 All the words and sentences used by \phpw is stored in special files
 called \emph{locales}. You'll find these files in the directory
-\filename{PHPWEATHER_BASE_DIR/locales}. Each file has a name like this
-\filename{locale_xx.php} where \filename{xx} corrosponds to a
-language-code found in
+\filename{PHPWEATHER_BASE_DIR/locales}. Each file is named after a
+scheme like this \filename{locale_xx.php} where \filename{xx}
+corresponds to a language-code found from
 \filename{PHPWEATHER_BASE_DIR/db/files/countries.php}. So the Danish
 translation is called \filename{locale_db.php}, the Hungarian is
 called \filename{locale_hu.php}, etc.
@@ -29,31 +30,10 @@
 \item Copy your chosen locale, and rename it according to your
 country-code.
 
-\item Change the top of the locale so that it looks like this:
-\begin{verbatim}
-<?php
-/* This code makes sure that the file is only included once. */
-if (defined('LOCALE_XX')) {
-  return;
-} else {
-  define('LOCALE_XX', true);
-}
-
-require(PHPWEATHER_BASE_DIR . '/locales/locale_common.php');
-
-/**
- * Provides all the strings needed by locale_common to
- * produce xx-ish output.
- *
- * @author   Foo Bar <fo...@ba...z>
- * @link     http://www.some.place.com  A description of
- *           the page you've chosen to link to.
- * @version  $Id$
- */
-class locale_xx extends locale_common {
-\end{verbatim}
+\item Change the top of the locale so that all occurences of \code{en}
+and \code{English} is substituted with \code{xx} and \code{xx-ish}.
 
-This involves
+This involves the following steps:
 \begin{enumerate}
 \item Changing the lines that defines the constant \code{LOCALE\_EN} so
 that it defines \code{LOCALE\_XX} instead.
@@ -67,8 +47,8 @@
 \item If you want, you can make a link to a page of your choice ---
 perhaps your homepage?
 
-\item Although not stricly necessary, you might change the line with
-\code{\$Id$Id$}.
+\item You can leave the line with \code{@version} intact. It will be
+updated automatically when the file is put under version control.
 
 \item Changing the line with \code{class locale\_en} into \code{class
 locale\_xx} instead.
@@ -86,7 +66,10 @@
 inches) of precipitation''. I hope you get the idea.
 
 \item Remember to translate all special charecters (things like \ae,
-\'e, \aa, etc) to their HTML-entities.
+\'e, \aa, \"o, etc) to their HTML-entities. Use my list of
+HTML-entities at \url{http://www.gimpster.com/linux/entities.php} as a
+help if you don't know the correct code for one of the special
+characters.
 
 \item When you're done, and have tested your translation, send it to
 the maillinglist at \email{php...@li...}.
@@ -107,7 +90,7 @@
 The good news is: ``You can!'' Now that \phpw uses objects it's
 possible for the translator to change almost every aspect of the
 translation. This can be done, because the translation you've made is
-the definition of a class called \class{locale\_xx} where \code{xx} is
-the country-code.
+the definition of a class called \class{locale\_xx}
+where \code{xx} is the country-code.
 
 To be continued\ldots