Deleted using web interface.

Ignore-this: 50d460f2b9d0605753baeb92327d5a33

Gitit User’s Guide.page

@@ -1,946 +0,0 @@
----
-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>