changeset 215:70e1f8448699

Document some hgweb config options.

--- a/en/collab.tex	Wed May 09 17:03:56 2007 -0700
+++ b/en/collab.tex	Wed May 09 17:04:06 2007 -0700
@@ -952,7 +952,7 @@
 into, or out of, the directory hierarchy in which you've configured
 \sfilename{hgwebdir.cgi} to look.
 
-\subsubsection{Explicitly specifying the repositories to publish}
+\subsubsection{Explicitly specifying which repositories to publish}
 
 In addition to the \texttt{collections} mechanism, the
 \sfilename{hgwebdir.cgi} script allows you to publish a specific list
@@ -979,6 +979,109 @@
   behave unpredictably.
 \end{note}
 
+\subsection{Downloading source archives}
+
+Mercurial's web interface lets users download an archive of any
+revision.  This archive will contain a snapshot of the working
+directory as of that revision, but it will not contain a copy of the
+repository data.
+
+By default, this feature is not enabled.  To enable it, you'll need to
+add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
+section of your \hgrc.
+
+\subsection{Web configuration options}
+
+Mercurial's web interfaces (the \hgcmd{serve} command, and the
+\sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
+number of configuration options that you can set.  These belong in a
+section named \rcsection{web}.
+\begin{itemize}
+\item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
+  download mechanisms Mercurial supports.  If you enable this
+  feature, users of the web interface will be able to download an
+  archive of whatever revision of a repository they are viewing.
+  To enable the archive feature, this item must take the form of a
+  sequence of words drawn from the list below.
+  \begin{itemize}
+  \item[\texttt{bz2}] A \command{tar} archive, compressed using
+    \texttt{bzip2} compression.  This has the best compression ratio,
+    but uses the most CPU time on the server.
+  \item[\texttt{gz}] A \command{tar} archive, compressed using
+    \texttt{gzip} compression.
+  \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
+    compression.  This format has the worst compression ratio, but is
+    widely used in the Windows world.
+  \end{itemize}
+  If you provide an empty list, or don't have an
+  \rcitem{web}{allow\_archive} entry at all, this feature will be
+  disabled.  Here is an example of how to enable all three supported
+  formats.
+  \begin{codesample4}
+    [web]
+    allow_archive = bz2 gz zip
+  \end{codesample4}
+\item[\rcitem{web}{allowpull}] Boolean.  Determines whether the web
+  interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
+  repository over~HTTP.  If set to \texttt{no} or \texttt{false}, only
+  the ``human-oriented'' portion of the web interface is available.
+\item[\rcitem{web}{contact}] String.  A free-form (but preferably
+  brief) string identifying the person or group in charge of the
+  repository.  This often contains the name and email address of a
+  person.
+\item[\rcitem{web}{description}] String.  A free-form (but preferably
+  brief) string that describes the contents or purpose of the
+  repository.
+\item[\rcitem{web}{maxchanges}] Integer.  The default maximum number
+  of changesets to display in a single page of output.
+\item[\rcitem{web}{maxfiles}] Integer.  The default maximum number
+  of modified files to display in a single page of output.
+\item[\rcitem{web}{stripes}] Integer.  If the web interface displays
+  alternating ``stripes'' to make it easier to visually align rows
+  when you are looking at a table, this number controls the number of
+  rows in each stripe.
+\item[\rcitem{web}{style}] Controls the template Mercurial uses to
+  display the web interface.  Mercurial ships with two web templates,
+  named \texttt{default} and \texttt{gitweb} (the latter is much more
+  visually attractive).  You can also specify a custom template of
+  your own; see chapter~\ref{chap:template} for details.  Here, you
+  can see how to enable the \texttt{gitweb} style.
+  \begin{codesample4}
+    [web]
+    style = gitweb
+  \end{codesample4}
+\item[\rcitem{web}{templates}] Path.  The directory in which to search
+  for template files.  By default, Mercurial searches in the directory
+  in which it was installed.
+\end{itemize}
+If you are using \sfilename{hgwebdir.cgi}, you can place a few
+configuration items in a \rcsection{web} section of the
+\sfilename{hgweb.config} file instead of a \hgrc\ file, for
+convenience.  These items are \rcitem{web}{motd} and
+\rcitem{web}{style}.
+
+\subsubsection{Options specific to the \hgcmd{serve} command}
+
+Some of the items in the \rcsection{web} section of a \hgrc\ file are
+only for use with the \hgcmd{serve} command.
+\begin{itemize}
+\item[\rcitem{web}{accesslog}] Path.  The name of a file into which to
+  write an access log.  By default, the \hgcmd{serve} command writes
+  this information to standard output, not to a file.  Log entries are
+  written in the standard ``combined'' file format used by almost all
+  web servers.
+\item[\rcitem{web}{address}] String.  The local address on which the
+  server should listen for incoming connections.  By default, the
+  server listens on all addresses.
+\item[\rcitem{web}{errorlog}] Path.  The name of a file into which to
+  write an error log.  By default, the \hgcmd{serve} command writes this
+  information to standard error, not to a file.
+\item[\rcitem{web}{ipv6}] Boolean.  Whether to use the IPv6 protocol.
+  By default, IPv6 is not used. 
+\item[\rcitem{web}{port}] Integer.  The TCP~port number on which the
+  server should listen.  The default port number used is~8000.
+\end{itemize}
+
 %%% Local Variables: 
 %%% mode: latex
 %%% TeX-master: "00book"