MarkdownよりrSTを好む理由

なぜ私はrSTを好むのか

この主張をやめるつもりはない

• 新しいバージョンの「Logic for Programmers」v0.2を公開した。このバージョンには、epubサポート、制約解決、形式仕様に関する内容が含まれている。
• 2冊目の本「Learn TLA+」もSphinxで執筆した。SphinxはreStructured Text（rST）という独特のマークアップを使う。
• rSTはMarkdownより学習コストが高い。何冊かの本をMarkdownで書いた後、より良いものが必要だと感じてrSTに移行した。

rSTが優れている理由

• MarkdownはHTMLの軽量表現である一方、rSTは抽象文書ツリーの中量級の表現である。
• Markdownで画像を作る方法:

  ![alttext](example.jpg)
  

• rSTで画像を作る方法:

  .. image:: example.jpg
     :alt: alttext
  

• rSTは拡張可能で、新しいテキストオブジェクトを追加できる。
• Sphinxはcross-referencingを処理できる。たとえば、ある文書にfooアンカーを入れ、別の文書に:ref:image <foo>``を入れると、Sphinxが正しいURLを挿入する。
• rSTでは、変換コードをビルドプロセスの残りの部分と一緒に構成できる。

あるユースケース

• 「Logic for Programmers」は数学関連の本であり、読者向けの練習問題が必要になる。
• 練習問題と解答を文書内で並べて配置したいが、読者向けには解答は本の後半に表示されるべきだ。
• そのために独自の練習問題拡張を書いた。

  .. in chapter.rst
  .. exercise:: Fizzbuzz
     :name: ex-fizzbuzz
     An exercise
     .. solution:: ex-fizzbuzz
        A solution
  .. in answers.rst
  .. solutionlist::
  

• HTMLでは練習問題と解答をインラインでレンダリングする。
• epubとlatexでは、変換によって解答ノードをsolutionlistの下に移動し、各練習問題に参照ノードを添付する。

「でも私は文法が嫌いだ」

• rSTの文法は見た目が悪いという意見が多い。
• 文法が嫌いだからという理由で良いツールを使わないのは理解できる。
• asciidoc、MyST、Typst、Pollen、pandoc-extended markdownなど、他の文書ビルダーもある。
• Markdownベースの文書生成器は、新しいユースケースをサポートするために独自の前処理ステップを追加することが多い。
• MarkdownとrST向けのLSPやtreesitterはあるが、gitbook-markdownやmd-markdown、leanpub-markdown向けのものはない。

来週はニュースレターなし

• 香港にいる予定だ。

2024-07-31 更新

• 「Logic for Programmers」に関する簡単な説明を追加した。
• この本は、形式論理が日常的なソフトウェアエンジニアリングでどのように役立つかを扱っている。
• 基本的な数学の概要と、8つの異なる応用例を含んでいる。
• まだアルファ段階だが、すでに20,000語以上が書かれており、多くの有用な内容を含んでいる。

GN⁺の要約

• rSTはMarkdownより強力な文書作成ツールである。
• Sphinxと組み合わせると、文書ツリーを変換・拡張できる機能がある。
• 「Logic for Programmers」のような本の執筆に役立つ。
• rSTの文法は見た目が悪いという意見が多いが、他の代替手段も存在する。
• 形式論理に関わるソフトウェアエンジニアリングに興味がある人にとって有用かもしれない。

[GN⁺]

Hacker Newsの意見

• Markdownの最大の長所は、読みやすく書きやすい点である
• Markdownは本を書くための最適なツールではないかもしれないが、素早く整形されたテキストを書くには最適である
• 本を書くならLaTeXを使うだろうし、Markdownはメモ作成、簡単な文書化、コメントの記述に向いている
• reStructuredText（reST）は単体ではやや粗削りだが、Sphinxと組み合わせると非常に優れている
  • Sphinxは大規模で専門的なドキュメントサイトに適した選択肢である
  • Sphinxはサイトの共通要素を簡単にカスタマイズできるようにしてくれる
  • 内部リンクが常に解決されることを保証する
  • 拡張機能とテーマのAPIが明確に定義されている
  • PyPIにはさまざまな拡張機能やテーマが存在する
• MarkdownはHTMLの軽量な表現であり、reSTは抽象的なドキュメントツリーの中量級の表現である
• Markdownは、メールメッセージやUsenet投稿の整形テキストを変換するために設計された
• reSTのツールには、RSTファイルを自動生成する機能が不足している
• Markdownは簡単な作業を素早くこなせるようにし、必要に応じて生のHTMLを挿入できる
• MySTはreStructuredTextの機能を提供しつつ、Markdown構文を使えるようにする
• GitHubプロジェクトページのドキュメント化は複雑になることがあり、SphinxとMarkdownを併用するのが有用な場合がある
• 著者は自分の本を組版する文脈でrSTに言及している
• reSTはMarkdownの競合ではなく、Markdownより先に登場した形式である
• MarkdownとreSTは基本的に同じ目標を持っている
• MarkdownとreSTはどちらも読みやすく、素早く書ける
• Markdownがより広く使われるようになったのは歴史的な理由による
• Markdownはカスタムのブロックタイプを定義し、ドキュメントツリーを変換できる
• Jupyter Bookは、Markdownを使ってPDFのような別のターゲットへレンダリングできる好例である