From 67affb7b4621f4b7089956d280b0737d245de852 Mon Sep 17 00:00:00 2001 From: sterni Date: Wed, 5 Feb 2025 19:49:29 +0100 Subject: [PATCH] docs(sterni/acme): move mkbqnkeyboard.bqn docs into its own file I'll probably have this added to the BQN website's editor support page. It'll probably be less confusing if the page people are sent to doesn't have information on random, semi-related stuff. Change-Id: I75e03afea1362e022923ef8781b35113bf26b2e9 Reviewed-on: https://cl.tvl.fyi/c/depot/+/13116 Autosubmit: sterni Reviewed-by: sterni Tested-by: BuildkiteCI --- users/sterni/acme/README.md | 60 ++---------------------------- users/sterni/acme/mkbqnkeyboard.md | 60 ++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 56 deletions(-) create mode 100644 users/sterni/acme/mkbqnkeyboard.md diff --git a/users/sterni/acme/README.md b/users/sterni/acme/README.md index 36d246bf6..c3ccb1ea0 100644 --- a/users/sterni/acme/README.md +++ b/users/sterni/acme/README.md @@ -5,62 +5,10 @@ from [Plan 9][]. ## mkbqnkeyboard.bqn -[mkbqnkeyboard.bqn][] is a script that updates a given Plan 9 `/lib/keyboard` -file to support the familiar [BQN keymap][] via compose sequences. Since -it uses the GNU Readline [inputrc distributed with BQN][inputrc] as a database -for the keymap, you can use a [remapped][] version of the layout. -Once applied, you'll be able to type the Unicode characters used by BQN -via Compose followed by \\ and the -mapped ASCII character. For details on the file and what button -is used for Compose, refer to -[keyboard(6)][p9f-keyboard] (see also -[plan9port's keyboard(7)][p9p-keyboard], [9front's keyboard(6)][9front-keyboard] etc.). - -TIP: [mkbqnkeyboard.bqn][] has only been tested with [plan9port][], -so the instructions below may not work with every Plan 9 variant. -If you have any any information on/trouble with getting it to work on -a proper Plan 9 (fork), feel free to [let me know][me] or -[send a patch][submitting-patches]. - -The process for updating `/lib/keyboard` with [mkbqnkeyboard.bqn][] is a follows: - -1. Prerequisites: - - - [CBQN][] (other BQN implementations are untested) - - A local checkout of [mlochbaum/BQN][], - `aecb56a323aa` is the latest tested revision. - -2. Run - - ./mkbqnkeyboard.bqn -i /path/to/mlochbaum/BQN/editors/inputrc /path/to/lib/keyboard - - If you omit `-i`, the modified `keyboard` file will be printed to stdout instead - of written to the file. If you add `-s`, the result will be sorted by (resulting) codepoint. - -3. If you're using **plan9port**, you'll need to - - 1. Apply [latin1-increase-compose-capacity.patch][] since the default compose - sequence lookup table is too small to hold all the mappings BQN adds. - 2. Recompile plan9port. - - Other Plan 9 variants may also require extra steps. - -4. The compose sequences should now work in the [acme][] and [sam][] text editors - as well as all other Plan 9 programs. +Script to generate Plan 9 `/lib/keyboard` entries providing compose +sequences for the Unicode characters used by [BQN][]. For usage +instructions, refer to [its own documentation](./mkbqnkeyboard.md). [acme]: https://9p.io/sys/doc/acme/acme.pdf -[sam]: https://9p.io/sys/doc/sam/sam.pdf [Plan 9]: https://p9f.org/about.html -[BQN keymap]: https://mlochbaum.github.io/BQN/keymap.html -[me]: https://grep.tvl.fyi/search/?q=%20path%3Aops%2Fusers%2Fdefault.nix%20name%20%3D%20%22sterni%22%3B&fold_case=auto®ex=false&context=true -[mkbqnkeyboard.bqn]: ./mkbqnkeyboard.bqn -[inputrc]: https://github.com/mlochbaum/BQN/blob/master/editors/inputrc -[remapped]: https://mlochbaum.github.io/BQN/editors/index.html#alternate-layouts -[p9f-keyboard]: https://p9f.org/magic/man2html/6/keyboard -[p9p-keyboard]: https://9fans.github.io/plan9port/man/man7/keyboard.html -[9front-keyboard]: http://man.9front.org/6/keyboard -[plan9port]: https://9fans.github.io/plan9port/ -[submitting-patches]: https://code.tvl.fyi/about/docs/REVIEWS.md -[mlochbaum/BQN]: https://github.com/mlochbaum/BQN -[CBQN]: https://github.com/dzaima/cbqn -[latin1-increase-compose-capacity.patch]: ./plan9port/latin1-increase-compose-capacity.patch \ No newline at end of file +[BQN]: https://mlochbaum.github.io/BQN/ diff --git a/users/sterni/acme/mkbqnkeyboard.md b/users/sterni/acme/mkbqnkeyboard.md new file mode 100644 index 000000000..744004aab --- /dev/null +++ b/users/sterni/acme/mkbqnkeyboard.md @@ -0,0 +1,60 @@ +# mkbqnkeyboard.bqn + +[mkbqnkeyboard.bqn][] is a script that updates a given Plan 9 `/lib/keyboard` +file to support the familiar [BQN keymap][] via compose sequences. Since +it uses the GNU Readline [inputrc distributed with BQN][inputrc] as a database +for the keymap, you can use a [remapped][] version of the layout. +Once applied, you'll be able to type the Unicode characters used by BQN +via Compose followed by \\ and the +mapped ASCII character. For details on the file and what button +is used for Compose, refer to +[keyboard(6)][p9f-keyboard] (see also +[plan9port's keyboard(7)][p9p-keyboard], [9front's keyboard(6)][9front-keyboard] etc.). + +TIP: [mkbqnkeyboard.bqn][] has only been tested with [plan9port][], +so the instructions below may not work with every Plan 9 variant. +If you have any any information on/trouble with getting it to work on +a proper Plan 9 (fork), feel free to [let me know][me] or +[send a patch][submitting-patches]. + +The process for updating `/lib/keyboard` with [mkbqnkeyboard.bqn][] is a follows: + +1. Prerequisites: + + - [CBQN][] (other BQN implementations are untested) + - A local checkout of [mlochbaum/BQN][], + `aecb56a323aa` is the latest tested revision. + +2. Run + + ./mkbqnkeyboard.bqn -i /path/to/mlochbaum/BQN/editors/inputrc /path/to/lib/keyboard + + If you omit `-i`, the modified `keyboard` file will be printed to stdout instead + of written to the file. If you add `-s`, the result will be sorted by (resulting) codepoint. + +3. If you're using **plan9port**, you'll need to + + 1. Apply [latin1-increase-compose-capacity.patch][] since the default compose + sequence lookup table is too small to hold all the mappings BQN adds. + 2. Recompile plan9port. + + Other Plan 9 variants may also require extra steps. + +4. The compose sequences should now work in the [acme][] and [sam][] text editors + as well as all other Plan 9 programs. + +[acme]: https://9p.io/sys/doc/acme/acme.pdf +[sam]: https://9p.io/sys/doc/sam/sam.pdf +[BQN keymap]: https://mlochbaum.github.io/BQN/keymap.html +[me]: https://grep.tvl.fyi/search/?q=%20path%3Aops%2Fusers%2Fdefault.nix%20name%20%3D%20%22sterni%22%3B&fold_case=auto®ex=false&context=true +[mkbqnkeyboard.bqn]: ./mkbqnkeyboard.bqn +[inputrc]: https://github.com/mlochbaum/BQN/blob/master/editors/inputrc +[remapped]: https://mlochbaum.github.io/BQN/editors/index.html#alternate-layouts +[p9f-keyboard]: https://p9f.org/magic/man2html/6/keyboard +[p9p-keyboard]: https://9fans.github.io/plan9port/man/man7/keyboard.html +[9front-keyboard]: http://man.9front.org/6/keyboard +[plan9port]: https://9fans.github.io/plan9port/ +[submitting-patches]: https://code.tvl.fyi/about/docs/REVIEWS.md +[mlochbaum/BQN]: https://github.com/mlochbaum/BQN +[CBQN]: https://github.com/dzaima/cbqn +[latin1-increase-compose-capacity.patch]: ./plan9port/latin1-increase-compose-capacity.patch