User’s guide (README)

Ignore-this: a5805685e72d851270c6553d587cc605

Gitit User’s Guide.page

@@ -0,0 +1,946 @@
+---
+format: DocBook
+...
+
+<sect1 id="gitit">
+  <title>Gitit</title>
+  <para>
+    Gitit is a wiki program written in Haskell. It uses
+    <ulink url="http://happstack.com">Happstack</ulink> for the web
+    server and
+    <ulink url="http://johnmacfarlane.net/pandoc">pandoc</ulink> for
+    markup processing. Pages and uploaded files are stored in a
+    <ulink url="http://git.or.cz">git</ulink>,
+    <ulink url="http://darcs.net">darcs</ulink>, or
+    <ulink url="http://mercurial.selenic.com/">mercurial</ulink>
+    repository and may be modified either by using the VCS’s
+    command-line tools or through the wiki’s web interface. By default,
+    pandoc’s extended version of markdown is used as a markup language,
+    but reStructuredText, LaTeX, HTML, DocBook, or Emacs Org-mode markup
+    can also be used. Pages can be exported in a number of different
+    formats, including LaTeX, RTF, OpenOffice ODT, and MediaWiki markup.
+    Gitit can be configured to display TeX math (using
+    <ulink url="http://github.com/jgm/texmath/tree/master">texmath</ulink>)
+    and highlighted source code (using
+    <ulink url="http://johnmacfarlane.net/highlighting-kate/">highlighting-kate</ulink>).
+  </para>
+  <para>
+    Other features include
+  </para>
+  <itemizedlist>
+    <listitem>
+      <para>
+        plugins: dynamically loaded page transformations written in
+        Haskell (see <quote>Network.Gitit.Interface</quote>)
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        categories
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        TeX math
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        syntax highlighting of source code files and code snippets
+        (using highlighting-kate)
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        caching
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Atom feeds (site-wide and per-page)
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        a library, <quote>Network.Gitit</quote>, that makes it simple to
+        include a gitit wiki in any happstack application
+      </para>
+    </listitem>
+  </itemizedlist>
+  <para>
+    You can see a running demo at
+    <ulink url="http://gitit.johnmacfarlane.net">http://gitit.johnmacfarlane.net</ulink>.
+  </para>
+</sect1>
+<sect1 id="getting-started">
+  <title>Getting started</title>
+  <sect2 id="compiling-and-installing-gitit">
+    <title>Compiling and installing gitit</title>
+    <para>
+      You’ll need the
+      <ulink url="http://www.haskell.org/ghc/">GHC</ulink> compiler and
+      the
+      <ulink url="http://hackage.haskell.org/trac/hackage/wiki/CabalInstall">cabal-install</ulink>
+      tool. GHC can be downloaded
+      <ulink url="http://www.haskell.org/ghc/">here</ulink>. Note that,
+      starting with release 0.5, GHC 6.10 or higher is required. For
+      <ulink url="http://hackage.haskell.org/trac/hackage/wiki/CabalInstall">cabal-install</ulink>
+      on *nix, follow the
+      <ulink url="http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#Quick+Installation+on+Unix">quick
+      install</ulink> instructions.
+    </para>
+    <para>
+      Once you’ve got cabal-install, installing gitit is trivial:
+    </para>
+    <programlisting>
+cabal update
+cabal install gitit
+</programlisting>
+    <para>
+      These commands will install the latest released version of gitit.
+      To install a version of gitit checked out from the repository,
+      change to the gitit directory and type:
+    </para>
+    <programlisting>
+cabal install
+</programlisting>
+    <para>
+      The <literal>cabal</literal> tool will automatically install all
+      of the required haskell libraries. If all goes well, by the end of
+      this process, the latest release of gitit will be installed in
+      your local <literal>.cabal</literal> directory. You can check this
+      by trying:
+    </para>
+    <programlisting>
+gitit --version
+</programlisting>
+    <para>
+      If that doesn’t work, check to see that <literal>gitit</literal>
+      is in your local cabal-install executable directory (usually
+      <literal>~/.cabal/bin</literal>). And make sure
+      <literal>~/.cabal/bin</literal> is in your system path.
+    </para>
+  </sect2>
+  <sect2 id="optional-syntax-highlighting-support">
+    <title>Optional syntax highlighting support</title>
+    <para>
+      If pandoc was compiled with optional syntax highlighting support,
+      this will be available in gitit too. This feature is recommended
+      if you plan to display source code on your wiki.
+    </para>
+    <para>
+      Highlighting support requires the
+      <ulink url="http://www.pcre.org/">pcre</ulink> library, so make
+      sure that is installed before continuing.
+    </para>
+    <para>
+      To install gitit with highlighting support, first ensure that
+      pandoc is compiled with highlighting support, then install gitit
+      as above:
+    </para>
+    <programlisting>
+cabal install pandoc -fhighlighting --reinstall
+cabal install gitit
+</programlisting>
+  </sect2>
+  <sect2 id="running-gitit">
+    <title>Running gitit</title>
+    <para>
+      To run gitit, you’ll need <literal>git</literal> in your system
+      path. (Or <literal>darcs</literal> or <literal>hg</literal>, if
+      you’re using darcs or mercurial to store the wiki data.)
+    </para>
+    <para>
+      Gitit assumes that the page files (stored in the git repository)
+      are encoded as UTF-8. Even page names may be UTF-8 if the file
+      system supports this. So you should make sure that you are using a
+      UTF-8 locale when running gitit. (To check this, type
+      <literal>locale</literal>.)
+    </para>
+    <para>
+      Switch to the directory where you want to run gitit. This should
+      be a directory where you have write access, since three
+      directories, <literal>static</literal>,
+      <literal>templates</literal>, and <literal>wikidata</literal>, and
+      two files, <literal>gitit-users</literal> and
+      <literal>gitit.log</literal>, will be created here. To start
+      gitit, just type:
+    </para>
+    <programlisting>
+gitit
+</programlisting>
+    <para>
+      If all goes well, gitit will do the following:
+    </para>
+    <orderedlist numeration="arabic" spacing="compact">
+      <listitem>
+        <para>
+          Create a git repository, <literal>wikidata</literal>, and add
+          a default front page.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Create a <literal>static</literal> directory containing files
+          to be treated as static files by gitit.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Create a <literal>templates</literal> directory containing
+          HStringTemplate templates for wiki pages.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Start a web server on port 5001.
+        </para>
+      </listitem>
+    </orderedlist>
+    <para>
+      Check that it worked: open a web browser and go to
+      <ulink url="http://localhost:5001">http://localhost:5001</ulink>.
+    </para>
+    <para>
+      You can control the port that gitit runs on using the
+      <literal>-p</literal> option: <literal>gitit -p 4000</literal>
+      will start gitit on port 4000. Additional runtime options are
+      described by <literal>gitit -h</literal>.
+    </para>
+  </sect2>
+</sect1>
+<sect1 id="using-gitit">
+  <title>Using gitit</title>
+  <sect2 id="wiki-links-and-formatting">
+    <title>Wiki links and formatting</title>
+    <para>
+      For instructions on editing pages and creating links, see the
+      <quote>Help</quote> page.
+    </para>
+    <para>
+      Gitit interprets links with empty URLs as wikilinks. Thus, in
+      markdown pages, <literal>[Front Page]()</literal> creates an
+      internal wikilink to the page <literal>Front Page</literal>. In
+      reStructuredText pages, <literal>`Front Page &lt;&gt;`_</literal>
+      has the same effect.
+    </para>
+    <para>
+      If you want to link to a directory listing for a subdirectory, use
+      a trailing slash: <literal>[foo/bar/]()</literal> creates a link
+      to the directory for <literal>foo/bar</literal>.
+    </para>
+  </sect2>
+  <sect2 id="page-metadata">
+    <title>Page metadata</title>
+    <para>
+      Pages may optionally begin with a metadata block. Here is an
+      example:
+    </para>
+    <programlisting>
+---
+format: latex+lhs
+categories: haskell math
+toc: no
+title: Haskell and
+  Category Theory
+...
+
+\section{Why Category Theory?}
+</programlisting>
+    <para>
+      The metadata block consists of a list of key-value pairs, each on
+      a separate line. If needed, the value can be continued on one or
+      more additional line, which must begin with a space. (This is
+      illustrated by the <quote>title</quote> example above.) The
+      metadata block must begin with a line <literal>---</literal> and
+      end with a line <literal>...</literal> optionally followed by one
+      or more blank lines. (The metadata block is a valid YAML document,
+      though not all YAML documents will be valid metadata blocks.)
+    </para>
+    <para>
+      Currently the following keys are supported:
+    </para>
+    <variablelist spacing="compact">
+      <varlistentry>
+        <term>
+          format
+        </term>
+        <listitem>
+          <para>
+            Overrides the default page type as specified in the
+            configuration file. Possible values are
+            <literal>markdown</literal>, <literal>rst</literal>,
+            <literal>latex</literal>, <literal>html</literal>,
+            <literal>markdown+lhs</literal>, <literal>rst+lhs</literal>,
+            <literal>latex+lhs</literal>. (Capitalization is ignored, so
+            you can also use <literal>LaTeX</literal>,
+            <literal>HTML</literal>, etc.) The <literal>+lhs</literal>
+            variants indicate that the page is to be interpreted as
+            literate Haskell. If this field is missing, the default page
+            type will be used.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          categories
+        </term>
+        <listitem>
+          <para>
+            A space or comma separated list of categories to which the
+            page belongs.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          toc
+        </term>
+        <listitem>
+          <para>
+            Overrides default setting for table-of-contents in the
+            configuration file. Values can be <literal>yes</literal>,
+            <literal>no</literal>, <literal>true</literal>, or
+            <literal>false</literal> (capitalization is ignored).
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          title
+        </term>
+        <listitem>
+          <para>
+            By default the displayed page title is the page name. This
+            metadata element overrides that default.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </sect2>
+  <sect2 id="highlighted-source-code">
+    <title>Highlighted source code</title>
+    <para>
+      If gitit was compiled against a version of pandoc that has
+      highlighting support (see above), you can get highlighted source
+      code by using
+      <ulink url="http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks">delimited
+      code blocks</ulink>:
+    </para>
+    <programlisting>
+~~~ {.haskell .numberLines}
+qsort []     = []
+qsort (x:xs) = qsort (filter (&lt; x) xs) ++ [x] ++
+               qsort (filter (&gt;= x) xs) 
+~~~
+</programlisting>
+    <para>
+      To see what languages your pandoc was compiled to highlight:
+    </para>
+    <programlisting>
+pandoc -v
+</programlisting>
+  </sect2>
+</sect1>
+<sect1 id="configuring-and-customizing-gitit">
+  <title>Configuring and customizing gitit</title>
+  <sect2 id="configuration-options">
+    <title>Configuration options</title>
+    <para>
+      Use the option <literal>-f [filename]</literal> to specify a
+      configuration file:
+    </para>
+    <programlisting>
+gitit -f my.conf
+</programlisting>
+    <para>
+      The configuation can be splitted between several files:
+    </para>
+    <programlisting>
+gitit -f my.conf -f additional.conf
+</programlisting>
+    <para>
+      One use case is to keep sensible part of the configuration outside
+      of a SCM (oauth client secret for example).
+    </para>
+    <para>
+      If this option is not used, gitit will use a default
+      configuration. To get a copy of the default configuration file,
+      which you can customize, just type:
+    </para>
+    <programlisting>
+gitit --print-default-config &gt; my.conf
+</programlisting>
+    <para>
+      The default configuration file is documented with comments
+      throughout.
+    </para>
+  </sect2>
+  <sect2 id="the-static-directory">
+    <title>The <literal>static</literal> directory</title>
+    <para>
+      On receiving a request, gitit always looks first in the
+      <literal>static</literal> directory (or in whatever directory is
+      specified for <literal>static-dir</literal> in the configuration
+      file). If a file corresponding to the request is found there, it
+      is served immediately. If the file is not found in
+      <literal>static</literal>, gitit next looks in the
+      <literal>static</literal> subdirectory of gitit’s data file
+      (<literal>$CABALDIR/share/gitit-x.y.z/data</literal>). This is
+      where default css, images, and javascripts are stored. If the file
+      is not found there either, gitit treats the request as a request
+      for a wiki page or wiki command.
+    </para>
+    <para>
+      So, you can throw anything you want to be served statically (for
+      example, a <literal>robots.txt</literal> file or
+      <literal>favicon.ico</literal>) in the <literal>static</literal>
+      directory. You can override any of gitit’s default css,
+      javascript, or image files by putting a file with the same
+      relative path in <literal>static</literal>. Note that gitit has a
+      default <literal>robots.txt</literal> file that excludes all URLs
+      beginning with <literal>/_</literal>.
+    </para>
+    <para>
+      Note: if you set <literal>static-dir</literal> to be a
+      subdirectory of <literal>repository-path</literal>, and then add
+      the files in the static directory to your repository, you can
+      ensure that others who clone your wiki repository get these files
+      as well. It will not be possible to modify these files using the
+      web interface, but they will be modifiable via git.
+    </para>
+  </sect2>
+  <sect2 id="using-a-vcs-other-than-git">
+    <title>Using a VCS other than git</title>
+    <para>
+      By default, gitit will store wiki pages in a git repository in the
+      <literal>wikidata</literal> directory. If you’d prefer to use
+      darcs instead of git, you need to add the following field to the
+      configuration file:
+    </para>
+    <programlisting>
+repository-type: Darcs
+</programlisting>
+    <para>
+      If you’d prefer to use mercurial, add:
+    </para>
+    <programlisting>
+repository-type: Mercurial
+</programlisting>
+    <para>
+      This program may be called <quote>darcsit</quote> instead of
+      <quote>gitit</quote> when a darcs backend is used.
+    </para>
+    <para>
+      Note: we recommend that you use gitit/darcsit with darcs version
+      2.3.0 or greater. If you must use an older version of darcs, then
+      you need to compile the filestore library without the (default)
+      maxcount flag, before (re)installing gitit:
+    </para>
+    <programlisting>
+cabal install --reinstall filestore -f-maxcount
+cabal install --reinstall gitit
+</programlisting>
+    <para>
+      Otherwise you will get an error when you attempt to access your
+      repository.
+    </para>
+  </sect2>
+  <sect2 id="changing-the-theme">
+    <title>Changing the theme</title>
+    <para>
+      To change the look of the wiki, you can modify
+      <literal>custom.css</literal> in <literal>static/css</literal>.
+    </para>
+    <para>
+      To change the look of printed pages, copy gitit’s default
+      <literal>print.css</literal> to <literal>static/css</literal> and
+      modify it.
+    </para>
+    <para>
+      The logo picture can be changed by copying a new PNG file to
+      <literal>static/img/logo.png</literal>. The default logo is
+      138x155 pixels.
+    </para>
+    <para>
+      To change the footer, modify
+      <literal>templates/footer.st</literal>.
+    </para>
+    <para>
+      For more radical changes, you can override any of the default
+      templates in
+      <literal>$CABALDIR/share/gitit-x.y.z/data/templates</literal> by
+      copying the file into <literal>templates</literal>, modifying it,
+      and restarting gitit. The <literal>page.st</literal> template is
+      the master template; it includes the others. Interpolated
+      variables are surrounded by <literal>$</literal>s, so
+      <literal>literal $</literal> must be backslash-escaped.
+    </para>
+  </sect2>
+  <sect2 id="adding-support-for-math">
+    <title>Adding support for math</title>
+    <para>
+      To write math on a markdown-formatted wiki page, just enclose it
+      in dollar signs, as in LaTeX:
+    </para>
+    <programlisting>
+Here is a formula:  $\frac{1}{\sqrt{c^2}}$
+</programlisting>
+    <para>
+      You can write display math by enclosing it in double dollar signs:
+    </para>
+    <programlisting>
+$$\frac{1}{\sqrt{c^2}}$$
+</programlisting>
+    <para>
+      Gitit can display TeX math in three different ways, depending on
+      the setting of <literal>math</literal> in the configuration file:
+    </para>
+    <orderedlist numeration="arabic">
+      <listitem>
+        <para>
+          <literal>mathml</literal> (default): Math will be converted to
+          MathML using
+          <ulink url="http://github.com/jgm/texmath/tree/master">texmath</ulink>.
+          This method works with IE+mathplayer, Firefox, and Opera, but
+          not Safari.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>jsMath</literal>: Math will be rendered using the
+          <ulink url="http://www.math.union.edu/~dpvc/jsmath/">jsMath</ulink>
+          javascript. If you want to use this method, download
+          <literal>jsMath</literal> and
+          <literal>jsMath Image Fonts</literal> from the
+          <ulink url="http://sourceforge.net/project/showfiles.php?group_id=172663">jsMath
+          download page</ulink>. You’ll have two <literal>.zip</literal>
+          archives. Unzip them both in the <literal>static/js</literal>
+          directory (a new subdirectory, <literal>jsMath</literal>, will
+          be created). This works with all browsers, but is slower and
+          not as nice looking as MathML.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>raw</literal>: Math will be rendered as raw LaTeX
+          codes.
+        </para>
+      </listitem>
+    </orderedlist>
+  </sect2>
+  <sect2 id="restricting-access">
+    <title>Restricting access</title>
+    <para>
+      If you want to limit account creation on your wiki, the easiest
+      way to do this is to provide an <literal>access-question</literal>
+      in your configuration file. (See the commented default
+      configuration file.) Nobody will be able to create an account
+      without knowing the answer to the access question.
+    </para>
+    <para>
+      Another approach is to use HTTP authentication. (See the config
+      file comments on <literal>authentication-method</literal>.)
+    </para>
+  </sect2>
+  <sect2 id="authentication-through-github">
+    <title>Authentication through github</title>
+    <para>
+      If you want to authenticate the user from github through oauth2,
+      you need to register your app with github to obtain a OAuth client
+      secret and add the following section to your configuration file:
+    </para>
+    <programlisting>
+[Github]
+oauthclientid: 01239456789abcdef012
+oauthclientsecret: 01239456789abcdef01239456789abcdef012394
+oauthcallback: http://mysite/_githubCallback
+oauthoauthorizeendpoint: https://github.com/login/oauth/authorize
+oauthaccesstokenendpoint: https://github.com/login/oauth/access_token
+## Uncomment if you are checking membership against an organization and change
+## gitit-testorg to this organization:
+# github-org: gitit-testorg
+</programlisting>
+    <para>
+      The github authentication uses the scope
+      <literal>user:email</literal>. This way, gitit gets the email of
+      the user, and the commit can be assigned to the right author if
+      the wikidata repository is pushed to github. Additionally, it uses
+      <literal>read:org</literal> if you uses the option
+      <literal>github-org</literal> to check membership against an
+      organization.
+    </para>
+    <para>
+      To push your repository to gitub after each commit, you can add
+      the file <literal>post-commit</literal> with the content below in
+      the .git/hooks directory of your wikidata repository.
+    </para>
+    <programlisting>
+#!/bin/sh
+git push origin master 2&gt;&gt; logit
+</programlisting>
+  </sect2>
+</sect1>
+<sect1 id="plugins">
+  <title>Plugins</title>
+  <para>
+    Plugins are small Haskell programs that transform a wiki page after
+    it has been converted from Markdown or another source format. See
+    the example plugins in the <literal>plugins</literal> directory. To
+    enable a plugin, include the path to the plugin (or its module name)
+    in the <literal>plugins</literal> field of the configuration file.
+    (If the plugin name starts with
+    <literal>Network.Gitit.Plugin.</literal>, gitit will assume that the
+    plugin is an installed module and will not look for a source file.)
+  </para>
+  <para>
+    Plugin support is enabled by default. However, plugin support makes
+    the gitit executable considerably larger and more memory-hungry. If
+    you don’t need plugins, you may want to compile gitit without plugin
+    support. To do this, unset the <literal>plugins</literal> Cabal
+    flag:
+  </para>
+  <programlisting>
+cabal install --reinstall gitit -f-plugins
+</programlisting>
+  <para>
+    Note also that if you compile gitit for executable profiling,
+    attempts to load plugins will result in <quote>internal error: PAP
+    object entered!</quote>
+  </para>
+</sect1>
+<sect1 id="accessing-the-wiki-through-git">
+  <title>Accessing the wiki through git</title>
+  <para>
+    All the pages and uploaded files are stored in a git repository. By
+    default, this lives in the <literal>wikidata</literal> directory
+    (though this can be changed through configuration options). So you
+    can interact with the wiki using git command line tools:
+  </para>
+  <programlisting>
+git clone ssh://my.server.edu/path/of/wiki/wikidata
+cd wikidata
+vim Front\ Page.page  # edit the page
+git commit -m &quot;Added message about wiki etiquette&quot; Front\ Page.page
+git push
+</programlisting>
+  <para>
+    If you now look at the Front Page on the wiki, you should see your
+    changes reflected there. Note that the pages all have the extension
+    <literal>.page</literal>.
+  </para>
+  <para>
+    If you are using the darcs or mercurial backend, the commands will
+    be slightly different. See the documentation for your VCS for
+    details.
+  </para>
+</sect1>
+<sect1 id="performance">
+  <title>Performance</title>
+  <sect2 id="caching">
+    <title>Caching</title>
+    <para>
+      By default, gitit does not cache content. If your wiki receives a
+      lot of traffic or contains pages that are slow to render, you may
+      want to activate caching. To do this, set the configuration option
+      <literal>use-cache</literal> to <literal>yes</literal>. By
+      default, rendered pages, highlighted source files, and exported
+      PDFs will be cached in the <literal>cache</literal> directory.
+      (Another directory can be specified by setting the
+      <literal>cache-dir</literal> configuration option.)
+    </para>
+    <para>
+      Cached pages are updated when pages are modified using the web
+      interface. They are not updated when pages are modified directly
+      through git or darcs. However, the cache can be refreshed manually
+      by pressing Ctrl-R when viewing a page, or by sending an HTTP GET
+      or POST request to <literal>/_expire/path/to/page</literal>, where
+      <literal>path/to/page</literal> is the name of the page to be
+      expired.
+    </para>
+    <para>
+      Users who frequently update pages using git or darcs may wish to
+      add a hook to the repository that makes the appropriate HTTP
+      request to expire pages when they are updated. To facilitate such
+      hooks, the gitit cabal package includes an executable
+      <literal>expireGititCache</literal>. Assuming you are running
+      gitit at port 5001 on localhost, and the environment variable
+      <literal>CHANGED_FILES</literal> contains a list of the files that
+      have changed, you can expire their cached versions using
+    </para>
+    <programlisting>
+expireGititCache http://localhost:5001 $CHANGED_FILES
+</programlisting>
+    <para>
+      Or you can specify the files directly:
+    </para>
+    <programlisting>
+expireGititCache http://localhost:5001 &quot;Front Page.page&quot; foo/bar/baz.c
+</programlisting>
+    <para>
+      This program will return a success status (0) if the page has been
+      successfully expired (or if it was never cached in the first
+      place), and a failure status (&gt; 0) otherwise.
+    </para>
+    <para>
+      The cache is persistent through restarts of gitit. To expire all
+      cached pages, simply remove the <literal>cache</literal>
+      directory.
+    </para>
+  </sect2>
+  <sect2 id="idle">
+    <title>Idle</title>
+    <para>
+      By default, GHC’s runtime will repeatedly attempt to collect
+      garbage when an executable like Gitit is idle. This means that
+      gitit will, after the first page request, never use 0% CPU time
+      and sleep, but will use ~1%. This can be bad for battery life,
+      among other things.
+    </para>
+    <para>
+      To fix this, one can disable the idle-time GC with the runtime
+      flag <literal>-I0</literal>:
+    </para>
+    <programlisting>
+gitit -f my.conf +RTS -I0 -RTS
+</programlisting>
+  </sect2>
+</sect1>
+<sect1 id="using-gitit-with-apache">
+  <title>Using gitit with apache</title>
+  <para>
+    Most users who run a public-facing gitit will want gitit to appear
+    at a nice URL like <literal>http://wiki.mysite.com</literal> or
+    <literal>http://mysite.com/wiki</literal> rather than
+    <literal>http://mysite.com:5001</literal>. This can be achieved
+    using apache’s <literal>mod_proxy</literal>.
+  </para>
+  <sect2 id="proxying-to-httpwiki.mysite.com">
+    <title>Proxying to <literal>http://wiki.mysite.com</literal></title>
+    <para>
+      Set up your DNS so that <literal>http://wiki.mysite.com</literal>
+      maps to your server’s IP address. Make sure that the
+      <literal>mod_proxy</literal>, <literal>mod_proxy_http</literal>
+      and <literal>mod_rewrite</literal> modules are loaded, and set up
+      a virtual host with the following configuration:
+    </para>
+    <programlisting>
+&lt;VirtualHost *&gt;
+    ServerName wiki.mysite.com
+    DocumentRoot /var/www/
+    RewriteEngine On
+    ProxyPreserveHost On
+    ProxyRequests Off
+
+    &lt;Proxy *&gt;
+       Order deny,allow
+       Allow from all
+    &lt;/Proxy&gt;
+
+    ProxyPassReverse /    http://127.0.0.1:5001
+    RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
+
+    ErrorLog /var/log/apache2/error.log
+    LogLevel warn
+
+    CustomLog /var/log/apache2/access.log combined
+    ServerSignature On
+
+&lt;/VirtualHost&gt;
+</programlisting>
+    <para>
+      Reload your apache configuration and you should be all set.
+    </para>
+  </sect2>
+  <sect2 id="using-nginx-to-achieve-the-same">
+    <title>Using nginx to achieve the same</title>
+    <para>
+      Drop a file called <literal>wiki.example.com.conf</literal> into
+      <literal>/etc/nginx/conf.d</literal> (or where ever your
+      distribution puts it).
+    </para>
+    <programlisting>
+server {
+    listen 80;
+    server_name wiki.example.com
+    location / {
+        proxy_pass        http://127.0.0.1:5001/;
+        proxy_set_header  X-Real-IP  $remote_addr;
+        proxy_redirect off;
+    }
+    access_log /var/log/nginx/wiki.example.com.log main;
+}
+</programlisting>
+    <para>
+      Reload your nginx config and you should be all set.
+    </para>
+  </sect2>
+  <sect2 id="proxying-to-httpmysite.comwiki">
+    <title>Proxying to <literal>http://mysite.com/wiki</literal></title>
+    <para>
+      Make sure the <literal>mod_proxy</literal>,
+      <literal>mod_headers</literal>, <literal>mod_proxy_http</literal>,
+      and <literal>mod_proxy_html</literal> modules are loaded.
+      <literal>mod_proxy_html</literal> is an external module, which can
+      be obtained <ulink url="http://www.haskell.org/ghc/">here</ulink>
+      (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs
+      that occur in web pages. Here we will use it to rewrite gitit’s
+      links so that they all begin with <literal>/wiki/</literal>.
+    </para>
+    <para>
+      First, tell gitit not to compress pages, since
+      <literal>mod_proxy_html</literal> needs uncompressed pages to
+      parse. You can do this by setting the gitit configuration option
+    </para>
+    <programlisting>
+compress-responses: no
+</programlisting>
+    <para>
+      Second, modify the link in the
+      <literal>reset-password-message</literal> in the configuration
+      file: instead of
+    </para>
+    <programlisting>
+http://$hostname$:$port$$resetlink$
+</programlisting>
+    <para>
+      set it to
+    </para>
+    <programlisting>
+http://$hostname$/wiki$resetlink$
+</programlisting>
+    <para>
+      Restart gitit.
+    </para>
+    <para>
+      Now add the following lines to the apache configuration file for
+      the <literal>mysite.com</literal> server:
+    </para>
+    <programlisting>
+# These commands will proxy /wiki/ to port 5001
+
+ProxyRequests Off
+
+&lt;Proxy *&gt;
+  Order deny,allow
+  Allow from all
+&lt;/Proxy&gt;
+
+ProxyPass /wiki/ http://127.0.0.1:5001/
+
+&lt;Location /wiki/&gt;
+  SetOutputFilter  proxy-html
+  ProxyPassReverse /
+  ProxyHTMLURLMap  /   /wiki/
+  ProxyHTMLDocType &quot;&lt;!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'&gt;&quot; XHTML
+  RequestHeader unset Accept-Encoding
+&lt;/Location&gt;
+</programlisting>
+    <para>
+      Reload your apache configuration and you should be set.
+    </para>
+    <para>
+      For further information on the use of
+      <literal>mod_proxy_http</literal> to rewrite URLs, see the
+      <ulink url="http://apache.webthing.com/mod_proxy_html/guide.html"><literal>mod_proxy_html</literal>
+      guide</ulink>.
+    </para>
+  </sect2>
+</sect1>
+<sect1 id="using-gitit-as-a-library">
+  <title>Using gitit as a library</title>
+  <para>
+    By importing the module <literal>Network.Gitit</literal>, you can
+    include a gitit wiki (or several of them) in another happstack
+    application. There are some simple examples in the haddock
+    documentation for <literal>Network.Gitit</literal>.
+  </para>
+</sect1>
+<sect1 id="reporting-bugs">
+  <title>Reporting bugs</title>
+  <para>
+    Bugs may be reported (and feature requests filed) at
+    <ulink url="http://code.google.com/p/gitit/issues/list">http://code.google.com/p/gitit/issues/list</ulink>.
+  </para>
+  <para>
+    There is a mailing list for users and developers at
+    <ulink url="http://groups.google.com/group/gitit-discuss">http://groups.google.com/group/gitit-discuss</ulink>.
+  </para>
+</sect1>
+<sect1 id="acknowledgements">
+  <title>Acknowledgements</title>
+  <para>
+    A number of people have contributed patches:
+  </para>
+  <itemizedlist spacing="compact">
+    <listitem>
+      <para>
+        Gwern Branwen helped to optimize gitit and wrote the
+        InterwikiPlugin. He also helped with the Feed module.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Simon Michael contributed the patch adding RST support.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Henry Laxen added support for password resets and helped with
+        the apache proxy instructions.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Anton van Straaten made the process of page generation more
+        modular by adding Gitit.ContentTransformer.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Robin Green helped improve the plugin API and interface, and
+        fixed a security problem with the reset password code.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Thomas Hartman helped improve the index page, making directory
+        browsing persistent, and fixed a bug in template recompilation.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Justin Bogner improved the appearance of the preview button.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Kohei Ozaki contributed the ImgTexPlugin.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Michael Terepeta improved validation of change descriptions.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        mightybyte suggested making gitit available as a library, and
+        contributed a patch to ifLoggedIn that was needed to make gitit
+        usable with a custom authentication scheme.
+      </para>
+    </listitem>
+  </itemizedlist>
+  <para>
+    I am especially grateful to the darcs team for using darcsit for
+    their public-facing wiki. This has helped immensely in identifying
+    issues and improving performance.
+  </para>
+  <para>
+    Gitit’s default visual layout is shamelessly borrowed from
+    Wikipedia. The stylesheets are influenced by Wikipedia’s stylesheets
+    and by the bluetrip CSS framework (see BLUETRIP-LICENSE). Some of
+    the icons in <literal>img/icons</literal> come from bluetrip as
+    well.
+  </para>
+</sect1>