From 6622792e718a7347622cbd5e20b24d28c351b298 Mon Sep 17 00:00:00 2001 From: Romain Failliot Date: Sun, 23 Oct 2022 16:32:04 -0400 Subject: [PATCH] Reword the documentation to take care of Mac OS too --- .markdownlint.json | 6 ++ docs/developers/developers-setup.md | 92 ++++++++++++++++++++--------- docs/developers/release-process.md | 6 +- docs/translators.md | 7 ++- docs/users.md | 9 +++ 5 files changed, 86 insertions(+), 34 deletions(-) create mode 100644 .markdownlint.json diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..8d91412 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,6 @@ +{ + "default": true, + "no-duplicate-heading": false, + "no-inline-html": false, + "no-emphasis-as-heading": false +} diff --git a/docs/developers/developers-setup.md b/docs/developers/developers-setup.md index 9813a3d..af78da6 100644 --- a/docs/developers/developers-setup.md +++ b/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! 😉 diff --git a/docs/developers/release-process.md b/docs/developers/release-process.md index b9a01f0..79ed8fc 100644 --- a/docs/developers/release-process.md +++ b/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 `` tag under ``, fill the `version` and `date` attributes - Create a new `` tag under the new `` 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 diff --git a/docs/translators.md b/docs/translators.md index ff986fa..ec3e222 100644 --- a/docs/translators.md +++ b/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: \:\:\ diff --git a/docs/users.md b/docs/users.md index 1c3fbe8..f858cc2 100644 --- a/docs/users.md +++ b/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 +```