Vì sao tôi thích rST hơn Markdown

 (buttondown.email)
1 điểm bởi GN⁺ 2024-08-02 | 1 bình luận | Chia sẻ qua WhatsApp
  • reStructured Text (rST) của Sphinx khó học hơn Markdown, nhưng dễ kiểm soát chi tiết cấu trúc và định dạng đầu ra hơn trong các tài liệu quy mô lớn như sách
  • Markdown gần với một kiểu ký pháp HTML gọn nhẹ, còn rST xoay quanh cây tài liệu trừu tượng, nơi có thể kết hợp directive, node và renderer để thêm các đối tượng tài liệu mới
  • Sphinx biến đổi doctree trước khi render, nên có thể xử lý tham chiếu chéo, xử lý theo từng định dạng đầu ra, hoặc các phép biến đổi ở những giai đoạn build cụ thể ngay trong hệ thống tài liệu
  • Trong Logic for Programmers, tác giả viết bài tập và lời giải gần nhau trong bản gốc, rồi dùng phần mở rộng tùy biến để thay đổi vị trí và cách hiển thị trong đầu ra EPUB và LaTeX
  • Markdown đơn giản thiếu cú pháp mở rộng thống nhất và hỗ trợ biến đổi trước khi render, nên càng phải lách qua tiền xử lý riêng trong trình tạo tài liệu thì càng yếu về hỗ trợ công cụ và khả năng mở rộng

Vì sao chọn rST

  • Phiên bản mới của Logic for Programmers là cuốn sách thứ hai được viết bằng Sphinx, và dự án trước đó là Learn TLA+ mới cũng dùng Sphinx
  • Sphinx sử dụng reStructured Text, và rST có đường cong học tập dốc hơn Markdown
  • Sau khi viết nhiều cuốn sách bằng Markdown, tác giả chuyển sang rST vì cần công cụ tốt hơn
  • Bản thân rST là độc lập với Sphinx, nhưng trên thực tế nhiều người dùng rST là vì Sphinx, nên bài viết xem xét cả hai cùng nhau

Khác biệt về cấu trúc giữa Markdown và rST

  • Khác biệt lớn nhất là Markdown gần với ký pháp HTML rút gọn, còn rST là một kiểu ký pháp tầm trung để tạo ra cây tài liệu trừu tượng
  • Cú pháp ảnh trong Markdown có thể được chuyển khá đơn giản thành HTML như <img alt="alttext" src="example.jpg"/>
    • Các engine Markdown hiện đại cũng thường parse sang biểu diễn trung gian, nhưng bản chất cơ bản của nó vẫn gần với ký pháp HTML nhẹ
  • Ảnh trong rST được biểu diễn bằng directive .. image::
    • Sphinx tìm handler của directive đã đăng ký rồi chạy ImageDirective.run
    • Kết quả thực thi là một đối tượng node như image_node có trường alt
    • Khi toàn bộ doctree đã được xử lý xong, HTML Writer sẽ tìm hàm render cho image_node và xuất ra thẻ HTML
  • Cách làm của rST phức tạp hơn về cả triển khai lẫn cú pháp và có nhiều boilerplate hơn Markdown, nhưng ảnh cũng được xử lý bằng cùng cơ chế mở rộng như các directive khác

Cách thêm đối tượng tài liệu mới

  • Trong rST/Sphinx, có thể thêm các đối tượng văn bản mới bằng extension
  • Ví dụ, nếu muốn tạo <figure> và <figcaption> thay vì <image>, thì trong Markdown cơ bản bạn phải chèn HTML trực tiếp
  • Trong Sphinx, việc này được xử lý bằng cách đăng ký một directive figure mới
    • FigureDirective thậm chí có thể kế thừa ImageDirective để tái sử dụng phần lớn logic xử lý ảnh
  • Mẫu đăng ký directive, tạo node và đăng ký renderer theo từng builder được áp dụng nhất quán cho mọi extension

Biến đổi doctree trước khi render

  • Sphinx có thể thực hiện biến đổi doctree trước khi render
  • Tham chiếu chéo giữa các tài liệu cũng được xử lý bằng tính năng này
    • Nếu một tài liệu có neo foo và tài liệu khác có :ref:\image <foo>``, Sphinx sẽ chèn đúng URL ở giai đoạn hậu xử lý
  • Mã biến đổi được coi như tính năng hạng nhất trong quy trình build
    • Có thể chỉ áp dụng một biến đổi nhất định khi xuất HTML
    • Có thể chạy biến đổi ở một giai đoạn build cụ thể
    • Cũng có thể gỡ bỏ các biến đổi tích hợp sẵn mà bạn không muốn chạy
  • Không phải tài liệu nào cũng cần mức mạnh mẽ như vậy, và Markdown vẫn được dùng rộng rãi vì nhẹ và dễ di chuyển

Ví dụ extension cho bài tập và lời giải

  • Logic for Programmers là một cuốn sách gần với toán học nên cần có bài tập cho người đọc
  • Khi viết, để bài tập và lời giải gần nhau trong tài liệu sẽ thuận tiện hơn, nhưng với người đọc thì lời giải nên xuất hiện ở phần cuối sách
  • Yêu cầu còn khác nhau tùy theo định dạng đầu ra
    • Bài tập và lời giải phải liên kết qua lại với nhau
    • Để có thể in ấn, bản PDF còn cần tham chiếu số trang
    • Cách render trong đầu ra LaTeX/PDF và EPUB phải khác nhau
  • Để làm việc đó, tác giả viết một extension Sphinx tùy biến xử lý exercise, solution, và solutionlist
  • Trong đầu ra HTML dùng để debug, bài tập và lời giải được render inline
  • Khi tạo EPUB và LaTeX, tác giả chạy biến đổi sau khi tạo xong toàn bộ doctree
    • Tất cả solution_node ở vị trí gốc sẽ được chuyển xuống dưới solutionlist
    • Mỗi bài tập sẽ được gắn một node tham chiếu đến vị trí mới của lời giải
    • Mỗi lời giải sẽ được gắn một node tham chiếu quay lại bài tập gốc
  • LaTeX builder bọc bài tập và lời giải bằng answers environment
  • EPUB builder render lời giải thành popup footnote
  • Cấu trúc này cũng hữu ích khi tạo bản mẫu miễn phí của sách
    • Phần cuối bản mẫu miễn phí chỉ chứa lời giải cho phần có trong mẫu, chứ không phải toàn bộ lời giải của cả cuốn sách

Sở thích cú pháp và các lựa chọn thay thế

  • Phản đối phổ biến nhất với rST là cú pháp của nó xấu
  • Việc không muốn dùng một công cụ chỉ vì thấy nó khó nhìn cũng là lựa chọn hoàn toàn hợp lý, và lý do nhiều người khó chấp nhận Lisp cũng có thể xem là cùng một vấn đề về gu
  • Các lựa chọn thay thế gồm có asciidoc, MyST, Typst, Pollen, pandoc-extended markdown
  • Điểm chính không phải là Sphinx/rST đặc biệt tốt cho tài liệu quy mô lớn, mà là Markdown đơn giản đặc biệt không phù hợp cho tài liệu quy mô lớn

Giới hạn của các trình tạo tài liệu dựa trên Markdown

  • Markdown đơn giản không có cú pháp mở rộng thống nhất hay hỗ trợ gốc cho biến đổi trước khi render
  • Nhiều trình tạo tài liệu dựa trên Markdown bổ sung thêm bước tiền xử lý riêng để hỗ trợ các trường hợp sử dụng mới
  • Cách này nhìn chung vẫn hoạt động, nhưng đó là xử lý vòng ngoài của Markdown chứ không phải xử lý bên trong chính Markdown
  • Kết quả là sức mạnh tính năng bị giới hạn, và các công cụ dành cho lập trình viên cũng khó hiểu được những biến thể đó
    • Có LSP và treesitter cho Markdown và rST, nhưng khó có thể kỳ vọng mức hỗ trợ tương tự cho gitbook-markdown, md-markdown, hay leanpub-markdown
  • Cú pháp xấu của rST đôi khi lại là một lợi thế vì cây cú pháp của nó phong phú hơn
    • Có thể viết truy vấn treesitter chỉ để thay phần thân của một directive todo cụ thể
    • Điều này khả thi vì cây cú pháp của rST phong phú hơn cây cú pháp của Markdown

Cập nhật về Logic for Programmers

  • Logic for Programmers là cuốn sách nói về cách logic hình thức có thể hữu ích cho kỹ thuật phần mềm hằng ngày
  • Sách bắt đầu bằng phần tổng quan về toán học cơ bản, rồi đi tiếp qua 8 ứng dụng như property testing, ràng buộc cơ sở dữ liệu, bảng quyết định, v.v.
  • Hiện vẫn ở giai đoạn alpha, dài khoảng 20.000 từ và đang nhận phản hồi từ độc giả

Bài viết liên quan

1 bình luận

 
GN⁺ 2024-08-02
Ý kiến trên Hacker News

  • Nếu hỏi “chỉ vì nhìn vào là muốn nôn mà anh sẽ không dùng một công cụ tốt sao”, thì tôi sẽ trả lời là đúng vậy. Ưu điểm lớn nhất của Markdown là dễ đọc, và ưu điểm lớn thứ hai là dễ viết
    Việc nó dễ phân tích cú pháp đến mức nào hay dễ mở rộng đến đâu gần như không quan trọng. Bỏ qua chuyện Markdown có phải lựa chọn tốt nhất để viết sách hay không, thì với mục đích nhanh chóng viết văn bản có định dạng theo cách mà ngay cả người không rành cú pháp cũng dễ đọc, Markdown là số một. Tôi đâu cần viết sách, tôi chỉ cần ghi chú, tài liệu nhanh, và viết bình luận; còn nếu viết sách thì tôi sẽ dùng LaTeX trước cả RST

    • Khi Markdown bắt đầu nổi lên trong giới lập trình viên, nó trông như một lựa chọn khá buồn cười. Ngay cả lúc đó cũng đã có nhiều lựa chọn tốt hơn để biến văn bản thuần thành tài liệu có định dạng, thế mà các lập trình viên lại xây dựng CMS, ứng dụng năng suất, công cụ quản lý tài liệu, rồi cả plugin xoay quanh Markdown
      Nhưng sau khi dùng trong ứng dụng thực tế, tôi nhận ra cốt lõi của Markdown không nằm ở đó. Mục tiêu của nó là chỉ cung cấp định dạng tối thiểu, để ngay cả ở trạng thái văn bản thuần nó cũng đọc tự nhiên gần như khi đã được render thành HTML. Các kiểu định dạng được hỗ trợ cố ý giữ ít để có thể nhớ trong đầu và dùng mà không cần thanh công cụ. Nó phù hợp với ô nhập bình luận, chat, commit message, có lẽ cả bài blog, nhưng không phù hợp để viết tài liệu sản phẩm cấp doanh nghiệp. Dạo này người ta còn dùng Markdown ở cả những nơi không được render ra HTML, vì bản thân nó đã dễ đọc rồi, và tôi cũng mong HN hỗ trợ điều đó
    • Tôi đã viết sách bằng Markdown và không gặp vấn đề gì lớn. Đó là tiểu thuyết chứ không phải tài liệu kỹ thuật, nhưng cũng không có gì mà chỉ cần thỉnh thoảng trộn thêm HTML vào Markdown lại không giải quyết được
      Tôi cũng đã làm khá nhiều tài liệu kỹ thuật bằng Markdown, và nếu dùng phần mở rộng của Pandochttps://pandoc.org/MANUAL.html thì có thể thêm gần như mọi kiểu định dạng cần thiết, gồm cả công thức phức tạp và code block có tô sáng cú pháp. Markdown đó có thể được chuyển đổi sang HTML, tài liệu Word, ePub, PDF, v.v. Muốn lấy thứ gì khác ngoài Markdown ra dùng thì phải có một lý do thật sự thuyết phục
    • Tôi chắc mình nằm đâu đó trong top 10% người dùng TeX, nhưng tôi không nghĩ còn nhiều chỗ cho một ngôn ngữ dàn trang khác chen vào giữa Markdown và TeX. Markdown thì dễ nhưng hạn chế, còn TeX thì hơi khó hơn nhưng gần như linh hoạt vô hạn
      Vấn đề lớn nhất tôi thấy ở TeX không phải là ngôn ngữ mà là con người. Mọi người rất hay viết TeX kiểu spaghetti với style tệ hại. Nhưng nếu viết với tư duy “tài liệu là code” thì có thể cho ra kết quả khá gọn gàng. Vấn đề lớn thứ hai là không có trình biên dịch TeX → HTML nào thật sự tốt
    • Câu “nếu viết sách thì tôi sẽ dùng LaTeX” nghe như một lựa chọn khủng khiếp ở giai đoạn viết và cấu trúc nội dung. Tôi thà viết bằng Markdown để không phải bận tâm đến dàn trang, rồi chỉ chuyển sang LaTeX ở giai đoạn xuất bản
      Tôi không thành thạo LaTeX, nhưng lần tôi thử học nó có cảm giác như đang học ngôn ngữ của một nền văn minh ngoài hành tinh dạng côn trùng. Nó hoàn toàn không trực quan, và nếu không theo kiểu sao chép thứ người khác đã làm sẵn rồi nhét nội dung của mình vào thì gần như không thể tự làm cái gì mới. Nếu tôi nhớ không nhầm thì nó cũng không có hỗ trợ Unicode hạng nhất
    • Tôi khó mà đồng ý với nhận định Markdown là “công cụ tốt nhất để nhanh chóng viết văn bản có định dạng theo cách mà ngay cả người không rành cú pháp cũng dễ đọc”. Ngay ở phần cơ bản thì nó cũng chưa phải tốt nhất
      Ngay cả việc dùng dấu sao hoặc dấu gạch dưới cho chữ nghiêng cũng đòi hỏi phải làm quen, trong khi có những cách trực quan hơn nhiều như /italic slashes/. Còn khi vượt ra ngoài phần cơ bản, bảng biểu, metadata, hay tag sẽ che mất nội dung văn bản, khiến việc viết và đọc không hề dễ nếu không có công cụ phù hợp. Nếu dễ mở rộng thì cũng có thể sửa những vấn đề cơ bản này, nên tính mở rộng cũng có liên quan

  • Tôi đã làm người viết tài liệu kỹ thuật khoảng 12 năm, và vào đầu sự nghiệp đã chuyển tài liệu của một startup từ Word sang Sphinx. Sau đó tôi làm với CMS/phần mềm nền tảng tài liệu dành cho lập trình viên độc quyền của Google, các trang dựa trên Eleventy, và 2 năm gần đây lại làm với pigweed.dev, một trang dựa trên Sphinx. Tôi cũng từng làm ở một startup dùng readme.com và có đụng qua Docusaurus, Astro, Hugo một chút
    Chỉ riêng reStructuredText có thể hơi thô, nhưng reST kết hợp với Sphinx thì rất tuyệt. Điểm mạnh của Sphinx vượt xa điểm yếu của reST. Nếu là một trang tài liệu chuyên môn lớn, hơn 100 trang, hơn 10 người đóng góp, thì về dài hạn tôi khá tin rằng Sphinx là lựa chọn có trách nhiệm nhất. Ví dụ ở Pigweed, chỉ cần viết :bug:\59385981`` là nó sẽ tự biến thành liên kết https://pwbug.dev/59385981, và nếu sau này cần di chuyển hàng loạt các liên kết bug thì cũng rất dễ. Các liên kết nội bộ cũng luôn được đảm bảo là có thể phân giải, và nếu liên kết tới chỗ không tồn tại thì sẽ có cảnh báo hoặc lỗi. Trước đây tôi đã viết ở https://technicalwriting.dev/src/link-text-automation.html rằng thật kỳ lạ khi đây không phải là tiêu chuẩn của các trang tài liệu. Sphinx cũng có API mở rộng và giao diện được định nghĩa tốt, hệ sinh thái trên PyPI cũng khá lớn. Dạo này tôi gọi Sphinx là gã khổng lồ đang ngủ của các hệ thống tài liệu, và chỉ cần thêm một chút nỗ lực tập thể thì nó có thể trở nên còn ấn tượng hơn nhiều

    • Điểm này thực sự rất quan trọng. Có quá nhiều CMS hay trình tạo trang tĩnh bắt người viết phải chèn URL cuối cùng trực tiếp khi viết bài
      Nếu slug thay đổi hoặc cấu trúc trang được tổ chức lại thì phải tìm và thay trên toàn bộ site. Trình tạo trang tĩnh hoàn toàn có thể cho phép liên kết kiểu [Hello](../hello.md) rồi phân giải khi build, nhưng nhiều công cụ tôi từng dùng hoặc từng xem qua lại bắt nhập trực tiếp kiểu [Hello](/why/hello/). Có vẻ tính năng này khá gây chia rẽ. Kể cả khi nói với thành viên các nhóm làm trình tạo trang tĩnh, tôi cũng chỉ nhận được câu trả lời kiểu “tại sao lại cần cái đó”, và dù có giải thích thì cũng không thuyết phục được. Không biết là phải từng gặp vấn đề này mới hiểu giá trị của giải pháp, hay vì họ quen với việc dùng một lần rồi không phải bảo trì hơn 10 năm, nhưng tôi mong nó được hỗ trợ rộng rãi hơn
    • Sphinx rất xuất sắc nhưng bị đánh giá thấp nghiêm trọng. Theo những gì tôi biết, Sphinx là framework tài liệu duy nhất vừa có cấu trúc vững chắc, vừa mở rộng được, lại còn được dùng rộng rãi
      Hệ sinh thái plugin rất tuyệt, tạo ra đòn bẩy cực lớn để cải thiện tài liệu của nhóm và dự án. Bản thân reStructuredText thì tôi không thích lắm, nhưng giờ nhờ MyST-Parser mà phần lớn những gì trước đây Sphinx bị gắn chặt với RST nay cũng có thể làm bằng Markdown: https://github.com/executablebooks/MyST-Parser
    • Việc tùy biến các thành phần dùng chung trên toàn site với Markdown+Pandoc cũng rất dễ. Tôi đã xử lý việc thay các thẻ ảnh chứa liên kết YouTube thành thẻ video và ảnh thumbnail có văn bản thay thế, đồng thời nối các thẻ ảnh của tệp video cục bộ với ffmpeg để tối ưu hóa và đổi kích thước, tất cả chỉ bằng vài dòng code
    • Trước khi đọc bình luận này tôi còn không biết đến Sphinx. Tôi đã viết tài liệu kỹ thuật hơn 20 năm như một phần việc phụ bên cạnh công việc phát triển, và trước giờ thiên về TeX và XSL tùy biến hơn
      Tôi vừa chuyển một cuốn sách hơn 200 trang giải thích ngôn ngữ/VM/lớp trừu tượng hóa nội bộ sang Sphinx, và đây thật sự là một hệ thống thay đổi cuộc đời. Tôi ước gì tài liệu của chính Sphinx dễ tiếp cận hơn hoặc có nhiều ví dụ hơn, nhưng hiện tại tôi đang ở đúng kiểu cảm giác trăng mật rất mãnh liệt. Mối quan tâm chính của tôi là cách tạo ra sách PDF đẹp mắt, và một hệ thống có thể cắt cuốn sách thành các trang man tương thích POSIX theo từng chương và mục
    • Nếu Sphinx muốn thành công lớn hơn với số đông, ưu tiên số một là phải có các theme đẹp, chất lượng cao
      Khi chọn trình tạo site, tính thẩm mỹ là một yếu tố khá quan trọng. Hugo và Gatsby có theme mặc định rất tốt, và thực tế tôi từng chọn chúng cho dự án chỉ vì lý do đó. Bộ sưu tập theme của Sphinx https://sphinx-themes.org/ và https://sphinxthemes.com/#featured-themes nhìn chung khá nhạt nhẽo. Theme RTD chuẩn của Sphinx https://sphinx-rtd-theme.readthedocs.io/en/stable/ nếu so với tài liệu của Apple https://developer.apple.com/documentation/swift/array hay Fluent UI https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--default thì trông đã lỗi thời

  • Tôi cho rằng câu “Markdown là một biểu diễn gọn nhẹ của HTML” là vấn đề lớn nhất trong bài này. Điều đó chắc chắn không chính xác.
    Markdown được thiết kế như một công cụ để chuyển đổi các quy ước định dạng văn bản từng được dùng gần như như chuẩn thực tế trong email và bài viết Usenet đầu thập niên 1990. Do ràng buộc 7-bit ASCII, các định dạng như nhấn mạnh hay tiêu đề được biểu thị bằng ký hiệu đặc biệt, và HTML cũng có nhiều điểm giống với quy ước vô danh đó. Vì vậy John Gruber đã viết một script cơ bản vào năm 2004 để chuyển nó sang HTML https://daringfireball.net/projects/markdown/, nhưng có lẽ ông không ngờ nó sẽ trở thành một chuẩn thực tế phổ biến đến vậy

    • Ngay câu đầu tiên ở liên kết đó đã là “Markdown is a text-to-HTML conversion tool for web writers.”
      Gruber không chỉ lấy chuẩn thực tế của Usenet rồi đơn giản làm ra một bộ chuyển đổi HTML, mà đã vay mượn từ Usenet và các quy ước khác để thiết kế markup của riêng mình. Phần “Acknowledgements” ở cuối trang liên kết cũng cho thấy điều đó. Markdown ngay từ đầu đã được định hướng là một cú pháp markup cho web CMS, và nói nó là một biểu diễn gọn nhẹ của HTML là đúng. Trọng tâm là khiến mọi phần của cú pháp tạo ra HTML tương ứng trực tiếp
    • Tôi không đồng ý. Markdown luôn gắn với HTML, đến mức các parser Markdown thực sự hỗ trợ trộn lẫn thẻ HTML
      Việc nó lấy cảm hứng từ quy ước email không làm cho câu “Markdown là một biểu diễn gọn nhẹ của HTML” kém đúng hơn
    • Mong là đừng tiếp tục kiểu tranh cãi ngữ nghĩa này nữa. Nó tạo ra một cuộc trò chuyện nhàm chán và cũng trái với guideline của HN
      Có quy tắc là hãy trả lời theo cách diễn giải hợp lý và mạnh nhất về điều đối phương nói, thay vì bám vào cách hiểu yếu hơn chỉ vì dễ công kích. Cũng có quy tắc là đừng chỉ chọn câu khiêu khích nhất trong bài để phàn nàn, mà hãy phản hồi phần thú vị: https://news.ycombinator.com/newsguidelines.html
      Nếu không đồng ý với luận điểm chính của bài, cứ nói rằng bạn thích Markdown hơn rST và giải thích vì sao. Cãi nhau chỉ vì đúng một câu về việc Markdown chính xác là gì thì thật ngớ ngẩn
    • Bản thân Markdown tách biệt với định dạng email và Usenet. Markdown là một cú pháp cụ thể, được định nghĩa không tốt, rồi sau đó mở rộng thành nhiều họ cú pháp nhìn chung khá giống nhau
      Nó đúng là lấy cảm hứng từ các quy ước như email hay Usenet, và một số trong đó còn có trước cả máy tính. Ví dụ, tôi nghĩ mình từng thấy tài liệu đánh máy cũ dùng dấu sao như chữ nghiêng. Nhưng Markdown gắn rất chặt với HTML, cú pháp của nó cũng bị ràng buộc mạnh bởi HTML, và những nỗ lực tách nó khỏi HTML phần lớn khó tránh khỏi thất bại
    • Cả hai bên đều đúng. Bản triển khai ban đầu là một siêu tập của HTML. Những gì thông dụng thì viết bằng cú pháp nhẹ, còn phần còn lại thì viết bằng HTML

  • Tôi cho rằng điểm cốt lõi của Markdown là làm những việc đơn giản nhanh hơn so với HTML thô, nhưng vẫn cho phép trộn HTML thô vào khi cần
    Trong các dự án mà tôi cần sức mạnh của RST hơn Markdown, tôi lại thấy viết HTML trực tiếp còn tiện hơn

    • Khi tác giả viết kiểu “có thể mở rộng Sphinx để tạo đối tượng văn bản mới; với Markdown cơ bản thì phải chèn HTML trực tiếp”, tôi lại thấy thắc mắc rằng nếu đã cần tính năng đó thì dùng HTML luôn có gì không ổn. Tôi không hiểu vì sao phải thêm một tầng nữa

  • Khi xây dựng một hệ thống tài liệu có độ phức tạp tương tự, tôi đã xem xét RST vì rất cần một loại markup có ngữ nghĩa rõ ràng, kiểu như lưu cấu trúc của file RST trong cơ sở dữ liệu rồi trộn kết quả từ cơ sở dữ liệu vào nội dung
    Tôi gặp hai vấn đề. Thứ nhất, công cụ RST không có unparser để xuất lại RST. Tôi muốn tự động tạo file RST bằng cách hợp nhất nhiều file RST và các nguồn khác, rồi thao tác chúng như một API tài liệu, nhưng nó không hỗ trợ. Thứ hai, công cụ RST kỳ vọng một tập hợp block được định nghĩa cho từng tài liệu cụ thể. Nếu block được biểu diễn theo cách tổng quát, lẽ ra có thể có công cụ chuyển đổi tài liệu ngay cả khi không biết định nghĩa block nội bộ, nhưng thực tế không phải vậy. Đây là vấn đề của công cụ hơn là của chính RST, nhưng mỗi lần phải đào code xuống tận đáy thì tôi lại nghĩ đến các hệ thống markup khác như loại dựa trên HTML

    • Có thể dùng XML thay vì HTML để viết tài liệu có cấu trúc. XML cho phép định nghĩa các thẻ tùy chỉnh cần thiết và nếu muốn thì còn có thể kiểm tra schema
      Ưu điểm của cách này là có thể kiểm soát hoàn toàn schema đầu vào và đầu ra, còn nhược điểm là cú pháp ồn ào hơn Markdown hay RST rất nhiều, đồng thời cần script để parse và chuyển đổi sang định dạng đầu ra mong muốn
    • Trong Python, rST chỉ là một trong nhiều định dạng đầu vào mà docutils hỗ trợ: https://docutils.sourceforge.io/README.html#purpose
      Toàn bộ mục đích của docutils là parse định dạng và chuyển nó thành API: https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers
    • rST và AsciiDoc có vẻ khá tương đồng về mặt tính năng. Tôi tò mò không biết các điểm yếu và tính năng còn thiếu của chúng có cũng tương tự nhau không
    • Tôi từng là committer của docutils, công cụ chính của rST. Một trong những lý do tôi chuyển công cụ sang Markdown là vì làm việc với docutils quá đau khổ. Chỉ riêng việc họ từ chối chuyển sang một nơi như GitHub cũng đã cho thấy cộng tác với họ thiếu thân thiện đến mức nào
    • Hiện tôi không có máy tính để kiểm tra, nhưng hình như có thể làm điều bạn muốn bằng chỉ thị include

  • Vài năm trước tôi từng tổng hợp một tập con của reStructuredText đủ đáng để ghi nhớ: https://simonwillison.net/2018/Aug/25/restructuredtext/
    Trong các dự án gần đây, tôi đã bắt đầu dùng MyST; nó cung cấp các tính năng tham chiếu và mục lục mà tôi coi trọng ở reStructuredText, đồng thời cho phép dùng cú pháp Markdown dễ viết hơn đối với người đóng góp

    • Điểm mạnh về liên kết, đặc biệt là liên kết ngoài, là rất lớn. Trên các trang tài liệu, bạn có thể tham chiếu cùng một liên kết ngoài ở nhiều nơi và nếu nó thay đổi thì chỉ muốn cập nhật một lần
      Thứ thực sự thay đổi cuộc chơi là rST+Sphinx với các chỉ thị :ref:, :doc: cho liên kết nội bộ. Khi tham chiếu anchor hoặc liên kết tài liệu trong cùng nội dung, bạn không cần tự gõ tiêu đề, và có thể tránh việc các tiêu đề gõ tay đó dần trở nên lỗi thời: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role
      Đây là một trong những tính năng tôi nhớ nhất khi không viết bằng rST

  • Không phải để chen ngang cuộc thảo luận về ReStructuredText, nhưng nếu đang tìm một ngôn ngữ đánh dấu cho nhiều thứ hơn Markdown, tôi muốn khuyên nên xem AsciiDoc thay vì ReStructuredText. Tôi đã viết tài liệu kỹ thuật nhiều năm bằng cả ba loại, và thấy AsciiDoc tốt hơn ReStructuredText lẫn Markdown
    Ví dụ, hỗ trợ bảng của Markdown và ReStructuredText đều rất phiền toái. Định dạng bảng của AsciiDoc dễ đọc, dễ viết và dễ bảo trì; còn mạnh hơn nhờ hỗ trợ header, caption, kích thước tùy chỉnh cho bảng và hàng, cũng như định dạng phức tạp bên trong bảng. Nó có một chuẩn duy nhất, không có nhiều phương ngữ như Markdown; cú pháp ngắn gọn, dễ đọc và đường cong học tập nhẹ hơn ReStructuredText. Các lựa chọn để tạo kiểu đầu ra cũng tốt hơn, chuỗi công cụ vượt trội hơn, và các tính năng tài liệu tích hợp rất phong phú nên ít phải phụ thuộc vào plugin bên thứ ba. AsciiDoc được thiết kế cho tài liệu kỹ thuật ngay từ đầu, còn hai loại kia giống như được uốn cho hợp với vai trò đó hơn

  • Khi trình bày đẹp một tài liệu Markdown cỡ 5~10 trang, rồi để chính nó được render bên trong các template Jinja năng động hơn, thì khởi đầu khá ổn. Cũng có quy trình build cho tài liệu tự động, và quy mô đã lớn hơn một README GitHub đơn lẻ. Nhưng từ đó trở đi là bắt đầu đau đầu
    Tài liệu trên trang dự án GitHub thì không thật sự khớp, không rõ có cần file .nojekyl hay không, gh-pages branch còn cần nữa không, cũng chẳng biết là cấu hình kho chứa sai hay thay đổi chưa được phản ánh. Thử GitHub Actions một hồi vài tiếng là thấy vô lý. Xem lại Read the Docs thì có vẻ nó muốn Sphinx, thế là ghép Markdown với Sphinx; build thì được nhưng sau khi triển khai độ rộng trang lại hỏng, trong khi local không tái hiện được nên có vẻ là do quảng cáo chèn vào ở gói cộng đồng. Rất nhiều dự án chạy tốt với nó và bản thân tôi cũng từng làm được, nhưng cho đến khi nó thực sự chạy thì có quá nhiều chi tiết nhỏ nhặt đến mức khó tin. Cuối cùng, vấn đề không phải Markdown đối đầu RST, mà là tìm ra tổ hợp phù hợp cho dự án tài liệu quy mô vừa và hosting tĩnh

    • Tôi tò mò không biết bạn đã xem qua mdBook chưa. Tôi chưa tự dùng, nhưng đã thấy tài liệu của nhiều dự án dùng mdBook khá tốt, và khi vượt qua mức một file README đơn lẻ thì nó trông có vẻ rất ổn
      Hướng dẫn triển khai tự động cũng được viết đầy đủ: https://github.com/rust-lang/mdBook

  • Có vẻ mọi người đang bỏ qua việc tác giả đang nói trong bối cảnh tự dàn trang sách của chính mình. Đây không phải là lập luận rằng nhìn chung rST tốt hơn Markdown
    Trong trường hợp phổ biến, sự đơn giản của Markdown là lý do nó được dùng rộng rãi, nhưng đối tượng mà tác giả đang nói đến không phải như vậy

  • Thật thú vị khi người ta phản ứng như thể reST được tạo ra để cạnh tranh với Markdown. Thực ra gần như ngược lại. reST là phiên bản phát triển của StructuredText từ năm 2002, còn Markdown được công bố lần đầu vào năm 2004
    Mục tiêu của hai bên rất giống nhau, và với những văn bản cơ bản nhất thì cả hai đều có thể được đọc và viết như văn bản thuần. Khi ấy ai cũng muốn có thứ như vậy nên mới xuất hiện nhiều định dạng. Tôi không nghĩ Markdown thắng là vì nó “đơn giản hơn” hay “dễ đọc hơn”. Với những nội dung có thể biểu đạt dễ dàng bằng ASCII thuần và khoảng trắng, nhìn chung hai bên có thể thay thế cho nhau. Có ai sẽ nói tài liệu reST trong ví dụ là một đoạn khó hiểu đến mức không thể đọc nếu không có parser không? Tôi cũng không rõ một biến thể Markdown nào đó tốt hơn ở điểm nào; có lẽ chỉ là sự ngẫu nhiên của lịch sử khiến một bên chiếm ưu thế, còn cả hai đều đủ tốt cho mục tiêu cốt lõi

    • Vì đây là một ví dụ rất đơn giản nên cả Markdown lẫn reST đều xử lý dễ dàng
      reST cung cấp nhiều tính năng định dạng bổ sung hữu ích khi cần, nhưng nếu không cần thì chúng lại là phần thừa. Tôi bắt đầu dùng GitHub-flavored Markdown khoảng năm 2010 khi đăng ký GitHub, và cũng đã vài lần dùng reStructuredText vì tài liệu Python. Loại sau có đường cong học tập cao hơn nhiều, và từ đó đến giờ tôi không có lý do gì để dùng lại
    • Bảo là không đọc được thì không, nhưng bảo là nhập vào thấy bực thì đúng. Tiêu đề kiểu gạch dưới rất phiền khi chỉnh sửa, và dù không cần khớp độ dài tuyệt đối thì vẫn tạo cảm giác bị ép phải canh cho đúng
      Dấu backtick kép cũng là một cú pháp gây khó chịu quá mức so với lượng thời gian thực sự phải bỏ ra