AsciiDoc の良さと、 pandoc の弱点

簡易な文書整形規格がいくつか在る。 一部の人は「軽量マークアップ」なんて呼んでいるが、その言葉は意味が判らない

簡易文書フォーマットで有名なものに、 Markdown が在る。 GitHub でも標準的になっているフォーマットだ

成程、Markdown は、markup をしない、つまり、線形に先へ先へと書けるため、記述を阻害されにくい。 例えば

        <h1>みだし<h1>

        <a href="https://github.com/">https://github.com/</a>

と書くのを

        # みだし

        <https://github.com/>

と書くので、後処理をしないで済む

Markdown の特徴は、少機能なことであり、これは pros でも cons でもある

Markdownに対して、多機能で論文向きなものに reStructeredText が在る。 ほら、複雑怪奇で憶えづらく書きづらい(笑)。まず、名が良くない。 特に厭なのは、ハイパーリンクだ

        `reStructeredText <http://docutils.sourceforge.net/rst.html>`_.

なんだよ貴君は(笑

そうしているうちに、 AsciiDoc を知った。 DocBook程では無いが、簡易的な書籍作成フォーマットになるらしい。 オライリーも採用しているらしい

        == みだし

        http://asciidoc.org/index.html[AsciiDoc]

        https://github.com/

となる。 生URLが自動的にリンクされる


ところで、 GitHub 内のエディタも、固定ファイルのウェブサイト生成器の Nikola も、AsciiDoc と対応している。(Nikola は、プラグインの追加が必要で、このプラグインと関連していくつかのソフトウェアの追加インストールも必要だ。GNU Source-highlight とか。 ) Nikola は、このサイトでも採用している。

それに対して、 Hakyll も私は利用している。 Hakyll はライブラリで、 Haskell でコーディングすることでやりたいようにウェブサイトを生成し得る。そのため、Haskell で書けないと困るわけだけれども。

その Hakyll は、フォーマット変換に Pandoc を利用している。 で、 Pandoc は、出力では AsciiDoc でも書くが、入力で AsciiDoc を読めない 。 ということは、Hakyll では、改造しないかぎりは AsciiDoc 非対応のようだ。

Pandoc は対応フォーマットが多くて、「スイス陸軍のアーミーナイフ」と比喩されているくらいなのだが。 実際に、TeXも ODT も、PDF も DOCX(笑)も書き出せるくらいなのだが。 残念だ。 改良することができないだろうか……


これに関連して、wjn-overlay に、

  • app-text/asciidoc-gtksourceview

  • app-text/markdown-gtksourceview

を追加した。 gedit や pluma のような gtksourceview を利用可能なエディタ用の、 ハイライト機能。

Gentoo の portage や emerge の日本語マニュアルは古い

Gentoo の日語の manpage は旧い。 man emerge したときの内容が obolete だ。 今は無いオプションも書いてある。

http://dev.gentoo.org/~zmedico/portage/doc/man/emerge.1.html
http://dev.gentoo.org/~zmedico/portage/doc/man/portage.5.html
が最新であるはずなので、参照している。 English だが、私にはむしろ、その方が精確なので良い。

そして、ハッキリ言って、これらを読まないと何がなんだか解らない。

man してローカルのを読んでも旧い、短い、で解らないというのは不親切だし、 そもそもそれだからダメなのだと思う。

思うに、オフィシャルの EN でさえゆっくりゆっくりにしか整備されていないくらいなのに、 特に JA はその EN よりも何年も後れている。


Gentoo に限ったことでなく、 JP は、島国性根、密室閉じ籠りが多い。 そもそも「鎖国」という言説はデマで、欧州に対する防衛政策として国交制限をしていただけなのだが。 だからその「島国根性」という奴は、封建国家の村気質で他所に口出してはいけないという言論弾圧と、明治以降にずっと学校で教えられていた「鎖国」という誤解、欧米礼賛・江戸時代を恰も大昔であるかのように云ってきた洗脳の帰結だ。

で、世界の潮流に入らずに閉じ籠もって、別のコミュニティを造り、MLやウェブフォーラム等も別にしてしまう。

あるいは原因は、学校の英語教育、学校と称する刑務所の更生軍隊教育によって確立される英語トラウマによるのかもしれない。


さて、

$ eix -e mpv

[I] media-video/mpv

Available versions: 0.3.10 (~)0.3.11 [M]0.6.2 [M]0.7.1 [M]0.7.2 (**)9999

[M] は、package.mask でマスクされている。

(~) は unstable で、(**) はキーワードが無い(動くと認定されたアーキテクチャが無く、何の動作保証も無い)。キーワードは ebuild ファイル内に書かれており、 package.accept_keywords と関連している。

マスクと、キーワードは、別の概念だ。

package.* は、 /etc/portage/ に書くのは、自分のカスタマイズ。 それ以外にオフィシャルのデフォルトが、 /usr/portage/profiles/ に格納されている。 何らかの理由で「マスクすべきだ」と判定されたものをマスクする設定が置かれている。 我々は、 /etc/portage/package.unmask で上書きしてマスクを外し得る。


$ emerge -pO mpv

These are the packages that would be merged, in order:

[ebuild R *] media-video/mpv-9999

R は、インストール済みで再 merge することを意味する。 * は、キーワードの無いこと。

http://dev.gentoo.org/~zmedico/portage/doc/man/emerge.1.html を参照すると説明が有る。

  • B | Blocked(他のパッケージと矛盾が有るのでブロック中)
  • N | New
  • S | Slot
  • R | Re-merge(再インストールしたければするよ)
  • F | Fetch manually
  • f | fetched
  • U | Update
  • D | Downgrade
  • r | rebuild(ライブラリのdependencyなどで再ビルドせねばならぬ)
  • * | キーワードが無い
  • # | マスクされている
  • ~ | unstable だ

git の merge と rebase の相異

git をいきなり始めても、git merge と git rebase の相異が解りづらい。

大部だけれど、 Git Book http://git-scm.com/book/ja/v1 を読むべきだというのは、ただしい。 Git に限らず、フリーソフトウェアだからといってもドキュメントを整備しないでいい訳がなく、 むしろ整備すべきだと言える。ドキュメントが無いと、多数の人に対して逐一教えて差し上げなければならない、教えなければ利用してもらえないで廃れるというサヴァイヴァルだ。

プロプライエタリの業界では、ドキュメントが無ければ創らせたり、サポートセンタに電凸ネットワーク(笑)すべきである。有料(not 有償。有料=カネ支払を強制すること)であるからむしろ、売上でサポセンを雇ってさらに儲けるというモデルが完成している。サポセンを造った方が儲かり、保守企業を創業させて儲けさせるという業界である。

さてともかくも、Git に関しては多くの人が、 GitHub を見かけて始めてみた、といういきさつだ。 だから、git を熟知せずに ビリーズではないがブートキャンプ(軍隊かっ!)から始める。 それで、 git merge と git rebase の重大な相異も、そもそも git merge の2種類のストラテジも解らないで、git のメッセジ見て「ああそうですか」「言葉の意味は判らないが何だか凄い自信だ」ということになる。

それでとにかく、 merge と rebase の相異だ。 http://git-scm.com/book/ja/v1/Git-%E3%81%AE%E3%83%96%E3%83%A9%E3%83%B3%E3%83%81%E6%A9%9F%E8%83%BD-%E3%83%AA%E3%83%99%E3%83%BC%E3%82%B9 に書いてある。読むべきだ。

知らないで git pull するのも、git merge をするのも、一人だからリア充の非公開repoで実験するので無ければ危険だと考える。

merge は、複数の、コミット(変更記録)の履歴を、併合する。 rebase は、片方のコミット履歴を、他方の履歴に付け足す。 一言で言うとこうなる。


merge には、 fast-forward と recursive の2種類の遣り方(ストラテジ)がある。

単にコミットを付け足せば構わない(conflict;矛盾、が生じない)ときに行われるのは、fast-forward;単に先へ進む、手法だ。

conflict が生ずるから「佳きに計らえ」ということになったときは、その「佳き計らい」というのは、変更ということなのだから、merge 時に変更を生じ、新たなコミットを記録せねばならない。 矛盾が生じるのは、双方が共通の起原を保ちながらも、別途の進化をしたからで、だから、遡って双方の矛盾を解消せねば、併合することはできないのだ。 だからこれを recursive と呼ぶ。

fast-forward はコミットを生じぬ merge で、 recursive はコミットする merge になる。


次に、 rebase だ。

これは、履歴を変更して、片方の末端に他方のコミットを付け足すものだ。 合併では無く、片方が旧い、他方が新しい、と決めつけて繋げる。

そうすると、履歴の書き換えをせねばならなくなる。 本当は共通の起原から変更されたのに、恰も片方の末端から他方が進化したことにするから、履歴("Git Book"では「歴史」と訳されている)が変わる

履歴が変わるのだから、 git rebase は、リスクの大きい作業だ。 付け足されるコミットの名前 (hash)も変わり、別の名前のコミットにされてしまう。

履歴が変わるので、 git push [origin master] 等するときには、--force しないといけなくなる場合が多い。 整合性が崩壊するからだ。

独りリア充の秘密リポジトリ、俺様だけが創造主の天国では、問題ない。 破壊的創造をするのは、創造主の独裁能力だ。

だが、公開リポジトリや、ましてやコミッタが独りでないリポジトリでは、危険だ。 付け足すコミットが、親を(付け足される側の末端に)変更され、名前も書き換えられてしまう。

GitHub では、公開リポジトリであることが原則だ(なぜならば、GitHub はフリーソフトウェアパラダイスだから)。 そして、そのリポがマイナで誰もフォークしていないクロンすらもしていないならば構わないのだけれど、誰かがクロンして編集していたときには、origin[/upstream] がリベースして、特に master ブランチが書き換わったなんてときには、マトリックス避けかジョジョ立ちのように仰け反ることになる。

逆に自分がクロンやフォークをした側であるときには、upstream と動向をよく見て、変更を同期させる方法を検討すべきだ。 齟齬が生じない最も安全なのは、 merge の fast-forward で解決する場合。 だから、安易に git pull (= git fetch && git merge) をするのには、一定のリスクがある(recursive されて、コミットしてねんと git に云われることがある)。

wjn's repos' info.

  Japenese , English