1.1 --- a/en/99book.bib	Wed Apr 25 15:23:44 2007 -0700
     1.2 +++ b/en/99book.bib	Tue May 08 17:00:44 2007 -0700
     1.3 @@ -68,3 +68,8 @@
     1.4    title =	 {PuTTY---open source ssh client for Windows},
     1.5    note =	 {\url{http://www.chiark.greenend.org.uk/~sgtatham/putty/}},
     1.6  }
     1.7 +
     1.8 +@Misc{web:configparser,
     1.9 +  title =	 {\texttt{ConfigParser}---Configuration file parser},
    1.10 +  note =	 {\url{http://docs.python.org/lib/module-ConfigParser.html}},
    1.11 +}

     2.1 --- a/en/collab.tex	Wed Apr 25 15:23:44 2007 -0700
     2.2 +++ b/en/collab.tex	Tue May 08 17:00:44 2007 -0700
     2.3 @@ -749,10 +749,22 @@
     2.4  directory, and ensure that it's executable.
     2.5  \begin{codesample2}
     2.6    cp .../hgweb.cgi ~/public_html
     2.7 -  chmod +x ~/public_html/hgweb.cgi
     2.8 +  chmod 755 ~/public_html/hgweb.cgi
     2.9 +\end{codesample2}
    2.10 +The \texttt{755} argument to \command{chmod} is a little more general
    2.11 +than just making the script executable: it ensures that the script is
    2.12 +executable by anyone, and that ``group'' and ``other'' write
    2.13 +permissions are \emph{not} set.  If you were to leave those write
    2.14 +permissions enabled, Apache's \texttt{suexec} subsystem would likely
    2.15 +refuse to execute the script.  In fact, \texttt{suexec} also insists
    2.16 +that the \emph{directory} in which the script resides must not be
    2.17 +writable by others.
    2.18 +\begin{codesample2}
    2.19 +  chmod 755 ~/public_html
    2.20  \end{codesample2}
    2.21  
    2.22  \subsubsection{What could \emph{possibly} go wrong?}
    2.23 +\label{sec:collab:wtf}
    2.24  
    2.25  Once you've copied the CGI script into place, go into a web browser,
    2.26  and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
    2.27 @@ -762,7 +774,7 @@
    2.28  over almost every one of the possible errors below, so please read
    2.29  carefully.  The following are all of the problems I ran into on a
    2.30  system running Fedora~7, with a fresh installation of Apache, and a
    2.31 -user account that I created specially.
    2.32 +user account that I created specially to perform this exercise.
    2.33  
    2.34  Your web server may have per-user directories disabled.  If you're
    2.35  using Apache, search your config file for a \texttt{UserDir}
    2.36 @@ -850,11 +862,12 @@
    2.37  script was properly edited.
    2.38  
    2.39  Once I had Apache running, getting \texttt{lighttpd} to serve the
    2.40 -repository was a snap.  I first had to edit the \texttt{mod\_access}
    2.41 -section of the config file to enable \texttt{mod\_cgi} and
    2.42 -\texttt{mod\_userdir}, both of which were disabled by default on my
    2.43 -system.  I then added a few lines to the end of the config file, to
    2.44 -configure these modules.
    2.45 +repository was a snap (in other words, even if you're trying to use
    2.46 +\texttt{lighttpd}, you should read the Apache section).  I first had
    2.47 +to edit the \texttt{mod\_access} section of its config file to enable
    2.48 +\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
    2.49 +disabled by default on my system.  I then added a few lines to the end
    2.50 +of the config file, to configure these modules.
    2.51  \begin{codesample2}
    2.52    userdir.path = "public_html"
    2.53    cgi.assign = ( ".cgi" => "" )
    2.54 @@ -866,6 +879,77 @@
    2.55  easier to configure than Apache, even though I've used Apache for over
    2.56  a decade, and this was my first exposure to \texttt{lighttpd}.
    2.57  
    2.58 +\subsection{Sharing multiple repositories with one CGI script}
    2.59 +
    2.60 +The \sfilename{hgweb.cgi} script only lets you publish a single
    2.61 +repository, which is an annoying restriction.  If you want to publish
    2.62 +more than one without wracking yourself with multiple copies of the
    2.63 +same script, each with different names, a better choice is to use the
    2.64 +\sfilename{hgwebdir.cgi} script.
    2.65 +
    2.66 +The procedure to configure \sfilename{hgwebdir.cgi} is only a little
    2.67 +more involved than for \sfilename{hgweb.cgi}.  First, you must obtain
    2.68 +a copy of the script.  If you don't have one handy, you can download a
    2.69 +copy from the master Mercurial repository at
    2.70 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
    2.71 +
    2.72 +You'll need to copy this script into your \dirname{public\_html}
    2.73 +directory, and ensure that it's executable.
    2.74 +\begin{codesample2}
    2.75 +  cp .../hgwebdir.cgi ~/public_html
    2.76 +  chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
    2.77 +\end{codesample2}
    2.78 +With basic configuration out of the way, try to visit
    2.79 +\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser.  It
    2.80 +should display an empty list of repositories.  If you get a blank
    2.81 +window or error message, try walking through the list of potential
    2.82 +problems in section~\ref{sec:collab:wtf}.
    2.83 +
    2.84 +The \sfilename{hgwebdir.cgi} script relies on an external
    2.85 +configuration file.  By default, it searches for a file named
    2.86 +\sfilename{hgweb.config} in the same directory as itself.  You'll need
    2.87 +to create this file, and make it world-readable.  The format of the
    2.88 +file is similar to a Windows ``ini'' file, as understood by Python's
    2.89 +\texttt{ConfigParser}~\cite{web:configparser} module.
    2.90 +
    2.91 +The easiest way to configure \sfilename{hgwebdir.cgi} is with a
    2.92 +section named \texttt{collections}.  This will automatically publish
    2.93 +\emph{every} repository under the directories you name.  The section
    2.94 +should look like this:
    2.95 +\begin{codesample2}
    2.96 +  [collections]
    2.97 +  /my/root = /my/root
    2.98 +\end{codesample2}
    2.99 +Mercurial interprets this by looking at the directory name on the
   2.100 +\emph{right} hand side of the ``\texttt{=}'' sign; finding
   2.101 +repositories in that directory hierarchy; and using the text on the
   2.102 +\emph{left} to strip off matching text from the names it will actually
   2.103 +list in the web interface.
   2.104 +
   2.105 +Given the example above, if we have a repository whose local path is
   2.106 +\dirname{/my/root/this/repo}, the CGI script will strip the leading
   2.107 +\dirname{/my/root} from the name, and publish the repository as
   2.108 +\dirname{this/repo}.  If the base URL for our CGI script is
   2.109 +\url{http://myhostname/~myuser/hgwebdir.cgi}, the URL for the
   2.110 +repository will be
   2.111 +\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
   2.112 +
   2.113 +If we replace \dirname{/my/root} on the left hand side of this example
   2.114 +with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
   2.115 +\dirname{/my} from the repository name, and will publish it as
   2.116 +\dirname{root/this/repo} instead of \dirname{this/repo}.
   2.117 +
   2.118 +The \sfilename{hgwebdir.cgi} script will recursively search each
   2.119 +directory listed in the \texttt{collections} section of its
   2.120 +configuration file, but it will \texttt{not} recurse into the
   2.121 +repositories it finds.
   2.122 +
   2.123 +The \texttt{collections} mechanism makes it easy to publish many
   2.124 +repositories in a ``fire and forget'' manner.  You only need to set up
   2.125 +the CGI script and configuration file one time.  Afterwards, you can
   2.126 +publish or unpublish a repository at any time by simply moving it
   2.127 +into, or out of, the directory hierarchy in which you've configured
   2.128 +\sfilename{hgwebdir.cgi} to look.
   2.129  
   2.130  %%% Local Variables: 
   2.131  %%% mode: latex