User's guide (README)

Gitit User's Guide.page

@@ -0,0 +1,583 @@
+Gitit
+=====
+
+Gitit is a wiki program written in Haskell. It uses [Happstack][] for
+the web server and [pandoc][] for markup processing. Pages and uploaded
+files are stored in a [git][], [darcs][], or [mercurial][] 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,
+or HTML 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 [texmath][]) and
+highlighted source code (using [highlighting-kate][]).
+
+Other features include
+
+* plugins: dynamically loaded page transformations written in Haskell
+  (see "Network.Gitit.Interface")
+
+* categories
+
+* TeX math
+
+* syntax highlighting of source code files and code snippets (using
+  highlighting-kate)
+
+* caching
+
+* Atom feeds (site-wide and per-page)
+
+* a library, "Network.Gitit", that makes it simple to include a gitit
+  wiki in any happstack application
+
+You can see a running demo at <http://gitit.johnmacfarlane.net>.
+
+[git]: http://git.or.cz
+[darcs]: http://darcs.net
+[mercurial]: http://mercurial.selenic.com/
+[pandoc]: http://johnmacfarlane.net/pandoc
+[Happstack]: http://happstack.com
+[highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/
+[texmath]: http://github.com/jgm/texmath/tree/master
+
+Getting started
+===============
+
+Compiling and installing gitit
+------------------------------
+
+You'll need the [GHC][] compiler and the [cabal-install][] tool. GHC can
+be downloaded [here][]. Note that, starting with release 0.5, GHC 6.10
+or higher is required. For [cabal-install][] on *nix, follow the [quick
+install][] instructions.
+
+[GHC]: http://www.haskell.org/ghc/
+[here]: http://www.haskell.org/ghc/
+[cabal-install]:  http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
+[quick install]:  http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#Quick Installation on Unix
+
+Once you've got cabal-install, installing gitit is trivial:
+
+    cabal update
+    cabal install gitit
+
+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:
+
+    cabal install
+
+The `cabal` 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 `.cabal` directory. You
+can check this by trying:
+
+    gitit --version
+
+If that doesn't work, check to see that `gitit` is in your local
+cabal-install executable directory (usually `~/.cabal/bin`). And make
+sure `~/.cabal/bin` is in your system path.
+
+Optional syntax highlighting support
+------------------------------------
+
+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.
+
+Highlighting support requires the [pcre][] library, so make sure that
+is installed before continuing.
+
+[pcre]:  http://www.pcre.org/ 
+
+To install gitit with highlighting support, first ensure that pandoc
+is compiled with highlighting support, then install gitit as above:
+
+    cabal install pandoc -fhighlighting --reinstall
+    cabal install gitit
+
+Running gitit
+-------------
+
+To run gitit, you'll need `git` in your system path. (Or `darcs` or
+`hg`, if you're using darcs or mercurial to store the wiki data.)
+
+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 `locale`.)
+
+Switch to the directory where you want to run gitit. This should be a
+directory where you have write access, since three directories, `static`,
+`templates`, and `wikidata`, and two files, `gitit-users` and `gitit.log`,
+will be created here. To start gitit, just type:
+
+    gitit
+
+If all goes well, gitit will do the following:
+
+ 1.  Create a git repository, `wikidata`, and add a default front page.
+ 2.  Create a `static` directory containing files to be treated as
+     static files by gitit.
+ 3.  Create a `templates` directory containing HStringTemplate templates
+     for wiki pages.
+ 4.  Start a web server on port 5001.
+
+Check that it worked: open a web browser and go to
+<http://localhost:5001>.
+
+You can control the port that gitit runs on using the `-p` option:
+`gitit -p 4000` will start gitit on port 4000. Additional runtime
+options are described by `gitit -h`.
+
+Using gitit
+===========
+
+Wiki links and formatting
+-------------------------
+
+For instructions on editing pages and creating links, see the "Help" page.
+
+Gitit interprets links with empty URLs as wikilinks. Thus, in markdown
+pages, `[Front Page]()` creates an internal wikilink to the page `Front
+Page`. In reStructuredText pages, `` `Front Page <>`_ `` has the same
+effect.
+
+If you want to link to a directory listing for a subdirectory, use a
+trailing slash:  `[foo/bar/]()` creates a link to the directory for
+`foo/bar`.
+
+Page metadata
+-------------
+
+Pages may optionally begin with a metadata block.  Here is an example:
+
+    ---
+    format: latex+lhs
+    categories: haskell math
+    toc: no
+    title: Haskell and
+      Category Theory
+    ...
+
+    \section{Why Category Theory?}
+
+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 "title" example above.) The metadata block must begin with a line
+`---` and end with a line `...` 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.)
+
+Currently the following keys are supported:
+
+format
+:   Overrides the default page type as specified in the configuration file.
+    Possible values are `markdown`, `rst`, `latex`, `html`, `markdown+lhs`,
+    `rst+lhs`, `latex+lhs`.  (Capitalization is ignored, so you can also
+    use `LaTeX`, `HTML`, etc.)  The `+lhs` variants indicate that the page
+    is to be interpreted as literate Haskell.  If this field is missing,
+    the default page type will be used.
+
+categories
+:   A space or comma separated list of categories to which the page belongs.
+
+toc
+:   Overrides default setting for table-of-contents in the configuration file.
+    Values can be `yes`, `no`, `true`, or `false` (capitalization is ignored).
+
+title
+:   By default the displayed page title is the page name.  This metadata element
+    overrides that default.
+
+Highlighted source code
+-----------------------
+
+If gitit was compiled against a version of pandoc that has highlighting
+support (see above), you can get highlighted source code by using
+[delimited code blocks][]:
+
+    ~~~ {.haskell .numberLines}
+    qsort []     = []
+    qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
+                   qsort (filter (>= x) xs) 
+    ~~~
+
+To see what languages your pandoc was compiled to highlight:
+
+    pandoc -v
+
+[delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
+
+Configuring and customizing gitit
+=================================
+
+Configuration options
+---------------------
+
+Use the option `-f [filename]` to specify a configuration file:
+
+    gitit -f my.conf
+
+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:
+
+    gitit --print-default-config > my.conf
+
+The default configuration file is documented with comments throughout.
+
+The `static` directory
+----------------------
+
+On receiving a request, gitit always looks first in the `static`
+directory (or in whatever directory is specified for `static-dir` 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
+`static`, gitit next looks in the `static` subdirectory of gitit's data
+file (`$CABALDIR/share/gitit-x.y.z/data`). 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.
+
+So, you can throw anything you want to be served statically (for
+example, a `robots.txt` file or `favicon.ico`) in the `static`
+directory. You can override any of gitit's default css, javascript, or
+image files by putting a file with the same relative path in `static`.
+Note that gitit has a default `robots.txt` file that excludes all
+URLs beginning with `/_`.
+
+Note:  if you set `static-dir` to be a subdirectory of `repository-path`,
+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.
+
+Using a VCS other than git
+--------------------------
+
+By default, gitit will store wiki pages in a git repository in the
+`wikidata` directory.  If you'd prefer to use darcs instead of git,
+you need to add the following field to the configuration file:
+
+    repository-type: Darcs
+
+If you'd prefer to use mercurial, add:
+
+    repository-type: Mercurial
+
+This program may be called "darcsit" instead of "gitit" when a darcs
+backend is used.
+
+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:
+
+    cabal install --reinstall filestore -f-maxcount
+    cabal install --reinstall gitit
+
+Otherwise you will get an error when you attempt to access your
+repository.
+
+Changing the theme
+------------------
+
+To change the look of the wiki, you can modify `custom.css` in
+`static/css`.
+
+To change the look of printed pages, copy gitit's default `print.css`
+to `static/css` and modify it.
+
+The logo picture can be changed by copying a new PNG file to
+`static/img/logo.png`. The default logo is 138x155 pixels.
+
+To change the footer, modify `templates/footer.st`.
+
+For more radical changes, you can override any of the default
+templates in `$CABALDIR/share/gitit-x.y.z/data/templates` by copying
+the file into `templates` and modifying it. The `page.st` template is
+the master template; it includes the others. Interpolated variables are
+surrounded by `$`s, so `literal $` must be backslash-escaped.
+
+Adding support for math
+-----------------------
+
+To write math on a markdown-formatted wiki page, just enclose it
+in dollar signs, as in LaTeX:
+
+    Here is a formula:  $\frac{1}{\sqrt{c^2}}$
+
+You can write display math by enclosing it in double dollar signs:
+
+    $$\frac{1}{\sqrt{c^2}}$$
+
+Gitit can display TeX math in three different ways, depending on the
+setting of `math` in the configuration file:
+
+1.  `mathml` (default): Math will be converted to MathML using
+    [texmath][]. This method works with IE+mathplayer, Firefox, and
+    Opera, but not Safari.
+
+2.  `jsMath`: Math will be rendered using the [jsMath][] javascript.
+    If you want to use this method, download `jsMath` and `jsMath
+    Image Fonts` from the [jsMath download page][]. You'll have two
+    `.zip` archives. Unzip them both in the `static/js` directory (a new
+    subdirectory, `jsMath`, will be created).  This works with all
+    browsers, but is slower and not as nice looking as MathML.
+
+3.  `raw`: Math will be rendered as raw LaTeX codes.
+
+[jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
+
+Restricting access
+------------------
+
+If you want to limit account creation on your wiki, the easiest way to do this
+is to provide an `access-question` 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.
+
+Another approach is to use HTTP authentication. (See the config file comments on
+`authentication-method`.)
+
+Plugins
+=======
+
+Plugins are small Haskell programs that transform a wiki page after it
+has been converted from Markdown or RST. See the example plugins in the
+`plugins` directory. To enable a plugin, include the path to the plugin
+(or its module name) in the `plugins` field of the configuration file.
+(If the plugin name starts with `Network.Gitit.Plugin.`, gitit will assume that
+the plugin is an installed module and will not look for a source file.)
+
+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 `plugins` Cabal flag:
+
+    cabal install --reinstall gitit -f-plugins
+
+Note also that if you compile gitit for executable profiling, attempts
+to load plugins will result in "internal error: PAP object entered!"
+
+Accessing the wiki through git
+==============================
+
+All the pages and uploaded files are stored in a git repository. By
+default, this lives in the `wikidata` directory (though this can be
+changed through configuration options). So you can interact with the
+wiki using git command line tools:
+
+    git clone ssh://my.server.edu/path/of/wiki/wikidata
+    cd wikidata
+    vim Front\ Page.page  # edit the page
+    git commit -m "Added message about wiki etiquette" Front\ Page.page
+    git push
+
+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 `.page`.
+
+If you are using the darcs or mercurial backend, the commands will
+be slightly different.  See the documentation for your VCS for
+details.
+
+Performance
+===========
+
+Caching
+-------
+
+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 `use-cache` to `yes`.
+By default, rendered pages, highlighted source files, and exported PDFs
+will be cached in the `cache` directory. (Another directory can be
+specified by setting the `cache-dir` configuration option.)
+
+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
+`/_expire/path/to/page`, where `path/to/page` is the name of the page to
+be expired.
+
+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 `expireGititCache`. Assuming you are
+running gitit at port 5001 on localhost, and the environment variable
+`CHANGED_FILES` contains a list of the files that have changed, you can
+expire their cached versions using
+
+    expireGititCache http://localhost:5001 $CHANGED_FILES
+
+Or you can specify the files directly:
+
+    expireGititCache http://localhost:5001 "Front Page.page" foo/bar/baz.c
+
+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 (> 0) otherwise.
+
+The cache is persistent through restarts of gitit.  To expire all cached
+pages, simply remove the `cache` directory.
+
+Idle
+----
+
+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.
+
+To fix this, one can disable the idle-time GC with the runtime flag
+`-I0`:
+
+    gitit -f my.conf +RTS -I0 -RTS
+
+Using gitit with apache
+=======================
+
+Most users who run a public-facing gitit will want gitit to appear
+at a nice URL like `http://wiki.mysite.com` or
+`http://mysite.com/wiki` rather than `http://mysite.com:5001`.
+This can be achieved using apache's `mod_proxy`.
+
+Proxying to `http://wiki.mysite.com`
+------------------------------------
+
+Set up your DNS so that `http://wiki.mysite.com` maps to
+your server's IP address. Make sure that the `mod_proxy` module is
+loaded, and set up a virtual host with the following configuration:
+
+    <VirtualHost *>
+        ServerName wiki.mysite.com
+        DocumentRoot /var/www/
+        RewriteEngine On
+        ProxyPreserveHost On
+        ProxyRequests Off
+    
+        <Proxy *>
+           Order deny,allow
+           Allow from all
+        </Proxy>
+    
+        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
+    
+    </VirtualHost>
+
+Reload your apache configuration and you should be all set.
+
+Proxying to `http://mysite.com/wiki`
+------------------------------------
+
+Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`,
+and `mod_proxy_html` modules are loaded. `mod_proxy_html`
+is an external module, which can be obtained [here]
+(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 `/wiki/`.
+
+First, tell gitit not to compress pages, since `mod_proxy_html` needs
+uncompressed pages to parse. You can do this by setting the gitit
+configuration option
+
+    compress-responses: no
+
+Second, modify the link in the `reset-password-message` in the
+configuration file:  instead of
+
+    http://$hostname$:$port$$resetlink$
+
+set it to
+
+    http://$hostname$/wiki$resetlink$
+
+Restart gitit.
+
+Now add the following lines to the apache configuration file for the
+`mysite.com` server:
+
+    # These commands will proxy /wiki/ to port 5001
+
+    ProxyRequests Off
+
+    <Proxy *>
+      Order deny,allow
+      Allow from all
+    </Proxy>
+
+    ProxyPass /wiki/ http://127.0.0.1:5001/
+
+    <Location /wiki/>
+      SetOutputFilter  proxy-html
+      ProxyPassReverse /
+      ProxyHTMLURLMap  /   /wiki/
+      RequestHeader unset Accept-Encoding
+    </Location>
+
+Reload your apache configuration and you should be set.
+
+For further information on the use of `mod_proxy_http` to rewrite URLs,
+see the [`mod_proxy_html` guide].
+
+[`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html
+
+Using gitit as a library
+========================
+
+By importing the module `Network.Gitit`, you can include a gitit wiki
+(or several of them) in another happstack application. There are some
+simple examples in the haddock documentation for `Network.Gitit`.
+
+Reporting bugs
+==============
+
+Bugs may be reported (and feature requests filed) at
+<http://code.google.com/p/gitit/issues/list>.
+
+There is a mailing list for users and developers at
+<http://groups.google.com/group/gitit-discuss>.
+
+Acknowledgements
+================
+
+A number of people have contributed patches:
+
+- Gwern Branwen helped to optimize gitit and wrote the
+  InterwikiPlugin. He also helped with the Feed module.
+- Simon Michael contributed the patch adding RST support.
+- Henry Laxen added support for password resets and helped with
+  the apache proxy instructions.
+- Anton van Straaten made the process of page generation
+  more modular by adding Gitit.ContentTransformer.
+- Robin Green helped improve the plugin API and interface, and
+  fixed a security problem with the reset password code.
+- Thomas Hartman helped improve the index page, making directory
+  browsing persistent, and fixed a bug in template recompilation.
+- Justin Bogner improved the appearance of the preview button.
+- Kohei Ozaki contributed the ImgTexPlugin.
+- Michael Terepeta improved validation of change descriptions.
+- 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.
+
+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.
+
+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
+`img/icons` come from bluetrip as well.
+