5ab3f85dd93b — Oben Sonne 11 years ago
Update doc
1 files changed, 69 insertions(+), 45 deletions(-)

M README
M README +69 -45
@@ 1,12 1,15 @@ 
 -*- restructuredtext -*-
 
+===============================================================================
 Diggie
-======
+===============================================================================
 
-*Diggie* is a `Django`_ wiki application. While it can be integrated into every
-Django driven site, it's main use case is to run it as a local wiki
-web application. *Diggie* ships with a command line utility which automatically
-sets up a local Django site running *Diggie*::
+*Diggie* is a `Markdown`_ and `Django`_ driven wiki application.
+
+As a Django app, it can be integrated it in every Django driven site. However,
+it's main use case is to run it as a personal local wiki application. *Diggie*
+ships with a command line utility which automatically sets up a local Django
+site running *Diggie*::
 
     $ diggie /path/to/wiki --init --name MyWiki
     $ diggie /path/to/wiki --run

          
@@ 15,10 18,12 @@ is all you need to get your local wiki u
 
 Install *Diggie* by running ``easy_install diggie`` or ``pip install diggie``.
 
+.. _Markdown: http://daringfireball.net/projects/markdown/
 .. _Django: http://www.djangoproject.com/
 
+-------------------------------------------------------------------------------
 Using Diggie as a personal local wiki
---------------------------------------
+-------------------------------------------------------------------------------
 
 This is easy!
 

          
@@ 32,24 37,30 @@ 2.  Run::
 
 3.  Point your browser to http://localhost:4000 .
 
-Run ``diggie --help`` to get some more actions and options.
+The new wiki contains a help page about using a *Diggie* wiki.
 
 Structure of a local wiki
-'''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A new wiki at ``/path/to/wiki`` consists of the following files and directories: 
 
-- ``wiki.db``: sqlite3 database containing wiki pages
-- ``templates/diggie``: symbolic link, just ignore this for now
-- ``media/diggie``: symbolic link, just ignore this for now
-- ``media/images``: image links refer to files located here 
-- ``media/math``: used to store rendered formula images
+``wiki.db``
+  An `SQLite`_ database containing wiki pages.
+``media/images``
+  Wiki image links refer to files located here (see in-wiki help for details). 
+``media/math``
+  Used to store rendered formula images (see in-wiki help for details).
        
-That is you can easily share you wiki across multiple computers using
-services like *UbuntuOne* or *DropBox*.
+The whole wiki s file based which makes it easy to share it across
+multiple computers, e.g. using services like `UbuntuOne`_ or `Dropbox`_.
 
+.. _SQLite: http://www.sqlite.org/
+.. _UbuntuOne: https://one.ubuntu.com/
+.. _Dropbox: http://www.dropbox.com/
+
+-------------------------------------------------------------------------------
 Using Diggie in a Django powered site
-----------------------------------------
+-------------------------------------------------------------------------------
 
 For a simple example, have a look into the Django site projects created by
 the tool *diggie* for local wikis.

          
@@ 59,56 70,69 @@ follows:
 
 1.  Add ``diggie`` to ``INSTALLED_APPS`` in the project's ``settings.py``.
 
-2.  Create a symbolic link ``diggie`` in the project's template directory
-    pointing to ``/path/to/diggie-python-module/templates/diggie``.
+2.  Either add ``django.template.loaders.app_directories.Loader`` to
+    ``TEMPLATE_LOADERS`` in ``settings.py`` or link to
+    ``/path/to/diggie-python-module/templates/diggie`` from one of the
+    project's template locations.
 
-3.  Create a symbolic link ``diggie`` in the project's ``MEDIA_ROOT`` pointing
-    to ``/path/to/diggie-python-module/media/diggie``.
-
-4.  Set *Diggie* specific options  in the projects ``settings.py``:
+3.  Set *Diggie* specific options  in the projects ``settings.py``:
 
-    +---------------------+--------------+------------------------------------+
-    | Setting             | Default      | Description                        |
-    +=====================+==============+====================================+
-    | ``DIGGIE_WIKINAME`` | ``"Diggie"`` | Name of the wiki.                  |
-    +---------------------+--------------+------------------------------------+
-    | ``DIGGIE_MEDIA``    | ``""``       | Path relative to ``MEDIA_ROOT``    |
-    |                     |              | (and ``MEDIA_URL``) to use for wiki|
-    |                     |              | content files (e.g. images). Must  |
-    |                     |              | use *slashes*! The server needs    |
-    |                     |              | write access to                    |
-    |                     |              | ``MEDIA_ROOT/DIGGIE_MEDIA/math``   |
-    |                     |              | for saving rendered math images.   |
-    +---------------------+--------------+------------------------------------+
-    | ``DIGGIE_MDX``      | ``[]``       | List of additional or custom       |
-    |                     |              | markdown extensions.               |
-    +---------------------+--------------+------------------------------------+
+    ``DIGGIE_WIKINAME = "Diggie"``
+      Name of the wiki.
+    
+    ``DIGGIE_MEDIA = ""``
+      Path relative to ``MEDIA_ROOT`` (and ``MEDIA_URL``) to use for wiki
+      content files (e.g. images). Must use *slashes*! The server needs write
+      access to ``MEDIA_ROOT/DIGGIE_MEDIA/math`` for saving rendered math
+      images.
+    
+    ``DIGGIE_MDX = []``
+      List of additional or custom markdown extensions.
 
-5.  Adjust your ``urls.py``, for instance::
+4.  Adjust the project's ``urls.py``, for instance::
 
         urlpatterns = patterns('',
             ...
             (r'diggie/^', include('diggie.urls')),
         )
 
-6.  Sync the project's database::
+5.  Sync the project's database::
 
         $ python manage.py syncdb
 
 Finished.
 
+-------------------------------------------------------------------------------
 Import and export
------------------
+-------------------------------------------------------------------------------
 
 The command line tool *diggie* can be used to import or export pages into or
-from a *Diggie* wiki.
+from a *Diggie* wiki. This is useful to backup wiki pages outside of an
+database, migrate between incompatible *Diggie* versions or to migrate
+pages from another wiki to a *Diggie* wiki or vice versa.
+
+Run ``diggie --help`` for details.
+
+-------------------------------------------------------------------------------
+A disclaimer on browser support
+-------------------------------------------------------------------------------
 
-TODO
+*Diggie* is a one-person free-time project. As that I'm not able to or willing
+to check if *Diggie* runs equally pleasant in all browsers. Indeed *Diggie*
+uses some rather new CSS and HTML features you'll probably won't find in older
+browsers.
 
+Personally I use it in Google Chrome 6. If you find something not working in
+other browsers, feel free to fix this and share your patches by forking the
+source repository. I'll happily integrate improvements, except dirty hacks for
+old IE versions.  
+
+===============================================================================
 Changes
-=======
+===============================================================================
 
+-------------------------------------------------------------------------------
 Version 0.1
------------
+-------------------------------------------------------------------------------
 
 - Initial release
  No newline at end of file