Fenomena lebih menyukai rST dibanding Markdown

Mengapa saya lebih menyukai rST

Saya tidak akan berhenti menyampaikan pendapat ini

• Saya telah menerbitkan versi baru "Logic for Programmers" v0.2. Versi ini mencakup dukungan epub, pemecahan kendala, dan pembahasan tentang spesifikasi formal.
• Buku kedua saya, "Learn TLA+", juga ditulis dengan Sphinx. Sphinx menggunakan markup unik bernama reStructured Text (rST).
• rST memiliki kurva belajar yang lebih terjal daripada markdown. Setelah menulis beberapa buku dengan markdown, saya merasa membutuhkan sesuatu yang lebih baik lalu beralih ke rST.

Mengapa rST lebih baik

• markdown adalah representasi ringan dari HTML, sedangkan rST adalah representasi berbobot menengah dari pohon dokumen abstrak.
• Cara membuat gambar di markdown:

  ![alttext](example.jpg)
  

• Cara membuat gambar di rST:

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

• rST dapat diperluas. Anda bisa menambahkan objek teks baru.
• Sphinx dapat menangani cross-referencing. Misalnya, jika Anda menaruh anchor foo di satu dokumen dan :ref:image <foo>`` di dokumen lain, Sphinx akan menyisipkan URL yang benar.
• rST memungkinkan Anda menyusun kode transformasi bersama bagian lain dari proses build.

Satu kasus penggunaan

• "Logic for Programmers" adalah buku terkait matematika, sehingga membutuhkan soal latihan untuk pembaca.
• Saya ingin menempatkan soal latihan dan jawabannya berdampingan di dokumen, tetapi bagi pembaca jawabannya harus muncul di bagian belakang buku.
• Untuk itu saya menulis ekstensi latihan sendiri.

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

• Di HTML, soal latihan dan jawaban dirender secara inline.
• Di epub dan latex, melalui transformasi node jawaban dipindahkan ke bawah solutionlist, dan node referensi dilampirkan ke tiap soal latihan.

"Tapi saya tidak suka sintaksnya"

• Banyak orang berpendapat bahwa sintaks rST itu jelek.
• Bisa dipahami jika Anda tidak ingin memakai alat yang bagus hanya karena tidak menyukai sintaksnya.
• Ada juga pembuat dokumen lain seperti asciidoc, MyST, Typst, Pollen, dan pandoc-extended markdown.
• Pembangkit dokumen berbasis markdown sering menambahkan tahap prapemrosesan sendiri untuk mendukung kasus penggunaan baru.
• Ada LSP dan treesitter untuk markdown dan rST, tetapi tidak ada untuk gitbook-markdown, md-markdown, atau leanpub-markdown.

Tidak ada newsletter minggu depan

• Saya akan berada di Hong Kong.

Pembaruan 2024-07-31

• Saya menambahkan penjelasan singkat tentang "Logic for Programmers".
• Buku ini membahas bagaimana logika formal dapat berguna dalam rekayasa perangkat lunak sehari-hari.
• Isinya mencakup gambaran dasar matematika dan delapan aplikasi yang berbeda.
• Masih dalam tahap alpha, tetapi sudah ditulis lebih dari 20.000 kata dan berisi banyak hal yang berguna.

Ringkasan GN⁺

• rST adalah alat penulisan dokumen yang lebih kuat daripada markdown.
• Saat digunakan bersama Sphinx, ada kemampuan untuk mentransformasi dan memperluas pohon dokumen.
• Ini berguna untuk menulis buku seperti "Logic for Programmers".
• Banyak yang menganggap sintaks rST jelek, tetapi alternatif lain juga tersedia.
• Ini bisa berguna bagi orang yang tertarik pada rekayasa perangkat lunak yang terkait dengan logika formal.

[GN⁺]

Opini Hacker News

• Kelebihan terbesar Markdown adalah mudah dibaca dan mudah ditulis
• Markdown mungkin bukan alat terbaik untuk menulis buku, tetapi sangat cocok untuk menulis teks berformat dengan cepat
• Akan menggunakan LaTeX untuk menulis buku, dan Markdown cocok untuk mencatat, dokumentasi cepat, serta menulis komentar
• reStructuredText (reST) sendiri agak kasar, tetapi sangat bagus jika digabungkan dengan Sphinx
  • Sphinx adalah pilihan yang cocok untuk situs dokumentasi profesional berskala besar
  • Sphinx memudahkan kustomisasi elemen-elemen umum situs
  • Menjamin tautan internal selalu terselesaikan
  • API ekstensi dan tema terdefinisi dengan baik
  • Ada beragam ekstensi dan tema di PyPI
• Markdown adalah representasi ringan dari HTML, sedangkan reST adalah representasi berbobot menengah dari pohon dokumen abstrak
• Markdown dirancang untuk mengubah teks berformat dari pesan email dan posting Usenet
• Alat reST kurang memiliki kemampuan untuk menghasilkan file RST secara otomatis
• Markdown memungkinkan pekerjaan sederhana diselesaikan dengan cepat, dan jika perlu dapat menyisipkan HTML mentah
• MyST memungkinkan penggunaan sintaks Markdown sambil tetap menyediakan kemampuan reStructuredText
• Dokumentasi pada halaman proyek GitHub bisa rumit, dan menggunakan Sphinx bersama Markdown dapat berguna
• Penulis menyebut rST dalam konteks menyusun tata letak bukunya sendiri
• reST bukan pesaing Markdown, melainkan format yang muncul lebih dulu daripada Markdown
• Markdown dan reST pada dasarnya memiliki tujuan yang sama
• Markdown dan reST sama-sama mudah dibaca dan cepat ditulis
• Markdown menjadi lebih luas digunakan karena alasan historis
• Markdown dapat mendefinisikan tipe blok kustom dan mentransformasikan pohon dokumen
• Jupyter Book adalah contoh yang baik untuk merender ke target lain seperti PDF menggunakan Markdown