remove admin-specific stuff from user's guide

1 files changed, 1 insertions, 525 deletions

diff --git a/Gitit User’s Guide.page b/Gitit User’s Guide.page
index c450c06..5ad0853 100644
--- a/Gitit User’s Guide.page
+++ b/Gitit User’s Guide.page
@@ -2,120 +2,6 @@
 format: Markdown
 ...
 
-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, HTML,
-DocBook, or Emacs Org-mode markup can also be used.  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
-
-[git]: http://git.or.cz
-[darcs]: http://darcs.net
-[mercurial]: http://mercurial.selenic.com/
-[pandoc]: http://pandoc.org
-[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
-------------------------------
-
-The most reliable way to install gitit from source is to get the
-[stack] tool.  Then clone the gitit repository and use stack
-to install:
-
-    git clone https://github.com/jgm/gitit
-    cd gitit
-    stack install
-
-Alternatively, instead of using [stack], you can get the
-[Haskell Platform] and do the following:
-
-    cabal update
-    cabal install gitit
-
-This 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.
-
-[stack]: https://github.com/commercialhaskell/stack
-[Haskell Platform]: https://www.haskell.org/platform/
-
-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
 ===========
 
@@ -196,105 +82,6 @@ To see what languages your pandoc was compiled to highlight:
 
 [delimited code blocks]: http://pandoc.org/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
-
-The configuration can be split between several files:
-
-	gitit -f my.conf -f additional.conf
-
-One use case is to keep sensible part of the configuration outside of a SCM
-(oauth client secret for example).
-
-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`, modifying it, and restarting gitit. 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
 -----------------------
 
@@ -318,315 +105,4 @@ setting of `math` in the configuration file:
 
 3.  `raw`: Math will be rendered as raw LaTeX codes.
 
-[MathJax]: https://www.mathjax.org/
-
-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`.)
-
-Authentication through github
------------------------------
-
-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:
-
-```
-[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
-```
-
-The github authentication uses the scope `user:email`. 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 `read:org` if you
-uses the option `github-org` to check membership against an organization.
-
-To push your repository to gitub after each commit, you can add the file
-`post-commit` with the content below in the .git/hooks directory of your
-wikidata repository.
-
-```
-#!/bin/sh
-git push origin master 2>> logit
-```
-
-Plugins
-=======
-
-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 `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, and highlighted source files
-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
-
-
-Note:
-
-To enable RTS, cabal needs to pass the compile flag `-rtsopts` to GHC while installing.
-
-    cabal install --reinstall gitit --ghc-options="-rtsopts"
-
-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`, `mod_proxy_http` and `mod_rewrite` modules are
-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.
-
-Using nginx to achieve the same
--------------------------------
-
-Drop a file called `wiki.example.com.conf` into `/etc/nginx/conf.d`
-(or where ever your distribution puts it).
-
-    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;
-    }
-
-Reload your nginx config 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/
-      ProxyHTMLDocType "<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>" XHTML
-      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
-<https://github.com/jgm/gitit/issues>.
-
-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.
-
+[MathJax]: https://www.mathjax.org/
\ No newline at end of file