Skip to content

Commit

Permalink
doc: Use scdoc to write and generate man pages (#299)
Browse files Browse the repository at this point in the history 
`scdoc` is much more user friendly, simpler to read / write & more "digest" than `groff`.
See #296 for the rational about the `scdoc` choice.

Note that this introduces two new targets in the `Makefile`:

- build (default target): Used to generate and archive the man pages (the generation of the `.mo` translation files has been moved here as well).
- clean: Used to clean up the project directory of files man pages generated during build (the deletion of the generated `.mo` translation files has been moved here as well).

Closes #296
  • Loading branch information
@Antiz96
Antiz96 authored Jan 20, 2025
1 parent 8e82be1 commit 6749a94
Show file tree
Hide file tree
Showing 12 changed files with 785 additions and 829 deletions.
6 changes: 6 additions & 0 deletions .github/workflows/CI.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,5 +26,11 @@ jobs:
- name: Run pylint
run: find . -name '*.py' -exec pylint -d E0611,E0401,C0103,C0301 --output-format=colorized {} +

- name: Run make clean
run: make clean

- name: Run make
run: make

- name: Run make test
run: make test
62 changes: 38 additions & 24 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,28 @@ _pkgname=Arch-Update

PREFIX ?= /usr/local

.PHONY: all install test uninstall
.PHONY: build test install clean uninstall

all:
build:
# Generate man pages
scdoc < "doc/man/${pkgname}.1.scd" > "doc/man/${pkgname}.1"
scdoc < "doc/man/${pkgname}.conf.5.scd" > "doc/man/${pkgname}.conf.5"
scdoc < "doc/man/fr/${pkgname}.1.scd" > "doc/man/fr/${pkgname}.1"
scdoc < "doc/man/fr/${pkgname}.conf.5.scd" > "doc/man/fr/${pkgname}.conf.5"

# Archive man pages
gzip -c "doc/man/${pkgname}.1" > "doc/man/${pkgname}.1.gz"
gzip -c "doc/man/${pkgname}.conf.5" > "doc/man/${pkgname}.conf.5.gz"
gzip -c "doc/man/fr/${pkgname}.1" > "doc/man/fr/${pkgname}.1.gz"
gzip -c "doc/man/fr/${pkgname}.conf.5" > "doc/man/fr/${pkgname}.conf.5.gz"

# Generate translations files
msgfmt po/fr.po -o po/fr.mo
msgfmt po/sv.po -o po/sv.mo

test:
# Run some simple unit tests on basic functions
bats test/case/basic_functions.bats

install:
# Install main script
Expand All @@ -27,33 +46,21 @@ install:
install -Dm 644 "res/systemd/${pkgname}.timer" "${DESTDIR}${PREFIX}/lib/systemd/user/${pkgname}.timer"
install -Dm 644 "res/systemd/${pkgname}-tray.service" "${DESTDIR}${PREFIX}/lib/systemd/user/${pkgname}-tray.service"

# Generate and install .mo files for translations
# .mo files are installed as "Arch-Update.mo" to avoid conflicting with the "arch-update.mo" files shipped by the arch-update Gnome extension (https://extensions.gnome.org/extension/1010/archlinux-updates-indicator/)
msgfmt po/fr.po -o po/fr.mo
msgfmt po/sv.po -o po/sv.mo
install -Dm 644 po/fr.mo "${DESTDIR}${PREFIX}/share/locale/fr/LC_MESSAGES/${_pkgname}.mo"
install -Dm 644 po/sv.mo "${DESTDIR}${PREFIX}/share/locale/sv/LC_MESSAGES/${_pkgname}.mo"
rm -f po/fr.mo
rm -f po/sv.mo

# Install shell completions
install -Dm 644 "res/completions/${pkgname}.bash" "${DESTDIR}${PREFIX}/share/bash-completion/completions/${pkgname}"
install -Dm 644 "res/completions/${pkgname}.zsh" "${DESTDIR}${PREFIX}/share/zsh/site-functions/_${pkgname}"
install -Dm 644 "res/completions/${pkgname}.fish" "${DESTDIR}${PREFIX}/share/fish/vendor_completions.d/${pkgname}.fish"

# Archive and install man pages
gzip -c "doc/man/${pkgname}.1" > "doc/man/${pkgname}.1.gz"
gzip -c "doc/man/${pkgname}.conf.5" > "doc/man/${pkgname}.conf.5.gz"
gzip -c "doc/man/fr/${pkgname}.1" > "doc/man/fr/${pkgname}.1.gz"
gzip -c "doc/man/fr/${pkgname}.conf.5" > "doc/man/fr/${pkgname}.conf.5.gz"
# Install man pages
install -Dm 644 "doc/man/${pkgname}.1.gz" "${DESTDIR}${PREFIX}/share/man/man1/${pkgname}.1.gz"
install -Dm 644 "doc/man/${pkgname}.conf.5.gz" "${DESTDIR}${PREFIX}/share/man/man5/${pkgname}.conf.5.gz"
install -Dm 644 "doc/man/fr/${pkgname}.1.gz" "${DESTDIR}${PREFIX}/share/man/fr/man1/${pkgname}.1.gz"
install -Dm 644 "doc/man/fr/${pkgname}.conf.5.gz" "${DESTDIR}${PREFIX}/share/man/fr/man5/${pkgname}.conf.5.gz"
rm -f "doc/man/${pkgname}.1.gz"
rm -f "doc/man/${pkgname}.conf.5.gz"
rm -f "doc/man/fr/${pkgname}.1.gz"
rm -f "doc/man/fr/${pkgname}.conf.5.gz"

# Install translations files
# Translations files are installed as "Arch-Update.mo" to avoid conflicting with the "arch-update.mo" files shipped by the arch-update Gnome extension (https://extensions.gnome.org/extension/1010/archlinux-updates-indicator/)
install -Dm 644 po/fr.mo "${DESTDIR}${PREFIX}/share/locale/fr/LC_MESSAGES/${_pkgname}.mo"
install -Dm 644 po/sv.mo "${DESTDIR}${PREFIX}/share/locale/sv/LC_MESSAGES/${_pkgname}.mo"

# Install documentation
install -Dm 644 README.md "${DESTDIR}${PREFIX}/share/doc/${pkgname}/README.md"
Expand All @@ -62,6 +69,17 @@ install:
# Install example config
install -Dm 644 "res/config/${pkgname}.conf.example" "${DESTDIR}${PREFIX}/share/${pkgname}/config/${pkgname}.conf.example"

clean:
# Delete generated and archived man pages
rm -f "doc/man/${pkgname}.1"{,.gz}
rm -f "doc/man/${pkgname}.conf.5"{,.gz}
rm -f "doc/man/fr/${pkgname}.1"{,.gz}
rm -f "doc/man/fr/${pkgname}.conf.5"{,.gz}

# Delete generated translations files
rm -f po/fr.mo
rm -f po/sv.mo

uninstall:
# Delete main script
rm -f "${DESTDIR}${PREFIX}/bin/${pkgname}"
Expand Down Expand Up @@ -98,7 +116,3 @@ uninstall:

# Delete documentation folder
rm -rf "${DESTDIR}${PREFIX}/share/doc/${pkgname}/"

test:
# Run some simple unit tests on basic functions
bats test/case/basic_functions.bats
68 changes: 38 additions & 30 deletions README-fr.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,18 +63,26 @@ Dépendances optionnelles supplémentaires dont vous pourriez avoir besoin ou qu
- [vim](https://archlinux.org/packages/extra/x86_64/vim/) : Programme de fusion par défaut pour pacdiff
- [qt6-wayland](https://archlinux.org/packages/extra/x86_64/qt6-wayland/) : Support de l'applet systray sur Wayland

Installez les dépendances de compilation requises :

```bash
sudo pacman -S --asdeps make scdoc bats
```

Téléchargez l'archive de la [dernière version stable](https://github.com/Antiz96/arch-update/releases/latest) et extrayez la *(vous pouvez également cloner ce référentiel via `git clone`)*.

Pour installer `arch-update`, allez dans le répertoire extrait / cloné et exécutez la commande suivante :
Pour installer `arch-update`, allez dans le répertoire extrait / cloné et exécutez les commandes suivantes :

```bash
sudo make
sudo make test
sudo make install
```

Si vous voulez exécuter des tests unitaires simples, vous pouvez exécuter la commande suivante (requiert [bats](https://archlinux.org/packages/extra/any/bats/)) :
Une fois l'installation terminée, vous pouvez optionnellement nettoyer le répertoire des fichiers générés durant l'installation en exécutant cette commande :

```bash
make test
sudo make clean
```

Pour désinstaller `arch-update`, allez dans le répertoire extrait / cloné et exécutez la commande suivante :
Expand Down Expand Up @@ -189,35 +197,35 @@ de fichiers pacnew & pacsave, de mise à jour du noyau en attente ainsi que des
et, s'il y en a, propose de les traiter.
Options :
-c, --check Vérifier les mises à jour disponibles, changer l'icône du systray et envoyer une notification de bureau contenant le nombre de mises à jour disponibles (s'il y a des nouvelles mises à jour disponibles depuis le dernier check)
-l, --list Afficher la liste des mises à jour en attente
-d, --devel Inclure les mises à jour des paquets de développement AUR
-n, --news [Num] Afficher les dernieres Arch News, vous pouvez optionellement spécifier le nombre de Arch news à afficher avec `--news [Num]` (e.g. `--news 10`)
-D, --debug Afficher les traces de débogage
--gen-config Générer un fichier de configuration `arch-update.conf` par défaut / exemple (voir la page de manuel arch-update.conf(5) pour plus de détails), vous pouvez optionnellement passer l'argument `--force` pour écraser un fichier de configuration `arch-update.conf` existant
--show-config Afficher le fichier de configuration `arch-update.conf` actuellement utilisé (s'il existe)
--edit-config Editer le fichier de configuration `arch-update.conf` actuellement utilisé (s'il existe)
--tray Lancer l'applet systray d'Arch-Update, vous pouvez optionnellement ajouter l'argument `--enable` pour la démarrer automatiquement au démarrage du système.
-h, --help Afficher ce message d'aide et quitter
-V, --version Afficher les informations de version et quitter
-c, --check Vérifier les mises à jour disponibles, changer l'icône du systray et envoyer une notification de bureau contenant le nombre de mises à jour disponibles (s'il y a des nouvelles mises à jour disponibles depuis le dernier check).
-l, --list Afficher la liste des mises à jour en attente.
-d, --devel Inclure les mises à jour des paquets de développement AUR.
-n, --news [Num] Afficher les dernieres Arch News, vous pouvez optionellement spécifier le nombre de Arch news à afficher avec `--news [Num]` (e.g. `--news 10`).
-D, --debug Afficher les traces de débogage.
--gen-config Générer un fichier de configuration `arch-update.conf` par défaut / exemple (voir la page de manuel arch-update.conf(5) pour plus de détails), vous pouvez optionnellement passer l'argument `--force` pour écraser un fichier de configuration `arch-update.conf` existant.
--show-config Afficher le fichier de configuration `arch-update.conf` actuellement utilisé (s'il existe).
--edit-config Editer le fichier de configuration `arch-update.conf` actuellement utilisé (s'il existe).
--tray Lancer l'applet systray d'Arch-Update, vous pouvez optionnellement ajouter l'argument `--enable` pour la démarrer automatiquement au démarrage du système..
-h, --help Afficher ce message d'aide et quitter.
-V, --version Afficher les informations de version et quitter.
Codes de sortie :
0 OK
1 Option invalide
2 Aucune commande d'élévation de privilège (sudo, doas ou run0) n'est installée ou celle définie dans le fichier de configuration `arch-update.conf` n'est pas disponible
3 Erreur lors du lancement de l'applet systray d'Arch-Update
4 L'utilisateur n'a pas donné la confirmation de procéder
5 Erreur lors de la mise à jour des paquets
6 Erreur lors de l'appel de la commande reboot pour appliquer une mise à jour du noyau en attente
7 Aucune mise à jour en attente durant l'utilisation de l'option `-l / --list`
8 Erreur lors de la génération d'un fichier de configuration avec l'option `--gen-config`
9 Erreur lors de la lecture du fichier de configuration avec l'option `--show-config`
10 Erreur lors de la creation du fichier desktop autostart pour l'applet systray avec l'option `--tray --enable`
11 Erreur lors du redémarrage des services nécessitant un redémarrage après mise à jour
12 Erreur lors du traitement des fichiers pacnew
13 Erreur lors de l'édition du fichier de configuration avec l'option `--edit-config`
14 Le dossier de librairies n'a pas été trouvé
15 L'éditeur "diff prog" défini dans le fichier de configuration `arch-update.conf` n'est pas disponible
0 OK.
1 Option invalide.
2 Aucune commande d'élévation de privilège (sudo, doas ou run0) n'est installée ou celle définie dans le fichier de configuration `arch-update.conf` n'est pas disponible.
3 Erreur lors du lancement de l'applet systray d'Arch-Update.
4 L'utilisateur n'a pas donné la confirmation de procéder.
5 Erreur lors de la mise à jour des paquets.
6 Erreur lors de l'appel de la commande reboot pour appliquer une mise à jour du noyau en attente.
7 Aucune mise à jour en attente durant l'utilisation de l'option `-l / --list`.
8 Erreur lors de la génération d'un fichier de configuration avec l'option `--gen-config`.
9 Erreur lors de la lecture du fichier de configuration avec l'option `--show-config`.
10 Erreur lors de la creation du fichier desktop autostart pour l'applet systray avec l'option `--tray --enable`.
11 Erreur lors du redémarrage des services nécessitant un redémarrage après mise à jour.
12 Erreur lors du traitement des fichiers pacnew.
13 Erreur lors de l'édition du fichier de configuration avec l'option `--edit-config`.
14 Le dossier de librairies n'a pas été trouvé.
15 L'éditeur "diff prog" défini dans le fichier de configuration `arch-update.conf` n'est pas disponible.
```

Pour plus d'informations, consultez la page de manuel arch-update(1).
Expand Down
72 changes: 40 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,18 +63,26 @@ Additional optional dependencies you might need or want:
- [vim](https://archlinux.org/packages/extra/x86_64/vim/): Default merge program for pacdiff
- [qt6-wayland](https://archlinux.org/packages/extra/x86_64/qt6-wayland/): Systray applet support on Wayland

Install required build dependencies:

```bash
sudo pacman -S --asdeps make scdoc bats
```

Download the archive of the [latest stable release](https://github.com/Antiz96/arch-update/releases/latest) and extract it *(alternatively, you can clone this repository via `git clone`)*.

To install `arch-update`, go into the extracted / cloned directory and run the following command:
To install `arch-update`, go into the extracted / cloned directory and run the following commands:

```bash
sudo make
sudo make test
sudo make install
```

If you want to run simple unit tests, you can run the following command (requires [bats](https://archlinux.org/packages/extra/any/bats/)):
Once the installation is complete, you may optionally clean up the directory of files generated during installation by running the following command:

```bash
make test
sudo make clean
```

To uninstall `arch-update`, go into the extracted / cloned directory and run the following command:
Expand Down Expand Up @@ -189,35 +197,35 @@ pending kernel update, as well as services requiring a post upgrade restart and,
offers to process them.
Options:
-c, --check Check for available updates, change the systray icon and send a desktop notification containing the number of available updates (if there are new available updates compared to the last check)
-l, --list Display the list of pending updates
-d, --devel Include AUR development packages updates
-n, --news [Num] Display latest Arch News, you can optionally specify the number of Arch news to display with `--news [Num]` (e.g. `--news 10`)
-D, --debug Display debug traces
--gen-config Generate a default / example `arch-update.conf` configuration file (see the arch-update.conf(5) man page for more details), you can optionally pass the `--force` argument to overwrite any existing `arch-update.conf` configuration file
--show-config Display the `arch-update.conf` configuration file currently used (if it exists)
--edit-config Edit the `arch-update.conf` configuration file currently used (if it exists)
--tray Launch the Arch-Update systray applet, you can optionally add the `--enable` argument to start it automatically at boot.
-h, --help Display this help message and exit
-V, --version Display version information and exit
-c, --check Check for available updates, change the systray icon and send a desktop notification containing the number of available updates (if there are new available updates compared to the last check).
-l, --list Display the list of pending updates.
-d, --devel Include AUR development packages updates.
-n, --news [Num] Display latest Arch News, you can optionally specify the number of Arch news to display with `--news [Num]` (e.g. `--news 10`).
-D, --debug Display debug traces.
--gen-config Generate a default / example `arch-update.conf` configuration file (see the arch-update.conf(5) man page for more details), you can optionally pass the `--force` argument to overwrite any existing `arch-update.conf` configuration file.
--show-config Display the `arch-update.conf` configuration file currently used (if it exists).
--edit-config Edit the `arch-update.conf` configuration file currently used (if it exists).
--tray Launch the Arch-Update systray applet, you can optionally add the `--enable` argument to start it automatically at boot..
-h, --help Display this help message and exit.
-V, --version Display version information and exit.
Exit Codes:
0 OK
1 Invalid option
2 No privilege elevation command (sudo, doas or run0) is installed or the one set in the `arch-update.conf` configuration file isn't found
3 Error when launching the Arch-Update systray applet
4 User didn't gave the confirmation to proceed
5 Error when updating the packages
6 Error when calling the reboot command to apply a pending kernel update
7 No pending update when using the `-l / --list` option
8 Error when generating a configuration file with the `--gen-config` option
9 Error when reading the configuration file with the `--show-config` option
10 Error when creating the autostart desktop file for the systray applet with the `--tray --enable` option
11 Error when restarting services that require a post upgrade restart
12 Error during the pacnew files processing
13 Error when editing the configuration file with the `--edit-config` option
14 Libraries directory not found
15 The diff prog editor set in the `arch-update.conf` configuration file isn't found
0 OK.
1 Invalid option.
2 No privilege elevation command (sudo, doas or run0) is installed or the one set in the `arch-update.conf` configuration file isn't found.
3 Error when launching the Arch-Update systray applet.
4 User didn't gave the confirmation to proceed.
5 Error when updating the packages.
6 Error when calling the reboot command to apply a pending kernel update.
7 No pending update when using the `-l / --list` option.
8 Error when generating a configuration file with the `--gen-config` option.
9 Error when reading the configuration file with the `--show-config` option.
10 Error when creating the autostart desktop file for the systray applet with the `--tray --enable` option.
11 Error when restarting services that require a post upgrade restart.
12 Error during the pacnew files processing.
13 Error when editing the configuration file with the `--edit-config` option.
14 Libraries directory not found.
15 The diff prog editor set in the `arch-update.conf` configuration file isn't found.
```

For more information, see the arch-update(1) man page.
Expand All @@ -238,8 +246,8 @@ The supported options are:
- NoColor # Do not colorize output.
- NoVersion # Do not show versions changes for packages when listing pending updates (including when using the `-l / --list` option).
- NewsNum=[Num] # Number of Arch news to display before updating and with the `-n / --news` option (see the arch-update(1) man page for more details). Defaults to 5.
- AURHelper=[AUR Helper] # AUR helper to be used for AUR packages support. Valid values are `paru`, `yay` or `pikaur`. If this option is not set, Arch-Update will use the first available AUR helper in the following order: `paru` then `yay` then `pikaur` (in case none of them is installed, Arch-Update will not take AUR packages into account).
- PrivilegeElevationCommand=[Cmd] # Command to be used for privilege elevation. Valid values are `sudo`, `doas` or `run0`. If this option is not set, Arch-Update will use the first available command in the following order: `sudo`, `doas` then `run0`.
- AURHelper=[AUR Helper] # AUR helper to be used for AUR packages support. Valid values are `paru`, `yay` or `pikaur`. If this option is not set, Arch-Update will use the first AUR helper available in the following order: `paru` then `yay` then `pikaur` (in case none of them is installed, Arch-Update will not take AUR packages into account).
- PrivilegeElevationCommand=[Cmd] # Command to be used for privilege elevation. Valid values are `sudo`, `doas` or `run0`. If this option is not set, Arch-Update will use the first command available in the following order: `sudo`, `doas` then `run0`.
- KeepOldPackages=[Num] # Number of old packages' versions to keep in pacman's cache. Defaults to 3.
- KeepUninstalledPackages=[Num] # Number of uninstalled packages' versions to keep in pacman's cache. Defaults to 0.
- DiffProg=[Editor] # Editor to use to visualize / edit differences during the pacnew files processing. Defaults to the `$DIFFPROG` environment variable's value (or `vimdiff` if `$DIFFPROG` isn't set).
Expand Down
Loading

0 comments on commit 6749a94

Please sign in to comment.