render README.md in a Github action

.github/workflows/readme.yml

@@ -0,0 +1,42 @@
+on:
+  push:
+    paths:
+      - README.md.in
+  pull_request:
+    paths:
+      - README.md.in
+  workflow_dispatch:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install vim
+        uses: rhysd/action-setup-vim@v1.3.2
+        id: vim
+      - name: Render README.md
+        run: |
+          sudo apt-get install -y pandoc
+          mkdir .vim
+          git clone https://github.com/jonathanfilip/vim-lucius vim-lucius
+          wget https://github.com/lyokha/vim-publish-helper/archive/refs/tags/0.15.tar.gz \
+              -Ovim-publish-helper.tar.gz
+          tar xvf vim-publish-helper.tar.gz
+          wget https://github.com/lyokha/vim-publish-helper/releases/download/0.15/vimhl-0.15-ghc-9.8 \
+              -Ovimhl
+          chmod a+x vimhl
+          sed '1s/.*/&\nset runtimepath^=vim-lucius,vim-publish-helper-0.15/' \
+               .vimrc.pandoc
+          pandoc -fmarkdown -tgfm -Fvimhl README.md.in > README.md
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email \
+              "github-actions[bot]@users.noreply.github.com"
+          git commit README.md -m "Render README.md"
+          git remote set-url origin \
+              "https://lyokha:${{ secrets.GITHUB_COMMIT_README }}@github.com"`
+             `"/${{ github.repository }}"
+          git push origin master
+

.vimrc.pandoc

@@ -0,0 +1,25 @@
+set nocompatible
+
+filetype off    " filetype is set by vimhl
+
+let g:lucius_style = 'light'
+let g:lucius_contrast = 'high'
+let g:lucius_contrast_bg = 'high'
+let g:lucius_no_term_bg = 1
+colorscheme lucius
+
+syntax on
+
+if !exists('g:PhHtmlPreAttrs')
+    let g:PhHtmlPreAttrs = 'style="overflow-x: auto; background: #FFE"'
+endif
+
+if exists('g:PhBlockRole') && g:PhBlockRole == 'gfm-output'
+    let g:PhHtmlPreAttrs = 'style="overflow-x: auto; '.
+            \ 'border-style: none none none solid; border-color: #6DF; '.
+            \ 'border-width: 3px; padding: 5px 10px"'
+endif
+
+runtime plugin/publish_helper.vim
+
+" vim: ft=vim

README.md.in

@@ -0,0 +1,192 @@
+# g3kb-switch
+
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/lyokha/g3kb-switch/master.svg)](https://results.pre-commit.ci/latest/github/lyokha/g3kb-switch/master)
+[![github/workflow](https://github.com/lyokha/g3kb-switch/actions/workflows/main.yml/badge.svg)](https://github.com/lyokha/g3kb-switch/actions)
+
+This is a CLI keyboard layout switcher for _Gnome 3_ and _4x_. It is not based
+on the X interface but rather implements direct D-Bus messaging with the Gnome
+Shell.
+
+## Installation
+
+### Install
+
+You can directly install this program by:
+
+_In Arch Linux_, this program can be got from
+[AUR](https://aur.archlinux.org/packages/g3kb-switch).
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| paru -S g3kb-switch
+```
+
+_In Fedora_.
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| sudo dnf install g3kb-switch
+```
+
+_In Nix / NixOS_, official repository have included it.
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| nix-env -iA nixos.g3kb-switch
+```
+
+You can just run this program without installing it to your OS by
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| nix run 'github#lyokha/g3kb-switch' -- --help
+```
+
+### Prerequisites
+
+Build requires _glib-2.0_, so you need to install the corresponding development
+package.
+
+_In Ubuntu._
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| sudo apt-get install libglib2.0-dev
+```
+
+_In Fedora / RHEL / CentOS._
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| sudo dnf install glib2-devel
+```
+
+_In Gentoo._
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| sudo emerge -av dev-libs/glib
+```
+
+Commands may differ in other Linux distributions.
+
+### Gnome 45 and newer
+
+Build and install the switcher.
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| cmake -Bbuild
+||| cmake --build build
+||| sudo cmake --install build
+```
+
+In _Gnome 41_ and newer, the switcher will only work with _G3kbSwitch Gnome
+Shell extension_, because method _org.gnome.Shell.Eval_ which was used in the
+original implementation of the switcher is now disabled for security reasons.
+Note that in _Gnome 41_ through _44_ the extension differs from that which is
+required in _Gnome 45_, see build instructions for older Gnome versions in the
+next section.
+
+You can use [unsafe-mode-menu](https://github.com/linushdot/unsafe-mode-menu) to
+toggle unsafe mode.
+
+After installing the extension, restart Gnome Shell for changes to take effect.
+
+It is wise to make sure that the extension is enabled and works correctly. To
+enable the extension, use program _gnome-extensions-app_ or command-line program
+_gnome-extensions_.
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| gnome-extensions enable g3kb-switch@g3kb-switch.org
+||| gnome-extensions info g3kb-switch@g3kb-switch.org
+g3kb-switch@g3kb-switch.org
+  Name: G3kbSwitch
+  Description: G3kbSwitch helper
+  Path: /usr/local/share/gnome-shell/extensions/g3kb-switch@g3kb-switch.org
+  URL: https://github.com/lyokha/g3kb-switch
+  Version: 1
+  State: ENABLED
+```
+
+A small smoke-test of the extension.
+
+<!-- markdownlint-disable MD013 -->
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| gdbus call --session --dest org.gnome.Shell --object-path /org/g3kbswitch/G3kbSwitch --method org.g3kbswitch.G3kbSwitch.List
+(true, '[{"key":"0","value":"ru"},{"key":"1","value":"us"}]')
+||| gdbus call --session --dest org.gnome.Shell --object-path /org/g3kbswitch/G3kbSwitch --method org.g3kbswitch.G3kbSwitch.Get
+(true, '1')
+||| gdbus call --session --dest org.gnome.Shell --object-path /org/g3kbswitch/G3kbSwitch --method org.g3kbswitch.G3kbSwitch.Set 1
+(true, '')
+```
+
+<!-- markdownlint-enable MD013 -->
+
+### Older versions of Gnome (41 through 44)
+
+Older versions of Gnome Shell require a different implementation of the
+extension. In this case, the cmake configuration step requires one extra option.
+
+Build and install the switcher.
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| cmake -Bbuild -DG3KBSWITCH_WITH_LEGACY_GNOME_SHELL_EXTENSION=ON
+||| cmake --build build
+||| sudo cmake --install build
+```
+
+### Even older versions of Gnome (3.x and 40)
+
+Even older versions of Gnome Shell expose method _org.gnome.Shell.Eval_ which
+means that the switcher can be built to work with this method rather than using
+the extension. In this case, the cmake configuration step requires one extra
+option.
+
+Build and install the switcher.
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| cmake -Bbuild -DG3KBSWITCH_WITH_GNOME_SHELL_EXTENSION=OFF
+||| cmake --build build
+||| sudo cmake --install build
+```
+
+### Package
+
+After `cmake --build build`, run:
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| cd build
+||| # generate *.deb for debian/ubuntu
+||| cpack -G DEB
+||| # generate *.rpm for redhat
+||| cpack -G RPM
+```
+
+## Usage
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+Usage: g3kb-switch [-p]      Show the current layout group
+       g3kb-switch -l        Show available layout groups
+       g3kb-switch -n        Switch to the next layout group
+       g3kb-switch -s ARG    Switch to layout group ARG
+       g3kb-switch -h        Show this message and exit
+       g3kb-switch -v        Show the program version and exit
+```
+
+## Integration with vim-xkbswitch
+
+Basically, put in _.vimrc_ lines
+
+```vim
+let g:XkbSwitchEnabled = 1
+let g:XkbSwitchLib = '/usr/local/lib64/libg3kbswitch.so'
+```
+
+Variable _g:XkbSwitchLib_ must contain the actual path to the installed library.
+The path can be found with _pkg-config_.
+
+``` {.shelloutput hl="vim" vars="PhBlockRole=gfm-output"}
+||| pkg-config g3kb-switch --variable libpath
+/usr/local/lib64/libg3kbswitch.so
+```
+
+Notice that setting this variable is optional because vim-xkbswitch tries its
+best to autodetect the path.
+
+See details about configuration rules for vim-xkbswitch
+[here](https://github.com/lyokha/vim-xkbswitch#basic-configuration).
+