Hiện tượng ưu tiên rST hơn Markdown

Vì sao tôi ưu tiên rST

Tôi sẽ không ngừng đưa ra lập luận này

• Tôi đã xuất bản phiên bản mới của "Logic for Programmers" v0.2. Phiên bản này bao gồm hỗ trợ epub, giải quyết ràng buộc và nội dung về đặc tả hình thức.
• Tôi cũng viết cuốn sách thứ hai "Learn TLA+" bằng Sphinx. Sphinx sử dụng một kiểu markup đặc trưng là reStructured Text (rST).
• rST có đường cong học tập dốc hơn markdown. Sau khi viết vài cuốn sách bằng markdown, tôi cảm thấy cần một thứ tốt hơn nên đã chuyển sang rST.

Vì sao rST tốt hơn

• markdown là biểu diễn nhẹ của HTML, trong khi rST là biểu diễn tầm trung của cây tài liệu trừu tượng.
• Cách tạo ảnh trong markdown:

  ![alttext](example.jpg)
  

• Cách tạo ảnh trong rST:

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

• rST có thể mở rộng. Bạn có thể thêm các đối tượng văn bản mới.
• Sphinx có thể xử lý cross-referencing. Ví dụ, nếu bạn đặt anchor foo trong một tài liệu và thêm :ref:image <foo>`` vào tài liệu khác, Sphinx sẽ chèn đúng URL.
• rST cho phép tổ chức mã chuyển đổi cùng với phần còn lại của quy trình build.

Một trường hợp sử dụng

• "Logic for Programmers" là một cuốn sách liên quan đến toán học, nên cần các bài tập cho độc giả.
• Tôi muốn đặt bài tập và lời giải cạnh nhau trong tài liệu, nhưng với độc giả thì lời giải phải xuất hiện ở phần cuối sách.
• Để làm điều này, tôi đã tự viết một extension cho bài tập.

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

• Trong HTML, bài tập và lời giải được render inline.
• Trong epub và latex, thông qua chuyển đổi, các node lời giải được chuyển xuống dưới solutionlist, và các node tham chiếu được gắn vào từng bài tập.

"Nhưng tôi ghét cú pháp"

• Nhiều người cho rằng cú pháp của rST xấu.
• Tôi có thể hiểu việc không dùng một công cụ tốt chỉ vì bạn không thích cú pháp.
• Cũng có các trình dựng tài liệu khác như asciidoc, MyST, Typst, Pollen và pandoc-extended markdown.
• Các trình tạo tài liệu dựa trên markdown thường thêm bước tiền xử lý riêng để hỗ trợ các trường hợp sử dụng mới.
• Có LSP và treesitter cho markdown và rST, nhưng không có cho gitbook-markdown, md-markdown hay leanpub-markdown.

Tuần sau sẽ không có bản tin

• Tôi sẽ ở Hồng Kông.

Cập nhật 2024-07-31

• Tôi đã thêm phần giải thích ngắn về "Logic for Programmers".
• Cuốn sách này nói về việc logic hình thức hữu ích như thế nào trong kỹ thuật phần mềm hằng ngày.
• Nó bao gồm phần tổng quan toán học cơ bản và tám ứng dụng khác nhau.
• Dù vẫn đang ở giai đoạn alpha, sách đã có hơn 20.000 từ và chứa nhiều nội dung hữu ích.

Tóm tắt của GN⁺

• rST là công cụ soạn thảo tài liệu mạnh hơn markdown.
• Khi dùng cùng Sphinx, nó có khả năng biến đổi và mở rộng cây tài liệu.
• Điều này hữu ích khi viết các cuốn sách như "Logic for Programmers".
• Nhiều người cho rằng cú pháp của rST xấu, nhưng vẫn có các lựa chọn thay thế khác.
• Điều này có thể hữu ích với những ai quan tâm đến kỹ thuật phần mềm liên quan đến logic hình thức.

[GN⁺]

Ý kiến Hacker News

• Ưu điểm lớn nhất của Markdown là dễ đọc và dễ viết
• Markdown có thể không phải là công cụ tối ưu để viết sách, nhưng lại tối ưu để nhanh chóng soạn văn bản có định dạng
• Sẽ dùng LaTeX để viết sách, còn Markdown phù hợp để ghi chú, viết tài liệu nhanh và đăng bình luận
• reStructuredText (reST) bản thân nó hơi thô, nhưng khi kết hợp với Sphinx thì rất xuất sắc
  • Sphinx là lựa chọn phù hợp cho các trang tài liệu chuyên nghiệp quy mô lớn
  • Sphinx cho phép tùy biến dễ dàng các thành phần dùng chung của trang
  • Đảm bảo các liên kết nội bộ luôn được phân giải
  • API cho phần mở rộng và giao diện được định nghĩa rõ ràng
  • Có nhiều phần mở rộng và giao diện trên PyPI
• Markdown là biểu diễn hạng nhẹ của HTML, còn reST là biểu diễn hạng trung của cây tài liệu trừu tượng
• Markdown được thiết kế để chuyển đổi văn bản có định dạng trong email và bài đăng Usenet
• Công cụ reST thiếu khả năng tự động tạo file RST
• Markdown cho phép thực hiện nhanh các tác vụ đơn giản và có thể chèn HTML thuần khi cần
• MyST cho phép dùng cú pháp Markdown trong khi vẫn cung cấp các tính năng của reStructuredText
• Việc tài liệu hóa cho trang dự án GitHub có thể phức tạp, và dùng kết hợp Sphinx với Markdown có thể hữu ích
• Tác giả đang nhắc đến rST trong bối cảnh dàn trang cuốn sách của mình
• reST không phải đối thủ của Markdown, mà là một định dạng ra đời trước Markdown
• Markdown và reST về cơ bản có cùng mục tiêu
• Cả Markdown và reST đều dễ đọc và viết nhanh
• Markdown trở nên được dùng rộng rãi hơn vì các lý do mang tính lịch sử
• Markdown có thể định nghĩa các kiểu khối tùy chỉnh và biến đổi cây tài liệu
• Jupyter Book là một ví dụ tốt về việc dùng Markdown để render sang các đích khác như PDF