diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 39e47f5b0..d85ae76d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,16 +2,16 @@ Thank you for your interest in contributing to MoinMoin! We welcome contributions and appreciate your support in improving this project. This guide outlines how -you can contribute, whether through bug reports, code contributions or help with +you can contribute, whether through bug reports, code contributions, or help with documentation. -## How to contribute +## How to Contribute -Find out how you can start reporting bugs, fixing bugs, adding new features or +Find out how you can start reporting bugs, fixing bugs, adding new features, or improving the documentation. -### Reporting bugs +### Reporting Bugs If you've encountered a bug, please report it by following these steps: @@ -20,9 +20,9 @@ If you've encountered a bug, please report it by following these steps: 3. Provide as much detail as possible, including: - A description of the bug - Steps to reproduce the issue - - Any relevant logs or error messages + - Any relevant logs or error messages. -### Suggesting enhancements +### Suggesting Enhancements If you have an idea for a new feature or improvement: @@ -30,11 +30,11 @@ If you have an idea for a new feature or improvement: 2. Open a new issue with a detailed description of the suggested enhancement. 3. Include a rough idea of how the enhancement could be implemented if possible. -### Submitting code or documentation enhancements +### Submitting Code or Documentation Enhancements To submit code or documentation updates, follow these steps: - * Setup your development environment, see next chapter. + * Set up your development environment; see the next chapter. * Create a new branch for your changes: ``` git checkout -b feature-branch @@ -51,17 +51,17 @@ To submit code or documentation updates, follow these steps: We encourage you to split complex changes into smaller, focused pull requests. This makes it easier to review and merge your contributions. -## Development setup +## Development Setup To begin contributing, you need to set up your development environment. Follow the steps below to get started: - * Fork the main moin repository from GitHub - * Clone your repo to your local development system - * Create a virtualenv and download Python packages - * Activate the virtualenv - * Create a wiki instance with help data and a welcome page - * Start the built-in server + * Fork the main Moin repository on GitHub. + * Clone your fork (repository) to your local development system. + * Create a virtual environment and install the required Python packages. + * Activate the virtual environment. + * Create a wiki instance with help data and a welcome page. + * Start the built-in server. For details on setting up your environment, please refer to the MoinMoin development documentation at @@ -70,8 +70,8 @@ development documentation at ## Code Style and Best Practices -MoinMoin follows some common coding standards to ensure the consistency of the -code base. Here are some major things to keep in mind: +MoinMoin follows common coding standards to ensure the consistency of the +codebase. Here are some major things to keep in mind: * Python Version: MoinMoin is based on Python 3. Make sure your changes work with the versions specified in pyproject.toml. @@ -81,8 +81,8 @@ code base. Here are some major things to keep in mind: * Documentation: Ensure that your changes are well-documented. Add docstrings to your functions and classes where appropriate. -We have added Git pre-commit hooks to ensure a consistent code quality. -The checks include the use of the tools black, ruff and bandit. For details please see +We use Git pre-commit hooks to help ensure consistent code quality. +The checks include the tools Black, Ruff, and Bandit. For details, please see [moin-20.readthedocs.io](https://moin-20.readthedocs.io/en/latest/devel/development.html#install-pre-commit-hooks) diff --git a/README.md b/README.md index d2d0caa2b..3dd651070 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,53 @@ -MoinMoin - a lightweight open source wiki engine +MoinMoin — a lightweight open-source wiki engine ================================================ MoinMoin Logo -MoinMoin is an easy to use, full-featured and extensible wiki software package +MoinMoin is an easy-to-use, full-featured, and extensible wiki software package written in Python. You can run it on all common operating systems (Windows, macOS, Linux, etc.). This wiki software can fulfill a wide range of roles, such as a personal notes organizer deployed on a laptop or home web server, a company knowledge base deployed on an intranet, or an Internet server open to individuals sharing the -same interests, goals or projects. +same interests, goals, or projects. Documentation and Support ========================= > [!NOTE] - moin2 is not released yet. +> Moin2 is not released yet. -You will find the latest docs at https://moin-20.readthedocs.io/en/latest. +You will find the latest documentation at https://moin-20.readthedocs.io/en/latest. -There is a wiki page collecting all moin2 specific information, links to -support resources and info about MoinMoin development status and plans: +There is a wiki page collecting all Moin2-specific information, links to +support resources, and information about MoinMoin’s development status and plans: https://moinmo.in/MoinMoin2.0 -In general, you should make sure that the documentation you are reading -is written for the moin version you are using. Much of the information -you find in the wiki refers to moin 1.9 and does not apply to moin2. +In general, ensure that the documentation you are reading +is written for the Moin version you are using. Much of the information +you find in the wiki refers to Moin 1.9 and does not apply to Moin2. -For support, please try the documentation, the homepage, the irc channel, -the mailing lists and the github issues before contacting the MoinMoin +For support, please try the documentation, the home page, the IRC channel, +the mailing lists, and GitHub issues before contacting the MoinMoin authors directly. If you have trouble with any web server configuration, please try reading -the web server's documentation. Same thing applies for any other 3rd party -software usually used with moin, but not written by the MoinMoin developers. +the web server's documentation. The same applies to any other third-party +software commonly used with Moin but not written by the MoinMoin developers. Contributing ============ You're welcome to help us make MoinMoin even better! Whether you have experience -with Python, HTML or CSS or are just starting out, there are many ways you -can contribute - please see [CONTRIBUTING](https://github.com/moinwiki/moin/blob/master/CONTRIBUTING.md). +with Python, HTML, or CSS, or are just starting out, there are many ways you +can contribute — please see [CONTRIBUTING](https://github.com/moinwiki/moin/blob/master/CONTRIBUTING.md). -Acknowledgements +Acknowledgments ================ -We have to thank a lot of people for their valuable ideas, time and -contributions - please see [contributors](https://github.com/moinwiki/moin/graphs/contributors). +We thank the many people who have contributed their valuable ideas, time, and +code — please see the [contributors](https://github.com/moinwiki/moin/graphs/contributors) page. diff --git a/SECURITY.md b/SECURITY.md index 716818779..d439d9fdc 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,7 +8,7 @@ ## Reporting a Vulnerability -Please report vulnerabilities privately via Github: +Please report vulnerabilities privately via GitHub: https://github.com/moinwiki/moin/security diff --git a/docs/admin/backup.rst b/docs/admin/backup.rst index b6e113f66..814b6ae96 100644 --- a/docs/admin/backup.rst +++ b/docs/admin/backup.rst @@ -8,37 +8,36 @@ Full Backup / Restore 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. -The procedure below explains how to selectively backup only the files +The procedure below explains how to selectively back up only the files essential to your MoinMoin installation. While there is no need to maintain both a full and a selective backup, having at least one of the two is strongly recommended. Selective Backup ================ -If you want a backup of MoinMoin and your data, then backup the following: +If you want a backup of MoinMoin and your data, then back up the following: * your data, usually everything under wiki/ -* moin configuration, e.g. wikiconfig.py -* logging configuration, e.g. logging.conf -* moin deployment script, e.g. moin.wsgi -* web server configuration, e.g. apache virtualhost config -* optional: moin code + dependencies; you should at least know which version +* Moin configuration, e.g., wikiconfig.py +* logging configuration, e.g., logging.conf +* Moin deployment 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 moinmoin (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 --all-backends --file backup.moin -Please note that this file contains sensitive data like user profiles, wiki +Please note that this file contains sensitive data like user profiles and wiki contents, so store your backups in a safe place that no unauthorized individual can access. -Backups require valid metadata to produce files which can be loaded +Backups require valid metadata to produce files that can be loaded; in particular, the size attribute must be correct for each revision. -if bad metadata is found during the backup, -there will be a warning logged and it is recommended -to run ``moin validate-metadata -a -f`` -see :ref:`validate-metadata` +If bad metadata is found during the backup, a warning will be logged and it is recommended +to run ``moin maint-validate-metadata --all-backends --fix``. +See :ref:`validate-metadata`. Selective Restore ================= diff --git a/docs/admin/changes.rst b/docs/admin/changes.rst index e94684022..34e0989b5 100644 --- a/docs/admin/changes.rst +++ b/docs/admin/changes.rst @@ -1,4 +1,3 @@ -:tocdepth: 2 .. _changes: diff --git a/docs/admin/configure.rst b/docs/admin/configure.rst index e8838da49..f79d0958d 100644 --- a/docs/admin/configure.rst +++ b/docs/admin/configure.rst @@ -3,7 +3,7 @@ Introduction into MoinMoin Configuration ======================================== Kinds of configuration files ============================ -To change how moinmoin behaves and looks, you may customize it by editing +To change how MoinMoin behaves and looks, you may customize it by editing its configuration files: * Wiki Engine Configuration @@ -21,7 +21,7 @@ its configuration files: * Logging Configuration - - optional; if you don't configure this, it will use the builtin defaults + - optional; if you don't configure this, it will use the built-in defaults - this is a separate file, often called logging.conf - it has an .ini-like file format @@ -70,11 +70,11 @@ The directories and files shown are referenced in this section of documentation wiki/ # the wiki instance; created by running "./m new-wiki" or "moin create-instance" commands data/ # wiki data and metadata index/ # wiki indexes - wiki_local/ # a convenient location to store custom CSS, Javascript, templates, logos, etc. + wiki_local/ # a convenient location to store custom CSS, JavaScript, templates, logos, etc. wikiconfig.py # main configuration file, modify this to add or change features intermap.txt # interwiki map: copied by quickinstall.py, updated by "./m interwiki" -After installing moin from pypi or unpacking using a package manager, the directory structure will +After installing Moin from PyPI or unpacking using a package manager, the directory structure will look like this:: myvenv/ # virtualenv root @@ -93,8 +93,8 @@ and execute `moin run`.:: data/ # wiki data and metadata index/ # wiki indexes preview/ # text item backups are created when user clicks edit Preview button - sql/ # sqlite database used for edit locking - wiki_local/ # store custom CSS, Javascript, templates, logos, etc. here + sql/ # SQLite database used for edit locking + wiki_local/ # store custom CSS, JavaScript, templates, logos, etc. here wikiconfig.py # main configuration file, modify this to add or change features intermap.txt # list of external wikis used in wikilinks: [[MeatBall:InterWiki]] @@ -270,7 +270,7 @@ Adding scripts ~~~~~~~~~~~~~~ You can add scripts like this:: - {# Additional Javascript #} + {# Additional JavaScript #} {% macro scripts() -%} {% endmacro %} @@ -401,7 +401,7 @@ That way they are easily usable on all operating systems, whether it has a packa system or not. In many cases, those external static files are maintained by someone else (like jQuery -javascript library or larger js libraries) and we definitely do not want to merge +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 pyproject.toml: @@ -426,7 +426,7 @@ For MoinMoin we require the following XStatic Packages in pyproject.toml: used by basic theme to adjust textarea on modify view. * `svgedit_moin `_ - is loaded at template modify_svg-edit. It is a fast, web-based, Javascript-driven + is loaded at template modify_svg-edit. It is a fast, web-based, JavaScript-driven SVG editor. * `jquery_tablesorter `_ @@ -723,7 +723,7 @@ Password strength As you might know, many users are bad at choosing reasonable passwords and some are tempted to use easily crackable passwords. -To help users choose reasonable passwords, moin has a simple builtin +To help users choose reasonable passwords, Moin has a simple built-in password checker that is enabled by default and does some sanity checks, so users don't choose easily crackable passwords. @@ -1305,7 +1305,7 @@ Features: * uses slqalchemy (without the ORM) for database abstraction * supports multiple types of databases, for example: - - sqlite (default, comes built-into Python) + - SQLite (default, comes built into Python) - postgresql - mysql - and others, see sqlalchemy docs. @@ -1326,12 +1326,12 @@ Please see the sqlalchemy docs about the DBURI part. Grant 'myuser' (his password: 'mypassword') full access to these databases. -sqlite store +SQLite store ------------ Features: -* directly talks to sqlite, without using sqlalchemy -* stores data into an sqlite database, which is a single file +* directly talks to SQLite, without using SQLAlchemy +* stores data into a SQLite database, which is a single file * 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 @@ -1343,11 +1343,11 @@ Features: stores:sqlite:/srv/mywiki/data/mywiki_%(nsname)s.db::%(kind)s stores:sqlite:/srv/mywiki/data/mywiki_%(nsname)s.db::%(kind)s::1 -The uri part after "sqlite:" is like:: +The URI part after "sqlite:" is like:: PATH::TABLENAME::COMPRESSION -It uses "::" as separator to support windows pathes which may have ":" after +It uses "::" as a separator to support Windows paths, which may have ":" after the drive letter. @@ -1471,15 +1471,15 @@ to convert a moin 1.9 wiki to moin 2.0, then an item `foo` would be renamed to ` Mail configuration ================== -Sending E-Mail +Sending Email -------------- -Moin can optionally send E-Mail. Possible uses: +Moin can optionally send email. Possible uses: * send out item change notifications * enable users to reset forgotten passwords * inform admins about runtime exceptions -You need to configure some settings before sending E-Mail can be supported:: +You need to configure some settings before sending email can be supported:: # the "from:" address [Unicode] mail_from = "wiki " @@ -1500,7 +1500,7 @@ You need to configure some settings before sending E-Mail can be supported:: describe more moin configuration -Admin Traceback E-Mails +Admin Traceback Emails ----------------------- If you want to enable admins to receive Python tracebacks, you need to configure the following:: @@ -1514,13 +1514,13 @@ the following:: Please also check the logging configuration example in `contrib/logging/email`. -User E-Mail Address Verification +User Email Address Verification -------------------------------- -At account creation time, Moin can require new users to verify their E-Mail +At account creation time, Moin can require new users to verify their email address by clicking a link that is sent to them. -Make sure that Moin is able to send E-Mails (see previous section) and add the +Make sure that Moin is able to send emails (see previous section) and add the following line to your configuration file to enable this feature:: user_email_verification = True diff --git a/docs/admin/index.rst b/docs/admin/index.rst index d5401a010..34ac30a3f 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -11,18 +11,18 @@ is doing all the hard and complex work. Indexes are used internally for many operations like item lookup, history, iterating over items, search, interactive search, etc. -MoinMoin won't be able to start with damaged, inaccessible or non-existing indexes. +MoinMoin won't be able to start with damaged, inaccessible, or non-existing indexes. 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. +Moin will automatically update the index when items are created, updated, deleted, +destroyed, or renamed via the storage API of Moin, the indexing layer, or above. Configuration ============= -Your need to have a ``index_storage`` entry in your wiki config. +You need to have an ``index_storage`` entry in your wiki config. -We use whoosh for indexing and as whoosh supports multiple storage backends, -this entry is made to potentially support any storage supported by whoosh. +We use Whoosh for indexing and, as Whoosh supports multiple storage backends, +this entry is made to potentially support any storage supported by Whoosh. In general, this entry has the form of:: @@ -42,9 +42,9 @@ has one parameter - the index directory:: moin index subcommand reference =============================== -You can use the ``moin index-*`` group of cli subcommands to manage indexes. +You can use the ``moin index-*`` group of CLI subcommands to manage indexes. -Many of the cli commands for index management support a `--tmp` option to use +Many of the CLI commands for index management support a `--tmp` option to use the temporary index location. This is useful if you want to do index operations in parallel to a running wiki which is still using the index at the normal index location. @@ -53,8 +53,8 @@ moin index-create ----------------- Creates an empty but valid index. -**Note:** the moin WSGI application needs an index and storage to successfully start up. -Please see command moin create-instance. +**Note:** The Moin WSGI application needs an index and storage to successfully start up. +Please see the command moin create-instance. moin index-build ---------------- @@ -78,7 +78,7 @@ index-update multiple times to keep even more caught up. moin index-destroy ------------------ -Destroy an index, such that nothing left at the respective location. +Destroy an index such that nothing is left at the respective location. moin index-move --------------- @@ -86,11 +86,11 @@ Move the index from the temporary location to the normal location. moin index-optimize ------------------- -Optimize an index:: see Whoosh docs for more details. +Optimize an index; see Whoosh docs for more details. moin index-dump --------------- -Output index contents in human readable form, e.g. for debugging purposes. +Output index contents in human-readable form, e.g., for debugging purposes. **Note:** only fields with attribute ``stored=True`` can be displayed. @@ -111,8 +111,8 @@ 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 the index needs a rebuild for some reason (e.g., index lost, index damaged, +incompatible upgrade, etc.), use:: moin index-destroy moin index-create @@ -138,11 +138,11 @@ index rebuilds, schedule them at some time when your server is not too busy. Building an index for a wiki farm ================================= 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 +between the wikis so users will be able to search in one wiki and also see results from the other wikis. Before you start, you must prepare your wiki configs. For example, for a company -that uses two farm wikis, such as ``Sales`` and ``Engineering``, Their respective +that uses two farm wikis, such as ``Sales`` and ``Engineering``. Their respective wiki configs could look like: ``Sales``:: diff --git a/docs/admin/install.rst b/docs/admin/install.rst index 67df06b05..bfb1f12f7 100644 --- a/docs/admin/install.rst +++ b/docs/admin/install.rst @@ -8,16 +8,16 @@ There are a lot of ways to do this and as this is not moin specific, we won't go into details: - As long as moin2 is in pre-release stages, this is likely your only and best choice. - If you use ldap, you will have to install OS dependant packages yourself. - You will have to install moin updates and security fixes your self. - Create a virtual env first for better separation, then install moin: + If you use LDAP, you will have to install OS-dependent packages yourself. + You will have to install Moin updates and security fixes yourself. + Create a virtual environment first for better separation, then install Moin: :: -m venv cd - source bin/activate # or "scripts\activate" on windows - pip install --pre moin + source bin/activate # or "scripts\activate" on Windows + pip install --pre moin - Or, use your operating system's / distribution's package manager to install the @@ -25,20 +25,20 @@ we won't go into details: all other software it requires. Also your OS / dist might have a mechanism for updating the installed software with security fixes and future releases. - E.g. on Debian/Ubuntu Linux + For example, on Debian/Ubuntu Linux: :: apt install moin -- Or, install into a virtual env from PyPI. - You will have to install moin updates and security fixes your self.: +- Or, install into a virtual environment from PyPI. + You will have to install Moin updates and security fixes yourself: :: -m venv cd - source bin/activate # or "scripts\activate" on windows + source bin/activate # or "scripts\activate" on Windows pip install moin @@ -63,8 +63,8 @@ and retry `moin --help` Creating a wiki instance ======================== -You'll need one instance directory per wiki site you want to run using moin - -this is where wiki data, indexes and configuration for that site are stored. +You'll need one instance directory per wiki site you want to run using Moin; +this is where wiki data, indexes, and configuration for that site are stored. Let's create a new instance: @@ -83,7 +83,7 @@ you'll find some comments in there. Review and change the settings for:: * sitename * interwikiname - * acls - SuperUser and SuperEditor + * ACLs - SuperUser and SuperEditor * registration only by superuser * edit locking policy * email configuration @@ -116,13 +116,13 @@ Or, if you have a moin 1.9.x wiki, convert it to moin 2: Run your wiki instance ====================== -Now try your new wiki using the builtin python-based web server: +Now try your new wiki using the built-in Python-based web server: :: moin run # visit the URL it shows in the log output -For production, please use a real web server like apache or nginx. +For production, please use a real web server like Apache or nginx. For more information on various wiki admin activities, see `Moin Command Line Interface`. @@ -131,7 +131,7 @@ For more information on various wiki admin activities, see `Moin Command Line In Installation (for developers) ============================= -Clone the git repository +Clone the Git repository ======================== If you like to work on the moin2 code, clone the master project repository or see the option below: @@ -142,8 +142,8 @@ or see the option below: git clone https://github.com/moinwiki/moin cd moin -If you use github, you can also first fork the project repo to your own -user's github repositories and then clone your forked repo to your local +If you use GitHub, you can also first fork the project repo to your own +user's GitHub repositories and then clone your forked repo to your local development machine. You can easily publish your own changes and do pull requests that way. If you do fork the project, then an alternative to the above command is to clone your fork and add a remote url to the @@ -206,7 +206,7 @@ Typing "./m" (or "m" on Windows) will display a menu similar to: quickinstall update virtual environment with required packages extras install packages required for docs and moin development - docs create moin html documentation (requires extras) + docs create moin HTML documentation (requires extras) interwiki refresh contrib/interwiki/intermap.txt (version control) log view detailed log generated by , omit to see list diff --git a/docs/admin/maintenance.rst b/docs/admin/maintenance.rst index 0cf28bd2e..9106ce645 100644 --- a/docs/admin/maintenance.rst +++ b/docs/admin/maintenance.rst @@ -9,32 +9,32 @@ This process removes all but the current revision of selected items, it reduces the storage required for your wiki at the expense of loss of history. -To perform on entire wiki, run the following command:: +To perform on the entire wiki, run the following command:: moin maint-reduce-revisions -To perform on an item with name "ItemName", run the following command:: +To perform on an item named "ItemName", run the following command:: moin maint-reduce-revisions -q ItemName Set Metadata -============= +============ -Manually modify metadata of items. +Manually modify item metadata. .. _validate-metadata: Validate and Optionally Fix Metadata ==================================== -Modifications of wiki data outside of edits via the webapp -such as use of the load-help and item-put moin commands +Modifications of wiki data outside of edits via the web app, +such as using the load-help and item-put moin commands, can result in invalid metadata. The processes below check for and optionally fix the following issues: -* size does not match size of the revision's data in bytes -* sha1 hash does not match has of the revision's data +* size does not match the size of the revision's data in bytes +* SHA1 hash does not match the hash of the revision's data * parent id should not be present for revision number 1 of a given item * parent id for each revision should be the data id for the previous revision number for that item * every revision should have a revision number @@ -44,11 +44,11 @@ To check for invalid metadata, run the following command:: moin maint-validate-metadata --all-backends -To view detailed list of invalid items:: +To view a detailed list of invalid items:: moin maint-validate-metadata --all-backends --verbose -To fix issues, add ``--fix`` option to any of the above commands. +To fix issues, add the ``--fix`` option to any of the above commands. -To operate on only a selection of backends, replace ``--all--backends`` option with ``--backends`` -followed by comma separated list of backends to process +To operate on only a selection of backends, replace the ``--all-backends`` option with ``--backends``, +followed by a comma-separated list of backends to process. diff --git a/docs/admin/password-reset.rst b/docs/admin/password-reset.rst index 01b63b05f..a68f7418f 100644 --- a/docs/admin/password-reset.rst +++ b/docs/admin/password-reset.rst @@ -8,9 +8,9 @@ For example: * you had a security breach on your wiki server (or somewhere else) and the old password hashes (or passwords) were exposed -* you want to make sure some user or all users set a new password, e.g. if: +* you want to make sure some user or all users set a new password, e.g., if: - - your password policy has changed (requiring longer passwords for example) + - your password policy has changed (requiring longer passwords, for example) - you changed your passlib configuration and want to immediately have all hashes upgraded @@ -21,19 +21,19 @@ against that hash). MoinMoin does not keep user passwords in cleartext. The files we refer to below are located in contrib/password-reset/... -Resetting one or few password(s) -================================ -If you somehow interact with the users corresponding to the user accounts in -question (by phone or directly), you don't need the extensive procedure as -described below, just use:: +Resetting one or a few password(s) +================================== +If you can interact with the users corresponding to the user accounts in +question (by phone or directly), you don't need the extensive procedure +below; just use:: moin account-password --name JoeDoe That will reset JoeDoe's password. Tell him to visit the login URL and use the "forgot my password" functionality to define a new password. -If that doesn't work (e.g. if e-mail is not enabled for your wiki or he has -a non-working e-mail address in his profile), you can also set a password for +If that doesn't work (e.g., if email is not enabled for your wiki or he has +a non-working email address in his profile), you can also set a password for him:: moin account-password --name JoeDoe --password uIkV9.-a3 @@ -50,34 +50,34 @@ avoids having to deal with too many users individually. Preparing your users -------------------- -Tell your users beforehands that you will be doing a password reset, otherwise -they might find the automatically generated E-Mail they'll get suspicious and -you'll have to explain it to them individually that the E-Mail is legitimate. +Tell your users beforehand that you will be doing a password reset; otherwise +they might find the automatically generated email they'll get suspicious and +you'll have to explain to them individually that the email is legitimate. -Also, remind your users that having a valid E-Mail address in their user -settings is essential for getting a password recovery E-Mail. +Also, remind your users that having a valid email address in their user +settings is essential for getting a password recovery email. -If an active user does somehow not get such a mail, you likely will have to -manually define a valid E-Mail address (or even password) for that user. +If an active user does not get such an email, you will likely have to +manually define a valid email address (or even a password) for that user. -Make sure E-Mail functionality works ------------------------------------- -If you know you have working E-Mail functionality, skip this section. +Make sure email functionality works +----------------------------------- +If you know you have working email functionality, skip this section. -Password recovery and password reset notification work via E-Mail, so you +Password recovery and password reset notification work via email, so you should have it configured:: - # the E-Mail address used for From: (consider using an address that + # the email address used for From: (consider using an address that # can be directly replied to, at least while doing the pw reset): mail_from = 'wiki@example.org' - # your smtp mail server hostname:port (default is 25) + # your SMTP mail server hostname:port (default is 25) mail_smarthost = 'mail.example.org:587' # the login there, if authentication is needed mail_username = 'wiki@example.org' mail_password = 'SuperSecretSMTPPassword' -You can try whether it works by using the "forgot my password" functionality +You can test whether it works by using the "forgot my password" functionality on the login page. @@ -86,7 +86,7 @@ Editing mailtemplate.txt If you edit mailtemplate.txt, please be very careful and follow these rules (otherwise you might just see the script command crashing): -The contents must be utf-8 (or ascii, which is a subset of utf-8). +The contents must be UTF-8 (or ASCII, which is a subset of UTF-8). In case of doubt, just use plain English. Some places you likely should edit are marked with XXX. @@ -94,24 +94,24 @@ Some places you likely should edit are marked with XXX. Do not use any % character in your text (except for the placeholders). If you need a verbatim % character, you need to write %%. -It is a very good idea to give some URL (e.g. of a web or wiki page) in +It is a very good idea to give some URL (e.g., of a web or wiki page) in the text where users can read more information. -Of course the information at that URL should be readable without requiring -a wiki login (you just have invalidated his/her password!), so the user can -get informed before clicking links he got from someone via E-Mail. +Of course, the information at that URL should be readable without requiring +a wiki login (you just invalidated his/her password!), so the user can +get informed before clicking links received via email. We have added a wikitemplate.txt you can use to create such a wiki page. Instead of creating a web or wiki page with the information, you could also write all the stuff into the mail template directly, but please consider -that E-Mail delivery to some users might fail for misc. reasons, so having +that email delivery to some users might fail for miscellaneous reasons, so having some information on the web/wiki is usually better. Editing wikitemplate.txt ------------------------ -Just copy & paste it to some public page in your wiki, e.g. "PasswordReset". +Just copy and paste it to some public page in your wiki, e.g., "PasswordReset". Some places you likely should edit are marked with XXX. @@ -123,11 +123,11 @@ Maybe first try it with a single user account:: moin account-password --name JoeDoe --notify --subject 'Wiki password reset' --text-from-file mailtemplate.txt Use some valid name, maybe a testing account of yourself. You should now have -mail. If that worked ok, you can now do a global password reset for your wiki:: +mail. If that worked OK, you can now do a global password reset for your wiki:: moin account-password --verbose --all-users --notify --subject 'Wiki password reset' --text-from-file mailtemplate.txt The subject may contain a placeholder for the sitename, which is useful for -wiki farms (showing the builtin default here):: +wiki farms (showing the built-in default here):: '[%(sitename)s] Your wiki account data' diff --git a/docs/admin/requirements.rst b/docs/admin/requirements.rst index c71a38a81..564cff923 100644 --- a/docs/admin/requirements.rst +++ b/docs/admin/requirements.rst @@ -5,10 +5,10 @@ Requirements MoinMoin requires Python 3.9+. A CPython distribution is recommended because it will likely be the fastest and most stable. Most developers use a CPython distribution for testing. -Typical linux distributions will either have Python 3.9+ installed by +Typical Linux distributions will either have Python 3.9+ installed by default or will have a package manager that will install Python 3.9+ as a secondary Python. -Windows users may download CPython distributions from https://www.python.org/ or +Windows users may download CPython distributions from https://www.python.org/ or https://www.activestate.com/. An alternative implementation of Python, PyPy, is available @@ -18,19 +18,19 @@ from https://www.pypy.org/. Servers ======= -For moin2, you can use any server compatible with WSGI: +For Moin2, you can use any server compatible with WSGI: -* the builtin server (used by the "moin run" command) is recommended for - desktop wikis, testing, debugging, development, adhoc-wikis, etc. -* apache with mod_wsgi is recommended for bigger/busier wikis. -* other WSGI-compatible servers or middlewares are usable -* For cgi, fastcgi, scgi, ajp, etc., you can use the "flup" middleware: +* the built-in server (used by the "moin run" command) is recommended for + desktop wikis, testing, debugging, development, ad hoc wikis, etc. +* Apache with mod_wsgi is recommended for bigger/busier wikis. +* Other WSGI-compatible servers or middleware are usable. +* For CGI, FastCGI, SCGI, AJP, etc., you can use the "flup" middleware: https://www.saddi.com/software/flup/ * IIS with ISAPI-WSGI gateway is also compatible: https://code.google.com/archive/p/isapi-wsgi .. caution:: When using the built-in server for public wikis (not recommended), use - "moin run --no-debugger --no-reload" to turn off the werkzeug debugger and auto reloader. + "moin run --no-debugger --no-reload" to turn off the Werkzeug debugger and auto reloader. See the Werkzeug docs for more information. @@ -38,7 +38,7 @@ Dependencies ============ Dependent packages will be automatically downloaded and installed during the -moin2 installation process. For a list of dependencies, see pyproject.toml. +Moin2 installation process. For a list of dependencies, see pyproject.toml. Clients diff --git a/docs/admin/serve.rst b/docs/admin/serve.rst index 619d1912d..fff8d0e49 100644 --- a/docs/admin/serve.rst +++ b/docs/admin/serve.rst @@ -5,38 +5,38 @@ Server Options Built-in Web Server (easy) ========================== Moin comes with a simple built-in web server powered by Werkzeug, which -is suitable for development, debugging, and personal and small group wikis. +is suitable for development, debugging, and personal, 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 5000. 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, then use your normal +are running a desktop wiki or doing Moin development, then use your normal login user. Running the built-in server --------------------------- -Run the moin built-in server as follows:: +Run the Moin built-in server as follows:: # easiest for debugging (single-process, single-threaded server): moin run - # or, if you need another configuration file, ip address, or port: + # or, if you need another configuration file, IP address, or port: MOINCFG='/path/to/wikiconfig.py' moin run --host 1.2.3.4 --port 7777 -While the moin server is starting up, you will see some log output, for example:: +While the Moin server is starting up, you will see some log output, for example:: INFO werkzeug WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead. * Running on http://127.0.0.1:5000 - INFO werkzeug Press CTRL+C to quit + INFO werkzeug Press Ctrl+C to quit -Now point your browser at that URL - your moin wiki is running! +Now point your browser at that URL — your Moin wiki is running! Stopping the built-in server ---------------------------- -To stop the wiki server, either use `Ctrl-C` or close the window. +To stop the wiki server, either press Ctrl+C or close the window. Debugging with the built-in server ---------------------------------- @@ -56,7 +56,7 @@ Using the built-in server for production ---------------------------------------- .. caution:: Using the built-in server for public wikis is not recommended. Should you - wish to do so, turn off the werkzeug debugger and auto reloader by passing the --no-debugger + wish to do so, turn off the Werkzeug debugger and auto reloader by passing the --no-debugger and --no-reload flags. The wikiconfig.py settings of `DEBUG = False` and `TESTING = False` are ignored by the built-in server. See Werkzeug docs for more information:: @@ -66,19 +66,19 @@ Using the built-in server for production External Web Server (advanced) ============================== -We won't go into details about using moin under an external web server, because every web server software is +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. -In order to use MoinMoin with another web server, ensure that your web server can talk to the moin WSGI +In order to use MoinMoin with another web server, ensure that your web server can talk to the Moin WSGI application, which you can get using this code:: from moin.app import create_app application = create_app('/path/to/config/wikiconfig.py') -MoinMoin is a Flask application, which is a micro framework for WSGI applications, -so we recommend you read Flask's good deployment documentation. +MoinMoin is a Flask application, which is a microframework for WSGI applications, +so we recommend you read Flask's deployment documentation. Make sure you use `create_app()` as shown above to create the application, because you can't import the application from MoinMoin. @@ -90,20 +90,20 @@ you can try a simpler WSGI app first. An example file is included at `contrib/deployment/test.wsgi`. As long as you can't make `test.wsgi` work, the problem is not with -moin, but rather with your web server and WSGI app deployment method. +Moin, but rather with your web server and WSGI app deployment method. 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 to troubleshoot the issue from there. -.. tip:: Check contents of /contrib/wsgi/ for sample wsgi files for your server. +.. tip:: Check the contents of /contrib/wsgi/ for sample WSGI files for your server. Create and Serve a Static Wiki Image ==================================== -"dump-html" is a utility used to create static html dumps of MoinMoin wiki content. +"dump-html" is a utility used to create static HTML dumps of MoinMoin wiki content. You may find it useful to create a static dump for a software release, -a high volume read-only copy for a busy web site, or a +a high-volume read-only copy for a busy website, or a thumb drive version to carry on trips when you do not have internet access. To execute dump-html, use the command line interface. @@ -120,12 +120,12 @@ HTML, will be placed under the wiki root. The --theme option specifies the theme. See "Customize the CMS Theme" within the "Introduction into MoinMoin Configuration" section for alternatives. -The --exclude-ns option specifies a comma separated list of namespaces that +The --exclude-ns option specifies a comma-separated list of namespaces that will be excluded from the dump. The "userprofiles" namespace should always be excluded. To exclude user home pages from the static dump, use **userprofiles,users** with no embedded spaces. -The --query option may be a single page name or a regex selecting the items +The --query option may be a single page name or a regular expression selecting the items to be included in the dump. The default of ".*" selects all items. Once created, the HTML directory may be moved anywhere as all the internal links are @@ -134,4 +134,4 @@ the file system. .. warning:: Some browsers (Chrome, IE11, Opera) serve files loaded from the OS - file system as plain text. https://github.com/moinwiki/moin/issues/641 + file system as plain text. See https://github.com/moinwiki/moin/issues/641 diff --git a/docs/admin/upgrade.rst b/docs/admin/upgrade.rst index 37ad94457..6f4502422 100644 --- a/docs/admin/upgrade.rst +++ b/docs/admin/upgrade.rst @@ -3,24 +3,24 @@ Upgrading ========= .. note:: - Internally, moin2 is very different than moin 1.x. + Internally, Moin2 is very different from Moin 1.x. - 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*. + 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 indicates *major and incompatible changes*. 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 - * Wiki content: expect 90% compatibility for existing moin 1.9 content. + * Server and wiki engine configuration: expect to review/rewrite it + * Wiki content: expect ~90% compatibility for existing Moin 1.9 content. - * The most commonly used simple moin wiki markup (like headlines, lists, bold) has not changed + * The most commonly used simple Moin wiki markup (like headlines, lists, bold) has not changed * CamelCase auto links will be converted to explicit [[CamelCase]] links * [[attachment:my.jpg]] will be converted to [[/my.jpg]] * {{attachment:my.jpg}} will be converted to {{/my.jpg}} - * expect to change custom macros, parsers, action links, 3rd party extensions + * Expect to change custom macros, parsers, action links, 3rd-party extensions -From moin < 1.9 +From Moin < 1.9 =============== If you run an older moin version than 1.9, please first upgrade to a recent moin 1.9.x version (preferably >= 1.9.7) before upgrading to moin2. @@ -30,7 +30,7 @@ Note: Both moin 1.9.x and moin2 are WSGI applications. Upgrading to 1.9 first also makes sense concerning the WSGI / server side. -From moin 1.9.x +From Moin 1.9.x =============== If you want to keep your user's password hashes and migrate them to moin2, @@ -47,7 +47,7 @@ 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 Moin2 ------------- Install and configure moin2, make it work, and start configuring it from the moin2 sample config. Do *not* just use your 1.9 wikiconfig. @@ -56,7 +56,7 @@ the moin2 sample config. Do *not* just use your 1.9 wikiconfig. Adjusting the moin2 configuration --------------------------------- It is essential that you edit wikiconfig.py before you import your 1.9 -data. In particular, review the settings for:: +data. In particular, review the settings for: - sitename - interwikiname @@ -66,7 +66,8 @@ data. In particular, review the settings for:: - users_acl -Clean up your moin 1.9 data + +Clean up your Moin 1.9 data --------------------------- 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 @@ -81,7 +82,7 @@ Deleted pages will not be migrated. A message will be written to the log for each deleted page. -Importing your moin 1.9 data +Importing your Moin 1.9 data ---------------------------- Before importing your existing wiki data please ensure you have created an instance and index as described in the install section above using commands:: @@ -89,24 +90,24 @@ and index as described in the install section above using commands:: moin create-instance moin index-create -The import19 cli subcommand needs your 1.9 data directory with pages, attachments and users. +The import19 CLI subcommand needs your 1.9 data directory with pages, attachments, and users. Usually you set up moin2 on a new current operating system and copy the old data directory to a temporary location. The utility will read the moin1.9 data, convert it and write it to your moin2 storage and build the index:: moin import19 --data_dir //wiki/data -Please review the logfile to find out whether the importer had critical issues with your data. +Please review the log file to find out whether the importer had critical issues with your data. By default, all items using moin 1.9 markup are converted to moin 2 markup. The converted revision will have a timestamp one second later than the last revision's timestamp to preserve revision history. Page revisions that were created with leading `#format creole` and `#format rst` commands -will retain the creole and rst markups. +will retain the Creole and reST markups. -There is an additional option to convert pages with moin wiki markup using one of the other moin2 -output converters: markdown, rst, html, or docbook. +There is an additional option to convert pages with Moin wiki markup using one of the other Moin2 +output converters: Markdown, reST, HTML, or DocBook. Add the `--markup_out` or `-m` option to the `moin import19` command above. To convert the last revision of all pages with moin wiki markup to markdown:: @@ -129,9 +130,9 @@ contains data used internally and should always be protected from any access by If you are importing a large wiki with more than 1000 entries or revisions, the index building part of the import will be time-consuming. You can use the following options to speed up the process:: - --procs --limitmb + --procs --limitmb -Choose the values according to your available hardware resources. The defaults are 1 process and 256 mb memory. +Choose the values according to your available hardware resources. The defaults are 1 process and 256 MB memory. See the `Whoosh Tips for speeding up batch indexing docs `_ for details. Use the following command to get an overview of all available options:: @@ -140,7 +141,7 @@ Use the following command to get an overview of all available options:: Testing ------- -Review the logs for error messages. Start the moin server and try the "Index" and "History" +Review the logs for error messages. Start the Moin server and try the "Index" and "History" views to see what is included. Check whether your data is complete and rendering correctly. If you find issues with data migration from moin 1.9 to 2, please check the @@ -157,22 +158,22 @@ Converting after reverting -------------------------- .. if the above title is changed, also change CONTENTTYPES_HELP_DOCS in constants/contenttypes.py -The import19 process converts text items using Moinmoin 1.9 syntax to -Moinmoin 2.0 syntax. +The import19 process converts text items using MoinMoin 1.9 syntax to +MoinMoin 2.0 syntax. -The conversion is accomplished by creating a new revision of each moin wiki text item. +The conversion is accomplished by creating a new revision of each Moin wiki text item. Click the History link under the Item Views panel to view the revisions. -The latest revision will have a content type of "Moinmoin" while the older revisions -created prior to conversion will have a content type of "Moinmoin 1.9" +The latest revision will have a content type of "MoinMoin" while the older revisions +created prior to conversion will have a content type of "MoinMoin 1.9" Click the Diff link to see the content changes made by import19. -If a moin wiki item is reverted to a revision having a content type of "Moinmoin 1.9" -with embedded old style CamelCase auto links and/or attachments (`{{attachment:my.jpg}}`), -the revision is not converted to the Moinmoin 2 syntax automatically. Editors must do +If a Moin wiki item is reverted to a revision having a content type of "MoinMoin 1.9" +with embedded old-style CamelCase autolinks and/or attachments (`{{attachment:my.jpg}}`), +the revision is not converted to the MoinMoin 2 syntax automatically. Editors must do the conversion by clicking the Convert link within the Item Views panel. -Reverted revisions left in the Moinmoin 1.9 format will render correctly and +Reverted revisions left in the MoinMoin 1.9 format will render correctly and the reverted item may be updated and saved using the old 1.9 syntax. However, -it is recommended that all such revisions be converted to the new moin syntax +it is recommended that all such revisions be converted to the new Moin syntax because the old CamelCase and attachment conventions are deprecated and will -never be included in the moin 2 docs. +never be included in the Moin 2 docs. diff --git a/docs/conf.py b/docs/conf.py index be325dddc..f66c4f081 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -115,7 +115,7 @@ # html_theme = 'bizstyle' # The style sheet to use for HTML pages. A file of that name must exist either -# in Sphinx’ static/ path, or in one of the custom paths given in +# in Sphinx's static/ path, or in one of the custom paths given in # html_static_path. Default is the stylesheet given by the selected theme. html_style = "custom.css" diff --git a/docs/devel/development.rst b/docs/devel/development.rst index 8553dd0ad..c53417c51 100644 --- a/docs/devel/development.rst +++ b/docs/devel/development.rst @@ -7,7 +7,7 @@ Useful Resources If you have any questions about MoinWiki you can use the following resources: -Documentation (installation, configuration, user docs, api reference): +Documentation (installation, configuration, user docs, API reference): * https://moin-20.readthedocs.io/en/latest/ @@ -29,16 +29,16 @@ Requirements for development The `virtualenv` Python package is required. The installation process for `virtualenv` varies with your OS and Python distribution. -Many linux distributions have a package manager that may do the installation. +Many Linux distributions have a package manager that may do the installation. Windows users (and perhaps others) may download setuptools from https://pypi.org/project/setuptools/. Once setuptools is installed, do "`easy_install virtualenv`". Current ActiveState distributions include virtualenv in the installation bundle. If all else fails, try your favorite search engine. -git is required should you wish to contribute patches to the moin2 development effort. -Even if you do not intend to contribute, git is highly recommended as it +Git is required if you wish to contribute patches to the Moin2 development effort. +Even if you do not intend to contribute, Git is highly recommended as it will make it easy for you to obtain fixes and enhancements from the moin2 repositories. -git can be installed with most linux package managers or downloaded from https://git-scm.com/. +Git can be installed with most Linux package managers or downloaded from https://git-scm.com/. You can also find GUI clients there. @@ -50,29 +50,35 @@ This is the typical workflow for anyone who wants to contribute to the developme create your development environment ----------------------------------- -* if you do not have a github account, create one at https://github.com/ +* if you do not have a GitHub account, create one at https://github.com/ * fork the main repository: https://github.com/moinwiki/moin to your gh user * clone your gh repo to your local development machine:: cd git clone https://github.com/yourname/moin.git + * cd to repo root:: cd moin + * create the virtualenv and download packages:: python quickinstall.py + * activate virtualenv:: . activate # Windows: activate + * create a wiki instance and load help data and welcome pages:: moin create-instance --full + * start the built-in server:: moin run + * point your browser at http://127.0.0.1:5000/ to access your development wiki -* key ctrl+C to stop the built-in server +* press Ctrl+C to stop the built-in server add more tools, exercise tools ------------------------------ @@ -85,22 +91,25 @@ add more tools, exercise tools ./m tests # Windows: m tests -* install NodeJS and NPM with Linux package manager; Windows users may download both from https://nodejs.org/download/ +* install Node.js and npm with a Linux package manager; Windows users may download both from https://nodejs.org/download/ * On Ubuntu 14.04 or any distribution based on Ubuntu you need to install "npm" and "nodejs-legacy" (to get the "node" command). * install sass:: sudo npm install -g sass # Windows: npm install -g sass - sass --version" # show version number to prove it works + sass --version # show version number to prove it works + * regenerate CSS files:: ./m css # Windows: m css git diff # verify nothing changed + * check for coding errors (tabs, trailing spaces, line endings, template indentation and spacing):: ./m coding-std # Windows: m coding-std git diff # verify nothing changed + * revert any changes from above:: git reset --hard @@ -114,9 +123,9 @@ add more tools, exercise tools - convert tabs to 4 spaces - delete trailing blanks on file save - use unix line endings (use Windows line endings on .bat and .cmd files) - - use mono-spaced font for editing + - use monospaced font for editing * if you are new to git, read about it (https://git-scm.com/book/), - consider printing a cheatsheet + consider printing a cheat sheet * if you want a Python IDE, try https://www.jetbrains.com/pycharm/ Free Community Edition * join #moin-dev IRC channel; ask questions, learn what other developers are doing @@ -223,7 +232,7 @@ review your working solution - if you have TortoiseGIT, use those graphical tools to review changes * look for poor variable names, spelling errors in comments, accidental addition or deletion of blank lines, complex code without comments, missing/extra spaces -* if Javascript files were changed, run https://www.jslint.com/ +* if JavaScript files were changed, run https://www.jslint.com/ * run tests again "./m tests" * do some final testing - edit an item and save, etc. @@ -251,7 +260,7 @@ update your virtualenv Every week or so, do "m quickinstall" to install new releases of dependent packages. If any new packages are installed, do a quick check for breakages by running tests, starting the -build-in server, modify an item, etc. +built-in server, modify an item, etc. MoinMoin architecture @@ -423,7 +432,7 @@ To run all the tests, the easiest way is to do:: ./m tests # windows: m tests To run selected tests, activate your virtual env and invoke pytest from the -toplevel directory:: +top-level directory:: pytest --pep8 # run all tests, including pep8 checks pytest -rs # run all tests and output information about skipped tests @@ -496,7 +505,7 @@ Debug a Test To debug a test, start by going to the Py``Charm edit configuration view. Click the + in the upper left corner to show the popup list of configuration types. Choose Tox, and then follow the example below for other field values. -Note the test starup will be rather slow, be patient. +Note the test startup will be rather slow; be patient. .. image:: pycharmC.png :alt: pycharm example @@ -504,7 +513,7 @@ Note the test starup will be rather slow, be patient. Documentation ============= -Moin provides two types of documention. The Sphinx docs (https://www.sphinx-doc.org) +Moin provides two types of documentation. The Sphinx docs (https://www.sphinx-doc.org) are written in reST markup, and have a target audience of developers and wiki admins. The Help docs have a target audience of wiki editors and are written in markups supported by moin. diff --git a/docs/devel/support.rst b/docs/devel/support.rst index 211ef39e5..0910c8668 100644 --- a/docs/devel/support.rst +++ b/docs/devel/support.rst @@ -6,19 +6,19 @@ Free Support You can get free support and information here: * on our chat channels, see https://moinmo.in/MoinMoinChat -* on our wiki, see https://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 - of information about moin2 and also links to all sorts of moin2 resources: +* on our wiki, see https://moinmo.in/ — please note that quite a lot of the content + there is about Moin 1.x and does not apply to Moin2. One page has a lot + of information about Moin2 and also links to all sorts of Moin2 resources: https://moinmo.in/MoinMoin2.0 * on our mailing list, see https://moinmo.in/MoinMoinMailingLists -* on github: https://github.com/moinwiki/moin +* on GitHub: https://github.com/moinwiki/moin .. note:: All free support is done voluntarily by helpful MoinMoin community members. Thanks to everyone who is helping! - If you enjoyed / want to enjoy free community support, please also consider - being an active part of the community and also supporting it. + If you enjoy or want to enjoy free community support, please also consider + being an active part of the community and supporting it. Commercial Support @@ -26,7 +26,7 @@ Commercial Support As MoinMoin 2.0 is not released yet, there is no support for production systems based on it. -If you want to talk about development topics, please contact the developers. +If you want to discuss development topics, please contact the developers. You Support MoinMoin @@ -34,8 +34,8 @@ You Support MoinMoin Like to help others? -------------------- -Just stay connected to IRC, our wiki, the mailing list (see above) and help -others searching for support there. +Stay connected to IRC, our wiki, and the mailing list (see above), and help +others who are searching for support there. Found a bug? ------------ @@ -49,18 +49,18 @@ Have an idea? Born to code? ------------- -* Help to work on moin2 core, so it gets released sooner. -* Help to maintain moin 1.9 until moin2 is ready. +* Help work on the Moin2 core so it gets released sooner. +* Help maintain Moin 1.9 until Moin2 is ready. Loving UI / UX design? ---------------------- -* Help us make moin2 look and feel better! +* Help us make Moin2 look and feel better! Have good language or documentation skills? ------------------------------------------- * If you are a native speaker of a language other than English, with a good - understanding of English, consider helping with improving translation to - your language. **(not yet for moin2, too early!)** see also :doc:`translate` + understanding of English, consider helping improve the translation into + your language. (Not yet for Moin2 — too early.) See also :doc:`translate` * Improve the documentation (see below). Here is a list of all TODOs in this documentation: diff --git a/docs/devel/translate.rst b/docs/devel/translate.rst index 98d910d96..2e09385a4 100644 --- a/docs/devel/translate.rst +++ b/docs/devel/translate.rst @@ -5,8 +5,8 @@ Translating MoinMoin If your language already exists ------------------------------- -To find out if someone has already started a translation of moin2 into your -language; check the folder moin/translations in the source tree. +To find out whether someone has already started a translation of MoinMoin 2 into your +language, check the folder moin/translations in the source tree. 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`_. @@ -34,19 +34,19 @@ language doesn't exist yet`_. * **never** edit the 'msgid' string, and only edit the 'msgstr' field * Variables like ``%(name)x``, where x is any character, must be kept as - they are. They must occur in the translated text. + they are. They must appear in the translated text. - * For better readability you can divide a text-string over more than - one line, by "surrounding" each line with double quotes ("). - It is a usual convention to have a maximal line-length of 80 - characters. + * For better readability you can split a text string across multiple + lines by surrounding each line with double quotes ("). + It is common convention to have a maximum line length of 80 + characters. * Comments starting with "#.", "*#:*" or "*#|*" are auto-generated and should not be modified. - * Comments starting with "# " (# and at least one whitespace) are - translator-comments. You can modify/add them. They have to be - placed right before the auto-generated comments. + * Comments starting with "# " (# and at least one space) are + translator comments. You can modify or add them. They have to be + placed directly before the auto-generated comments. * Comments starting with "*#,*" and separated with "," are flags. They can be auto-generated, but they can also be set by the @@ -55,8 +55,8 @@ language doesn't exist yet`_. An important flag is "fuzzy". It shows that the msgstr string might not be a correct translation. Only the translator can judge if the translation requires further modification, or is - acceptable as it is. Once satisfied with the translation, he/she then - removes this fuzzy attribute. + acceptable as it is. Once satisfied with the translation, the translator then + removes this fuzzy attribute. 4. Save the messages.po file and execute:: @@ -105,8 +105,8 @@ A newly created translation needs a few initial preparations: * replace "``FIRST AUTHOR ``" with the appropriate information about yourself -* replace "``PROJECT VERSION``" in the head msgstr with - "``MoinMoin 2.0``" or newer if neccessary +* replace "``PROJECT VERSION``" in the header msgstr with + "``MoinMoin 2.0``" or newer if necessary * change the value of "``Last-Translator``" to your data @@ -116,7 +116,7 @@ A newly created translation needs a few initial preparations: Note for developers ------------------- -We use the ``format()``-Method in internationalized Strings, e.g. +We use the ``format()`` method in internationalized strings, e.g. ``_('Hello {name}').format(name='World')``. ``_()`` is an alias for ``gettext()`` If the translatable string contains a variable plural, that means @@ -146,8 +146,8 @@ using:: 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 -for this. +Another option for better readability is to make a separate commit +for this purpose. ------ diff --git a/docs/index.rst b/docs/index.rst index 1bb69231a..ce364baeb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,8 @@ .. warning:: - This documentation **only** applies to **MoinMoin version 2** (aka moin2, - moin 2.0, mm2, MoinMoin2, etc.), except where explicitly noted otherwise. - Moin2 is very different from moin 1.x, so docs from one version will not + This documentation applies **only** to **MoinMoin version 2** (also known as Moin2, + Moin 2.0, MoinMoin2, etc.), except where explicitly noted otherwise. + Moin2 is very different from Moin 1.x, so documentation from one version will not apply to the other. Introducing MoinMoin @@ -29,7 +29,7 @@ Using MoinMoin user/namespaces user/subscriptions -Administrating MoinMoin +Administering MoinMoin ======================= .. toctree:: @@ -56,16 +56,16 @@ Getting Support for and Contributing to MoinMoin devel/support devel/translate -Developing of MoinMoin -====================== +Developing MoinMoin +===================== .. toctree:: :maxdepth: 2 devel/development -Autogenerated API docs -====================== +Auto-generated API Docs +========================= .. toctree:: :maxdepth: 4 diff --git a/docs/intro/features.rst b/docs/intro/features.rst index fd759c370..5a4127cfa 100644 --- a/docs/intro/features.rst +++ b/docs/intro/features.rst @@ -5,7 +5,7 @@ Features Operating System Support ======================== Moin is implemented in Python, a platform-independent language. -It works on Linux, Mac OS X, Windows, FreeBSD and other OSes that support +It works on Linux, macOS, Windows, FreeBSD and other OSes that support Python. That said, Linux is the preferred and most tested deployment platform and @@ -13,8 +13,8 @@ will likely have fewer issues than, for example, Windows. Servers ======= -* Builtin Python server from werkzeug, which is easy to use. -* Any server that talks WSGI to moin: +* Built-in Python server from Werkzeug, which is easy to use. +* Any server that talks WSGI to Moin: - Apache2 with mod_wsgi - nginx with uwsgi @@ -31,8 +31,8 @@ Servers Authentication ============== -* Builtin - username / password login form of moin, MoinAuth -* Builtin HTTP Basic Auth - browser login form, HTTPAuthMoin +* Built-in - username/password login form of Moin, MoinAuth +* Built-in HTTP Basic Auth - browser login form, HTTPAuthMoin * Auth against LDAP / Active Directory (LDAPAuth) * Any authentication your web server supports via GivenAuth @@ -73,7 +73,7 @@ Storage Backend Types --------------------- * file system * sqlite3 -* everything supported by SQLalchemy +* everything supported by SQLAlchemy * you can easily add your own backend with little code Serialization @@ -108,7 +108,7 @@ Wiki features * Local History for one item ("History") * Diffs between any revision - + text item diffs, rendered nicely with html + + text item diffs, rendered nicely with HTML + image diffs + binary "diff" (same or not same) * Tags / Tag Cloud @@ -122,7 +122,7 @@ Wiki features Markup support -------------- -* Moin Wiki +* MoinWiki * Creole * MediaWiki * reST @@ -148,12 +148,12 @@ Translation / Localization Logging ======= -* Flexible logging provided by `logging` module of python stdlib +* Flexible logging provided by the `logging` module of the Python standard library Technologies ============ -* html5, css, javascript with jquery, svg -* python -* flask, flask-caching, flask-babel, flask-theme, click -* whoosh, werkzeug, pygments, flatland, blinker, babel, emeraldtree -* sqlalchemy (supports all popular SQL DBMS), sqlite, kyoto tycoon/cabinet +* HTML5, CSS, JavaScript with jQuery, SVG +* Python +* Flask, Flask-Caching, Flask-Babel, Flask-Theme, Click +* Whoosh, Werkzeug, Pygments, Flatland, Blinker, Babel, EmeraldTree +* SQLAlchemy (supports all popular SQL DBMS), SQLite, Kyoto Tycoon/Cabinet diff --git a/docs/intro/general.rst b/docs/intro/general.rst index f936b18c6..dc638d348 100644 --- a/docs/intro/general.rst +++ b/docs/intro/general.rst @@ -21,7 +21,7 @@ You can use it: You can use it for: -* your company / organisation, your work group +* your company / organization, your work group * your school, college, or university * your projects and interests * just yourself @@ -31,7 +31,7 @@ You can run it on: * a public web server * an intranet server * your desktop or laptop -* Linux, Mac OS X, Windows, and other OSes +* Linux, macOS, Windows, and other OSes What makes MoinMoin special? @@ -44,9 +44,9 @@ There are lots of wiki engines out there, making it hard to pick one. However, choosing wisely is important because you may have to live with your choice for a long time because switching wiki engines is not easy. -We won't list all of moin's features, because comparing feature lists +We won't list all of Moin's features, because comparing feature lists is just not enough. Some features are best left unimplemented, -even if they sound great at first. In moin, you will find most +even if they sound great at first. In Moin, you will find most important features like in most major wiki engines. But still, you and your wiki users might feel quite a different overall experience just because of a bunch of small, superficial differences. Of course the quality of some features' @@ -57,7 +57,7 @@ MoinMoin has **been around since about 2000**. It has rapidly grown and evolved through moin 1.9.x. Its developers have increased their experience with Python and wiki technology over the years. With **moin 2.0**, there has been a rather **revolutionary cleanup / rewrite** -of how moin works based on that experience. This promises to make it easier, +of how Moin works based on that experience. This promises to make it easier, cleaner, more consistent, more powerful, more flexible and more modular. @@ -65,19 +65,19 @@ Moin is **written in Python**, an easy to read, high-level, object-oriented, dynamic, well-designed and platform-independent programming language. Moin is **Free Software** (that implies that it is **Open Source**) and, -because we use Python, you may even *like* to read and modify moin's code. +because we use Python, you may even *like* to read and modify Moin's code. Who is using MoinMoin? ---------------------- This shows some of the better-known users of MoinMoin: -Web Sites +Websites ~~~~~~~~~ * KernelNewbies, Xen, LinuxWireless, GCC * Debian, Ubuntu, CentOS -* Apache, Gnome, Wine, OpenOffice, Squid, Exim, Dovecot -* Python, ScyPy, TurboGears +* Apache, GNOME, Wine, OpenOffice, Squid, Exim, Dovecot +* Python, SciPy, TurboGears * Mercurial, Darcs * FSFE, FFII, c-base, MusicBrainz * linuxwiki.de, jurawiki.de, ooowiki.de and ... moinmo.in :D diff --git a/docs/intro/glossary.rst b/docs/intro/glossary.rst index 7c4ef4c60..e13d3678c 100644 --- a/docs/intro/glossary.rst +++ b/docs/intro/glossary.rst @@ -13,9 +13,9 @@ Glossary your wiki. contenttype - A formal, standardized way of specifying of which type some data is. - E.g. 'text/plain;charset=utf-8' is the contenttype for some simple piece - of text (encoded using utf-8 encoding), 'image/png' is the contenttype + A formal, standardized way of specifying the type of some data. + For example, 'text/plain;charset=UTF-8' is the contenttype for a simple piece + of text (encoded using UTF-8), and 'image/png' is the contenttype for a PNG image. item @@ -28,21 +28,21 @@ Glossary revision. data - Just the raw data, no more, no less; can be some text, an image, a pdf. + Just the raw data, no more, no less; it can be text, an image, or a PDF. metadata Additional information related to or about some data. For example, if you create a new PDF item revision, the revision data will be the PDF - file's content, but moin will also additionally store revision metadata - that tells that this revision is in fact a PDF (its contenttype - we do not - rely on or require .pdf extension on the item name), when it was saved, - maybe some comment you gave when saving, etc. + file's content, but Moin will also store revision metadata + that indicates this revision is a PDF (its contenttype - we do not + rely on or require a .pdf extension in the item name), when it was saved, + any comment you provided when saving, etc. session - As the protocol (http) used by a web browser is stateless, a means + As the protocol (HTTP) used by web browsers is stateless, a way to keep state is needed. This is usually done by using a cookie stored - within the user's browser. It is used for example to stay logged-in into your - user account or store the trail of items you visited and for easier + in the user's browser. It is used, for example, to stay logged in to your + user account, to store the trail of items you visited, and for easier navigation. wiki engine @@ -66,24 +66,24 @@ Glossary A web site implemented using a wiki engine. WSGI - Web Server Gateway Interface. It is a specification about how web servers, - like e.g. Apache with mod_wsgi, communicate with web applications, like + Web Server Gateway Interface. It is a specification for how web servers, + such as Apache with mod_wsgi, communicate with web applications, such as MoinMoin. It is a Python standard, described in detail in PEP 333. emeraldtree - An XML / tree processing library used by moin. + An XML/tree processing library used by Moin. flask - A micro framework used by moin. + A microframework used by Moin. jinja - A templating engine used by moin. + A templating engine used by Moin (Jinja2). sqlalchemy - An SQL database abstraction library used by moin. + An SQL database abstraction library used by Moin (SQLAlchemy). sqlite - An easy-to-use SQL database used by moin. + An easy-to-use SQL database used by Moin (SQLite). werkzeug - A WSGI library used by moin. + A WSGI library used by Moin (Werkzeug). diff --git a/docs/intro/license.rst b/docs/intro/license.rst index 6c977fe4d..2007b30af 100644 --- a/docs/intro/license.rst +++ b/docs/intro/license.rst @@ -6,8 +6,8 @@ License .. literalinclude:: ../../LICENSE.txt -For a FAQ about the GPL and a copy of the misc. GPL license versions, -please see there: http://www.gnu.org/licenses/gpl.html +For an FAQ about the GPL and copies of various GPL license versions, +please see: https://www.gnu.org/licenses/gpl.html This is the GNU GPL version 2. From file docs/licenses/COPYING: diff --git a/docs/man/moin.rst b/docs/man/moin.rst index 996523557..df89241c3 100644 --- a/docs/man/moin.rst +++ b/docs/man/moin.rst @@ -4,13 +4,13 @@ Moin Command Line Interface =========================== Moin2 has two command line interfaces. The first interface, powered -by quickinstall.py and started by the **./m** command (**m** on windows), +by quickinstall.py and started by the **./m** command (**m** on Windows), implements the most common functions used by developers. -This CLI is only available when moin is installed using git to +This CLI is only available when moin is installed using Git to clone a repository from https://github.com/moinwiki/moin or alternative. The second interface, **moin**, is implemented by several Python scripts -located in the /cli/ directory. This interface targets wiki migration, +located in the cli/ directory. This interface targets wiki migration, account creation and maintenance, and wiki maintenance. There is some overlap between the two interfaces. Several of the commands @@ -21,14 +21,14 @@ cli interface commands to accomplish a task. ------------- The virtual environment must be activated before using the ./m -interface. Executing **./m** (**m** on windows) without any options produces +interface. Executing **./m** (**m** on Windows) without any options produces the menu:: usage: "{0} " where is: quickinstall update virtual environment with required packages extras install packages required for docs and moin development - docs create moin html documentation (requires extras) + docs create moin HTML documentation (requires extras) interwiki refresh intermap.txt log view detailed log generated by , omit to see list diff --git a/docs/user/accounts.rst b/docs/user/accounts.rst index 230a1b65b..580a034ef 100644 --- a/docs/user/accounts.rst +++ b/docs/user/accounts.rst @@ -15,7 +15,7 @@ by clicking the account creation button, and you will be presented with an accou The fields of this form are as follows: Name - Your username on the wiki. Names must not contain "/", ":", or "," characters, invisible unicode + Your username on the wiki. Names must not contain "/", ":", or "," characters, invisible Unicode characters, or leading or trailing whitespace characters. Embedded single space characters are allowed. This is a required field. @@ -33,7 +33,7 @@ E-Mail the wiki. This is a required field. .. note:: - Some wikis require email verification, in which case you will have click an activation link which + Some wikis require email verification, in which case you will have to click an activation link that will be sent to the email address you provide. You must complete this step before you start using the wiki. @@ -44,12 +44,12 @@ E-Mail User Settings ============= -User settings provide a way for to customise your MoinMoin experience and perform account -maintenance functions like changing email address or password. To access your settings page, click +User settings provide a way for you to customize your MoinMoin experience and perform account +maintenance functions like changing your email address or password. To access your settings page, click the :guilabel:`Settings` button at the top of the page. The settings page appears as a list of links to various sub-pages for changing elements of your -wiki experience, each of these sub-pages are listed below: +wiki experience; each of these sub-pages is listed below: Personal Settings ----------------- @@ -66,7 +66,7 @@ Name Display-Name If your wiki has a custom auth method that creates cryptic user names, then - the display-name can be created as an alternative. You will still login using your username + the display-name can be created as an alternative. You will still log in using your username or alias. The display-name will appear as links in history pages and the footer of items you have edited. Use your display-name to create your home page in the users namespace. @@ -100,13 +100,13 @@ Notification Settings Notification settings allow you to configure the way MoinMoin notifies you of changes and important information. -E-Mail - Change the email address MoinMoin sends emails to. +Email + Change the email address MoinMoin sends email to. Wiki Appearance Settings ------------------------ -Appearance settings allow you to customise the look and feel of the wiki. +Appearance settings allow you to customize the look and feel of the wiki. Theme name The bundled MoinMoin wiki theme which you would like to use. @@ -116,7 +116,7 @@ User CSS URL custom stylesheet here. Custom CSS provides an advanced level of control over appearance of MoinMoin pages. -Number rows in edit textarea +Number of rows in edit textarea The size (in lines) of MoinMoin's plain text editor when you edit an item. The default of 0 resizes the textarea to hold the entire document being edited. @@ -143,14 +143,14 @@ The "Options" section allows you to control privacy and advanced features of Moi Always use ISO 8601 date-time format Display dates and times in ISO 8601 format rather than the usual Babel formats - based upon the user's locale. If the UTC time zone is selected, dates and times - will have a "z" suffix indicating the date or time is a UTC Zulu time. + based on the user's locale. If the UTC time zone is selected, dates and times + will have a "Z" suffix indicating the date or time is UTC (Zulu time). Publish my email (not my wiki homepage) in author info Control whether or not other wiki users may see your email address. -Open editor on double click - This option allows you to simply double click the text on any MoinMoin item and have it opened +Open editor on double-click + This option allows you to simply double-click the text on any MoinMoin item and have it opened in the editor. When using the MoinMoin text editor, the textarea caret will be positioned on the paragraph that was clicked. If the textarea is larger than the display window, pressing the right-arrow key will scroll the page so the caret is visible near the bottom of the window. @@ -169,7 +169,7 @@ Special Features for Users with Accounts Your User Page -------------- -You user page is a wiki space in which you may share information about yourself with other users of +Your user page is a wiki space in which you may share information about yourself with other users of that wiki. It can be accessed by clicking the button with your username on it at the top of the screen, and is edited like a normal wiki item. @@ -186,7 +186,7 @@ has only one revision, the icon will indicate the content type. The second column will show the item name, aliases, or item ID (if the item was deleted) at that revision with a link to a revision display. -The remaining columns with display timestamps, sizes, revision numbers, and comments. +The remaining columns will display timestamps, sizes, revision numbers, and comments. Bookmarking ----------- @@ -203,8 +203,8 @@ Quicklinks ---------- At the top of every MoinMoin page, there is a row of buttons for quick access to commonly used MoinMoin -features like the global index, global history and homepage. Often, users need quick access to MoinMoin -items without having to search for them each time - quicklinks allow you to access your favourite wiki +features like the global index, global history, and home page. Often, users need quick access to MoinMoin +items without having to search for them each time — quicklinks allow you to access your favorite wiki items at the click of a button by placing links to them at the top of every page. To quicklink an item, click the :guilabel:`Add Link` button at the top or bottom of a MoinMoin item. To remove a quicklink, simply navigate back to the item and click the :guilabel:`Remove Link` button. diff --git a/docs/user/creolewiki.rst b/docs/user/creolewiki.rst index 881df3e68..974fd9e79 100644 --- a/docs/user/creolewiki.rst +++ b/docs/user/creolewiki.rst @@ -5,9 +5,9 @@ WikiCreole markup overview ========================== -Features currently not working with moin's WikiCreole parser are marked with **CREOLETODO**. +Features currently not working with Moin's WikiCreole parser are marked with **CREOLETODO**. -Features currently not working with moin's rst parser are marked with **reSTTODO**. +Features currently not working with Moin's reST parser are marked with **reSTTODO**. Headings ======== @@ -46,7 +46,7 @@ Level 6 **Notes**: Closing equals signs are optional and do not affect the output. -Also, whitespace between the first word of the heading and the opening equals sign will not be shown in the output (ie. leading whitespace is stripped). +Also, whitespace between the first word of the heading and the opening equals sign will not be shown in the output (i.e., leading whitespace is stripped). Text formatting =============== @@ -58,7 +58,7 @@ The following is a table of inline markup that can be used to format text in Cre +=====================================+=======================================+ | ``**Bold Text**`` | **Bold text** | +-------------------------------------+---------------------------------------+ -| ``//Italic Text//`` | *Italic Text* | +| ``//Italic Text//`` | *Italic text* | +-------------------------------------+---------------------------------------+ | ``//**Bold and Italic**//`` | :bolditalic:`Bold and Italic` | +-------------------------------------+---------------------------------------+ @@ -70,7 +70,7 @@ The following is a table of inline markup that can be used to format text in Cre | | | Second line | +-------------------------------------+---------------------------------------+ -**reSTTODO**: Restructured Text line blocks are not working in Moin2 +**reSTTODO**: reStructuredText line blocks are not working in Moin2 Hyperlinks ========== diff --git a/docs/user/docbook.rst b/docs/user/docbook.rst index ccd67c3b0..1ba37a88b 100644 --- a/docs/user/docbook.rst +++ b/docs/user/docbook.rst @@ -1,16 +1,16 @@ .. contents:: -================== -Docbook XML Markup -================== +=================== +DocBook XML Markup +=================== This page shows the different features of our native DocBook support. A table of contents is automatically generated from section titles. -This content, describing the Docbook syntax, is written in reST. Instances where reST cannot -duplicate the same rendering produced by Docbook are flagged with **reST NOTE**. +This content, describing the DocBook syntax, is written in reST. Instances where reST cannot +duplicate the same rendering produced by DocBook are flagged with **reST NOTE**. The reST parser used by Moin and the parser used by Sphinx are different. @@ -76,7 +76,7 @@ i. One #. Four -**reST NOTE**: should show small roman numbers here +**reST NOTE**: Should show small Roman numerals here. Simple text formatting @@ -105,13 +105,13 @@ Quotes **Markup:**:: - This software is provided as is, without expressed + This software is provided as is, without express or implied warranty. **Results:** -This software is provided "as is", without expressed +This software is provided "as is", without express or implied warranty. @@ -219,7 +219,7 @@ Tables b2 b3 b4 - + Vertical Span diff --git a/docs/user/markdown.rst b/docs/user/markdown.rst index 038e1a9d8..e254841de 100644 --- a/docs/user/markdown.rst +++ b/docs/user/markdown.rst @@ -7,12 +7,12 @@ Markdown Markup This page introduces you to the most important elements of the Markdown syntax. For details on the Python implementation of Markdown see https://python-markdown.github.io/ -In addition to being supported by moin2, the Markdown markup language is used by issue trackers -such as those found in Bitbucket and Github. So what you learn here can be used there also. +In addition to being supported by Moin2, the Markdown markup language is used by issue trackers +such as those found in Bitbucket and GitHub. What you learn here can be used there as well. .. _para3: -Features currently not working with moin's Markdown parser are marked with **MDTODO**. +Features currently not working with Moin's Markdown parser are marked with **MDTODO**. This page, describing the Markdown syntax, is written in reST. Instances where reST cannot duplicate the same rendering produced by Markdown are flagged with **reST NOTE**. @@ -765,3 +765,5 @@ For example, to automatically link URLs: :: class Config(DefaultConfig): ... markdown_extensions = ['pymdownx.magiclink'] + + diff --git a/docs/user/markups.rst b/docs/user/markups.rst index d7163c61e..2604b049b 100644 --- a/docs/user/markups.rst +++ b/docs/user/markups.rst @@ -15,15 +15,15 @@ Markups Supported by MoinMoin .. _MoinWiki: https://moinmo.in/HelpOnMoinWikiSyntax .. _WikiCreole: https://www.wikicreole.org/ .. _reStructuredText: https://docutils.sourceforge.io/rst.html -.. _Docbook: https://docbook.org/ +.. _DocBook: https://docbook.org/ .. _MediaWiki: https://www.mediawiki.org/wiki/Help:Formatting .. _Markdown: https://daringfireball.net/projects/markdown/syntax In Moin2, you specify the item's markup language when you create a new item. -Currently Moin2 supports `MoinWiki`_, `WikiCreole`_, `reStructuredText`_, `Docbook`_, +Currently Moin2 supports `MoinWiki`_, `WikiCreole`_, `reStructuredText`_, `DocBook`_, `MediaWiki`_ and `Markdown`_ markups. Moin2 currently provides output converters for MoinWiki, Markdown, -reST, HTML, and Docbook. +reST, HTML, and DocBook. When viewing any markup item, the item may be converted to a different markup language by clicking the Convert link. diff --git a/docs/user/mediawiki.rst b/docs/user/mediawiki.rst index 39fb26e6d..70e46d723 100644 --- a/docs/user/mediawiki.rst +++ b/docs/user/mediawiki.rst @@ -3,12 +3,12 @@ .. role:: bolditalic ========================= -Mediawiki markup overview +MediaWiki markup overview ========================= -Features currently not working with moin's mediawiki parser are marked with **MWTODO**. +Features currently not working with Moin's MediaWiki parser are marked with **MWTODO**. -Features currently not working with moin's rst parser are marked with **reSTTODO**. +Features currently not working with Moin's reST parser are marked with **reSTTODO**. Headings ======== @@ -64,7 +64,7 @@ These markups can be used within text to apply character style. +------------------------------------+------------------------------------+ | | ``strikethrough`` | :strikethrough:`strikethrough` | | | or | | -| | ``striketrough`` | | +| | ``strikethrough`` | | +------------------------------------+------------------------------------+ | | ``Fixed width`` | ``Fixed width`` | | | or | | diff --git a/docs/user/moinwiki.rst b/docs/user/moinwiki.rst index 5b9575c39..39d2c4a81 100644 --- a/docs/user/moinwiki.rst +++ b/docs/user/moinwiki.rst @@ -8,19 +8,19 @@ ========================== -Moin Wiki markup overview +MoinWiki markup overview ========================== This document describes the features of the moinwiki markup language. -Because this document was created using Restructured Text, which +Because this document was created using reStructuredText, which does not support some of the features available in moinwiki, the -examples below may show both the markup and result as block or -predefined code. +examples below may show both the markup and the result as block or +preformatted code. -Features currently not working with moin's Wiki parser are marked +Features not currently working with Moin's wiki parser are marked with **MOINTODO**. -Table Of Contents +Table of Contents ================= Table of contents: @@ -278,14 +278,14 @@ Lists ===== .. warning:: - * All Moin Wiki list syntax (including that for unordered lists, + * All MoinWiki list syntax (including that for unordered lists, ordered lists and definition lists) requires a leading space before each item in the list. * Unfortunately, reStructuredText does not allow leading whitespace in code samples, so the example markup here will not work if copied verbatim, and requires that each line of the list be indented by one space in order to - be valid Moin Wiki markup. + be valid MoinWiki markup. * This is also an **reSTTODO** Unordered Lists @@ -441,7 +441,7 @@ Definition Lists - reStructuredText does not support multiple definitions for a single term, so a line break has been forced to illustrate the appearance of several definitions. - - Using the prescribed Moin Wiki markup will, in fact, produce two + - Using the prescribed MoinWiki markup will, in fact, produce two separate definitions in MoinMoin (using separate ``
`` tags). Horizontal Rules diff --git a/docs/user/namespaces.rst b/docs/user/namespaces.rst index 667a6f29d..711b2827d 100644 --- a/docs/user/namespaces.rst +++ b/docs/user/namespaces.rst @@ -20,27 +20,27 @@ URL layout ========== ``http://server/[NAMESPACE/][[@FIELD/]VALUE][/+VIEW]`` -Above defines the URL layout, where uppercase letters are variable parts defined below and [] denotes optional. -It basically means search for the item field ``FIELD`` value ``VALUE`` in the namespace ``NAMESPACE`` and apply the -view ``VIEW`` on it. +The above defines the URL layout, where uppercase terms are variables defined below and [] denotes optional segments. +It means: search for items where field ``FIELD`` has value ``VALUE`` in namespace ``NAMESPACE`` and apply the +view ``VIEW`` to it. NAMESPACE Defines the namespace for looking up the item. NAMESPACE value ``all`` is the "namespace doesn't matter" identifier. It is used to access global views like global history, global tags etc. FIELD - Whoosh schema field where to lookup the VALUE (default: ``name_exact``, lookup by name). - FIELD can be a unique identifier like (``itemid, revid, name_exact``) or can be non-unique like (``tags``). + Whoosh schema field to look up the VALUE (default: ``name_exact``, lookup by name). + FIELD can be a unique identifier (``itemid``, ``revid``, ``name_exact``) or non-unique (e.g., ``tags``). VALUE Value to search in the FIELD (default: the default root within that namespace). If the FIELD is non-unique, we show a list of items that have ``FIELD:VALUE``. VIEW - used to select the intended view method (default: ``show``). + Used to select the intended view method (default: ``show``). **Examples**: - The following examples show how a url can look like, ``ns1, ns1/ns2`` are namespaces. + The following examples show how a URL can look, ``ns1`` and ``ns1/ns2`` are namespaces. - ``http://localhost:8080/Home`` - ``http://localhost:8080/ns1/@tags/sometag`` diff --git a/docs/user/rest.rst b/docs/user/rest.rst index 6f4917668..fa3882c37 100644 --- a/docs/user/rest.rst +++ b/docs/user/rest.rst @@ -1,21 +1,21 @@ =============================== -reST (ReStructured Text) Markup +reST (reStructuredText) Markup =============================== .. This document is duplicated within Moin2 as `/docs/user/rest.rst` and `contrib/sample/rst.data`. Please update both. -Depending upon your source, this document may have been created by +Depending on your source, this document may have been created by the Moin2 reST parser (Docutils) or the Sphinx reST parser. These parsers -have slight differences in the rendering of reST markup, some of those differences +have slight differences in the rendering of reST markup. Some of those differences are noted below. The purpose of this document is to define the features of the Moin2 reST (Docutils) parser. The Sphinx extensions to reST markup that are not supported by the Docutils parser are not included here. -See the the Docutils Restructured Text documentation for more information. +See the Docutils reStructuredText documentation for more information. Headings ======== @@ -391,7 +391,7 @@ Field lists are part of an extension syntax for directives usually intended for Option lists ============ -Option lists are intended to document Unix or DOS command line options. +Option lists are intended to document Unix or DOS command-line options. **Markup**:: @@ -532,7 +532,7 @@ Complex tables can have any number of rows or columns. They are made by ``|``, ` +--------------------------------+ One difference between the Sphinx and Moin reST parsers is demonstrated below. -With the Spinx parser, grid table column widths can be expanded by adding spaces. +With the Sphinx parser, grid table column widths can be expanded by adding spaces. **Markup**:: @@ -549,7 +549,7 @@ With the Spinx parser, grid table column widths can be expanded by adding spaces **Notes:** - The Moin2 reST parser does not add the HTML markup added by the Sphinx parser (the width attribute generates an HTML - validation error), nor does it use Javascript to adjust the width of tables. + validation error), nor does it use JavaScript to adjust the width of tables. - Under Moin2, tables and table cells will be of minimal width (unless there is CSS styling to set tables larger). @@ -610,7 +610,7 @@ Comments link within item views. Literal Blocks ============== -Literal blocks are used to show text as-it-is. i.e no markup processing is done within a literal block. +Literal blocks are used to show text as is; i.e., no markup processing is done within a literal block. A minimum (1) indentation is required for the text block to be recognized as a literal block. **Markup**:: diff --git a/docs/user/search.rst b/docs/user/search.rst index b1d3d8583..4bf10c0f1 100644 --- a/docs/user/search.rst +++ b/docs/user/search.rst @@ -5,31 +5,31 @@ Searching and Finding Entering search queries ======================= -To start a search, enter a query into the short query input field and type -enter or click the search icon. By default, the names, summary, tags, content, namengram, -summaryngram, and contentngram fields of each item's last revisions are searched. +To start a search, enter a query into the short query input field and press +Enter or click the search icon. By default, the names, summary, tags, content, namengram, +summaryngram, and contentngram fields of each item's last revision are searched. Deleted items (trash) are excluded. The search results view provides a form for refining the search through -ajax updates. Click the `More Search Options` link to see the form. +AJAX updates. Click the More Search Options link to see the form. A transaction is started each time a character is added or removed -in the search field. If keying is rapid, it is possible that results will -processed out of order. The `Whoosh query` shows the last term processed. +in the search field. If typing is rapid, it is possible that results will be +processed out of order. The Whoosh query shows the last term processed. Clicking the Search Options link displays alternatives for modifying the search. -Ajax updates will be made whenever a radio button or checkbox is changed. +AJAX updates will be made whenever a radio button or checkbox is changed. -Below the search form is the query processed by Whoosh, and Whoosh generated +Below the search form is the query processed by Whoosh, and Whoosh-generated suggestions for additional searches by input, item name, and item content. Finally, the search hits are presented. These are ordered by -the whoosh scoring number. Each hit will contain the item name and some -meta data. If available, the item summary and partial item content with the +the Whoosh scoring number. Each hit will contain the item name and some +metadata. If available, the item summary and partial item content with the search term highlighted will be shown. Simple search queries ===================== -Just enter one or more words into the query input field and hit ``Enter``. +Just enter one or more words into the query input field and press Enter. If your query consists of multiple words, it will only find documents containing ALL those words. You can use AND, OR, NOT to refine your search. "AND" is the default. @@ -67,9 +67,9 @@ Group terms using ():: Redirect to best match ====================== -If you know the target item name, start the search term with a back-slash character. +If you know the target item name, start the search term with a backslash character. Only the names and namengram fields will be searched. If there is a hit, the browser will be -redirected to the highest scoring hit. +redirected to the highest-scoring hit. Examples -------- @@ -103,9 +103,9 @@ Search for something like wiki, willi, wi, ...:: w*i -You can also use it for poor man's language independent word stemming. +You can also use it for a poor man's language-independent word stemming. -Matches on clean, cleaner, cleanest, cleaning, ...:: +Matches on clean, cleaner, cleanest, cleaning, etc.:: clean* @@ -116,7 +116,7 @@ Regular expressions enable even more flexibility for specifying search terms. See https://en.wikipedia.org/wiki/Regular_expression for basics about regexes. -See https://docs.python.org/3/library/re.html about python's regex implementation, +See https://docs.python.org/3/library/re.html about Python's regex implementation, which we use for MoinMoin. You need to use this syntax when entering regexes: r"yourregex" @@ -143,12 +143,12 @@ Search for something like wiki, willi, wi, ...:: Searching an item's subitems ============================ -To limit the search to an item's sub-items, use a leading `>`, followed by the +To limit the search to an item's subitems, use a leading `>`, followed by the item's name, followed by the search arguments. Examples -------- -Wild cards, regular expressions, etc. may be used in the search arguments:: +Wildcards, regular expressions, etc. may be used in the search arguments:: >colors blue >users/JohnDoe red* @@ -157,64 +157,64 @@ Wild cards, regular expressions, etc. may be used in the search arguments:: Searching in specific fields ============================ -If not specified otherwise, moin will search in ``names``, -``tags``, ``summary``, ``comment`` and ``content`` fields. Three fields with -n-gram support are also searched by default: ``namengram``, ``summaryngram`` +If not specified otherwise, Moin will search in ``names``, +``tags``, ``summary``, ``comment``, and ``content`` fields. Three fields with +n-gram support are also searched by default: ``namengram``, ``summaryngram``, and ``contentngram``. N-gram indexing is a powerful method for getting fast, “search as you type” functionality. -A tokinizer splits words within ngram content fields into strings of 3 to 6 characters. -These small strings may be matched against search terms that are tokinized into strings +A tokenizer splits words within n-gram content fields into strings of 3 to 6 characters. +These small strings may be matched against search terms that are tokenized into strings of 3 to 6 characters. -To specify the field to search in, just use the `fieldname:searchterm` syntax. -If embedded spaces are desired then do: `fieldname:"search term"`. Separate +To specify the field to search in, use the `fieldname:searchterm` syntax. +If embedded spaces are desired, use `fieldname:"search term"`. Separate multiple terms with a space: `content:foo tags:Foo` is the same as `content:foo AND tags:Foo`. The following table includes fields that may be useful for searching. -+-------------------------+-------------------------------------------------------+ -| Field name | Field value | -+-------------------------+-------------------------------------------------------+ -| ``acl`` ** | access control list (see below) | -+-------------------------+-------------------------------------------------------+ -| ``address`` | submitter IP address, e.g. 127.0.0.1 | -+-------------------------+-------------------------------------------------------+ -| ``comment`` | editor comment on save, rename, etc. | -+-------------------------+-------------------------------------------------------+ -| ``content`` | document contents, e.g. This is some example content. | -+-------------------------+-------------------------------------------------------+ -| ``contentngram`` ** | document contents, tokenized by 3 to 6 characters. | -+-------------------------+-------------------------------------------------------+ -| ``contenttype`` | document type: text, image, audio, moinwiki, jpg, ... | -+-------------------------+-------------------------------------------------------+ -| ``itemlinks`` ** | link targets of the document, e.g. OtherItem | -+-------------------------+-------------------------------------------------------+ -| ``itemtransclusions`` **| transclusion targets of the document, e.g. OtherItem | -+-------------------------+-------------------------------------------------------+ -| ``language`` | (main) language of the document contents, e.g. en | -+-------------------------+-------------------------------------------------------+ -| ``mtime`` | document modification (submission) date, 2011-08-07 | -+-------------------------+-------------------------------------------------------+ -| ``namengram`` ** | document names, tokenized by 3 to 6 characters. | -+-------------------------+-------------------------------------------------------+ -| ``names`` | document names, e.g. Home, MyWikiPage | -+-------------------------+-------------------------------------------------------+ -| ``namespace`` | namespace:"" for default or namespace:users | -+-------------------------+-------------------------------------------------------+ -| ``name_exact`` | same as ``name``, but is not tokenized | -+-------------------------+-------------------------------------------------------+ -| ``name_old`` | name_old:* for all renamed items | -+-------------------------+-------------------------------------------------------+ -| ``summary`` | summary text, if provided by author | -+-------------------------+-------------------------------------------------------+ -| ``summaryngram`` ** | summary text, tokenized by 3 to 6 characters. | -+-------------------------+-------------------------------------------------------+ -| ``tags`` | tags of the document, e.g. important, hard, todo | -+-------------------------+-------------------------------------------------------+ -| ``username`` | submitter user name, e.g. JoeDoe | -+-------------------------+-------------------------------------------------------+ ++-------------------------+--------------------------------------------------------------+ +| Field name | Field value | ++-------------------------+--------------------------------------------------------------+ +| ``acl`` ** | access control list (see below) | ++-------------------------+--------------------------------------------------------------+ +| ``address`` | submitter IP address, e.g. 127.0.0.1 | ++-------------------------+--------------------------------------------------------------+ +| ``comment`` | editor comment on save, rename, etc. | ++-------------------------+--------------------------------------------------------------+ +| ``content`` | document contents, e.g. This is some example content. | ++-------------------------+--------------------------------------------------------------+ +| ``contentngram`` ** | document contents, tokenized by 3 to 6 characters. | ++-------------------------+--------------------------------------------------------------+ +| ``contenttype`` | document type: text, image, audio, MoinWiki, JPG, ... | ++-------------------------+--------------------------------------------------------------+ +| ``itemlinks`` ** | link targets of the document, e.g. OtherItem | ++-------------------------+--------------------------------------------------------------+ +| ``itemtransclusions`` **| transclusion targets of the document, e.g. OtherItem | ++-------------------------+--------------------------------------------------------------+ +| ``language`` | (main) language of the document contents, e.g. en | ++-------------------------+--------------------------------------------------------------+ +| ``mtime`` | document modification (submission) date, e.g. 2025-12-31 | ++-------------------------+--------------------------------------------------------------+ +| ``namengram`` ** | document names, tokenized by 3 to 6 characters. | ++-------------------------+--------------------------------------------------------------+ +| ``names`` | document names, e.g. Home, MyWikiPage | ++-------------------------+--------------------------------------------------------------+ +| ``namespace`` | namespace:"" for default or namespace:users | ++-------------------------+--------------------------------------------------------------+ +| ``name_exact`` | same as ``names``, but is not tokenized | ++-------------------------+--------------------------------------------------------------+ +| ``name_old`` | name_old:* for all renamed items | ++-------------------------+--------------------------------------------------------------+ +| ``summary`` | summary text, if provided by author | ++-------------------------+--------------------------------------------------------------+ +| ``summaryngram`` ** | summary text, tokenized by 3 to 6 characters. | ++-------------------------+--------------------------------------------------------------+ +| ``tags`` | tags of the document, e.g. important, hard, TODO | ++-------------------------+--------------------------------------------------------------+ +| ``username`` | submitter username, e.g. JoeDoe | ++-------------------------+--------------------------------------------------------------+ ** These fields exist only in the current revisions index, see Notes below. @@ -225,7 +225,7 @@ Search in metadata fields:: contenttype:text contenttype:image/jpeg tags:todo - mtime:2022-01-08 # use ISO 8601 dates, not time; `mtime:2022-01 works + mtime:2022-01-08 # use ISO 8601 dates; `mtime:2022-01` works address:127.0.0.1 username:JoeDoe @@ -236,35 +236,35 @@ Search items with an item ACL that explicitly gives Joe read rights:: Notes ===== -There are two indexes. The smaller index is used by default. It only indexes the -current revision of each item. The larger index is used when the `All` radio -button under the Search Options link is selected. The larger indexes all -revisions of all items including revisions of deleted items. As noted in the table -above the larger index omits several fields to save space. +There are two indexes. The smaller index is used by default. It indexes only the +current revision of each item. The larger index is used when the All radio +button under the Search Options link is selected. The larger index includes all +revisions of all items, including revisions of deleted items. As noted in the table +above, the larger index omits several fields to save space. By default, all namespaces are searched, including the userprofiles index. Because -the userprofiles index is normally read restricted, hits will be blocked and included -as `n items are not shown because read permission was denied` at the bottom of the page. +the userprofiles index is normally read-restricted, hits will be blocked and included +as “n items are not shown because read permission was denied” at the bottom of the page. Items with transcluded content do not contain the transcluded content within the -item's index. An item containing "foo" within its content and trancluding an item with +item's index. An item containing "foo" within its content and transcluding an item with "bar" within its content cannot be matched by searching for "foo AND bar". Both items will be matched by searching for "foo OR bar". Moin only uses an indexed search. Keep in mind that this has some special properties: - * By using an index, the search is fast - * Because it is only using an index, it can only find what was put there - * If you use wildcards or regexes, it will still use the index, but in a different, slower way +* By using an index, the search is fast. +* Because it uses only an index, it can find only what was put there. +* If you use wildcards or regexes, it will still use the index, but in a different, slower way. For example: - * create an item with "FooBar" in the name, content, summary, tag, and comment fields - * search for "ooba" - the namengram, summaryngram, and contentngram will match - * search for "FooBar": names, namengram, tags, summary, summaryngram, content, - contentngram, and comment will match - * search for "foobar": names, namengram, summary, summaryngram, content, contentngram, - and comment will match +* create an item with "FooBar" in the name, content, summary, tag, and comment fields +* search for "ooba" — the namengram, summaryngram, and contentngram will match +* search for "FooBar": names, namengram, tags, summary, summaryngram, content, + contentngram, and comment will match +* search for "foobar": names, namengram, summary, summaryngram, content, contentngram, + and comment will match More information ================ diff --git a/docs/user/subscriptions.rst b/docs/user/subscriptions.rst index a0836de34..a57964cd5 100644 --- a/docs/user/subscriptions.rst +++ b/docs/user/subscriptions.rst @@ -2,7 +2,7 @@ User Subscriptions ================== -Users can subscribe to moin items in order to receive notifications about item +Users can subscribe to Moin items to receive notifications about item changes. Item changes include: * creation of a new item @@ -14,7 +14,7 @@ changes. Item changes include: * destruction of a revision * destruction of all item's revisions -Make sure that Moin is able to send E-Mails, see :ref:`mail-configuration`. +Make sure that Moin is able to send emails; see :ref:`mail-configuration`. Types of subscriptions ====================== @@ -28,24 +28,24 @@ There are 5 types of subscriptions: *Subscribe* on item's page, then you will be subscribed using this type. * by item name (`name::`), - The user will be notified, if the name matches any of the item names and also - its namespace. Keep in mind that an item can be renamed and notifications for - this item would stop working if the new name doesn't match any more. + The user will be notified if the name matches any of the item names and also + its namespace. Keep in mind that an item can be renamed, and notifications for + this item would stop working if the new name doesn't match anymore. * by tag name (`tags::`) - The user will be notified, if the tag name matches any of the item tags and + The user will be notified if the tag name matches any of the item tags and its namespace. * by a prefix name (`nameprefix::`) - Used for subscription to a set of items. The user will be notified, if at least - one of the item names starts with the given prefix and matches item's namespace. - For example if you want to receive notifications about all the items from the + Used for subscription to a set of items. The user will be notified if at least + one of the item names starts with the given prefix and matches the item's namespace. + For example, if you want to receive notifications about all the items from the default namespace whose name starts with `foo`, you can use `nameprefix::foo`. * by a regular expression (`namere::`) - Used for subscription to a set of items. The user will be notified, if the - regexp matches any of the item names and also its namespace. For example, - if you want to receive notifications about all the items on wiki from the default + Used for subscription to a set of items. The user will be notified if the + regular expression matches any of the item names and also its namespace. For example, + if you want to receive notifications about all the items on the wiki from the default namespace, then you can use `namere::.*` @@ -53,11 +53,11 @@ Editing subscriptions ===================== The itemid subscription is the most common one and will be used if you click on -*Subscribe* on item's page. Respectively the *Unsubscribe* will remove the itemid +*Subscribe* on the item's page. Conversely, *Unsubscribe* will remove the itemid subscription. -If you were subscribed to an item by some other way rather than itemid subscription, -then on *Unsubscribe* you will be told that it is impossible to remove the subscription +If you were subscribed to an item by some method other than an itemid subscription, +then on *Unsubscribe* you will be told that it is not possible to remove the subscription and you need to edit it manually in the User Settings. All the subscriptions can be added/edited/removed in the User Settings, diff --git a/docs/user/templates_metadata.rst b/docs/user/templates_metadata.rst index b3e935f5c..acc0f5c3d 100644 --- a/docs/user/templates_metadata.rst +++ b/docs/user/templates_metadata.rst @@ -1,22 +1,22 @@ -======================= -Templates and Meta Data -======================= +====================== +Templates and Metadata +====================== -Two features that are related to the creation, editing and saving of an -item are templates and meta data. +Two features that are related to the creation, editing, and saving of an +item are templates and metadata. Templates ========= Templates make it easier for users to create new items that are similar to many other items. -Instead of starting from scratch or using a copy, paste, and modify technique; +Instead of starting from scratch or using a copy, paste, and modify technique, templates that contain the common text and structure can be created. A template item must have a tag of "template". When creating a new item, if there are available templates for -the selected content type and namespace, then an extra step added to the -create item dialog allows the editor to choose a template. If a template is selected, the +the selected content type and namespace, then an extra step is added to the +create item dialog that allows the editor to choose a template. If a template is selected, the content of the template item will be loaded and copied to the modify screen's textarea. @@ -28,19 +28,19 @@ of the available templates. Templates may define data for the ACL, Summary, and Tags fields. These values will be copied to the modify form within the item creation dialog; note the `template` tag will not be copied. Users wanting to create a new template using an old -template will need to rekey the `template` tag. +template will need to re-enter the `template` tag. For templates with MoinWiki markup, Predefined Variables can be used to insert -date, time, user name, item name, and others. See Predefined Variables -in the Moin Wiki markup overview. +date, time, username, item name, and others. See Predefined Variables +in the MoinWiki markup overview. The example below is a very simple template for the **users** namespace. Each user -is encouraged to create a home page using the 4-line moinwiki markup template. +is encouraged to create a home page using the 4-line MoinWiki markup template. **@ITEM@** and **@EMAIL@** are predefined variables and will be replaced with -the item name (the new item name is expected to be the user's name) and the users +the item name (the new item name is expected to be the user's name) and the user's email address (copied from the current user's settings) when the item is saved. To create a home page, each user begins the creation of a new item in the **users** namespace, -selects the template, keys in a nickname and hobbies, and saves the item.:: +selects the template, enters a nickname and hobbies, and saves the item.:: = @ITEM@ = Nickname: @@ -48,12 +48,12 @@ selects the template, keys in a nickname and hobbies, and saves the item.:: Email: @EMAIL@ -Meta Data +Metadata ========= When an item is edited (including non-text items like images, etc.), -most themes provide a means of updating certain meta data -associated with the item. The meta data fields that may be updated by +most themes provide a means of updating certain metadata +associated with the item. The metadata fields that may be updated by all editors include Summary, Tags, and Names. Users with admin authority on the item may update the item's ACLs. @@ -62,7 +62,7 @@ authorization. Most themes will display the Summary field above the item's content. The use of this field is optional. When used, it may contain a one-line -summary of the pages content, a TODO list of additional content that +summary of the page's content, a TODO list of additional content that should be added or verified, or other special instructions to future readers and editors. @@ -80,6 +80,6 @@ While most items will have a single name, item editors may add or delete multiple names. Editors may find multiple names useful when renaming or merging items. Item names cannot span multiple namespaces. Most themes will show all item names within the Page Trail panel. Some reports, such as -History, will show all item names in a single row. Other reports which are +History, will show all item names in a single row. Other reports that are sorted by name, such as Index and Tags, will show each name in a separate row. diff --git a/docs/user/upload.rst b/docs/user/upload.rst index 4ebc7387a..3bf4574e2 100644 --- a/docs/user/upload.rst +++ b/docs/user/upload.rst @@ -5,7 +5,7 @@ File Upload File upload functionality is accessed through the +modify item view or the Index view. -To upload a file on the +modify item view, click the browsers Browse/Choose +To upload a file on the +modify item view, click the browser's Browse/Choose button. Use the browser's file dialog to select an item, then click the OK button. The file will be uploaded and saved with the previously chosen content type; file name suffixes are ignored. @@ -14,21 +14,21 @@ To upload a file or files on the global index navigation view, start by clicking the `New Item` link to bring the `Create new item` dialog into view. -From the Index view, there are two methods of uploading files, single file or multiple files. -Uploaded files will be logically placed within the current index, sub-index or namespace. +From the Index view, there are two methods of uploading files: single file or multiple files. +Uploaded files will be logically placed within the current index, sub-index, or namespace. Multiple file uploads have several restrictions: * the files will be uploaded and saved using the current name * existing items with the same name will be overwritten * the file names should have a valid suffix that defines the file type - * files without a known suffix will be stored as is and available for download + * files without a known suffix will be stored as-is and available for download Single File Upload ================== Enter the new item name into the input area and click the `Create` button. Select the content type to proceed to the +modify view. -Use the browsers file dialog to select an item, then click the OK button. +Use the browser's file dialog to select an item, then click the OK button. The file will be uploaded and saved with the chosen content type; file name suffixes are ignored. @@ -36,9 +36,9 @@ file name suffixes are ignored. Multiple File Upload ==================== -Click the browsers Browse/Choose button and select one or more files from the browser's -file dialog or use the drag & drop method to copy files. +Click the browser's Browse/Choose button and select one or more files from the browser's +file dialog, or use the drag-and-drop method to copy files. The file uploads will start immediately. Upload status will be displayed by overall and individual progress bars. The names of the files successfully uploaded will be -prepended to list of files in the index. +prepended to the list of files in the index. diff --git a/src/moin/constants/contenttypes.py b/src/moin/constants/contenttypes.py index a6513eda8..fe54e8f14 100644 --- a/src/moin/constants/contenttypes.py +++ b/src/moin/constants/contenttypes.py @@ -173,7 +173,7 @@ def ext_link(href, link_text=None): CONTENTTYPES_HELP_DOCS = { # content type: tuple - content type, button text; link generated later based on user preferred language - "text/x.moin.wiki;charset=utf-8": (("moin", _("Click for help on Moin Wiki markup."))), + "text/x.moin.wiki;charset=utf-8": (("moin", _("Click for help on MoinWiki markup."))), "text/x.moin.wiki;format=1.9;charset=utf-8": (("moin", _("Moinmoin 1.9 format is deprecated, convert to moin 2."))), "text/x-mediawiki;charset=utf-8": (("mediawiki", _("Click for help on Media Wiki markup."))), "text/x.moin.creole;charset=utf-8": (("creole", _("Click for help on Creole Wiki markup."))), diff --git a/src/moin/help/help-en/Home.data b/src/moin/help/help-en/Home.data index 10199638a..07f8bcd8d 100644 --- a/src/moin/help/help-en/Home.data +++ b/src/moin/help/help-en/Home.data @@ -28,7 +28,7 @@ Because of the way the Markdown parser is constructed, it is frequently not poss * [[help-en/moin]] - * [[../moin|Moin Wiki markup item]] + * [[../moin|MoinWiki markup item]] * [[../creole|Creole Wiki markup item]] * [[../rst|ReST markup item]] * [[../markdown|Markdown markup item]] diff --git a/src/moin/help/help-en/MoinWikiMacros.data b/src/moin/help/help-en/MoinWikiMacros.data index 321d3136f..4e0287be9 100644 --- a/src/moin/help/help-en/MoinWikiMacros.data +++ b/src/moin/help/help-en/MoinWikiMacros.data @@ -1,4 +1,4 @@ -= Moin Wiki Macros = += MoinWiki Macros = With the exception of the markup supported within FootNotes, the MoinWiki and CreoleWiki parsers have identical macro syntax and features. The contents of this MoinWiki page will yield similar results when copied to a CreoleWiki page. diff --git a/src/moin/help/help-en/moin.data b/src/moin/help/help-en/moin.data index 9bdba5c6f..2e931ee74 100644 --- a/src/moin/help/help-en/moin.data +++ b/src/moin/help/help-en/moin.data @@ -1,4 +1,4 @@ -= Moin Wiki Syntax = += MoinWiki Syntax = == Table Of Contents ==