Mengapa Lebih Memilih rST daripada Markdown

 (buttondown.email)
1 poin oleh GN⁺ 2024-08-02 | 1 komentar | Bagikan ke WhatsApp
  • reStructured Text(rST) dari Sphinx lebih sulit dipelajari daripada Markdown, tetapi memudahkan kontrol yang lebih rinci atas struktur dan format keluaran pada dokumen berskala besar seperti buku
  • Markdown lebih mirip notasi ringan untuk menulis HTML, sedangkan rST berpusat pada pohon dokumen abstrak dan dapat menambahkan objek dokumen baru dengan menggabungkan directive, node, dan renderer
  • Sphinx mentransformasi doctree sebelum rendering, sehingga pekerjaan seperti cross-reference, pemrosesan per format keluaran, dan transformasi pada tahap build tertentu dapat ditangani di dalam sistem dokumentasi
  • Dalam Logic for Programmers, latihan dan pembahasannya ditulis dekat dengan teks asli, lalu menggunakan ekstensi kustom untuk mengubah posisi dan cara tampilnya pada keluaran EPUB dan LaTeX
  • Markdown sederhana tidak memiliki sintaks ekstensi yang terpadu dan dukungan transformasi prarendering; semakin generator dokumen mengakalinya dengan preprocessing terpisah, semakin lemah dukungan alat dan ekstensibilitasnya

Alasan memilih rST

  • Versi baru Logic for Programmers adalah buku kedua yang ditulis dengan Sphinx, dan karya sebelumnya, Learn TLA+ yang baru, juga menggunakan Sphinx
  • Sphinx menggunakan reStructured Text, dan rST memiliki kurva belajar yang lebih curam daripada Markdown
  • Setelah menulis beberapa buku dengan Markdown, penulis membutuhkan alat yang lebih baik dan beralih ke rST
  • rST sendiri independen dari Sphinx, tetapi dalam praktiknya banyak orang memakai rST karena Sphinx, jadi keduanya dibahas bersama

Perbedaan struktur Markdown dan rST

  • Perbedaan terbesarnya adalah Markdown lebih mirip notasi ringan HTML, sedangkan rST adalah notasi skala menengah yang membuat pohon dokumen abstrak
  • Sintaks gambar Markdown dapat diubah menjadi HTML seperti <img alt="alttext" src="example.jpg"/> hanya dengan transformasi sederhana
    • Mesin Markdown modern pun sering mem-parse ke representasi perantara, tetapi karakter dasarnya lebih dekat ke notasi HTML ringan
  • Gambar dalam rST direpresentasikan dengan directive .. image::
    • Sphinx mencari handler directive yang terdaftar dan menjalankan ImageDirective.run
    • Hasil eksekusinya menjadi objek node seperti image_node yang memiliki field alt
    • Setelah seluruh pemrosesan doctree selesai, HTML Writer mencari fungsi rendering image_node dan mengeluarkan tag HTML
  • Pendekatan rST memiliki implementasi dan sintaks yang lebih kompleks serta lebih banyak boilerplate dibanding Markdown, tetapi gambar pun ditangani melalui mekanisme ekstensi yang sama seperti directive lain

Cara menambahkan objek dokumen baru

  • Di rST/Sphinx, objek teks baru dapat ditambahkan sebagai ekstensi
  • Misalnya, jika ingin membuat <figure> dan <figcaption> alih-alih <image>, pada Markdown dasar harus menyisipkan HTML secara langsung
  • Di Sphinx, ini ditangani dengan mendaftarkan directive figure baru
    • FigureDirective juga bisa mewarisi ImageDirective untuk memakai ulang sebagian besar pemrosesan gambar
  • Pola pendaftaran directive, pembuatan node, dan pendaftaran renderer per builder diterapkan dengan cara yang sama pada semua ekstensi

Transformasi doctree sebelum rendering

  • Sphinx dapat melakukan transformasi doctree sebelum rendering
  • Cross-reference antar dokumen juga ditangani dengan fitur ini
    • Jika satu dokumen memiliki anchor foo dan dokumen lain memiliki :ref:\image <foo>``, Sphinx akan menyisipkan URL yang benar pada tahap post-processing
  • Kode transformasi diperlakukan seperti fitur kelas satu dalam proses build
    • Transformasi tertentu dapat diterapkan hanya saat keluaran HTML
    • Transformasi dapat dijalankan pada tahap build tertentu
    • Transformasi bawaan yang tidak ingin dijalankan juga dapat dihapus
  • Tidak semua dokumen membutuhkan kekuatan seperti ini, dan Markdown banyak digunakan karena ringan dan portabel

Contoh ekstensi latihan dan pembahasan

  • Logic for Programmers adalah buku yang dekat dengan matematika, sehingga membutuhkan latihan untuk pembaca
  • Saat menulis, lebih mudah menaruh latihan dan pembahasannya berdekatan di dalam dokumen, tetapi bagi pembaca pembahasan harus muncul di bagian belakang buku
  • Kebutuhannya berbeda untuk tiap format keluaran
    • Latihan dan pembahasan harus saling ditautkan
    • Dengan mempertimbangkan kemungkinan dicetak, PDF juga membutuhkan referensi halaman
    • Cara rendering harus berbeda antara keluaran LaTeX/PDF dan keluaran EPUB
  • Untuk itu, penulis membuat ekstensi Sphinx kustom yang menangani exercise, solution, dan solutionlist
  • Pada keluaran debugging HTML, latihan dan pembahasan dirender secara inline
  • Pada pembuatan EPUB dan LaTeX, transformasi dijalankan setelah seluruh doctree dibuat
    • Semua solution_node dari posisi aslinya dipindahkan ke bawah solutionlist
    • Pada setiap latihan ditambahkan node referensi menuju lokasi pembahasan yang baru
    • Pada setiap pembahasan ditambahkan node referensi untuk kembali ke latihan asal
  • Builder LaTeX membungkus latihan dan pembahasan dengan answers environment
  • Builder EPUB merender pembahasan sebagai popup footnote
  • Struktur ini juga membantu saat membuat sampel gratis dari buku
    • Di bagian belakang sampel gratis, yang dimasukkan hanya pembahasan untuk bagian yang ada dalam sampel, bukan pembahasan seluruh buku

Preferensi sintaks dan alternatif

  • Keberatan paling umum terhadap rST adalah sintaksnya jelek
  • Memilih tidak memakai alat karena tidak enak dilihat adalah pilihan yang sepenuhnya masuk akal, dan alasan sulit menerima Lisp juga bisa dilihat sebagai masalah selera yang sama
  • Alternatifnya antara lain asciidoc, MyST, Typst, Pollen, dan pandoc-extended markdown
  • Intinya bukan bahwa Sphinx/rST luar biasa bagus untuk dokumentasi berskala besar, melainkan bahwa Markdown sederhana luar biasa tidak cocok untuk dokumentasi berskala besar

Keterbatasan generator berbasis Markdown

  • Markdown sederhana tidak memiliki sintaks ekstensi terpadu atau dukungan native untuk transformasi sebelum rendering
  • Banyak generator dokumen berbasis Markdown menambahkan tahap preprocessing sendiri untuk mendukung kasus penggunaan baru
  • Cara ini umumnya berfungsi, tetapi strukturnya bukan memproses di dalam Markdown, melainkan mengakalinya di sekitar Markdown
  • Akibatnya ada batas pada kekuatan fiturnya, dan alat untuk programmer sulit memahami varian tersebut dengan baik
    • Ada LSP dan treesitter untuk Markdown dan rST, tetapi sulit mengharapkan alat dengan tingkat yang sama untuk gitbook-markdown, md-markdown, atau leanpub-markdown
  • Sintaks rST yang jelek justru dapat menjadi keunggulan karena pohon sintaksnya kaya
    • Query treesitter yang hanya mengubah isi directive todo tertentu dimungkinkan
    • Ini mungkin karena pohon sintaks rST lebih kaya daripada pohon sintaks Markdown

Pembaruan Logic for Programmers

  • Logic for Programmers adalah buku tentang bagaimana logika formal berguna dalam rekayasa perangkat lunak sehari-hari
  • Buku ini dimulai dengan ikhtisar matematika dasar, lalu berlanjut ke 8 aplikasi seperti property testing, constraint database, dan tabel keputusan
  • Masih dalam tahap alfa, tetapi sudah berukuran 20.000 kata dan sedang menerima masukan dari pembaca

Bacaan terkait

1 komentar

 
GN⁺ 2024-08-02
Komentar Hacker News

  • Jika ditanya, “apa kamu tidak akan memakai alat yang bagus hanya karena melihatnya saja sudah bikin ingin muntah,” maka jawabannya ya. Kelebihan terbesar Markdown adalah mudah dibaca, dan kelebihan keduanya adalah mudah ditulis
    Seberapa mudah diparsing atau diperluas hampir tidak penting. Terlepas dari apakah Markdown adalah pilihan terbaik untuk menulis buku, untuk menulis cepat dengan format yang tetap mudah dibaca bahkan oleh orang yang tidak terlalu paham sintaks, Markdown adalah yang terbaik. Yang dibutuhkan bukan menulis buku, melainkan catatan, dokumentasi cepat, dan menulis komentar; dan jika harus menulis buku, saya akan memilih LaTeX sebelum RST

    • Saat Markdown mulai populer di kalangan developer, itu terlihat seperti pilihan yang cukup lucu. Bahkan saat itu sudah ada banyak pilihan yang lebih baik untuk mengubah teks biasa menjadi dokumen berformat, tetapi para developer justru membangun CMS, aplikasi produktivitas, alat manajemen dokumentasi, sampai plugin dengan Markdown sebagai pusatnya
      Namun setelah dipakai di aplikasi nyata, ternyata inti Markdown bukan itu. Tujuannya adalah menyediakan format seminimal mungkin agar dalam keadaan teks biasa pun tetap terbaca senatural saat dirender menjadi HTML. Format yang didukung sengaja sedikit sehingga mudah diingat dan bisa dipakai tanpa toolbar. Cocok untuk kotak komentar, chat, pesan commit, mungkin juga posting blog, tetapi tidak cocok untuk penulisan dokumentasi produk tingkat enterprise. Sekarang Markdown bahkan dipakai di tempat yang tidak akan dirender menjadi HTML, karena memang enak dibaca apa adanya, dan saya berharap HN juga mendukungnya
    • Saya pernah menulis buku dengan Markdown dan tidak ada masalah berarti. Memang itu novel, bukan dokumen teknis, tetapi tidak ada yang tidak bisa diatasi hanya dengan sesekali mencampurkan HTML ke dalam Markdown
      Saya juga cukup banyak membuat dokumen teknis dengan Markdown, dan dengan ekstensi Pandochttps://pandoc.org/MANUAL.html hampir semua format yang dibutuhkan bisa dimasukkan, termasuk rumus yang kompleks dan code block dengan syntax highlighting. Markdown itu bisa dikonversi menjadi HTML, dokumen Word, ePub, PDF, dan lain-lain. Perlu alasan yang sangat meyakinkan untuk memilih sesuatu selain Markdown
    • Mungkin saya termasuk 10% pengguna TeX teratas, tetapi saya tidak melihat ada banyak ruang untuk bahasa typesetting lain di antara Markdown dan TeX. Markdown itu mudah tetapi terbatas, sedangkan TeX agak sulit tetapi pada praktiknya hampir tak terbatas fleksibilitasnya
      Masalah terbesar yang saya lihat di TeX bukan pada bahasanya, melainkan pada manusianya. Orang-orang sering menulis TeX spaghetti dengan gaya yang buruk. Namun jika ditulis dengan pola pikir “dokumen adalah kode”, hasilnya bisa cukup rapi. Masalah terbesar kedua adalah tidak adanya kompiler TeX → HTML yang bagus
    • “Kalau menulis buku saya akan memakai LaTeX” terdengar seperti pilihan yang mengerikan untuk tahap menulis dan menyusun struktur. Saya lebih memilih menulis dalam Markdown tanpa memikirkan typesetting, lalu baru mengonversinya ke LaTeX pada tahap penerbitan
      Saya memang tidak mahir LaTeX, tetapi saat pernah mencoba mempelajarinya rasanya seperti belajar bahasa milik peradaban alien serangga. Sama sekali tidak intuitif, dan rasanya hampir mustahil melakukan sesuatu yang baru kecuali menyalin apa yang sudah dibuat orang lain lalu menyisipkan tulisan saya sendiri. Kalau tidak salah ingat, dulu juga tidak ada dukungan Unicode kelas satu
    • Saya sulit setuju dengan pernyataan bahwa Markdown adalah “alat terbaik untuk menulis cepat dengan format yang tetap mudah dibaca bahkan oleh orang yang tidak paham sintaks.” Bahkan pada dasar-dasarnya pun belum tentu terbaik
      Memakai tanda bintang atau garis bawah untuk huruf miring juga perlu pembiasaan, padahal ada cara yang jauh lebih intuitif seperti /italic slashes/. Di luar hal-hal dasar, tabel, metadata, dan tag justru menutupi teks sehingga tanpa alat yang tepat tidak mudah ditulis maupun dibaca. Jika mudah diperluas, masalah-masalah dasar seperti ini juga bisa diperbaiki, jadi ekstensibilitas juga relevan

  • Saya telah bekerja sekitar 12 tahun sebagai penulis dokumentasi teknis, dan di awal karier saya memindahkan dokumentasi startup dari Word ke Sphinx. Setelah itu saya bekerja dengan CMS/platform dokumentasi developer milik Google, situs berbasis Eleventy, dan dalam 2 tahun terakhir kembali bekerja di situs berbasis Sphinx, pigweed.dev. Saya juga pernah bekerja di startup berbasis readme.com dan sedikit mencoba Docusaurus, Astro, serta Hugo
    reStructuredText sendiri bisa terasa kasar, tetapi reST yang dipadukan dengan Sphinx sangat bagus. Kekuatan Sphinx jauh melampaui kelemahan reST. Untuk situs dokumentasi profesional besar dengan lebih dari 100 halaman dan lebih dari 10 kontributor, saya cukup yakin bahwa dalam jangka panjang Sphinx adalah pilihan yang paling bertanggung jawab. Misalnya, di Pigweed kami membuat cukup dengan menulis :bug:\59385981`` agar otomatis berubah menjadi tautan https://pwbug.dev/59385981, dan nanti pun mudah jika harus memindahkan banyak tautan bug sekaligus. Tautan internal juga selalu dijamin bisa di-resolve, dan jika menautkan ke lokasi yang tidak ada akan muncul peringatan atau error. Dulu saya pernah menulis di https://technicalwriting.dev/src/link-text-automation.html bahwa aneh rasanya jika ini bukan standar untuk situs dokumentasi. Sphinx juga punya API ekstensi dan tema yang terdefinisi dengan baik, dan ekosistemnya di PyPI cukup besar. Belakangan ini saya menyebut Sphinx sebagai raksasa tidur di dunia sistem dokumentasi, dan dengan sedikit dorongan bersama, potensinya bisa menjadi jauh lebih hebat

    • Bagian ini benar-benar penting. Terlalu banyak CMS atau static site generator yang memaksa penulis memasukkan URL akhir secara langsung saat menulis
      Begitu slug berubah atau struktur situs dirombak, kita harus melakukan find-and-replace di seluruh situs. Static site generator sebenarnya bisa saja membiarkan kita menautkan seperti [Hello](../hello.md) lalu me-resolve-nya saat build, tetapi banyak alat yang saya pakai atau telusuri justru mengharuskan kita mengetik [Hello](/why/hello/) secara langsung. Fitur ini tampaknya memang memecah pendapat. Bahkan ketika saya membicarakannya dengan anggota tim static site generator, jawabannya adalah “kenapa Anda menginginkan itu”, dan penjelasan saya pun tidak mempan. Entah orang baru memahami nilai solusinya setelah mengalami masalahnya sendiri, atau mungkin mereka terbiasa dengan sesuatu yang dipakai sekali lalu tidak dipelihara selama 10 tahun lebih, tetapi saya berharap dukungannya bisa lebih luas
    • Sphinx luar biasa, tetapi sangat diremehkan
      Sepengetahuan saya, Sphinx adalah satu-satunya framework dokumentasi yang kokoh secara struktural, dapat diperluas, dan digunakan luas. Ekosistem pluginnya luar biasa sehingga menjadi pengungkit besar untuk meningkatkan dokumentasi tim dan proyek. Saya sendiri tidak menyukai reStructuredText, tetapi sekarang berkat MyST-Parser, banyak hal yang dulu membuat Sphinx sangat terikat pada RST kini juga bisa dilakukan dengan Markdown: https://github.com/executablebooks/MyST-Parser
    • Mengustomisasi elemen bersama di seluruh situs juga sangat mudah dengan Markdown+Pandoc. Saya pernah mengganti tag gambar yang berisi tautan YouTube menjadi tag video dengan thumbnail dan teks alternatif, lalu menghubungkan tag gambar untuk file video lokal ke ffmpeg agar dioptimalkan dan di-resize, semuanya hanya dengan beberapa baris kode
    • Sampai melihat komentar ini, saya belum mengenal Sphinx. Saya sudah menulis dokumentasi teknis selama lebih dari 20 tahun sebagai pekerjaan sampingan dari kerja pengembangan, dan selama ini lebih dekat ke TeX serta XSL kustom
      Saya baru saja memindahkan buku lebih dari 200 halaman yang menjelaskan bahasa/VM/lapisan abstraksi internal ke Sphinx, dan ini benar-benar sistem yang mengubah hidup. Saya berharap dokumentasi Sphinx sendiri punya hambatan masuk yang lebih rendah atau lebih banyak contoh, tetapi untuk saat ini rasanya seperti fase bulan madu yang cukup kuat. Minat utama saya adalah cara membuat buku PDF yang enak dilihat, serta sistem untuk memotong buku menjadi halaman man yang kompatibel dengan POSIX per bab dan per bagian
    • Jika Sphinx ingin benar-benar sukses secara luas, prioritas nomor satu adalah memiliki tema yang indah dan berkualitas tinggi
      Estetika adalah faktor yang cukup penting saat memilih site generator. Hugo dan Gatsby punya tema bawaan yang sangat bagus, dan saya benar-benar pernah memilih keduanya untuk sebuah proyek hanya karena alasan itu. Kumpulan tema Sphinx di https://sphinx-themes.org/ dan https://sphinxthemes.com/#featured-themes umumnya terasa hambar. Jika membandingkan tema RTD standar Sphinx https://sphinx-rtd-theme.readthedocs.io/en/stable/ dengan dokumentasi Apple https://developer.apple.com/documentation/swift/array atau Fluent UI https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--default, tampilannya terlihat usang

  • Saya menganggap kalimat “Markdown adalah representasi ringan dari HTML” sebagai masalah terbesar dalam tulisan ini. Itu jelas tidak akurat.
    Markdown dirancang sebagai alat untuk mengonversi kebiasaan pemformatan teks yang secara de facto digunakan seperti standar dalam email dan posting Usenet pada awal 1990-an. Karena keterbatasan 7-bit ASCII, format seperti penekanan dan judul ditandai dengan simbol khusus, dan HTML juga punya banyak kemiripan dengan kebiasaan tak bernama itu. Karena itu John Gruber pada 2004 menulis skrip dasar untuk mengubahnya menjadi HTML https://daringfireball.net/projects/markdown/, tetapi kemungkinan ia tidak menyangka ini akan menjadi standar de facto yang begitu universal

    • Kalimat pertama di tautan itu justru berbunyi “Markdown is a text-to-HTML conversion tool for web writers.”
      Gruber tidak sekadar mengambil standar de facto Usenet lalu membuat konverter HTML sederhana, melainkan merancang markup versinya sendiri dengan meminjam dari Usenet dan kebiasaan lain. Bagian “Acknowledgements” di bawah tautan itu juga menunjukkan hal tersebut. Sejak awal Markdown memang dimaksudkan sebagai sintaks markup untuk web CMS, dan menyebutnya sebagai representasi ringan dari HTML itu tepat. Intinya adalah membuat setiap bagian sintaks menghasilkan HTML yang berkorespondensi langsung
    • Saya tidak setuju. Markdown selalu terkait dengan HTML, sampai parser Markdown pun mendukung pencampuran tag HTML secara langsung.
      Fakta bahwa ia terinspirasi oleh kebiasaan email tidak membuat pernyataan “Markdown adalah representasi ringan dari HTML” jadi kurang tepat
    • Saya berharap perdebatan semantik seperti ini dihentikan saja. Ini membuat percakapan jadi membosankan dan juga melanggar pedoman HN
      Ada aturan untuk menanggapi tafsiran paling masuk akal dan paling kuat dari ucapan lawan, bukan menangkap tafsiran lemah yang lebih mudah dikritik. Ada juga aturan agar tidak hanya memilih kalimat paling provokatif dari tulisan untuk dikeluhkan, tetapi menanggapi bagian yang menarik: https://news.ycombinator.com/newsguidelines.html
      Jika Anda tidak setuju dengan inti tulisannya, cukup katakan Anda lebih memilih Markdown daripada rST dan jelaskan alasannya. Bertengkar hanya soal satu kalimat tentang apa sebenarnya Markdown itu adalah hal yang konyol
    • Markdown sendiri terpisah dari format email dan Usenet. Markdown adalah sintaks tertentu, definisinya buruk, lalu kemudian meluas menjadi beberapa keluarga sintaks yang sebagian besar mirip satu sama lain
      Memang terinspirasi oleh kebiasaan seperti email atau Usenet, dan sebagian di antaranya bahkan sudah ada sebelum era komputer. Misalnya, rasanya saya pernah melihat contoh dokumen ketikan lama yang memakai tanda bintang seperti huruf miring. Namun Markdown sangat terikat dengan HTML, sintaksnya juga sangat dibatasi oleh HTML, dan upaya untuk memisahkannya dari HTML pada umumnya memang sulit untuk berhasil
    • Keduanya benar. Implementasi aslinya adalah superset dari HTML. Hal yang umum ditulis dengan sintaks ringan, sisanya ditulis dalam HTML

  • Menurut saya inti Markdown adalah memungkinkan hal-hal yang lebih sederhana daripada HTML mentah dilakukan lebih cepat, sambil tetap memungkinkan HTML mentah dicampurkan bila perlu
    Dalam proyek yang membutuhkan kekuatan RST melebihi Markdown, saya justru merasa lebih nyaman menulis HTML langsung

    • Ketika penulis menulis seperti, “Sphinx bisa diperluas untuk membuat objek teks baru. Dalam Markdown dasar Anda harus menyisipkan HTML secara langsung,” saya jadi bertanya-tanya, kalau memang butuh fitur seperti itu, apa masalahnya kalau langsung pakai HTML. Saya tidak paham kenapa harus menambah satu lapisan lagi

  • Saat membangun sistem dokumentasi dengan kompleksitas serupa, saya mempertimbangkan RST karena sangat membutuhkan markup yang punya makna jelas, misalnya menyimpan struktur file RST di database dan mencampurkan hasil database ke dalam konten
    Ada dua masalah yang saya hadapi. Pertama, alat RST tidak punya unparser untuk mengeluarkan RST lagi. Saya ingin menggabungkan beberapa file RST dan sumber lain, lalu otomatis menghasilkan file RST dan menanganinya sebagai API dokumen, tetapi itu tidak didukung. Kedua, alat RST mengharapkan sekumpulan blok yang sudah didefinisikan untuk dokumen tertentu. Jika blok bisa direpresentasikan secara umum, seharusnya mungkin membuat alat yang mengubah dokumen tanpa mengetahui definisi blok internal, tetapi kenyataannya tidak begitu. Ini lebih merupakan masalah alat daripada RST itu sendiri, tetapi setiap kali harus membongkar kode sampai ke lapisan paling bawah, saya jadi memikirkan sistem markup lain yang berbasis HTML

    • Alih-alih HTML, Anda bisa memakai XML untuk dokumen terstruktur. XML memungkinkan Anda mendefinisikan tag kustom yang dibutuhkan, dan jika mau juga bisa memakai validasi skema
      Kelebihan pendekatan ini adalah Anda bisa mengontrol sepenuhnya skema input dan output, sedangkan kekurangannya adalah kebisingan sintaksnya jauh lebih besar daripada Markdown atau RST, dan Anda perlu skrip untuk parsing dan mengubahnya ke format keluaran yang diinginkan
    • Dalam Python, rST hanyalah salah satu dari beberapa format input yang didukung docutils: https://docutils.sourceforge.io/README.html#purpose
      Seluruh tujuan docutils adalah mem-parsing format dan mengubahnya menjadi API: https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers
    • Dari sisi fitur, rST dan AsciiDoc tampak kurang lebih mirip. Saya penasaran apakah kelemahan dan fitur yang hilang juga kira-kira serupa
    • Saya pernah menjadi committer di docutils, alat utama untuk rST. Salah satu alasan kami memindahkan alat itu ke Markdown adalah karena docutils terlalu menyakitkan untuk ditangani. Hanya dari penolakannya pindah ke tempat seperti GitHub saja sudah terlihat betapa tidak ramahnya proyek itu untuk diajak bekerja sama
    • Saya sedang tidak di depan komputer jadi tidak bisa mengujinya sekarang, tetapi sepertinya directive include bisa dipakai untuk melakukan yang Anda inginkan, bukan?

  • Beberapa tahun lalu saya pernah merangkum subset reStructuredText yang layak dihafal: https://simonwillison.net/2018/Aug/25/restructuredtext/
    Dalam proyek terbaru saya mulai menggunakan MyST, yang menyediakan fitur referensi dan daftar isi yang saya anggap penting di reStructuredText, sambil tetap memungkinkan kontributor memakai sintaks Markdown yang lebih mudah ditulis

    • Keunggulannya besar untuk tautan, terutama tautan eksternal. Dalam situs dokumentasi, tautan eksternal yang sama bisa dirujuk dari banyak tempat, dan jika berubah saya ingin cukup memperbaruinya sekali saja
      Yang benar-benar mengubah permainan adalah rST+Sphinx untuk tautan internal serta direktif :ref: dan :doc:. Saat merujuk anchor atau tautan dokumen di dalam konten yang sama, kita tidak perlu mengetik header secara langsung, dan bisa menghindari masalah header yang diketik manual lalu akhirnya usang: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role
      Ini salah satu fitur yang paling saya rindukan saat menulis dengan rST

  • Bukan bermaksud membajak percakapan tentang ReStructuredText, tetapi jika Anda mencari bahasa markup yang memberi lebih banyak daripada Markdown, saya ingin menyarankan agar melihat AsciiDoc alih-alih ReStructuredText. Saya telah menulis dokumentasi teknis selama bertahun-tahun dengan ketiganya, dan menurut saya AsciiDoc lebih baik daripada ReStructuredText maupun Markdown
    Misalnya, dukungan tabel di Markdown dan ReStructuredText sangat merepotkan. Pemformatan tabel AsciiDoc mudah dibaca, ditulis, dan dipelihara, serta lebih kuat karena mendukung header, caption, ukuran kustom tabel dan baris, sampai pemformatan kompleks di dalam tabel. Tidak seperti Markdown, ia memiliki satu format standar tanpa banyak dialek, sintaksnya ringkas dan mudah dibaca, serta kurva belajarnya lebih landai daripada ReStructuredText. Pilihan styling output juga lebih baik, toolchain-nya unggul, dan fitur dokumentasi bawaannya kaya sehingga lebih jarang perlu bergantung pada plugin pihak ketiga. AsciiDoc sejak awal dirancang untuk dokumentasi teknis, sementara dua lainnya lebih merupakan alat yang dipaksa menyesuaikan diri dengan peran itu

  • Kalau Anda menyusun dokumen Markdown sekitar 5–10 halaman dengan rapi, lalu membiarkannya dirender dalam template Jinja yang lebih dinamis, awalnya semuanya terasa cukup memuaskan. Ada juga proses build untuk dokumentasi otomatis, dan skalanya sudah terlalu besar untuk sekadar satu README GitHub. Namun sejak titik itu, penderitaan dimulai
    Dokumentasi halaman proyek GitHub rasanya kurang cocok, membingungkan apakah perlu file .nojekyl, apakah branch gh-pages masih dibutuhkan, dan tidak jelas apakah perubahan tidak muncul karena salah konfigurasi repositori atau sebab lain. Setelah mencoba GitHub Actions selama beberapa jam, semuanya mulai terasa tidak masuk akal. Saat melihat lagi Read the Docs, tampaknya ia ingin memakai Sphinx, jadi Markdown saya sambungkan ke Sphinx; build-nya berhasil, tetapi setelah deployment lebar halaman rusak dan masalah itu tidak bisa direproduksi secara lokal, jadi sepertinya karena penyisipan iklan di tier komunitas. Banyak proyek berjalan baik dengan ini dan saya juga pernah melakukannya sendiri, tetapi sampai benar-benar berjalan, detail-detail kecilnya terasa sangat rewel dan sulit dipercaya. Pada akhirnya, Markdown versus RST bukanlah inti persoalannya; yang penting adalah menemukan kombinasi yang cocok untuk proyek dokumentasi skala menengah dan static hosting

    • Saya penasaran apakah Anda sudah melihat mdBook. Saya sendiri belum pernah memakainya, tetapi saya menyukai dokumentasi dari beberapa proyek yang menggunakan mdBook, dan untuk tahap ketika kebutuhan sudah melampaui satu file README, ini tampak cukup bagus
      Panduan deployment otomatisnya juga bagus: https://github.com/rust-lang/mdBook

  • Tampaknya orang melewatkan bahwa penulis berbicara dalam konteks typesetting bukunya sendiri. Ia bukan sedang mengklaim bahwa rST secara umum lebih baik daripada Markdown
    Dalam kasus umum, kesederhanaan Markdown adalah alasan ia dipakai luas, tetapi itu bukan sasaran pembahasan penulis

  • Menarik melihat orang bereaksi seolah-olah reST dibuat sebagai pesaing Markdown. Sebenarnya hampir sebaliknya. reST adalah pengembangan dari StructuredText pada 2002, sedangkan Markdown pertama kali dipublikasikan pada 2004
    Tujuan keduanya sangat mirip, dan untuk teks yang paling dasar keduanya sama-sama bisa dibaca dan ditulis seperti plain text. Yang terjadi adalah banyak format bermunculan pada masa itu karena semua orang menginginkan hal semacam ini. Menurut saya, alasan Markdown menang hampir tidak ada hubungannya dengan “lebih sederhana” atau “lebih mudah dibaca”. Untuk hal-hal yang mudah direpresentasikan dengan ASCII murni dan spasi, keduanya umumnya bisa saling menggantikan. Adakah yang akan mengatakan bahwa dokumen reST pada contoh itu adalah tulisan rumit yang tidak bisa dibaca tanpa parser? Saya juga tidak begitu paham dalam hal apa varian Markdown lebih baik dari itu; lebih terasa seperti kebetulan sejarah satu format akhirnya lebih dominan, sementara keduanya sama-sama cukup baik untuk tujuan intinya

    • Karena yang diberikan hanya contoh yang sangat sederhana, baik Markdown maupun reST sama-sama bisa menanganinya dengan mudah
      reST memang menyediakan banyak fitur pemformatan tambahan yang berguna bila diperlukan, tetapi menjadi berlebihan saat tidak dibutuhkan. Saya mulai menggunakan GitHub-flavored Markdown sekitar saat mendaftar GitHub pada 2010, dan juga beberapa kali memakai reStructuredText karena dokumentasi Python. Yang terakhir punya kurva belajar yang jauh lebih tinggi, dan setelah itu saya tidak punya alasan untuk memakainya lagi
    • Kalau dibilang tidak bisa dibaca, tentu tidak, tetapi kalau dibilang menjengkelkan untuk diketik, ya benar. Judul bergaya underline merepotkan saat mengedit, dan meskipun panjangnya tidak harus benar-benar pas, tetap ada tekanan untuk menyesuaikannya
      Backtick ganda juga merupakan sintaks yang terasa terlalu menjengkelkan dibanding waktu yang sebenarnya dibutuhkan