1. Daniel Neuhäuser
  2. moin-2.0-gsoc-pastebin

Commits

Tech Nossomy  committed 356390d

Syntactical changes to docs

  • Participants
  • Parent commits 3989635
  • Branches default

Comments (0)

Files changed (21)

File docs/admin/backup.rst

View file
 Backup and Restore
 ==================
 
-General remarks
-===============
-
-Everyone wants Restore. Nobody wants Backup.
-
-.. warning::
-
-   Unfortunately, that doesn't work. Read below about a working procedure.
-
 Full Backup / Restore
 =====================
 
-Of course, it's best to have a **full** backup of your machine. If you do,
-you can easily restore it to a working condition, even if things go horribly wrong.
+The best way to recover from data loss is to have a **full** backup of your machine. 
+With this backup you can easily restore your machine to a working condition.
 
-However, you can use the procedure below to selectively backup only the files
+The procedure below explains how to selectively backup only the files
 essential to your MoinMoin installation. While there is no need to maintain both a full
-and a selective backup, having one of the two is strongly advised.
+and a selective backup, having at least one of the two is strongly recommended.
 
 Selective Backup
 ================
-If you just want a backup of MoinMoin and your data, backup the following files:
+If you want a backup of MoinMoin and your data, then backup the following::
 
-* your data (most important)
-* moin configuration (e.g. wikiconfig.py)
-* logging configuration (e.g. logging.conf)
-* moin script (e.g. moin.wsgi)
-* web server configuration (e.g. apache virtualhost config)
-* optional: moin code + dependencies (you should at least know which
-  version you ran, so you can download and install that version when you
-  need to restore)
+* your data
+* moin configuration, e.g. wikiconfig.py
+* logging configuration, e.g. logging.conf
+* moin script, e.g. moin.wsgi
+* web server configuration, e.g. apache virtualhost config
+* optional: moin code + dependencies; you should at least know which
+  version you ran, so you can reinstall that version when you
+  need to restore
 
-To create a dump of all data stored in moin (wiki items, user profiles), run the
+To create a dump of all data stored in moinmoin (wiki items, user profiles), run the
 following command::
 
  moin save --file backup.moin
 
-Please note that this file contains sensitive data (like user profiles, wiki
-contents), so store your backups in a safe place and make sure no unauthorized
-individuals can access them.
+Please note that this file contains sensitive data like user profiles, wiki
+contents, so store your backups in a safe place that no unauthorized
+individual can access.
 
 Selective Restore
 =================
 
-To restore all software and configuration files (see above) to their original
-place. Make sure your (empty) wiki works as expected::
+To restore all software and configuration files to their original
+place, create an empty wiki first::
 
  moin moin -s -i  # -s = create new storage
                   # -i = create new index
 To load the backup file into your empty wiki, run::
 
  moin load --file backup.moin
-

File docs/admin/changes.rst

View file
 :tocdepth: 2
 
-.. _changes:
+.. _changes::
 
 Changes in MoinMoin
 ===================

File docs/admin/configure.rst

View file
 ========================================
 Kinds of configuration files
 ============================
-To change how moin behaves and looks like, you may customize it by editing
-its misc. configuration files:
+To change how moinmoin behaves and looks, you may customize it by editing
+its configuration files::
 
 * Wiki Engine Configuration
 
   - the file is often called wikiconfig.py, but it can have any name
-  - in that file, there is a Config class - this is the wiki engine's config
-  - this is Python code
+  - in that file, there is a Config class; this is the wiki engine's configuration
+  - it is written in Python
 
 * Framework Configuration
   
   - this is also located in the same file as the Wiki Engine Configuration
-  - there are some UPPERCASE settings at the bottom - this is the framework's
+  - there are some UPPERCASE settings at the bottom; this is the framework's
     config (for Flask and Flask extensions)
-  - this is Python code
+  - it is written in Python
 
 * Logging Configuration
 
-  - optional, if you don't configure this, it'll use builtin defaults
-  - this is a separate file, often called logging.conf or so
-  - .ini-like file format
+  - optional; if you don't configure this, it will use the builtin defaults
+  - this is a separate file, often called logging.conf
+  - it has an .ini-like file format
 
 Do small steps and have backups
 -------------------------------
-It is a good idea to start from one of the sample configs provided with moin
-and only do small careful changes, then try it and then do the next change.
+Start from one of the sample configs provided with moin
+and only perform small changes, then try it before testing the next change.
 
 If you're not used to the config file format, backup your last working config
 so you can revert to it in case you make some hard to find typo or other error.
 Editing Python files
 --------------------
 When editing Python files, be careful with indentation, only use multiples of
-4 spaces to indent, no tabs!
+4 spaces to indent, and no tabs!
 
-Also, be careful with syntax in general, it must be valid python code or else
-it'll crash with some error when trying to load the config. If that happens,
-read the error message, it'll usually tell the line number and what the problem
-is. If you can't fix it easily, just revert to your backup of your last working
+Also, be careful with syntax in general, it must be valid Python code or else
+it will crash with some error when trying to load the config. If that happens,
+read the error message, it will usually tell the line number and what the problem
+is. If you can't fix it easily, then revert to your backup of your last working
 config.
 
-Why Python for configuration?
------------------------------
-At first, you might wonder why we use Python code for configuration. It is
-simply because it is powerful and we can make use of that power there.
-Using something else would usually mean much more work when developing new
-stuff and also would be much less flexible and powerful, dumbing down
-everything.
+Why use Python for configuration?
+---------------------------------
+At first, you might wonder why we use Python code for configuration. One of the 
+reasons is that it is a powerful language. Moinmoin itself is developed in Python 
+and using something else would usually mean much more work when developing new 
+functionality.
+
 
 wikiconfig.py Layout
 ====================
  from MoinMoin.config.default import DefaultConfig
 
  class Config(DefaultConfig):
-     # a comment
+     # some comment
      sometext = u'your value'
      somelist = [1, 2, 3]
 
- MOINCFG = Config  # Flask only likes uppercase stuff
+ MOINCFG = Config  # Flask only likes uppercase characters
  SOMETHING_FLASKY = 'foobar'
 
-Let's go through this line-by-line:
+Let's go through this line-by-line::
 
-0. this declares the encoding of the config file. make sure your editor uses
-   the same encoding (character set), esp. if you intend to use non-ASCII
-   characters (e.g. non-english stuff).
-1. this gets the DefaultConfig class from the moin code - it has default
-   values for all settings (this will save you work, you only have to define
-   stuff you want different from the default).
-2. an empty line, for better readability
-3. now we define a new class `Config` that inherits most stuff from
-   `DefaultConfig` - this is the wiki engine configuration. If you define some
-   setting within this class, it'll overwrite the setting from DefaultConfig.
-4. with a `#` character you can write a comment into your config. This line (as
-   well as all other following lines with Config settings) is indented by 4
+0. this declares the encoding of the config file; make sure your editor uses
+   the same encoding (character set), especially if you intend to use non-ASCII
+   characters.
+1. this gets the DefaultConfig class from the moin code; it has default
+   values for all settings and this will save you work, because you only have to define
+   the parts that should be different from the defaults.
+2. empty line, for better readability
+3. define a new class `Config` that inherits most content from
+   `DefaultConfig`; this is the wiki engine configuration and if you define some
+   setting within this class, it will overwrite the setting from DefaultConfig.
+4. a `#` character defines a comment in your config. This line, as
+   well as all other following lines with Config settings, is indented by 4
    blanks, because Python defines blocks by indentation.
-5. define a Config attribute called `sometext` with value u'your value' -
+5. define a Config attribute called `sometext` with value u'your value' whereby
    the `u'...'` means that this is a unicode string.
-6. define a Config attribute called `somelist` with value [1, 2, 3] - this is
-   a list with the numbers 1, 2 and 3 as list elements.
+6. define a Config attribute called `somelist` with value [1, 2, 3]; this is
+   a list with the numbers 1, 2 and 3 as its elements.
 7. empty line, for better readability
-8. The special line "MOINCFG = Config" must stay there in exactly this form due to
+8. the special line "MOINCFG = Config" must stay there in exactly this form for
    technical reasons.
-9. UPPERCASE stuff at the bottom, outside the Config class - this is framework
-   configuration (usually something for Flask or some Flask extension).
+9. UPPERCASE code at the bottom, outside the Config class is a framework
+   configuration; usually something for Flask or some Flask extension.
 
 A real-life example of a `wikiconfig.py` can be found in the
 `docs/examples/config/` directory.
 
 Using a custom snippets.html template
 -------------------------------------
-Some user interface or html elements that often need customization are
+The user interface or html elements that often need customization are
 defined as macros in the template file `snippets.html`.
 
-If you'ld like to customize some stuff, you have to make a copy of the built-in
-`MoinMoin/templates/snippets.html` and configure moin so it will prefer your
+If you would like to customize some parts, you have to make a copy of the built-in
+`MoinMoin/templates/snippets.html` and configure moin so it will use your
 copy instead of the built-in one.
 
-This is done by just giving a list of template directories where moin will
+This is done by giving a list of template directories where moin itself will
 look first::
 
     template_dirs = ['path/to/my/templates', ]
 
-To customize something, you usually have to insert your stuff between the
+To customize something, you usually have to insert your code between the
 `{% macro ... %}` and `{% endmacro %}` lines, see below for more details.
 
 Logo
 ~~~~
-To replace the default MoinMoin logo with your own logo (which is **strongly**
-recommended, especially if your wiki has private or sensitive information),
-so your users will immediately recognize which wiki site they are currently using.
+To replace the default MoinMoin logo with your own logo, apply the following code::
 
-You can even use some simple text (or just nothing) for the logo, it is not
+    {% macro logo() -%}
+    <img src="http://wiki.example.org/logos/my_logo.png" id="moin-img-logo" alt="Example Logo">
+    {%- endmacro %}
+
+This is recommended to allow your users to immediately recognize which wiki site they are currently on.
+
+You can even use some simple text or even nothing at all for the logo, it is not
 required to be an image.
 
 Make sure the dimensions of your logo image or text fit into the layout of
 the theme(s) your wiki users are using.
 
-Example code::
-
-    {% macro logo() -%}
-    <img src="http://wiki.example.org/logos/my_logo.png" id="moin-img-logo" alt="Example Logo">
-    {%- endmacro %}
-
 Displaying license information
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you need to display something like license information for your content or
-some other legalese, use this macro to do it::
+some other legalese, use this macro::
 
     {# License information in the footer #}
     {% macro license_info() -%}
 
 Inserting pieces of HTML
 ~~~~~~~~~~~~~~~~~~~~~~~~
-At some specific places, you can just add a piece of your own html into the
+At some specific places, you can add a piece of your own html into the
 head or body of the theme's html output::
 
     {# Additional HTML tags inside <head> #}
 
 Credits and Credit Logos
 ~~~~~~~~~~~~~~~~~~~~~~~~
-At the bottom, we usually show some text and image links pointing out that
-this wiki runs MoinMoin, uses Python, that MoinMoin is GPL licensed, etc.
+At the bottom of your wiki pages, usually some text and image links are shown
+pointing out that the wiki runs MoinMoin, uses Python, that MoinMoin is GPL licensed, etc.
 
-If you run a public site using MoinMoin, we would appreciate if you please
-*keep* those links (esp. the "MoinMoin powered" one).
+If you run a public site using MoinMoin, we would appreciate if you
+*keep* those links, especially the "MoinMoin powered" one.
 
 However, if you can't do that for some reason, feel free to modify these
-macros to show whatever you want::
+macros to show something else::
 
     {# Image links in the footer #}
     {% macro creditlogos(start='<ul id="moin-creditlogos"><li>'|safe, end='</li></ul>'|safe, sep='</li><li>'|safe) %}
 
 Adding CSS
 ~~~~~~~~~~
-If you just want some style changes, you can maybe do them by just adding
-some custom css (and overwrite any style you don't like in the base theme)::
+To apply some style changes, add some custom css and overwrite any style you 
+don't like in the base theme::
 
     {# Additional Stylesheets (after theme css, before user css #}
     {% macro stylesheets() -%}
         <link media="screen" href="http://wiki.example.org/static/green.css" title="Green Style" rel="alternate stylesheet" />
     {%- endmacro %}
 
-You can either just add some normal css stylesheet or add a choice of alternate
+You can either add some normal css stylesheet or add a choice of alternate
 stylesheets.
 
-See:
+See::
 
 * `CSS media types <http://www.w3.org/TR/CSS2/media.html>`_
 * `Alternate Stylesheets <http://www.alistapart.com/articles/alternate/>`_
 
-A good way to test a stylesheet is to first use it as user CSS before you
-configure it for everybody.
+A good way to test a stylesheet is to first use it as user CSS before
+configuring it for the public.
 
-Please note that `stylesheets` will be included no matter what theme the wiki
-user has selected, so maybe either only do changes applying to all available
-themes or force all users to use same theme, so that your CSS applies
-correctly.
+Please note that `stylesheets` will be included no matter what theme the
+user has selected, so either only apply changes to all available themes or 
+force all users to use the same theme, so that your CSS displays correctly.
 
 Displaying user avatars
 ~~~~~~~~~~~~~~~~~~~~~~~
 Please note that using the gravatar service has some privacy issues::
 
 * to register your image for your email at gravatar.com, you need to give them
-  your email address (same as you use in your wiki user profile).
+  your email address, which is the same as you use in your wiki user profile.
 * we try to avoid exposing the referrer URL to gravatar.com, but this only
   works if your browser correctly implements rel="noreferrer". If it does not,
   your wiki item URLs will be exposed, so they will roughly know which people
 XStatic Packages
 ----------------
 `XStatic <http://readthedocs.org/projects/xstatic>`_ is a packaging standard 
-to package external (often 3rd party) static files as a python package. 
-So they are easily usable on all operating systems, 
-with any package management system or even without one.
+to package external static files as a Python package, often third party. 
+That way they are easily usable on all operating systems, whether it has a package management 
+system or not.
 
 In many cases, those external static files are maintained by someone else (like jQuery
-javascript library or even much bigger js libraries or applications) and we
-definitely do not want to merge them into our project.
+javascript library or larger js libraries) and we definitely do not want to merge 
+them into our project.
 
-For MoinMoin we require the following XStatic Packages in setup.py:
+For MoinMoin we require the following XStatic Packages in setup.py::
 
 * `jquery <http://pypi.python.org/pypi/XStatic-jQuery>`_
   for jquery lib functions loaded in the template file base.html
   used in the template of index view for multiple parallel downloads.
 
 
-These packages are imported in wikiconfig by ::
+These packages are imported in wikiconfig by::
 
     from xstatic.main import XStatic
     mod_names = ['jquery', 'jquery_file_upload', 'ckeditor',
         xs = XStatic(mod, root_url='/static', provider='local', protocol='http')
         serve_files.update([(xs.name, xs.base_dir)])
 
-In a template file you access the files of such a package by its module name ::
+In a template file you access the files of such a package by its module name::
 
     url_for('serve.files', name='the mod name', filename='the file to load')
 
 
 Custom Themes
 -------------
-In case you want to do major changes to how MoinMoin looks (so just
-changing snippets or CSS is not enough), you could also write your own theme.
+In case you want to do major changes to how MoinMoin displays its pages, you 
+could also write your own theme.
 
-Be warned: doing this is a long-term thing, you don't just have to write it,
-but you'll also have to maintain and update it. Thus, we suggest you try
-living with the built-in themes or collaborate with the MoinMoin core and
-other interested developers on the internet.
-
-A few well-made, well-maintained and widespread themes are much better than
-lots of the opposite.
+Caution: developing your own theme means you also have to maintain and update it, 
+which normally requires a long-term effort.
 
 .. todo::
 
 
 Each authenticator is an instance of some specific class, configuration of
 the authenticators usually works by giving them keyword arguments. Most have
-reasonable defaults, though.
+reasonable defaults though.
 
 MoinAuth
 --------
 
 HTTPAuthMoin
 ------------
-With HTTPAuthMoin moin does http basic auth all by itself (without help of
-the web server)::
+With HTTPAuthMoin moin does http basic authentication by itself without the help of
+the web server::
 
     from MoinMoin.auth.http import HTTPAuthMoin
     auth = [HTTPAuthMoin(autocreate=True)]
 asking for username and password. Both then gets transmitted to moin and it
 is compared against the password hash stored in the user's profile.
 
-Note: when HTTPAuthMoin is used, the browser will show that login dialogue, so
+**Note:** when HTTPAuthMoin is used, the browser will show that login dialogue, so
 users must login to use the wiki.
 
 GivenAuth
 ---------
 With GivenAuth moin relies on the webserver doing the authentication and giving
-the result to moin (usually via environment variable REMOTE_USER)::
+the result to moin, usually via the environment variable REMOTE_USER::
 
     from MoinMoin.auth import GivenAuth
     auth = [GivenAuth(autocreate=True, coding='utf-8')]
 
-Using this has some pros and cons:
+Using this method has some pros and cons::
 
 * you can use lots of authentication extensions available for your web server
-* but the only information moin will get (via REMOTE_USER) is the authenticated
+* but the only information moin will get via REMOTE_USER is the authenticated
   user's name, nothing else. So, e.g. for LDAP/AD, you won't get additional
-  stuff stored in the LDAP directory.
-* all the stuff you won't get (but you need) will need to be manually stored
-  and updated in the user's profile (e.g. the user's email address, etc.)
+  content stored in the LDAP directory.
+* everything you won't get, but which you need, will need to be manually stored
+  and updated in the user's profile, e.g. the user's email address, etc.
 
-Please note that you must give the correct coding (character set) so that moin
+Please note that you must give the correct character set so that moin
 can decode the username to unicode, if necessary. For environment variables
 like REMOTE_USER, the coding might depend on your operating system.
 
 
 LDAPAuth with single LDAP server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This example shows how to use it with a single LDAP/AD server::
+This example shows how to use LDAPAuth with a single LDAP/AD server::
 
     from MoinMoin.auth.ldap_login import LDAPAuth
     ldap_common_arguments = dict(
 
 LDAPAuth with two LDAP servers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This example shows how to use it with a two LDAP/AD servers (like e.g. a primary
-and backup domain controller)::
+This example shows how to use LDAPAuth with a two LDAP/AD servers, such as in a setup
+with a primary controller and backup domain controller::
 
-    # ... same stuff as for single server (except the line with "auth =") ...
+    # ... same as for single server (except the line with "auth =") ...
     ldap_authenticator2 = LDAPAuth(
         server_uri='ldap://otherldap',  # ldap / active directory server URI for second server
         name='ldap2',
 
 AuthLog
 -------
-AuthLog is no real authenticator in the sense that it authenticates (logs in) or
-deauthenticates (logs out) users, it is just passively logging informations for
+AuthLog is not a real authenticator in the sense that it authenticates (logs in) or
+deauthenticates (logs out) users. It is passively logging informations for
 authentication debugging::
 
     from MoinMoin.auth import MoinAuth
  2011-02-05 16:35:06,294 INFO MoinMoin.auth.log:22 logout: user_obj=<MoinMoin.user.User at 0x92b5d4c name:u'ThomasWaldmann' valid:False> kw={}
  2011-02-05 16:35:06,328 INFO MoinMoin.auth.log:22 session: user_obj=None kw={}
 
-Note: there are sensitive informations like usernames and passwords in this
-log output. Make sure you only use this for testing and delete the logs when
+**Note:** there is sensitive information like usernames and passwords in this
+log output. Make sure you only use this for testing only and delete the logs when
 done.
 
 SMBMount
 --------
 SMBMount is no real authenticator in the sense that it authenticates (logs in)
-or deauthenticates (logs out) users. It just catches the username and password
+or deauthenticates (logs out) users. It instead catches the username and password
 and uses them to mount a SMB share as this user.
 
 SMBMount is only useful for very special applications, e.g. in combination
 =====================
 Credentials
 -----------
-Some of the authentication methods described above will transmit credentials
-(like usernames and password) in unencrypted form:
+Some of the authentication methods described above will transmit credentials,
+like usernames and password, in unencrypted form:
 
 * MoinAuth: when the login form contents are transmitted to moin, they contain
-  username and password in cleartext.
+  username and password in clear text.
 * HTTPAuthMoin: your browser will transfer username and password in a encoded
-  (but NOT encrypted) form with EVERY request (it uses http basic auth).
-* GivenAuth: please check the potential security issues of the authentication
-  method used by your web server. For http basic auth please see HTTPAuthMoin.
+  (but NOT encrypted) form with EVERY request; it uses http basic auth.
+* GivenAuth: check the potential security issues of the authentication
+  method used by your web server; for http basic auth please see HTTPAuthMoin.
 * OpenID: please check yourself.
 
 Contents
 --------
-http transmits everything in cleartext (not encrypted).
+http transmits everything in clear text and is therefore not encrypted.
 
 Encryption
 ----------
-Transmitting unencrypted credentials or contents is a serious issue in many
+Transmitting unencrypted credentials or contents can cause serious issues in many
 scenarios.
 
-We recommend you make sure connections are encrypted, like with https or VPN
+We recommend you make sure the connections are encrypted, like with https or VPN
 or an ssh tunnel.
 
 For public wikis with very low security / privacy needs, it might not be needed
-to encrypt their content transmissions, but there is still an issue for the
+to encrypt the content transmissions, but there is still an issue for the
 credential transmissions.
 
 When using unencrypted connections, wiki users are advised to make sure they
-use unique credentials (== not reusing passwords that are also used for other
-stuff).
+use unique credentials and not reuse passwords that are used for other purposes.
 
 
 Password security
 Password strength
 -----------------
 As you might know, many users are bad at choosing reasonable passwords and some
-are tempted to use passwords like 123456 everywhere.
+are tempted to use easily crackable passwords.
 
-To help the users choose reasonable passwords, moin has a simple builtin
-password checker that does some sanity checks (the checker is enabled by
-default), so users don't choose too short or too easy passwords.
+To help users choose reasonable passwords, moin has a simple builtin
+password checker that is enabled by default and does some sanity checks, 
+so users don't choose easily crackable passwords.
 
-If you don't like this and your site has rather low security requirements,
-feel free to DISABLE the checker by::
+If your site has rather low security requirements, you can disable the checker by::
 
     password_checker = None # no password checking
 
 
 Password storage
 ----------------
-Moin never stores passwords in cleartext, but always as cryptographic hash
-with random salt (currently ssha256 is the default).
+Moin never stores passwords in clear text, but always as cryptographic hash
+with a random salt. Currently ssha256 is the default.
 
 
 Authorization
 a given action.
 
 Please note that wikis usually make much use of so-called *soft security*,
-which means that they are rather open and give freedom to users, while
-providing means to revert damage in case it happens.
+which means that they are rather open and give freedom to users, while at the same time
+providing the means to revert any damage that may have been caused.
 
 *Hard security* means that one would lock items, etc. so that no damage can possibly be done.
 
 Moin's default configuration tries to give a sane compromise of both soft
-and hard security. Depending on the situation the wiki
-admin/owner/community has to deal with, however, you may need different settings.
+and hard security. However, you may need different settings depending on the situation that the wiki
+admin, wiki owner or wiki community will have to deal with.
 
-So just keep in mind:
+So keep in mind::
 
-* if your wiki is rather open, you might make it easy to contribute (e.g. a
+* if your wiki is rather open, you might make it easy to contribute, e.g. a
   user who is not a regular user of your wiki could fix some typos he has just
-  found). However, a hostile user (or bot) might also put some spam into your wiki
-  (you'd be able to revert the spam later).
-* if your wiki is rather closed (e.g. you require every user to first apply for an
-  account and to log in before being able to do changes), you'll rarely get
+  found. However, a hostile user or bot might also put some spam into your wiki
+  with the ability to be able to revoke the spam later.
+* if your wiki is rather closed, e.g. you require every user to first apply for an
+  account and to log in before being able to do changes, you will rarely get
   contributions from casual users and maybe also less from members of your
-  community. But, it's likely you won't get spam either.
+  community. But, getting spam is then less likely.
  
 
 ACL for functions
 -----------------
 This ACL controls access to some specific functions / views of moin::
 
-    # we just show the default value of acl_rights_functions for information,
-    # you usually do not have to change it:
+    # the default value of acl_rights_functions for information, you usually do not have to change it:
     #acl_rights_functions = ['superuser', 'notextcha', ]
     acl_functions = u'+YourName:superuser TrustedEditorGroup:notextcha'
 
 
 ACLs for contents
 -----------------
-These ACLs control access to contents stored in the wiki - they are configured
+These ACLs control access to contents stored in the wiki, they are configured
 per storage backend (see storage backend docs) and optionally in the metadata of wiki
 items::
 
-    # we just show the default value of acl_rights_contents for information,
-    # you usually do not have to change it:
+    # the default value of acl_rights_contents for information, you usually do not have to change it:
     #acl_rights_contents = ['read', 'write', 'create', 'destroy', 'admin', ]
     ... backend configuration ...
     ... before=u'YourName:read,write,create,destroy,admin',
    "before" -> "item acl from metadata (if specified)" -> "after";
    "before" -> "default (otherwise)"                   -> "after";
 
-How to use before/default/after:
+How to use before/default/after::
 
-* `before` is usually used to force stuff (e.g. if you want to give some
-  wiki admin all permissions no matter what)
-* `default` is the behavior if nothing special has been specified (no ACL in
-  item metadata)
-* `after` is rarely used. When it is, it's used to "not forget something unless otherwise specified".
+* `before` is usually used to force something, for example if you want to give some
+  wiki admin all permissions indiscriminately
+* `default` is the behavior if nothing special has been specified, ie no ACL in the
+  item's metadata
+* `after` is rarely used and when it is, it is used to "not forget something unless otherwise specified".
 
 When configuring content ACLs, you can choose between standard (flat) ACL
 processing and hierarchic ACL processing. Hierarchic processing means that
-subitems inherit ACLs from their parent items if they don't have an ACL.
+subitems inherit ACLs from their parent items if they don't have an ACL themselves.
 
 Note that while hierarchic ACLs are rather convenient sometimes, they make the
-system more complex. You have to be very careful with potential permissions
-changes happening due to changes in the hierarchy, like when you create,
+system more complex. You have to be very careful with permission
+changes happening as a result of changes in the hierarchy, such as when you create,
 rename or delete items.
 
-Supported capabilities (rights):
+Supported capabilities (rights)::
 
 * read - read content
 * write - write (edit, modify) content
 * create - create new items
-* destroy - completely destroy revisions or items (give this only to *fully-trusted* users)
-* admin - change (create, remove) ACLs for the item (give this only to *fully-trusted* users)
+* destroy - completely destroy revisions or items; to be given only to *fully-trusted* users
+* admin - change (create, remove) ACLs for the item; to be given only to *fully-trusted* users
 
 ACLs - special groups
 ---------------------
 In addition to the groups provided by the group backend(s), there are some
-special group names available within ACLs:
+special group names available within ACLs::
 
 * All - a virtual group containing every user
 * Known - a virtual group containing every logged-in user
 
 An entry is a colon-separated set of two values::
 
-* the left side is a comma-separated list of user and/or group names and
+* the left side is a comma-separated list of user and/or group names
 * the right side is a comma-separated list of rights / capabilities for those users/groups.
 
 An ACL is processed from left to right, where the first left-side match counts.
 
     u"SuperMan:read,write,create,destroy,admin All:read,write"
 
-If "SuperMan" is currently logged in and moin processes this ACL, it'll find
+If "SuperMan" is currently logged in and moin processes this ACL, it will find
 a name match in the first entry. If moin wants to know whether he may destroy,
 the answer will be "yes", as destroy is one of the capabilities/rights listed
 on the right side of this entry.
 destroy is not listed on the right side of the "All" entry. If moin wants to know
 whether he may write, the answer will be "yes".
 
-Notes:
+Notes::
 
 * As a consequence of the left-to-right and first-match-counts processing,
   you must order ACL entries so that the more specific ones (like for
   "SuperMan") are left of the less specific ones.
-  Usually, you want this order:
+  Usually, you want this order::
 
   1) usernames
   2) special groups
 
 If you use one of the two, MoinMoin will search for both a username and permission, and a match will have to match
 both the name of user (left-side) *and* the permission MoinMoin is searching for (right-side), otherwise
-it will just continue with the next entry.
+it will continue with the next entry.
 
 '+' indicates that MoinMoin should give the permission(s) specified on the right side.
 
     u"+SuperMan:create,destroy,admin -Idiot:write All:read,write"
 
 If "SuperMan" is currently logged in and moin wants to know whether he may
-destroy, it'll find a match in the first entry (name matches *and* permission
-in question matches). As the prefix is '+', the answer is "yes".
+destroy, it'll find a match in the first entry, because the name matches *and* permission
+in question matches. As the prefix is '+', the answer is "yes".
 If moin wants to know whether he may write, the first entry will not match
 on both sides, so moin will proceed and look at the second entry. It doesn't
-match, so it'll look at the third entry. Of course "SuperMan" is a member of
+match, so it will look at the third entry. Of course "SuperMan" is a member of
 group "All", so we have a match here. As "write" is listed on the right side,
 the answer will be "yes".
 
 If "Idiot" is currently logged in and moin wants to know whether he may write,
-it'll find no match in the first entry, but the second entry will match. As
-the prefix is '-', the answer will be "no" (and it will not even proceed and
-look at the third entry).
+it will find no match in the first entry, but the second entry will match. As
+the prefix is '-', the answer will be "no" and it will not even proceed and
+look at the third entry.
 
-Notes:
+Notes::
 
 * you usually use these modifiers if most of the rights for a given user shall be specified
   later, but a special user or group should be treated slightly different for
 default ACL.
 
 This is useful, for example, if when you mostly want the default ACL, but
-with a slight modification - but you don't want to type in the default ACL
-all the time (and you also want to be able to change the default ACL without
-having to edit lots of items).
+with a slight modification, but you don't want to type in the default ACL
+all the time and you also want to be able to change the default ACL without
+having to edit lots of items.
 
 Example::
 
 A TextCHA is a pure text alternative to ''CAPTCHAs''. MoinMoin uses it to
 prevent wiki spamming and it has proven to be very effective.
 
-Features:
+Features::
 
 * when registering a user or saving an item, it can ask a random question
-* match the given answer against a regular expression
+* moin matches the given answer against a regular expression
 * questions and answers can be configured in the wiki config
-* multi language support: a user gets a textcha in his language or in
-  language_default or in English (depending on availability of questions and
-  answers for the language)
+* multi language support: a user gets a textcha in his language or in the
+  language_default or in English, depending on availability of questions and
+  answers for the language
 
 TextCha Configuration
 ~~~~~~~~~~~~~~~~~~~~~
 
-Tips for configuration:
+Tips for configuration::
 
 * have 1 word / 1 number answers
 * ask questions that normal users of your site are likely to be able to answer
 * do not ask overly obvious questions
 * do not share your questions with other sites / copy questions from other
   sites (or spammers might try to adapt to this) 
-* you should at least give textchas for 'en' (or for your language_default, if
-  that is not 'en') as this will be used as fallback if MoinMoin does not find
+* you should at least give textchas for 'en' or for your language_default, if
+  that is not 'en', as this will be used as fallback if MoinMoin does not find
   a textcha in the user's language
 
 In your wiki config, do something like this::
 
 Secrets
 =======
-Moin uses secrets (just use a long random string; *not* a reuse of any of your
-passwords) to encrypt or cryptographically sign some stuff like:
+Moin uses secrets to encrypt or cryptographically sign something like::
 
 * textchas
 * tickets
 
+Secrets are long random strings and *not* a reuse of any of your passwords.
 Don't use the strings shown below, they are NOT secret as they are part of the
-moin documentation - make up your own secrets::
+moin documentation. Make up your own secrets::
 
     secrets = {
         'security/textcha': 'kjenrfiefbeiaosx5ianxouanamYrnfeorf',
 Groups and Dicts
 ================
 Moin can get group and dictionary information from some supported backends
-(like the wiki configuration or wiki items).
+like the wiki configuration or wiki items.
 
-A group is just a list of unicode names. It can be used for any application:
+A group is a list of unicode names. It can be used for any application:
 one application is defining user groups for usage in ACLs.
 
 A dict is a mapping of unicode keys to unicode values. It can be used for any
 =======
 MoinMoin supports storage backends as different ways of storing wiki items.
 
-Setup of storage is rather complex and layered, involving:
+Setup of storage is rather complex and layered, involving::
 
 * a router middleware that dispatches parts of the namespace to the respective
   backend
   authorized to access
 * Indexing mixin that indexes some data automatically on commit, so items can
   be selected / retrieved faster.
-* storage backends that really store wiki items somewhere
+* storage backends that store wiki items
 
 create_simple_mapping
 ---------------------
-This is a helper function to make storage setup easier - it helps you:
+This is a helper function to make storage setup easier. It helps you to::
 
 * create a simple setup that uses 3 storage backends internally for these
   parts of the namespace:
 
   - content
   - userprofiles
-* to configure ACLs protecting these parts of the namespace
-* to setup a router middleware that dispatches to these parts of the namespace
-* to setup a indexing mixin that maintains an index
+* configure ACLs protecting these parts of the namespace
+* setup a router middleware that dispatches to these parts of the namespace
+* setup a indexing mixin that maintains an index
 
-Call it like::
+Call it as follows::
 
     from MoinMoin.storage import create_simple_mapping
 
                               after=..., ),
     )
 
-The `uri` depends on the kind of storage backend and stores you want to use
-(see below). Usually it is a URL-like string in the form of::
+The `uri` depends on the kind of storage backend and stores you want to use, 
+see below. Usually it is a URL-like string in the form of::
 
     stores:fs:/srv/mywiki/%(nsname)s/%(kind)s
     
 `stores` is the name of the backend, followed by a colon, followed by a store
 specification. `fs` is the name of the store, followed by a specification
-that makes sense for the fs (filesystem) store (i.e. a path with placeholders).
+that makes sense for the fs (filesystem) store, i.e. a path with placeholders.
 
 `%(nsname)s` placeholder will be replaced 'content' or 'userprofiles' for
 the respective backend. `%(kind)s` will be replaced by 'meta' or 'data'
 later.
 
-In this case, the mapping created will look like this:
+In this case, the mapping created will look like this::
 
 +----------------+-----------------------------+
 | Namespace part | Filesystem path for storage |
 
 protecting middleware
 ---------------------
-Features:
+Features::
 
 * protects access to lower storage layers by ACLs (Access Control Lists)
 * makes sure there won't be ACL security issues, even if upper layers have bugs
-* if you use create_simple_mapping, you just give the ACL parameters. The
+* if you use create_simple_mapping, you just give the ACL parameters; the
   middleware will be set up automatically by moin.
 
 routing middleware
 ------------------
-Features:
+Features::
 
 * dispatches storage access to different backends depending on the item name
-* in POSIX terms, it's something like fstab/mount
+* in POSIX terms, it is something like fstab/mount
 * if you use create_simple_mapping, the router middleware will be set up
   automatically by moin.
 
 indexing middleware
 -------------------
-Features:
+Features::
 
 * maintains an index for important metadata values
 * speeds up looking up / selecting items
 
 stores backend
 --------------
-This is a backend that ties together 2 stores (one for meta, one for data) to
-form a backend.
+This is a backend that ties together 2 stores to form a backend: one for meta, one for data
 
 fs store
 --------
-Features:
+Features::
 
 * stores into the filesystem
 * store metadata and data into separate files/directories
 
 sqla store
 ----------
-Features:
+Features::
 
 * stores data into an (SQL) database / table
-* can either use 1 database per store or 1 table per store (you need to
-  give different table names then)
+* can either use 1 database per store or 1 table per store and you need to
+  give different table names then
 * uses slqalchemy (without the ORM) for database abstraction
-* supports multiple types of databases. For example:
+* supports multiple types of databases, for example::
  
   - sqlite (default, comes built-into Python)
   - postgresql
   - mysql
-  - and others (see sqlalchemy docs).
+  - and others, see sqlalchemy docs.
 
 `uri` for `create_simple_mapping` looks like e.g.::
 
 
 sqlite store
 ------------
-Features:
+Features::
 
-* directly talks to sqlite, not using sqlalchemy
+* directly talks to sqlite, without using sqlalchemy
 * stores data into an sqlite database, which is a single file
-* can either use 1 database per store or 1 table per store (you need to
-  give different table names then)
-* can optionally compress/decompress the data using zlib (default compression
-  level is 0, which means to not compress)
+* can either use 1 database per store or 1 table per store and you need to
+  give different table names then
+* can optionally compress/decompress the data using zlib: default compression
+  level is 0, which means "do not compress"
  
 `uri` for `create_simple_mapping` looks like e.g.::
 
 
 kc store
 --------
-Features:
+Features::
 
 * uses a Kyoto Cabinet file for storage
 * very fast
 
 kt store
 --------
-Features:
+Features::
 
 * uses a Kyoto Tycoon server for storage
 * fast
 
 memory store
 --------------
-Features:
+Features::
 
 * keeps everything in RAM
-* definitely not for production use
+* if your system or the moin process crashes, all data is lost, so definitely not for production use
 * mostly intended for testing
-* if your system or the moin process crashes, you'll lose everything
 * single process only
 
 .. todo:
 
 fileserver backend
 ------------------
-Features:
+Features::
 
 * exposes a part of the filesystem as read-only wiki items
 
 
 Sending E-Mail
 --------------
-Moin can optionally send E-Mail. Possible uses:
+Moin can optionally send E-Mail. Possible uses::
 
 * send out item change notifications.
 * enable users to reset forgotten passwords
 Framework Configuration
 =======================
 
-Some stuff you may want to configure for Flask and its extensions (see
+Things you may want to configure for Flask and its extensions (see
 their docs for details)::
 
  # for Flask
 =====================
 
 By default, logging is configured to emit output on `stderr`. This will work
-well for the built-in server (it will just show up on the console) or for Apache2 and similar
+well for the built-in server (it will show up on the console) or for Apache2 and similar
 (logging will be put into error.log).
 
 Logging is very configurable and flexible due to the use of the `logging`
 module of the Python standard library.
 
-The configuration file format is described there:
+The configuration file format is described there::
 
 http://www.python.org/doc/current/library/logging.html#configuring-logging
 
 `docs/examples/config/logging/` directory.
 
 Logging configuration needs to be done very early, usually it will be done
-from your adaptor script (e.g. moin.wsgi)::
+from your adaptor script, e.g. moin.wsgi::
 
     from MoinMoin import log
     log.load_config('wiki/config/logging/logfile')
 You have to fix that path to use a logging configuration matching your
 needs.
 
-Please note that the logging configuration has to be a separate file (don't
-try this in your wiki configuration file)!
+Please note that the logging configuration has to be a separate file, so don't
+try this in your wiki configuration file!
 

File docs/admin/index.rst

View file
 General
 =======
 MoinMoin relies strongly on indexes that accelerate access to item metadata and
-data, and make it possible to have simple backends, because the index layer
+data, and makes it possible to have simple backends, because the index layer
 is doing all the hard and complex work.
 
 Indexes are used internally for many operations like item lookup, history,
-iterating over items, search (also for interactive searches), etc.
+iterating over items, search, interactive search, etc.
 
 MoinMoin won't be able to start with damaged, inaccessible or non-existing indexes.
-As a result, you'll need to configure and initialize indexing correctly first.
+As a result, you will need to configure and initialize indexing correctly first.
 
 moin will automatically update the index when items are created, updated, deleted,
-destroyed, or renamed (via the storage api of moin, indexing layer or above).
+destroyed, or renamed via the storage api of moin, indexing layer or above.
 
 Configuration
 =============
-Your wiki config needs ``index_dir`` to point to a writable directory - a fast,
+Your wiki config needs ``index_dir`` to point to a writable directory. A fast,
 local filesystem is preferred.
 Use something like::
 
 
 **Note:** the moin WSGI application needs an index to successfully start up.
 As the moin index-* script commands are also based on the moin WSGI application,
-this can lead to a chicken and the egg problem.
-
-To solve this, the moin command has a ``-i`` (``--index-create``) option that
-will trigger index creation on startup.
+this can lead to a chicken and egg problem. To solve this, the moin command has 
+a ``-i`` (``--index-create``) option that will trigger index creation on startup.
 
 Additionally, if the storage is also non-existent yet, one might also need
 ``-s`` (``--storage-create``) to create an empty storage on startup.
 * For big wikis, this can take rather long; consider using --tmp.
 * index-build does NOT clear the index at the beginning.
 * index-build does not check the current contents of the index. Therefore you must not run
-  index-build multiple times for the same data / same wiki.
+  index-build multiple times for the same data or the same wiki.
 
 moin index-update
 -----------------
 Compare an index to the current storage contents and update the index as
-needed (add, remove, update stuff) to reflect the current storage contents.
+needed (add, remove, update) to reflect the current storage contents.
 
 **Note:** You can use this after building at the tmp location to get
 the changes that happened to the wiki while building the index as well. You can run
     moin index-create --storage-create --index-create
     moin index-create -s -i  # same, but shorter
 
-Storage and index are now initialized (both empty).
+Storage and index are now initialized and both empty.
 
-If you add data to your wiki, the index will get updated on the fly.
+If you add data to your wiki, the index will get updated automatically.
 
 
 If your wiki has data and is shut down
 --------------------------------------
-If index needs a rebuild for some reason (e.g. index lost, index damaged,
-incompatible upgrade, etc.), use::
+If index needs a rebuild for some reason, e.g. index lost, index damaged,
+incompatible upgrade, etc., use::
 
     moin index-create -i
     moin index-build  # can take a while...
      moin index-create -i --tmp
      moin index-build --tmp  # can take a while...
      moin index-update --tmp  # should be quicker, make sure we have 99.x%
-     # better shut down the wiki now (or at least make sure it is not changed)
-     moin index-update --tmp  # make sure we have indexed ALL content - should be even quicker.
+     # better shut down the wiki now or at least make sure it is not changed
+     moin index-update --tmp  # make sure we have indexed all content, should be even quicker.
      moin index-move  # instantaneously
-     # start the wiki again (or allow changes now again)
+     # start the wiki again or allow changes now again
 
 **Note:** Indexing puts load onto your server, so if you like to do regular
 index rebuilds, schedule them at some time when your server is not too busy.
 =================================
 If you run a wiki farm (multiple related wikis), you may share the index
 between the wikis, so users will be able to search in one wiki
-and also see results from the others.
+and also see results from the other wikis.
 
-Before you start, you must prepare your wiki configs.
-
-For example, imagine a company that uses 2 "farm" wikis: ``Sales``, ``Engineering``
-
-Their respective wiki configs would look like:
+Before you start, you must prepare your wiki configs. For example, for a company 
+that uses two wiki farms, such as ``Sales`` and ``Engineering``, Their respective 
+wiki configs could look like:
 
 ``Sales``::
 
 Now do the initial index building::
 
      moin index-create -i  # create an empty index
-     # now ADD stuff from all your wikis:
+     # now add the indexes from both other wikis:
      moin index-build  # with Sales wiki configuration
      moin index-build  # with Engineering wiki configuration
 
-Now you should have a shared index for all these wikis.
+Now you should have a shared index for all wikis.
 
 **Note:** Do not build indexes for multiple wikis in parallel. This is not
 supported.

File docs/admin/install.rst

View file
 ===========
 For moin2, there is currently no packaged download available, so you have to get
 it from the repository.
-You can use one of two repository URLs (there is little difference between them),
-and either use Mercurial to keep a constantly updated copy of the code or download an archive of the files in tar.gz format:
+You can use one of two repository URLs and either use Mercurial to keep a 
+constantly updated copy of the code or download an archive of the files in tar.gz format:
 
-Using Mercurial to clone one of our repos::
+Using Mercurial to clone one of the repositories::
 
  hg clone http://hg.moinmo.in/moin/2.0 moin-2.0
  OR
  hg clone http://bitbucket.org/thomaswaldmann/moin-2.0 moin-2.0
 
-Now make sure your work dir is using the default branch::
+Now make sure your work directory is using the default branch::
 
  hg up -C default
 
 -----------------
 Using your standard Python install or a virtualenv directory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Please make sure you have `virtualenv` installed (it includes `pip`).
+Please make sure you have `virtualenv` installed, it includes `pip`.
 
 If you just want to run moin in-place in your mercurial working directory
 with your normal system installation of Python, run the following command
-from your mercurial moin2 working directory (you should not run this as an
-administrator/root user; use your standard user account)::
+from your mercurial moin2 working directory. You should not run this as an
+administrator or root user; use your standard user account::
 
- ./quickinstall  # for Linux (or other posix OS's)
+ ./quickinstall  # for Linux or other POSIX OSes
  # or
- quickinstall.bat  # for windows
+ quickinstall.bat  # for Windows
 
 This will use virtualenv to create a directory `env/` within the current directory,
 create a virtual environment for MoinMoin and then install moin2 including all dependencies into that directory.
 Further, the quickinstall script will create a `moin` script for your
 platform which you can use for starting the built-in server or invoke moin script commands.
 
-After you activated the virtual environment, the built-in server script (named `moin`) will be in the standard PATH,
-so you can just run the command `moin` verbatim on the command line.
+After you activated the virtual environment, the built-in server script, which is named 
+`moin`, will be in the standard PATH, so you can just run the command `moin` on the command line.
 
-Note: in this special mode, it won’t copy the MoinMoin code to the env/ directory,
-it will run everything from your work dir, so you can modify code and directly try it out
-(you only need to do this installation procedure once).
+**Note:** in this special mode, it won't copy the MoinMoin code to the env/ directory,
+it will run everything from your work dir, so you can modify code and directly try it out.
+You only need to do this installation procedure once.
 
 Using a different Python or a different virtualenv directory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  env\Scripts\activate.bat  # for windows
 
 As you have activated the virtual env now, the moin command should be in your
-path now, so you can just invoke it using "moin".
+path now, so you can invoke it using "moin".
 
 Letting moin find the wiki configuration
 ----------------------------------------
 
 moin needs to find the wiki configuration. If you want it to run in the most
-simple way (without giving parameters to the moin command), it is easiest if
-you are in the same directory as the configuration files (e.g. wikiconfig.py).
+simple way without giving parameters to the moin command, it is easiest if
+you are in the same directory as the configuration files, e.g. wikiconfig.py.
 
-If you are working from a repository workdir, this is just the top level
+If you are working from a repository workdir, this is the top level
 directory and there is already a ready-to-use wikiconfig.py.
 
 In case you want to just give the configuration file location, make sure you
 
 Initializing index and/or storage
 ---------------------------------
-If you have an existing storage AND a valid index (for this storage’s content, and for this moin version),
+If you have an existing storage AND a valid index (for this storage’s content and for this moin version),
 you can skip this section.
 
-If you start from scratch (no storage created yet, and no index created yet),
-you need to create an (empty) storage and an (empty) index::
+If you start from scratch, ie no storage and no index created yet,
+you need to create an empty storage and an empty index::
 
  # create storage and index:
  moin index-create -s -i
 
 Installing PIL
 ~~~~~~~~~~~~~~
-For some image processing functions that MoinMoin uses (like resizing, rotating),
-you need PIL (Python Imaging Library).
+For some image processing functions that MoinMoin uses like resizing and rotating,
+you need PIL, which is the Python Imaging Library.
 
 Windows users who want to install PIL should skip the remainder of this section and read
 Troubleshooting -- PIL Installation Under Windows below.
 
-If you install PIL with pip, pip will try to find a jpeg support library and associated development
-headers on your system and if you do not have that, there will be no jpeg support in PIL.
+If you install PIL with pip, then pip will try to find a jpeg support library and associated development
+headers on your system and if you do not have them, there will be no jpeg support in PIL.
 So, if you want jpeg support, make sure you have the jpeg libs/headers::
 
  # install jpeg library and development headers:
 
 Now activate your virtual environment and install PIL into it::
 
- pip install pil # for linux (or other posix OSes)
+ pip install pil # for Linux or other POSIX OSes
 
 Troubleshooting
 ---------------
 Now and then, PyPi might be down or unreachable.
 
 There are mirrors b.pypi.python.org, c.pypi.python.org, d.pypi.python.org
-you can use in such cases, you just need to tell pip to do so::
+you can use in such cases. You just need to tell pip to do so::
 
  # put this into ~/.pip/pip.conf
  [global]
 ~~~~~~~~~~~~~~~~~~~~~~
 If you have a poor or limited network connection, you may run into trouble with the commands issued by
 the quickinstall script.
-You may see tracebacks from pip, timeout errors, etc. (see the output of the quickinstall script).
+You may see tracebacks from pip, timeout errors, etc. See the output of the quickinstall script.
 
 If this is the case, try it manually::
 
  # confirm the problems by running:
  pip install -e .
 
-Now install each package into your virtual env manually:
+Now install each package into your virtual env manually::
 
 * Find the required packages by looking at "install_requires" within `setup.py`.
 * Download each required package from http://pypi.python.org/
-* Install each of them individually by::
+* Install each of them individually::
 
     pip install package.tar
 
 PIL Installation Under Windows
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 PIL version 1.1.7 does not install correctly via "pip install pil" on Windows.
-Some users have had success using "pip install pillow" (a fork of PIL fixing
-a packaging issue).  Other users have resorted to installing PIL 1.1.6 in the
+Some users have had success using "pip install pillow", a fork of PIL fixing
+a packaging issue. Other users have resorted to installing PIL 1.1.6 in the
 main Python directory using the Windows installers available at
 http://www.pythonware.com/products/pil/
 

File docs/admin/requirements.rst

View file
 
 For dependency information, please see setup.py.
 
-If you use easy_install or pip (or our ``quickinstall`` script),
+If you use easy_install or pip or our ``quickinstall`` script, then
 dependencies are usually automatically dealt with.
 

File docs/admin/serve.rst

View file
 
 Built-in Web Server (easy)
 ==========================
-Moin comes with a simple built-in web server (powered by Werkzeug), which
+Moin comes with a simple built-in web server powered by Werkzeug, which
 is suitable for development, debugging, and personal and small group wikis.
 
 It is *not* made for serving bigger loads, but it is easy to use.
 
 Please note that by default the built-in server uses port 8080. As this is
 above port 1024, root (Administrator) privileges are not required and we strongly
-recommend that you use a normal (unprivileged) user account instead. If you
-are running a desktop wiki or doing moin development, just use your normal
+recommend that you use a normal, unprivileged user account instead. If you
+are running a desktop wiki or doing moin development, then use your normal
 login user.
 
 Running the built-in server
 ---------------------------
-Then you can run the moin built-in server by::
+Run the moin built-in server as follows::
 
  # easiest for debugging (single-process, single-threaded server):
  moin
 
 External Web Server (advanced)
 ==============================
-We won't go into details about this, because every web server software is
-different and has its own documentation (please read it). Also, in general,
+We won't go into details about using moin under an external web server, because every web server software is
+different and has its own documentation, so please read the documentation that comes with it. Also, in general,
 server administration requires advanced experience with the operating system,
 permissions management, dealing with security, the server software, etc.
 
  from MoinMoin.app import create_app
  application = create_app('/path/to/config/wikiconfig.py')
 
-MoinMoin is a Flask application (Flask is a micro framework for WSGI apps),
-so we recommend you just read Flask's good deployment documentation.
+MoinMoin is a Flask application, which is a micro framework for WSGI applications,
+so we recommend you read Flask's good deployment documentation.
 
-Make sure you use `create_app()` as shown above to create the
-application (you can't just import the application from MoinMoin).
+Make sure you use `create_app()` as shown above to create the application, 
+because you can't import the application from MoinMoin.
 
 Continue reading here: http://flask.pocoo.org/docs/deploying/
 
 
 When the test app starts doing something other than Server Error 500, please
 proceed with the MoinMoin app and its configuration.
-Otherwise, read your web server error log files.
+Otherwise, read your web server error log files to troubleshoot the issue from there.
 

File docs/admin/upgrade.rst

View file
    moin 2.0 is *not* just a +0.1 step from 1.9 (like 1.8 -> 1.9), but the
    change of the major version number is indicating *major and incompatible changes*.
 
-   So please consider it to be a different and incompatible piece of software that tries
+   So please consider it to be different and incompatible software that tries
    to be compatible in some areas:
 
    * Server and wiki engine Configuration: expect to review/rewrite it
 
 From moin < 1.9
 ===============
-As MoinMoin 1.9.x has been out there for quite a while, we only describe how
-to upgrade from moin 1.9.x to moin2. If you still run an older moin
-version than 1.9, please first upgrade to moin 1.9.x. You may want to run 1.9.x for a
-while, so you can be sure everything is working as expected.
+If you run an older moin version than 1.9, please first upgrade to moin 1.9.x
+before upgrading to moin2. 
+You may want to run 1.9.x for a while to be sure everything is working as expected.
 
 Note: Both moin 1.9.x and moin2 are WSGI applications.
 Upgrading to 1.9 first also makes sense concerning the WSGI / server side.
 Backup
 ------
 Have a backup of everything, so you can go back in case it doesn't do what
-you expect. If you have a 2nd machine, it is a good idea to try it there
-first (and not directly modify your production machine).
+you expect. If you have a testing machine, it is a good idea to try it there
+first and not directly modify your production machine.
 
 
 Install moin2
 -------------
-Install and roughly configure moin2, make it work, and start configuring it from
-the moin2 sample config (do *not* just use your 1.9 wikiconfig).
+Install and configure moin2, make it work, and start configuring it from
+the moin2 sample config. Do *not* just use your 1.9 wikiconfig.
 
 
 Adjusting the moin2 configuration
 ---------------------------
 It is a good idea to clean up your 1.9 data first, before trying to import
 it into moin2. In doing so you can avoid quite some
-warnings that the importer would otherwise produce.
+warnings that the moin2 importer would produce.
 
-You do this with moin *1.9* (!), using these commands::
+You do this with moin *1.9*, using these commands::
 
   moin ... maint cleanpage
   moin ... maint cleancache
 
 Importing your moin 1.9 data
 ----------------------------
-It is assumed that you have no moin2 storage and no index created yet.
-Thus, we include -s and -i options to create the storage and an empty index.
+Assuming you have no moin2 storage and no index created yet, include the 
+-s and -i options to create the storage and an index.
 
 The import19 argument to the `moin` script will then read your 1.9 data_dir (pages, attachments and users),
-convert the data as needed, and write it to your moin2 storage (and also
-build the index)::
+convert the data as needed, and write it to your moin2 storage and also
+build the index::
 
   moin import19 -s -i --data_dir /your/moin/1.9/data 1>import1.log 2>import2.log
 
-If you use the command as given, it will write all output into 2 log files.
+If you use the command as given, it will write all output into two log files.
 Please review them to find out whether the importer had critical issues with your
 data.
 
 
 Testing
 -------
-Just start moin now, as it should have your data available.
+Start moin now, as it should have your data available.
 
-Try "Index" and "History" views to see what's there.
+Try "Index" and "History" views to see what is included.
 
-Check whether your data is complete and working OK.
+Check whether your data is complete and working fine.
 
 If you find issues with data migration from moin 1.9 to 2, please check the
 moin2 issue tracker.
 
 Keep your backups
 -----------------
-Make sure you keep all backups of your moin 1.9 installation (code, config,
-data), just in case you are not happy with moin2 and need to go back for
-some reason.
+Make sure you keep all backups of your moin 1.9 installation, such as code, config,
+data, just in case you are not happy with moin2 and need to revert to the old version.
 

File docs/conf.py

View file
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('..'))
 
+
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
     ('index', 'moinmoin', u'MoinMoin Documentation', [u'The MoinMoin developers'], 1),
 ]
 
+
 # -- Options for Texinfo output ------------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples

File docs/devel/development.rst

View file
 
 Project Organisation
 ====================
-We mainly use IRC and the wiki for communication, documentation and
-planning.
+We mainly use IRC and the wiki for communication, documentation and planning.
 
-IRC channels (on chat.freenode.net):
+IRC channels on chat.freenode.net::
 
 * #moin-dev (core development topics)
 * #moin (user support, extensions)
 
-Wikis:
+Wikis::
 
 * http://moinmo.in/
 
-Documentation:
+Documentation::
 
 * http://readthedocs.org/docs/moin-20/en/latest/
 
-Issue tracker:
+Issue tracker::
 
 * http://bitbucket.org/thomaswaldmann/moin-2.0/issues
 
-Code Repositories:
+Code Repositories::
 
-* http://hg.moinmo.in/moin/2.0 (main repository)
-* http://bitbucket.org/thomaswaldmann/moin-2.0 (bb mirror for your
-  convenience, simplifying forking and contributing)
+* http://hg.moinmo.in/moin/2.0 - main repository
+* http://bitbucket.org/thomaswaldmann/moin-2.0 - bitbucket mirror for your
+  convenience, simplifying forking and contributing
 
-We use Mercurial DVCS (hg) for distributed version control.
+We use Mercurial DVCS and mercurial for distributed version control.
 
-If you are not using Mercurial, you can of course also just send us patches.
+If you are not using Mercurial, you can still submit patches.
 In that case, open an issue in the issue tracker and attach the patch there.
 
-Code review:
+Code review::
 
 Please use http://codereview.appspot.com/ for getting feedback on moin-related
-code (especially if you want to contribute or publish that code).
+code, especially if you want to contribute or publish that code.
 
-If you are using a local mercurial repository/workdir you can very easily
-upload your uncommitted workdir state to codereview (using their "upload.py").
+If you are using a local mercurial repository/workdir, you can very easily
+upload your uncommitted workdir state to codereview using their "upload.py".
 
-Then just ask on the IRC channel for review (give the codereview URL).
+Then just ask on the IRC channel for review and provide the codereview URL.
 
 MoinMoin architecture
 =====================
-moin2 is a WSGI application and uses:
+moin2 is a WSGI application and uses::
 
 * flask as framework
 
-  - flask-script for commandline scripts
+  - flask-script for command line scripts
   - flask-babel / babel / pytz for i18n/l10n
   - flask-themes for theme switching
   - flask-cache as cache storage abstraction
-* werkzeug for lowlevel web/http stuff, debugging, builtin server, etc.
-* jinja2 for templating (theme, user interface)
+* werkzeug for low level web/http page serving, debugging, builtin server, etc.
+* jinja2 for templating, such as the theme and user interface
 * flatland for form data processing
-* EmeraldTree for xml / tree processing
+* EmeraldTree for xml and tree processing
 * blinker for signalling
 * pygments for syntax highlighting
-* for stores: filesystem, sqlite3, sqlalchemy, kyoto cabinet/tycoon, ...
+* for stores: filesystem, sqlite3, sqlalchemy, kyoto cabinet/tycoon, memory
 * jquery javascript lib
-* CKeditor - GUI editor for (x)html
+* CKeditor, the GUI editor for (x)html
 * TWikiDraw, AnyWikiDraw, svgdraw drawing tools
 
 .. todo::
 
 How MoinMoin works
 ==================
-This is just a very high level overview about how moin works. If you would like
-to acquire a more in-depth understanding, try reading more docs and code.
+This is a very high level overview about how moin works. If you would like
+to acquire a more in-depth understanding, please read the other docs and code.
 
 WSGI application creation
 -------------------------
-First, the moin Flask application is created (see `MoinMoin.app.create_app`) -
-this will:
+First, the moin Flask application is created; see `MoinMoin.app.create_app`::
 
 * load the configuration (app.cfg)
 * register some modules that handle different parts of the functionality
 
-  - MoinMoin.apps.frontend - most stuff a normal user uses
-  - MoinMoin.apps.admin - some stuff for admins
-  - MoinMoin.apps.feed - feeds (e.g. atom)
-  - MoinMoin.apps.serve - serving some configurable static 3rd party stuff
+  - MoinMoin.apps.frontend - most of what a normal user uses
+  - MoinMoin.apps.admin - for admins
+  - MoinMoin.apps.feed - feeds, e.g. atom
+  - MoinMoin.apps.serve - serving some configurable static third party code
 * register before/after request handlers
 * initialize the cache (app.cache)
 * initialize index and storage (app.storage)
 
 Request processing
 ------------------
-Let's look at how it shows a wiki item:
+Let's look at how it shows a wiki item::
 
 * the Flask app receives a GET request for /WikiItem
 * Flask's routing rules determine that this request should be served by
   `MoinMoin.apps.frontend.show_item`.
-* Flask calls the before request handler of this module, which:
+* Flask calls the before request handler of this module, which::
 
-  - sets up the user as flaskg.user (anon user or logged in user)
+  - sets up the user as flaskg.user - an anonymous user or logged in user
   - initializes dicts/groups as flaskg.dicts, flaskg.groups
-  - initializes jinja2 environment (templating)
+  - initializes jinja2 environment - templating
 * Flask then calls the handler function `MoinMoin.apps.frontend.show_item`,
-  which
+  which::
 
   - creates an in-memory Item
 
     + by fetching the item of name "WikiItem" from storage
-    + it looks at the mimetype of this item (stored in metadata)
-    + it creates an appropriately typed Item instance (depending on the mimetype)
+    + it looks at the mimetype of this item, which is stored in the metadata
+    + it creates an appropriately typed Item instance, depending on the mimetype
   - calls Item._render_data() to determine what the rendered item looks like
     as HTML
-  - renders the `show_item.html` template (and gives it the rendered item html)
+  - renders the `show_item.html` template and returns the rendered item html
   - returns the result to Flask
 * Flask calls the after request handler which does some cleanup
 * Flask returns an appropriate response to the server
 
 Storage
 -------
-Moin supports different stores (like storing directly into files /
-directories, using key/value stores, using an SQL database, etc. - see
-`MoinMoin.storage.stores`). A store is extremly simple: just store a value
+Moin supports different stores, like storing directly into files /
+directories, using key/value stores, using an SQL database etc, see
+`MoinMoin.storage.stores`. A store is extremely simple: store a value
 for a key and retrieve the value using the key + iteration over keys.
 
 A backend is one layer above. It deals with objects that have metadata and
-data (see `MoinMoin.storage.backends`) - still very simple stuff.
+data, see `MoinMoin.storage.backends`.
 
-Above that, there is miscellaneous stuff in `MoinMoin.storage.middleware` for:
+Above that, there is miscellaneous functionality in `MoinMoin.storage.middleware` for::
 
-* routing by name to some specific backend (like fstab / mount)
+* routing by name to some specific backend, like fstab / mount
 * indexing metadata and data + comfortable and fast index-based access,
   selection and search
-* protecting stuff by ACLs (access control lists)
+* protecting content by ACLs (Access Control Lists)
 
 DOM based transformations
 -------------------------
-But how does moin know what the HTML rendering of an item looks like?
+How does moin know what the HTML rendering of an item looks like?
 
-Each Item has some mimetype (stored in metadata) - the input mimetype.
-We also know what we want as output - the output mimetype.
+Each Item has some mimetype that is stored in the metadata, also called the input mimetype.
+We also know what we want as output, also called the output mimetype.
 
 Moin uses converters to transform the input data into the output data in
 multiple steps. It also has a registry that knows all converters and their supported
 input and output mimetypes.
 
 For example, if the mimetype is `text/x-moin-wiki`, it will find that the input
-converter handling this is the one defined in `converter.moinwiki_in`. It then
+converter handling, this is the one defined in `converter.moinwiki_in`. It then
 feeds the data of this item into this converter. The converter parses this
 input and creates an in-memory `dom tree` representation from it.
 
-This dom tree is then transformed through multiple dom-to-dom converters for
-e.g.:
+This dom tree is then transformed through multiple dom-to-dom converters for example::
 
 * link processing
 * include processing
 * macros
 
 Finally, the dom-tree will reach the output converter, which will transform it
-into the desired output format, e.g. `text/html`.
+into the desired output format, such as `text/html`.
 
 This is just one example of a supported transformation. There are quite a few 
 converters in `MoinMoin.converter` supporting different input formats,
 Templates and Themes
 --------------------
 Moin uses jinja2 as its templating engine and Flask-Themes as a flask extension to
-support multiple themes (each theme has static data like css and templates).
+support multiple themes, each theme has static data like css and templates.
 
 When rendering a template, the template is expanded within an environment of
-values it can use. In addition to this (general) environment, parameters can
+values it can use. In addition to this general environment, parameters can
 also be given directly to the render call.
 
 Testing
 =======
 
-We use py.test for automated testing (it is currently automatically installed
-into your virtualenv as a dependency).
+We use py.test for automated testing. It is currently automatically installed
+into your virtualenv as a dependency.
 
 Running the tests
 -----------------
 To run the tests, activate your virtual env and invoke py.test from the
 toplevel directory::
 
-    py.test  # runs all tests
-    py.test -rs  # runs all tests and outputs infos about skipped tests
-    py.test -k somekeyword  # just run the tests matching somekeyword
-    py.test sometests.py  # just run the tests contained in sometests.py
+    py.test  # run all tests
+    py.test -rs  # run all tests and outputs information about skipped tests
+    py.test -k somekeyword  # run the tests matching somekeyword only
+    py.test sometests.py  # run the tests contained in sometests.py
 
 Tests output
 ------------
     F test failed
     x test was expected to fail (xfail)
 
-If something went wrong, you'll also see some traceback and stdout/stderr.
+If something went wrong, you will also see some traceback and stdout/stderr.
 
 Writing tests
 -------------
-Writing tests with `py.test` is easy and has little overhead. You basically just
-use `assert` statements.
+Writing tests with `py.test` is easy and has little overhead. Just
+use the `assert` statements.
 
-For more information, please read http://pytest.org/ - but keep in
+For more information, please read http://pytest.org/, but keep in
 mind that we currently still use **py.test 1.3.4**.
 
 Documentation
 =============
-We use Sphinx (see http://sphinx.pocoo.org/) and reST markup for documenting
+Sphinx (http://sphinx.pocoo.org/) and reST markup are used for documenting
 moin. Documentation reST source code, example files and some other text files
 are located in the `docs/` directory in the source tree.
 

File docs/devel/support.rst

View file
 
 Free Support
 ------------
-You can get free support and informations there:
+You can get free support and information here:
 * on our chat channels, see http://moinmo.in/MoinMoinChat
 * on our wiki, see http://moinmo.in/ - please note that quite a lot of content
   there is about moin 1.x and does not apply to moin2. One page has a lot
 Commercial Support
 ------------------
 As MoinMoin 2.0 is not released yet, there is no support for production
-systems based on it (we do not recommend that and do not support that).
+systems based on it.
 
 If you want to talk about development topics, please contact the developers.
 
 
 Found a bug?
 ------------
-* File a bug report on the issue tracker (on bitbucket).
-* Even better: fix the bug, file a bug report and submit a patch (consider
-  adding a unit test)
+* File a bug report on the issue tracker on bitbucket.
+* Even better: fix the bug, file a bug report and submit a patch and consider
+  adding a unit test
 
 Have an idea?
 -------------
-* Discuss it on IRC and file a feature request (on bitbucket).
-* Even better: discuss + write some Python code implementing it.
+* Discuss it on IRC and file a feature request on bitbucket.
+* Even better: discuss and write some Python code implementing it.
 
 Born to code?
 -------------
-* Help to work on moin2 core, so it gets finished faster.
-* Help maintaining moin 1.9 until moin2 is ready.
+* Help to work on moin2 core, so it gets released sooner.
+* Help to maintain moin 1.9 until moin2 is ready.
 
 Loving UI / UX design?
 ----------------------
-* Help us making moin2 look and feel better!
+* Help us make moin2 look and feel better!
 
 Have good language or documentation skills?
 -------------------------------------------

File docs/devel/translate.rst

View file
 
 To find out if someone has already started a translation of moin2 into your
 language; check the folder MoinMoin/translations in the source tree.
-If there is a folder with your language code (locale) [#]_, you can just
+If there is a folder with your language code (locale) [#]_, you can 
 start with the steps below. If not, please take a look at `If your
 language doesn't exist yet`_.
 
 3. Open the file ``MoinMoin/translations/<locale>/LC_MESSAGES/messages.po``
    and do your translation. A short explanation of this process follows:
    
-   * find an entry, with an empty or bad translated text (the text after
-     msgstr) and do your changes.
+   * Find an entry with an empty or bad translated text, the text after
+     msgstr, and apply your changes.
    
-   * **never** edit the 'msgid' string, just edit the 'msgstr' field
+   * **never** edit the 'msgid' string, and only edit the 'msgstr' field
    
-   * Variables like ``%(name)x`` (x can be any character) must be kept as
+   * Variables like ``%(name)x``, where x is any character, must be kept as
      they are. They must occur in the translated text.
    
    * For better readability you can divide a text-string over more than
-     one lines, by "surrounding" each line with double quotes (").
+     one line, by "surrounding" each line with double quotes (").
      It is a usual convention to have a maximal line-length of 80
      characters.
    
      translator.
      
      An important flag is "fuzzy". It shows that the msgstr string might
-     not be a correct translation (anymore). Only the translator can
+     not be a correct translation. Only the translator can
      judge if the translation requires further modification, or is
-     acceptable as is. Once satisfied with the translation, he/she then
+     acceptable as it is. Once satisfied with the translation, he/she then
      removes this fuzzy attribute.
-     
-     
 
 4. Save the messages.po file and execute::
 
 
 Guidelines for translators
 ``````````````````````````
-In languages where a separate polite form of address exists (like the
-German "Sie"/"Du") always use the polite form.
+In languages where a separate polite form of address exists, like the
+German "Sie"/"Du", always use the polite form.
 
    
 If your language doesn't exist yet
 
        python setup.py init_catalog -l <locale>
    
-2. Adjust the ``MoinMoin/translations/<locale>/LC_MESSAGES/messages.po`` .
+2. Adjust the ``MoinMoin/translations/<locale>/LC_MESSAGES/messages.po``.
 
    Follow the instructions in `First steps with a new *.po file`_ and
    then you can remove the fuzzy flag, which prevents the file from
    being compiled.
 
-3. Follow the steps above (`If your language already exists`_).
+3. Follow the steps above, see `If your language already exists`_.
 
 First steps with a new ``*.po`` file
 ````````````````````````````````````
 
-A newly created translation needs a few initial preparations.
+A newly created translation needs a few initial preparations::
 
 * replace "``PROJECT``" with "``MoinMoin 2``"
 
 * replace "``FIRST AUTHOR <EMAIL@ADDRESS>``" with the appropriate information
-  about you
+  about yourself
 
 * replace "``PROJECT VERSION``" in the head msgstr with
-  "``MoinMoin 2.0``" (or newer if neccessary)
+  "``MoinMoin 2.0``" or newer if neccessary
   
 * change the value of "``Last-Translator``" to your data
 
 
 If the translatable string contains a variable plural, that means
 the string contains an object which you don't know the exact quantity
-of at the time of writing the code, then you will have to use
+of, then you will have to use
 ``ngettext()``. Note that this is not only needed for the decision
 between one and more objects, because other languages have other
-(and more difficult) plurals than English. The usage is
+and more difficult plurals than English. The usage is
 ``ngettext(singular, plural, num, **variables)``. ``**variables``
-enables you to use the newstyle form just as explained above.
+enables you to use the newstyle form as explained above.
 
 For example:
 ``ngettext("%(number)d file removed from %(directory)s", "%(number)d files removed from %(directory)s", num=n, number=n, directory=directory)``
 
-``n`` has to appear twice because the first gives ngettext information
+``n`` has to appear twice because the first gives ngettext() information
 about the exact number and the second is the variable for the format
 string replacement.
 
-If you made changes to any gettext string, please update the .pot file
+If you made changes to any gettext() string, please update the .pot file
 using::
 
     python setup.py extract_messages
 
-Because this sometimes creates large diffs, just because of a slight
+Because this sometimes creates large diffs, just because of a
 change in line numbers, you can of course use this command sparingly.
-Another option (for better readability) is to do a separate commit
+Another option for better readability is to do a separate commit