MySQLマニュアルの差分

MySQL 8.0.x はパッチレベルのリリースで機能追加がされていくんだけど、マニュアルは常に 8.0 の最新版しか公開されてない。 MySQL は OSS だけど、MySQL のマニュアルは自由なライセンスではないしリポジトリも公開されてない。 ライセンスは自由でなくてもせめてリポジトリが公開されてれば、古いバージョンのマニュアルを見れたり差分を表示できるんだけどなー。

しかたないので自分でなんとかしてみる。

MySQL のマニュアルは何かの形式(XMLと聞いたような気がする)から変換して作られているのだけど、ソースは公開されてない。 HTML は https://downloads.mysql.com/docs/refman-8.0-en.html-chapter.tar.gz で一括でダウンロードできるので、これを定期的にダウンロードして Git のリポジトリに突っ込めばどうにかなるだろう。

% mkdir mysql-refman
% cd mysql-refman
% git init
% git commit -m 'Initial commit' --allow-empty

としておいて、定期的にダウンロードして Git に入れるように cron に設定しとく。

wget -q -N https://downloads.mysql.com/docs/refman-8.0-en.html-chapter.tar.gz && cd mysql-refman && rm -rf * && tar xf ../refman-8.0-en.html-chapter.tar.gz && git add . && git commit -m "$(date '+\%F \%T')" > /dev/null

wget に -N を指定すると更新されてなければダウンロードしないのでそんなに負荷にはならないはず。

これでリポジトリが定期的に更新されるようになったんだけど、差分を見ようとすると意味のないものが大量に出てきちゃう。 こんな感じ:

@@ -161,7 +161,7 @@ MEDIUMINT, BIGINT</a></span></dt><dt><span class="section"><a href="data-types.h
 </div>
 </div>
 </div>
-<a class="indexterm" name="idm45408272163120"></a><a class="indexterm" name="idm45408272162080"></a><a class="indexterm" name="idm45408272161008"></a><p>
+<a class="indexterm" name="idm46446106154096"></a><a class="indexterm" name="idm46446106153056"></a><a class="indexterm" name="idm46446106151984"></a><p>
         For integer data types, <em class="replaceable"><code>M</code></em> indicates
         the maximum display width. The maximum display width is 255.
         Display width is unrelated to the range of values a type can
@@ -226,9 +226,9 @@ Warning
 </div>
 <div class="itemizedlist">
 <ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
-            <a class="indexterm" name="idm45408272132704"></a>
+            <a class="indexterm" name="idm46446106123680"></a>
 
-            <a class="indexterm" name="idm45408272131632"></a>
+            <a class="indexterm" name="idm46446106122608"></a>
 
             <a class="link" href="data-types.html#bit-type" title="11.1.5 Bit-Value Type - BIT"><code class="literal">BIT[(<em class="replaceable"><code>M</code></em>)]</code></a>
           </p><p>

どうやら HTML が生成される時に a 要素の name 属性の値が自動で生成されるらしく、実際には変更がないところまで差分として表示されてしまう。

まあ、そうでなくても HTML のまま差分が表示されても厳しいものがあるので、次のようにしてみる。

.git/config に次を追加:

[diff "html2text"]
    textconv = html2text

.gitattributes を次で作成:

*.html diff=html2text

これで git diff 時に HTML そのままではなく、html2text でプレーンテキストに変換した結果で差分が表示されるようになる。見やすい。

diff --git a/refman-8.0-en.html-chapter/mysql-cluster.html b/refman-8.0-en.html-
chapter/mysql-cluster.html
index 1197b89..b0ad15f 100644
--- a/refman-8.0-en.html-chapter/mysql-cluster.html
+++ b/refman-8.0-en.html-chapter/mysql-cluster.html
@@ -1577,17 +1577,21 @@ interest are shown in the following list:
             option. For ndb_restore, use the option together with the --decrypt
             option; for ndb_print_backup_file, use the option in place of the -
             P option.
-          o For ndb_mgm, the same option is supported together with --execute
-            "START_BACKUP_[options]" for starting a cluster backup from the
-            system shell.
+          o For ndb_mgm the option --backup-password-from-stdin, is supported
+            together with --execute_"START_BACKUP_[options]" for starting a
+            cluster backup from the system shell.
           o Two ndbxfrm options, --encrypt-password-from-stdin and --decrypt-
             password-from-stdin, cause similar behavior when using that program
             to encrypt or to decrypt a backup file.
       See the descriptions of the programs just listed for more information.
-      This feature also implements the ability to enforce encrypted backups by
-      setting RequireEncryptedBackup=1 in the [ndbd default] section of the
-      cluster global configuration file. When this is done, the ndb_mgm client
-      rejects any attempt to perform a backup that is not encrypted.
+      It is also possible, beginning with NDB 8.0.22, to enforce encryption of
+      backups by setting RequireEncryptedBackup=1 in the [ndbd default] section
+      of the cluster global configuration file. When this is done, the ndb_mgm
+      client rejects any attempt to perform a backup that is not encrypted.
+      Beginning with NDB 8.0.24, you can cause ndb_mgm to use encryption
+      whenever it creates a backup by starting it with --encrypt-backup. In
+      this case, the user is prompted for a password when invoking START_BACKUP
+      if none is supplied.
     * IPv6 support.  Beginning with NDB 8.0.22, IPv6 addressing is supported
       for connections to management and data nodes; this includes connections
       between management and data nodes with SQL nodes. When configuring a
@@ -15118,13 +15122,18 @@ stdin[=value]           STDIN; use together with -- AD
DED: NDB 8.0.24
 --connect-retries=#     giving up; 0 means 1        releases based on MySQL
                         attempt only (and no        8.0)
                         retries)
+                        Cause START BACKUP to
+--encrypt-backup        encrypt whenever making a
+[=TRUE|FALSE]           backup, prompting for       ADDED: NDB 8.0.24
+                        password if not supplied by
+                        user
+--execute=name,                                     (Supported in all NDB
+-e                      Execute command and exit    releases based on MySQL
+                                                    8.0)
                         Set number of times to      (Supported in all NDB
 --try-reconnect=#,      retry connection before     releases based on MySQL
 -t                      giving up; synonym for --   8.0)
                         connect-retries
---execute=name,                                     (Supported in all NDB
--e                      Execute command and exit    releases based on MySQL
-                                                    8.0)
 
     *  --backup-password-from-stdin[=TRUE|FALSE]
       Command-Line Format --backup-password-from-stdin[=value]

このリポジトリを GitHub とかで公開できるといいのかも知れないけど、MySQL のマニュアルは自由なライセンスではないので出来ないのであった。残念。

ていうか、公式が MySQL のマニュアルのリポジトリを公開してくれればいいんだけどなー。