README: explain the build process

README-ja_JP.md

@@ -21,7 +21,7 @@
 巨大なデータの処理 (補完、貼り付けなど) の局面でPOSIX 標準コマンドを利用しています。
 
 呼称: `ble.sh` はお好きな様に読んでいただいて問題ありませんが、一番短いのは標記の /blɛʃ/ になりましょう。
-しかし個人的には脳裡で /biːɛliː dɑt ɛseɪtʃ/ と読んでいるものですから、標記の読み方は飽くまで参考と受け止めていただければ幸いです。
+しかし個人的には脳裡で /biːɛliː/ または /biːɛliː dɑt ɛseɪtʃ/ と読んでいるものですから、標記の読み方は飽くまで参考と受け止めていただければ幸いです。
 
 ## 簡単設定
 
@@ -49,6 +49,11 @@ make -C ble.sh install PREFIX=~/.local
 echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc
 ```
 
+生成過程では、複数のBashスクリプトファイルを結合することで `ble.sh` を生成し、
+他の関連ファイルを正しく配置し、またソースコード中のコードコメントを削除してロードを最適化します。
+生成過程は、C/C++ のコンパイルも伴わずバイナリも生成しませんので、コンパイラを準備していただく必要はありません。
+</details>
+
 <details><summary><b><code>curl</code> を用いて nightly ビルドをダウンロード</b></summary>
 
 この方法では `curl`, `tar` (オプション `J` に対応), 及び `xz` (XZ Utils) が必要です。
@@ -95,7 +100,7 @@ echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc
 
 - [AUR (Arch Linux)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-AUR) `blesh-git` (devel), `blesh` (stable 0.3.3)
 - [NixOS (nixpkgs)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-nixpkgs) `blesh` (devel)
-- [Guix](https://guix.gnu.org/ja/packages/blesh-0.4.0-devel2/) `blesh` (0.4.0-devel2)
+- [Guix](https://packages.guix.gnu.org/packages/blesh/0.4.0-devel2/) `blesh` (0.4.0-devel2)
 </details>
 
 <details open><summary><b>既存の <code>ble.sh</code> を更新</b></summary>
@@ -113,12 +118,38 @@ bash /path/to/ble.sh --update
 
 <details><summary><b><code>ble.sh</code> のパッケージ作成</b></summary>
 
+`ble.sh` は単にシェルスクリプトの集合ですので環境に依存せずにお使いいただけます (いわゆる "`noarch`") ので、
+単にリリースページからビルド済みの tar ボールをダウンロードし中身を `/tmp/blesh-package/usr/local` など所定の位置に配置するだけで問題ありません。
+それでも何らかの理由により自前でビルドする必要がある場合には以下のコマンドをお使いください。
+ビルドの為には git リポジトリ (`.git`) が必要になることにご注意ください。
+
 ```bash
-# パッケージ作成用コマンド
+# ビルド & パッケージ作成用コマンド
 
 git clone --recursive https://github.com/akinomyoga/ble.sh.git
 make -C ble.sh install DESTDIR=/tmp/blesh-package PREFIX=/usr/local
 ```
+
+パッケージ管理システムを用いたパッケージ更新方法を指定すると `ble-update` でそれが呼び出されます。
+更新方法を指定するにはスクリプトファイルを `${prefix}/share/blesh/lib/_package.bash` に配置します。
+スクリプトは次の様な変数と関数を定義します。但し `XXX` はパッケージ管理システムの名前に置き換えてください。
+
+```bash
+# ${prefix}/share/blesh/lib/_package.bash
+
+_ble_base_package_type=XXX
+
+function ble/base/package:XXX/update {
+  update-the-package-in-a-proper-way
+  return 0
+}
+```
+
+シェル関数がステータス 0 で終了した場合、更新が成功した事を表し `ble.sh` のリロードが自動的に行われます。
+シェル関数がステータス 6 で終了した場合、`ble.sh` のタイムスタンプが確認され、`ble.sh` が現セッションの開始時刻よりも新しい時に限りリロードが行われます。
+シェル関数がステータス 125 で終了した場合、`ble.sh` に組み込みの更新処理が試みられます。
+それ以外の場合には更新処理が中断されます。この場合、シェル関数が状況を説明するメッセージを出力するようにして下さい。
+具体例として `AUR` パッケージの [`_package.bash`](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git) も参考にしていただければ幸いです。
 </details>
 
 ## 機能概要

README.md

@@ -23,7 +23,7 @@ processing of large data in completions, paste of large data, etc.
 
 Pronunciation: The easiest pronunciation of `ble.sh` that users use is /blɛʃ/, but you can actually pronounce it as you like.
 I do not specify the canonical way of pronoucing `ble.sh`.
-In fact, I personally read it verbosely as /biːɛliː dɑt ɛseɪtʃ/ in my head.
+In fact, I personally call it simply /biːɛliː/ or verbosely read it as /biːɛliː dɑt ɛseɪtʃ/ in my head.
 
 ## Quick instructions
 
@@ -50,6 +50,28 @@ git clone --recursive https://github.com/akinomyoga/ble.sh.git
 make -C ble.sh install PREFIX=~/.local
 echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc
 ```
+
+The build process integrates multiple Bash script files into a single Bash script `ble.sh`,
+place other module files in appropriate places, and strip code comments for shorter initialization time.
+This does not involve any C/C++/Fortran compilations and generating binaries, so C/C++/Fortran compilers are not needed.
+
+<sup><sub>
+[ Some people seem to bilindly believe that one always need to use `make` with C/C++/Fortran compilers to generate binaries.
+They complain about `ble.sh`'s make process, which comes from the lack of knowledge on `make`.
+One should learn the general principle of `make`.
+
+C/C++ programs in the repository is used to update the Unicode character table from the Unicode database when a new Unicode standard appears.
+The generated table is included in the repository:
+[`canvas.GraphemeClusterBreak.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.GraphemeClusterBreak.sh),
+[`canvas.c2w.musl.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.c2w.musl.sh),
+[`canvas.c2w.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.c2w.sh),
+and [`canvas.emoji.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.emoji.sh),
+so there is no need to run these C/C++ programs in the build process.
+Another C file is used as an adapter in a old system MSYS1,
+which is used with an old compiler toolchain in Windows, but it will never be used in Unix-like systems.
+
+Each file used in the build process is explained in [make/README.md](make/README.md). ]
+</sub></sup>
 </details>
 
 <details><summary><b>Download the nightly build with <code>curl</code></b></summary>
@@ -98,7 +120,7 @@ This only requires the corresponding package manager.
 
 - [AUR (Arch Linux)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-AUR) `blesh-git` (devel), `blesh` (stable 0.3.3)
 - [NixOS (nixpkgs)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-nixpkgs) `blesh` (devel)
-- [Guix](https://guix.gnu.org/en/packages/blesh-0.4.0-devel2/) `blesh` (0.4.0-devel2)
+- [Guix](https://packages.guix.gnu.org/packages/blesh/0.4.0-devel2/) `blesh` (0.4.0-devel2)
 </details>
 
 <details open><summary><b>Update an existing copy of <code>ble.sh</code></b></summary>
@@ -116,12 +138,39 @@ bash /path/to/ble.sh --update
 
 <details><summary><b>Create a package of <code>ble.sh</code></b></summary>
 
+Since `ble.sh` is just a set of shell scripts and do not contain any binary (i.e., "`noarch`"), 
+you may just download the pre-built tarball from release pages and put the extracted contents in e.g. `/tmp/blesh-package/usr/local`.
+Nevertheless, if you need to build the package from the source, please use the following commands.
+Note that the git repository (`.git`) is required for the build.
+
 ```bash
-# PACKAGE (for package maintainers)
+# BUILD & PACKAGE (for package maintainers)
 
 git clone --recursive https://github.com/akinomyoga/ble.sh.git
 make -C ble.sh install DESTDIR=/tmp/blesh-package PREFIX=/usr/local
 ```
+
+When you would like to tell `ble.sh` the way to update the package for `ble-update`,
+you can place `_package.bash` at `${prefix}/share/blesh/lib/_package.bash`.
+The file `_package.bash` is supposed to define a shell variable and a shell function
+as illustrated in the following example (please replace `XXX` with the package management system):
+
+```bash
+# ${prefix}/share/blesh/lib/_package.bash
+
+_ble_base_package_type=XXX
+
+function ble/base/package:XXX/update {
+  update-the-package-in-a-proper-way
+  return 0
+}
+```
+
+When the shell function returns exit status 0, it means that the update has been successfully done, and the reload of `ble.sh` will be automatically happen.
+When the shell function returns exit status 6, the timestamp of `ble.sh` is checked, and the reload of `ble.sh` only happens when `ble.sh` is actually update.
+When the shell function returns exit status 125, the default `ble.sh` update procedure is attempted.
+Otherwise, the updating procedure is canceled, where any message explaining situation should be output by the shell function.
+An example `_package.bash` for `AUR` can be found [here](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git).
 </details>
 
 ## Features

docs/ChangeLog.md

@@ -361,6 +361,7 @@
 - README: add a link to the explanation on the "more reliable setup" of bashrc (motivated by telometto) `#D1905` 09bb4d3
 - README: describe `contrib/fzf` integration (reported by SuperSandro2000, tbagrel1) `#D1907` 3bc3bea b568ade
 - README: add links to Manual pages for *kspec* and `modifyOtherKeys` `#D1917` fb7bd0b1 b568ade
+- README: explain the build process `#D1964` `#D1965` xxxxxxx
 
 ## Optimization
 

make/README.md

@@ -0,0 +1,10 @@
+# make scripts and programs
+
+- `canvas.c2w.wcwidth*.cpp` ... These C++ codes are used to generate the character-width table by the C-library implementations and different terminal implementations.
+  [`src/canvas.c2w.musl.sh`](../src/canvas.c2w.musl.sh) is generated by this program.
+- `canvas.c2w.list-ucsver-detection-codes.sh` ... This script is used to analyze the character-width table based on Unicode database.
+  The character codes used by the test for [`bleopt char_width_{mode,version}=auto`] are determined based on the result of this script.
+- `canvas.emoji.sh` ... This script is used to test the emoji supports of different terminals.
+- `mwg_pp.awk` ... This is a preprocessor program written in AWK, which is used to preprocess and combine multiple shell scripts into a single file `ble.sh`.
+  The source repository is [`akinomyoga/mwg_pp`](https://github.com/akinomyoga/mwg_pp).
+- `debug.leakvar.exclude-list.txt` ... This is a white list for the global variables.

note.txt

@@ -1936,8 +1936,6 @@ bash_tips
 
   * blerc.template: update unicode versions
 
-  * README: Guix package の位置が変わっている。
-
   * syntax: 5.0 以降では関数名として function `xxx` 等も実は許されている。5.3
     以降では更に <(...) も関数名として使える。しかもこれらは `xxx`() や
     <(...)() の形式でも定義できる。
@@ -6678,6 +6676,17 @@ bash_tips
     Done (実装ログ)
 -------------------------------------------------------------------------------
 
+2023-02-13
+
+  * README: ビルド過程に対する説明 [#D1965]
+
+    勘違いする人が沢山いるし勝手に馬鹿にしている人がいるので README の make の
+    部分に色々書いておく。
+
+    * make/README にも各ファイルの説明を書いている。
+
+  * README: Guix package の位置が変わっている [#D1964]
+
 2023-02-12
 
   * prompt: \g{} は ble/color/setface/.spec2g を使う? [#D1963]