Reword the documentation to take care of Mac OS too

.markdownlint.json

@@ -0,0 +1,6 @@
+{
+    "default": true,
+    "no-duplicate-heading": false,
+    "no-inline-html": false,
+    "no-emphasis-as-heading": false
+}

docs/developers/developers-setup.md

@@ -63,34 +63,42 @@ For developer tools, run this one instead (it includes requirements.txt):
 pip install -r requirements.dev.txt
 ```
 
-## Setup on Linux
+## Setup
 
-### Build, test and install using Flatpak
+### Setup on Linux using Flatpak
 
-To install Diffuse locally:
+#### Build, test and install
+
+To build, test and install Diffuse locally:
 
 ```sh
 flatpak install runtime/org.gnome.Sdk/$(uname -p)/42
 flatpak-builder --user --install build-flatpak io.github.mightycreak.Diffuse.yml
 ```
 
+#### Run
+
 To run Diffuse through Flatpak:
 
 ```sh
 flatpak run io.github.mightycreak.Diffuse
 ```
 
+#### Uninstall
+
 To uninstall Diffuse:
 
 ```sh
 flatpak remove io.github.mightycreak.Diffuse
 ```
 
-## Build, test and install using Meson on Linux and Mac OS
+### Setup on Linux using Meson
 
-Diffuse build system is meson.
+#### Build and test
 
-To compile and test Diffuse:
+Diffuse is using Meson as its build system.
+
+To build and test Diffuse:
 
 ```sh
 meson setup build
@@ -99,55 +107,81 @@ meson compile
 meson test
 ```
 
+#### Install on system and run
+
 To install Diffuse on your system (e.g. `/usr/local/`):
 
 ```sh
 meson install # requires admin privileges
+```
 
-# Run Diffuse
+To run Diffuse:
+
+```sh
 diffuse
 ```
 
-To install Diffuse on a custom directory (e.g. `~/bin/diffuse`):
+#### Install in a custom directory and run
+
+Meson allows to change the default installation directories, see
+[command-line documentation](https://mesonbuild.com/Commands.html#configure).
+
+To install Diffuse in a custom directory (e.g. `~/bin/diffuse`):
 
 ```sh
 meson install --destdir ~/bin/diffuse
-
-# Run Diffuse
-cd ~/bin/diffuse/usr/local/bin
-PYTHONPATH=$HOME/bin/diffuse/usr/local/share/diffuse ./diffuse
 ```
 
-To uninstall diffuse afterwards:
+To run Diffuse:
+
+```sh
+export PYTHONPATH=$HOME/bin/diffuse/usr/local/share/diffuse
+cd ~/bin/diffuse/usr/local/bin
+./diffuse
+```
+
+#### Uninstall
+
+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 Mac OS
 
-## Setup on Mac OS
+#### Build and test
 
-Building on Mac OS is similar to building on Linux. To recap, these are
-the steps needed to build and install Diffuse manually:
+Diffuse is using Meson as its build system.
 
-```brew install meson python3 py3cairo pygobject3 gtk+3 librsvg
-  meson setup build
-  cd build
-  meson compile
-  meson test
-  meson install
+To build and test Diffuse:
+
+```sh
+meson setup build
+cd build
+meson compile
+meson test
 ```
 
-After `meson install`, the `diffuse` command can be used to launch Diffuse
-as a native Mac app that is installed into `/Applications/Diffuse.app`.
+#### Install on system and run
 
-The `diffuse` command is compatible with git. To use Diffuse as git's
-`git difftool` run `git config --global diff.tool diffuse`
+To install Diffuse on your system (e.g. `/usr/local/`):
 
-## Setup on Windows
+```sh
+meson install # requires admin privileges
+```
+
+To run Diffuse:
+
+```sh
+diffuse
+```
+
+_Note: The `diffuse` command can be used to launch Diffuse as a native Mac app_
+_that is installed into `/Applications/Diffuse.app`._
+
+### Setup on Windows (deprecated)
 
 _Note:_ The Windows port is not maintained and would need some love.
 Contributions are very welcome! 😉

docs/developers/release-process.md

@@ -19,16 +19,16 @@ few manual steps.
    - data/usr/share/gnome/help/diffuse/*/diffuse.xml
    - data/usr/share/omf/diffuse/diffuse-*.omf
    - utils/book2manual.xsl
-3. Update CHANGELOG.md
+4. Update CHANGELOG.md
    - Add new line under `## Unreleased` following this syntax: `## x.y.z - YYYY-MM-DD`
    - Copy the content of the changes for this release
-4. Update AppData release notes in data/io.github.mightycreak.Diffuse.appdata.xml.in:
+5. Update AppData release notes in data/io.github.mightycreak.Diffuse.appdata.xml.in:
    - Create a new `<release>` tag under `<releases>`, fill the `version` and
      `date` attributes
    - Create a new `<description>` tag under the new `<release>` tag
    - Add one paragraph to sum the release in one sentence (e.g. highlights, ...)
    - Paste the changes from the changelog and adapt it to HTML
-5. Create new branch and PR
+6. Create new branch and PR
 
 ## Create new release on GitHub
 

docs/translators.md

@@ -70,6 +70,7 @@ Use `update-translations.py` to validate one or more PO files.
 Here is an example with `ja.po` and `ko.po`:
 
 Command-line:
+
 ```sh
 ./update-translations.py --check-only ja.po ko.po
 ```
@@ -99,8 +100,10 @@ POSIX platforms. The conversion tools insert some English text that gets
 localized using search and replace. Manually add new search and replace rules
 to these files:
 
-    ../windows-installer/translations.txt
-    ../utils/translations.txt
+```text
+../windows-installer/translations.txt
+../utils/translations.txt
+```
 
 The format of each line is: \<language id\>:\<English text\>:\<localised text\>
 

docs/users.md

@@ -22,3 +22,12 @@ The Diffuse package statuses for every distributions can been seen on
 
 Huge thanks to [@bongochong](https://github.com/bongochong) for maintaining the
 Diffuse package on Fedora.
+
+## Integrate with Git
+
+Diffuse is compatible with `git difftool` command-line. To use Diffuse as Git
+diff tool, run:
+
+```sh
+git config --global diff.tool diffuse
+```