競プロで使っているマイライブラリを整理するためのメモ。

現状

• jupyter notebook で作成している。

  • 解説を markdown ブロックで、コードをコードブロックで書いており、解説→コード→解説→コード・・・のような構造。

  • markdownで数式を記入できる

  • 画像は draw.io を使って作成し、ドキュメントに埋め込む。

• いいところ

  • 前後を視認しながら作成、修正できる。

    • ファイルを通してプレビューするのではなく、markdownをセル毎に表示/修正できるので、前後の markdownセルを視認しながらコンテンツ作成、修正ができる。

  • コードのコピペが簡単

    • 一つのクラスやひとまとまりのコードを一つのコードセルに入れておくことで、[ctrl]-a [ctrl]-c で簡単にセルだけのコピーができる。

      • 他のドキュメントだと、[ctrl]-a でファイル全体が選択されてしまい、コピペしたくない解説部分や、別のコードなど不要な部分も選択されてしまう。コードブロックのみをコピーするショートカットが存在しない？

• 画像の挿入も簡単

  • 画像だけ別ファイルで作成しリンクを貼るのは冗長すぎるのでやりたくない。このnotebookファイルだけで完結させたい。

  • そこで、画像を base64 でエンコードし、<img> タグで直接 markdownセルに入れると、画像として表示される。

  • エンコードされたテキストは非常に大きいのだが、1セル1画像にしておけば折りたためるので、テキストの大きさが気にならない。

jupyter notebook の問題点

• 項目が増えてきて、目的のドキュメントを探しにくくなった。

  • 現状では大項目別でファイルを作成しており、その数が約20個程度あるので、ファイルを選び出すのに手間取る。どのファイルに何を書いたか思い出せないので、ファイル名だけから目的を探せない。

  • 目次を自動作成できないので、ファイルから先のドキュメントにたどり着くのにも手間取る。さほど大きな量でもないのだが、コンテスト中ではちょっとの迷いもロスになる。かといって、手作り目次は作業が途方もないし、メンテしきれない。

  • ファイルをまたぐリンクがうまく機能しない（ファイルを探しやすくする目的でファイル名に日本語を使っており、そのせいでパスが文字化けしてしまって ipynb markdown セルのリンクと繋がらない。）また、アンカーもうまく機能しない。これは vscode との相性の問題？

markdown 移行における問題

vscode の markdown に移行しようとしても実は次のような問題があった：

• 「コードブロックのコピー」ができない

  • もし vscode の markdown でマイライブラリを作ったとすると、競技中は markdown preview で参照することになるだろう。ライブラリの中から目的のコンテンツを見つけ出したとき、多くの場合それをコピーして競技用の .cpp に貼り付けるのだが、（jupyter notebook ではできていた）コードブロックの中だけの選択ができないので、わざわざ範囲をマウス等で指定しなければならない。これは超面倒。

• .mdファイルで画像の折りたたみができない

  • 画像は base64 エンコードされたテキストで書いておきたいのだが、その分量がドキュメントに対して巨大すぎる。一つのファイルの9割程度を img のエンコードデータが占めていることがあり、.md ファイルの取り回しが大変になる。jupyterlab はセルを描画モードにすればエンコードされた文字列は表示されなかった。

一方で、markdown で解決されたり便利になることも多い。

• ファイルをまたぐリンクが張れるので、すべてをまとめた目次を作ることができる。アンカーも機能する。

• 自動目次生成機能が使える。（要拡張機能）

• 数式を記入するときなど、preview を視認しながら書ける。

課題の解決方法

次の方法で課題を解決できることがわかったので、markdown に移行することにした。

• 「コードブロックのコピー」問題

  • vscode 付属の preview ではそのようなことはできないらしいし、またそれをできるようにするための改造（拡張機能や script の追加）はいろいろ問題がありそう。

  • しかし、この .md ファイルを github に送ってしまえば、そこで確認する際は github の viewer が使われる。そして、github の viewer には「コードブロックをコピ－」するボタンがある。これを使えばいい。

  • 一旦 github にコミットする、という手間が増えるのだが、そもそもライブラリ自体は github で管理していたし、作るとき（平時）と使うとき（競技中）は時間が異なるので、大きな問題はなさそう。

• 画像の base64 折りたたみ問題

  • <div></div> タグの中に入れて .md に書くと、vscode の text editor 側の折りたたみが機能するようになるので、これで十分かも。<detail></detail> に入れたら preview 側でも折りたたむことができるので、使い分けられる。

ただ、もう一つ届かないところもあって、

• 複数ファイルを通した目次生成ができない

  • 1つのファイルの中だけで目次生成はできるが、複数ファイル分の目次生成を行う方法がまだわからない。もしかしたら探せば見つかるかも。

  • 今のところ、次の方法で対処しようと思う。

    • 各ファイルで TOC を作成

    • TOC部分をコピーして、目次一覧用.md にコピペ

    • 参照している部分にファイル名をペタペタ貼り付け

  • これによって、目次一覧用.md は全ての目次を集めたドキュメントになり、そこからリンクでそれぞれのファイルの部分に飛ぶことができるのだが、手作業が入る。でも、これまでよりはかなり楽になる。

    • 機械的なコピペなので、markdown 用のスクリプトを書けば自動化できるかも。目次部分をクロールしてファイル名を挿入するだけ。