Improve the documentation

* Simplify the main README.md
* Moved more detailed documentations into a new docs/ directory

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - main.py slimmed down by about 5000 lines
 - The new widgets.py is a bit fat though (~4000 lines)
+- Cleaned the README.md and moved the documentation to docs/
 
 ### Fixed
 - The intense code cleaning seems to have fixed a bug with the `-c` argument

README.md

@@ -18,17 +18,7 @@ Some key features of Diffuse:
 * Unlimited undo
 * Easy keyboard navigation
 
-## Requirements
+## Installation
-
-Diffuse is implemented entirely in Python and should run on any platform with
-Python and PyGObject.
-
-* Python >= 3.4
-* PyGObject >= 3.18
-
-## Users
-
-### Installing using Flatpak
 
 This is the easiest way to install Diffuse:
 
@@ -36,97 +26,10 @@ This is the easiest way to install Diffuse:
 flatpak install io.github.mightycreak.Diffuse
 ```
 
-## Translators
+## Documentation
 
-Please refer to the [translation documentation](po/README.md).
+For a more detailed documentation for users, translators and developers, see
-
+the [documentation](docs/).
-## Developers
-
-### Setup
-
-#### Run Diffuse from source
-
-To run Diffuse from the source code, type this:
-```sh
-python main.py
-```
-
-To debug with VS Code, open the directory in VS Code, place your breakpoints and hit F5.
-
-#### Build Diffuse
-
-To build Diffuse, type this:
-```sh
-python setup.py build
-```
-
-To run from the build, type this:
-```sh
-PYTHONPATH=build/lib ./build/scripts-3.7/diffuse
-```
-
-#### Install Diffuse locally
-
-Diffuse build system is meson.
-
-To install diffuse locally:
-
-```sh
-meson setup build
-cd build
-meson compile
-meson install # requires admin privileges
-```
-
-To uninstall diffuse afterwards:
-
-```sh
-sudo ninja uninstall -C build
-sudo rm -v /usr/local/share/locale/*/LC_MESSAGES/diffuse.mo
-```
-
-Meson allows to change the default installation directories, see
-[command-line documentation](https://mesonbuild.com/Commands.html#configure).
-
-### Installing on Windows
-
-The `windows-installer` directory contains scripts for building an installable
-package for Windows that includes all dependencies.
-
-Diffuse can be packaged as a portable application by copying the installation
-directory to a pen drive and creating a front end that sets the
-`XDG_CONFIG_HOME` and `XDG_DATA_DIR` environment variables prior to launching
-Diffuse.  The `XDG_CONFIG_HOME` and `XDG_DATA_DIR` environment variables
-indicate where Diffuse should store persistent settings (eg. the path to a
-writable directory on the pen drive).
-
-## Building and testing the Flatpak package
-
-To install Diffuse locally:
-
-```sh
-flatpak install runtime/org.gnome.Sdk/$(uname -p)/3.38
-flatpak-builder build-flatpak --user --install io.github.mightycreak.Diffuse.yml
-```
-
-To run Diffuse through Flatpak:
-
-```sh
-flatpak run io.github.mightycreak.Diffuse
-```
-
-To uninstall Diffuse:
-
-```sh
-flatpak remove io.github.mightycreak.Diffuse
-```
-
-## Help Documentation
-
-Diffuse's help documentation is written in the DocBook format and can be easily
-converted into other formats using XSLT stylesheets.  If the local help
-documentation or its browser are unavailable, Diffuse will attempt to display
-the on-line help documentation using a web browser.
 
 ## Licenses
 

docs/README.md

@@ -0,0 +1,9 @@
+# Diffuse documentation
+
+Welcome to Diffuse documentation!
+
+Here are the main sections:
+
+1. [Users](users.md)
+2. [Translators](translators.md)
+3. [Developers](developers.md)

docs/developers.md

@@ -0,0 +1,63 @@
+# Developers documentation
+
+## Setup on Linux
+
+### Build, test and install using Flatpak
+
+To install Diffuse locally:
+
+```sh
+flatpak install runtime/org.gnome.Sdk/$(uname -p)/3.38
+flatpak-builder build-flatpak --user --install io.github.mightycreak.Diffuse.yml
+```
+
+To run Diffuse through Flatpak:
+
+```sh
+flatpak run io.github.mightycreak.Diffuse
+```
+
+To uninstall Diffuse:
+
+```sh
+flatpak remove io.github.mightycreak.Diffuse
+```
+
+### Build, test and install using Meson
+
+Diffuse build system is meson.
+
+To install diffuse locally:
+
+```sh
+meson setup build
+cd build
+meson compile
+meson test
+meson install # requires admin privileges
+```
+
+To uninstall diffuse afterwards:
+
+```sh
+sudo ninja uninstall -C build
+sudo rm -v /usr/local/share/locale/*/LC_MESSAGES/diffuse.mo
+```
+
+Meson allows to change the default installation directories, see
+[command-line documentation](https://mesonbuild.com/Commands.html#configure).
+
+## Setup on Windows
+
+_Note:_ The Windows port is not maintained and would need some love.
+Contributions are very welcome! 😉
+
+The `windows-installer` directory contains scripts for building an installable
+package for Windows that includes all dependencies.
+
+Diffuse can be packaged as a portable application by copying the installation
+directory to a pen drive and creating a front end that sets the
+`XDG_CONFIG_HOME` and `XDG_DATA_DIR` environment variables prior to launching
+Diffuse.  The `XDG_CONFIG_HOME` and `XDG_DATA_DIR` environment variables
+indicate where Diffuse should store persistent settings (eg. the path to a
+writable directory on the pen drive).

docs/translators.md

@@ -1,5 +1,4 @@
-User Interface
+# Translators documentation
-==============
 
 Below are basic instructions for adding and maintaining Gettext translations
 for Diffuse.  The installer will discover .po files in this directory and
@@ -9,8 +8,7 @@ The example commands below show how to create and manage the Japanese
 translations.  Replace all instances of "ja" with the code for the desired
 language.
 
-Create PO template
+## Create PO template
-------------------
 
 To create or update the PO template (`po/diffuse.pot`), use this command at the
 repo root:
@@ -19,8 +17,7 @@ repo root:
 xgettext -o po/diffuse.pot -f po/POTFILES.in
 ```
 
-Create a new translation
+## Create a new translation
-------------------------
 
 To create a new translation file, you'll need a PO template. If not already
 created, refer to previous section "Create PO template".
@@ -39,8 +36,7 @@ created, refer to previous section "Create PO template".
 [gedit]: https://www.flathub.org/apps/details/org.gnome.gedit
 [vim]: https://www.vim.org/
 
-Update a translation
+## Update a translation
---------------------
 
 Use `update-translations.py` to update one or more PO files.
 
@@ -57,8 +53,7 @@ This command also validate the files, so if you see a message saying "N
 untranslated messages", use the text editor of your choice to complete the
 translations.
 
-Validate a translation
+## Validate a translation
-----------------------
 
 Use `update-translations.py` to validate one or more PO files.
 
@@ -69,8 +64,9 @@ Command-line:
 ./update-translations.py --check-only ja.po ko.po
 ```
 
-System Integration
+## Windows-specific files
-==================
+
+### Installer
 
 Localized text for the Microsoft Windows installer is stored in separate ISL
 files. Copy the [English version][english-win-docs] and replace the text to the
@@ -78,16 +74,19 @@ right of each equal sign.
 
 [english-win-docs]: ../windows-installer/en.isl
 
-Documentation
+### DocBook
-=============
 
-Documentation is stored in DocBook format.  Start a new translation of the
+Diffuse's help documentation is written in the DocBook format and can be easily
-manual by copying the English version of the [DocBook manual][docbook-manual]
+converted into other formats using XSLT stylesheets. If the local help
-and then edit the contents.
+documentation or its browser are unavailable, Diffuse will attempt to display
+the on-line help documentation using a web browser.
+
+Start a new translation of the manual by copying the English version of the
+[DocBook manual][docbook-manual] and then edit the contents.
 
 The DocBook manual is converted to HTML for Windows and Unix man pages for
-POSIX platforms.  The conversion tools insert some English text that gets
+POSIX platforms. The conversion tools insert some English text that gets
-localized using search and replace.  Manually add new search and replace rules
+localized using search and replace. Manually add new search and replace rules
 to these files:
 
     ../windows-installer/translations.txt

docs/users.md

@@ -0,0 +1,9 @@
+# Users documentation
+
+## Requirements
+
+Diffuse is implemented in Python and should run on any platform with Python and
+PyGObject.
+
+* Python >= 3.4
+* PyGObject >= 3.18