MySQLマニュアルに関する思い出話と、最近差分を追っている話

MySQL Technology Cafe #11 MySQLリファレンスマニュアル に関する思い出話 と 最近差分を追っている話 2021/02/17 日本MySQLユーザ会 坂井 恵 (@sakaik)

はじめに MySQL 8.0 日本語マニュアルのリリース おめでとうございます ＆ ありがとうございます

みんなで作ろう 日本語マニュアル MySQLユーザ会メーリングリスト #16635

bugs.mysql.comで報告できる！ 「MySQL Server: Japanese Documentation」カテゴリで報告。 例： https://bugs.mysql.com/bug.php?id=102513

• https://bugs.mysql.com/bug.php?id=102513

自己紹介 • 坂井 恵 SAKAI, Kei • SNS等では概ね @sakaik 日本MySQLユーザ会 有限会社アートライ • 副代表 • 代表取締役 • イベント開催したり • 外部イベントにユーザ会として 参加したり → 人と人が、人と情報が出会え る「場」が大好き • 先週23歳になりました(会社が) • DB(MySQL)そのものだけではなく、 「データの流れ」を押さえた改善 や問題解決のお手伝い →情報と情報が出会い、人の役に立 つ「場」が大好き

今日のお話 「MySQLリファレンスマニュアルに関する思い出話」 と 「最近差分を追っている話」

MySQLはすごい！ 初期より、マニュアルが充実 × 動く物があればいいだろ？ × 動かしてみればわかるだろ？ × わかんなければコミュティで教えてもらってよ

しかし基本的には英語 • MySQLのマニュアルは、 MySQLの公用語で書かれて いる • 我々日本人の中には、 MySQLの公用語の読み書き に苦労する人も多い（私も！ 私も！） 我々のMySQLの歴史は、日本 語マニュアルの歴史とも言える 『MySQLの公用語は「へたな英語」』 https://news.mynavi.jp/article/20070919-mysql02/

• https://news.mynavi.jp/article/20070919-mysql02/

MySQL 日本語マニュアルの歴史 • 英語以外の自国語で情報が用意されているとい うのは恵まれている

MySQL 日本語マニュアルの歴史 • ～2003年 ユーザ会有志による翻訳(v.3.21～4.0) • 2008年 MySQL社による翻訳(v.5.1) • 2015年 Oracle社による翻訳(v.5.6) v. 4.1 v. 5.0 v. 5.5 v. 5.7 • 2021年 Oracle社による翻訳(v.8.0)←NEW!

日本語の話のまとめ 最新の日本語マニュアルが あることは、ありがたい！ • まず、今回の8.0日本語マニュアルの提供に、大大大大 感謝！！！ • MySQLのマニュアルは日々更新されている • 機能が追加されたり、動作が変更になっているものも ある • 従って、日本語マニュアルも最新情報への追随、 少なくとも変更されていることが分かる状態であるこ とに期待したい

MySQLのマニュアルの 最新状態とは？ ここからは MySQL Reference Manual (英語) の 「最新の状態」についてお話をします。

MySQL のマニュアルの形態 様々な フォーマット

MySQLマニュアルの特徴 • 随時更新されています（ほぼ毎日） • 「MySQL 8.0.23 のマニュアル」みたいなもの は存在しない（常に最新状態） • リリース前の機能も(おそらく内部での実装が完了 したタイミングで)マニュアルに追加される。

マニュアル の リビジョン

そこに 頻繁に更新されるものがあるなら 何が変化しているのか、見たくなりますよね。 • 構想15年、 • 時々やってみては、すぐに飽きて • 今回 久々に再開

比較のやりかたの案 課題 • どのフォーマットを使おうか • どうやって差分を取ろうか • どうやって確認しようか → PDFは比較しにくいので、やっぱりテキスト。 とすると、HTML Download (Zip) あたりがちょうどよさそう → 差分は、テキストなら diff 取れば一発。 → 確認は当面は目視でいいか。

更新頻度を見る • ということで、年末あたりから差分を追いかけてみて います • とりあえず、変更の分量や内容などを自分の目で見て みたい、という目的 • 自動化は、していない。半手動での実施

更新頻度とリビジョン 20200405_00: (revision: 65614) 20210124_14: (revision: 68580) 20200903_00: (revision: 67190) 20210126_18: (revision: 68592) 20201225_22: (revision: 68406) 20210129_18: (revision: 68613) 20201226_12: (revision: 68408) 20210130_11: (revision: 68621) 20210105_01: (revision: 68409) 20210201_11: (revision: 68623) 20210105_12: (revision: 68413) 20210203_09: (revision: 68624) 20210106_16: (revision: 68430) 20210203_18: (revision: 68642) 20210107_10: (revision: 68436) 20210204_21: (revision: 68659) ★20210119_00: (revision: 68447) 20210205_17: (revision: 68675) (revision: 68526) 20210206_10: (revision: 68681) 20210120_21: (revision: 68545) 20210209_15: (revision: 68691) 20210121_14: (revision: 68549) 20210210_15: (revision: 68708) 20210122_18: (revision: 68555) 20210211_23: (revision: 68732) 20210123_15: (revision: 68571) 20210213_00: (revision: 68738) 20210213_09: (revision: 68747) 20210108_18:

主な変更内容パタン ① 新機能の追加（関数、パラメタ、変数etc） ② 既存動作の変更 ③ 言い回し・用語の変更 Spatial(GIS)まわりの関数 や機能の追加をいち早く キャッチアップできる！ 機能に関するものは、「まぁそういう機能が入ったのね」 という話なので、ここでは話題提供として、③の表現まわ りの変更の例をいくつか紹介します。

表現・言い回しの変更 の例 - If your server unexpectedly exits because .. + If the server unexpectedly exits because .. - When you design your database with .. + When you design a database with .. - ..storage engine only affects new tables as they are created, + ..storage engine only affects newly created tables,

表現・言い回しの変更 Removed in MySQL 8.0.3 Deprecated in MySQL 8.0.25. Removed in 8.0.3 Deprecated in 8.0.25. Removed in MySQL 8.0.3 Deprecated in MySQL 8.0.25. の例

時間があれば 少し技術的な話を ・・・というほど大した技術は 使っていませんが、工夫はあります

MySQLマニュアル 差分確認のしくみ 雑な 以下の作業を Linux 上で実施しています • wgetで mysql.com から HTML, Zip 形式のマニュアル を取得 • unzip で展開 • 展開されたフォルダをリネーム(日付等をつける) • 展開されたフォルダ内の可変記述部分を置換 • diff でひとつ前のフォルダとの差分確認

HTMLマニュアル比較の工夫 • HTMLファイルには、生成のたび に変化する部分がある。 → 置換して比較可能にする • HTMLファイル中のテキスト1行は、 結構長いものがある →比較のために行を短くすると便 利 XML File PDF HTML (web) HTML (DL) MySQLマニュアル生成の しくみ(推定) 可変部分の例： <a class="indexterm" name="idm46417401159024"> <dt id="ientry-idm46417405270000">

HTMLマニュアル比較の工夫 可変部分の例： <dt id="ientry-idm46417405270000"> <a class="indexterm" name="idm46417401159024"> sed -i -e 's/ientry-idm[0-9]*/ientry-idmX/g' sed -i -e 's/[#"]idm[0-9]*/.idmX/g' 適当に改行を入れる工夫 sed -i -e 's/>/>¥n/g'

最新リビジョンの確認 最初は、時々ブラウザでマニュアルのトップページを確 認して、リビジョンが上がっているかを確認していた

最新リビジョンの確認 今は少しだけ進化（でも手動） • curlで refman/8.0/en/ のトップページを取ってきて • grep で "revision" の行を取得 • 見やすいように加工 （ここまでできているなら、あとは、マニュアルのリビジョンが新しくなってい たなら取得、という処理を自動でできるのですが、今はまだそこまでは）

まとめ • 丁寧なマニュアルを常に最新に保ってくれてい るドキュメント チームに、万歳！ • 8.0日本語マニュアルの提供、そしてそのため に尽力してくださった皆さんに、万歳！ • 今回紹介したような比較作業をやってみたい！ と思った時に、すぐに試せる環境が用意できる OCI (Oracle Cloud Infrastructure) Free Tier、万歳！