ทำไมฉันถึงชอบ rST มากกว่า Markdown

 (buttondown.email)
1 คะแนน โดย GN⁺ 2024-08-02 | 1 ความคิดเห็น | แชร์ทาง WhatsApp

ทำไมฉันถึงชอบ rST

ฉันจะไม่หยุดยืนยันเรื่องนี้

  • ได้เผยแพร่ "Logic for Programmers" เวอร์ชันใหม่ v0.2 แล้ว โดยเวอร์ชันนี้มีการรองรับ epub การแก้ปัญหาข้อจำกัด และเนื้อหาเกี่ยวกับสเปกของ formalism
  • หนังสือเล่มที่สอง "Learn TLA+" ก็เขียนด้วย Sphinx เช่นกัน โดย Sphinx ใช้มาร์กอัปเฉพาะตัวชื่อ reStructured Text (rST)
  • rST มีเส้นโค้งการเรียนรู้ที่ชันกว่า markdown หลังจากเขียนหนังสือหลายเล่มด้วย markdown ก็รู้สึกว่าต้องการสิ่งที่ดีกว่า จึงเปลี่ยนมาใช้ rST

ทำไม rST ถึงดีกว่า

  • markdown เป็นตัวแทนแบบน้ำหนักเบาของ HTML ขณะที่ rST เป็นตัวแทนแบบน้ำหนักปานกลางของ abstract document tree
  • วิธีสร้างรูปภาพใน markdown: 
    ![alttext](example.jpg)
  • วิธีสร้างรูปภาพใน rST: 
    .. image:: example.jpg
   :alt: alttext
  • rST สามารถขยายได้ สามารถเพิ่ม text object แบบใหม่ได้
  • Sphinx สามารถจัดการ cross-referencing ได้ ตัวอย่างเช่น ถ้าใส่แองเคอร์ foo ในเอกสารหนึ่ง และใส่ :ref:image <foo>`` ในอีกเอกสารหนึ่ง Sphinx จะใส่ URL ที่ถูกต้องให้
  • rST สามารถจัดโค้ดแปลงเอกสารให้ทำงานร่วมกับส่วนที่เหลือของ build process ได้

กรณีการใช้งานหนึ่ง

  • "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 ดูไม่สวย
  • เข้าใจได้ถ้าใครไม่อยากใช้เครื่องมือดี ๆ เพราะไม่ชอบไวยากรณ์
  • ยังมี document builder อื่น ๆ เช่น asciidoc, MyST, Typst, Pollen และ pandoc-extended markdown
  • ตัวสร้างเอกสารที่อิง markdown มักเพิ่มขั้นตอน preprocessing ของตัวเองเพื่อรองรับกรณีใช้งานใหม่ ๆ
  • มีทั้ง LSP และ treesitter สำหรับ markdown และ rST แต่ไม่มีสำหรับ gitbook-markdown, md-markdown หรือ leanpub-markdown

สัปดาห์หน้าไม่มีจดหมายข่าว

  • จะอยู่ที่ฮ่องกง

อัปเดต 2024-07-31

  • ได้เพิ่มคำอธิบายสั้น ๆ เกี่ยวกับ "Logic for Programmers"
  • หนังสือเล่มนี้พูดถึงวิธีที่ตรรกะเชิงรูปแบบมีประโยชน์ต่อวิศวกรรมซอฟต์แวร์ในชีวิตประจำวัน
  • มีภาพรวมคณิตศาสตร์พื้นฐานและแอปพลิเคชันที่แตกต่างกันแปดแบบ
  • ยังอยู่ในช่วงอัลฟา แต่เขียนไปแล้วมากกว่า 20,000 คำ และมีเนื้อหาที่มีประโยชน์มากมาย

สรุปโดย GN⁺

  • rST เป็นเครื่องมือเขียนเอกสารที่ทรงพลังกว่า markdown
  • เมื่อใช้ร่วมกับ Sphinx จะสามารถแปลงและขยาย document tree ได้
  • มีประโยชน์สำหรับการเขียนหนังสืออย่าง "Logic for Programmers"
  • แม้หลายคนจะมองว่าไวยากรณ์ของ rST ดูไม่สวย แต่ก็ยังมีทางเลือกอื่นอยู่
  • อาจเป็นประโยชน์สำหรับผู้ที่สนใจวิศวกรรมซอฟต์แวร์ที่เกี่ยวข้องกับตรรกะเชิงรูปแบบ

บทความที่เกี่ยวข้อง

1 ความคิดเห็น

 
GN⁺ 2024-08-02
ความคิดเห็นจาก Hacker News
  • จุดเด่นที่สุดของ Markdown คืออ่านง่ายและเขียนง่าย
  • Markdown อาจไม่ใช่เครื่องมือที่เหมาะที่สุดสำหรับการเขียนหนังสือ แต่เหมาะที่สุดสำหรับการเขียนข้อความที่มีการจัดรูปแบบอย่างรวดเร็ว
  • จะใช้ LaTeX ในการเขียนหนังสือ และ Markdown เหมาะกับการจดบันทึก การเขียนเอกสารอย่างรวดเร็ว และการเขียนคอมเมนต์
  • reStructuredText (reST) เองอาจจะดูหยาบอยู่บ้าง แต่เมื่อใช้ร่วมกับ Sphinx แล้วถือว่ายอดเยี่ยมมาก
    • Sphinx เป็นตัวเลือกที่เหมาะสำหรับเว็บไซต์เอกสารขนาดใหญ่และเป็นมืออาชีพ
    • Sphinx ทำให้ปรับแต่งองค์ประกอบร่วมของเว็บไซต์ได้ง่าย
    • ช่วยรับประกันได้ว่าลิงก์ภายในจะถูกแก้ไขได้เสมอ
    • มี API สำหรับส่วนขยายและธีมที่กำหนดไว้อย่างชัดเจน
    • มีส่วนขยายและธีมหลากหลายบน PyPI
  • Markdown เป็นตัวแทนแบบน้ำหนักเบาของ HTML ส่วน reST เป็นตัวแทนแบบน้ำหนักปานกลางของ abstract document tree
  • Markdown ถูกออกแบบมาเพื่อแปลงข้อความที่มีการจัดรูปแบบจากอีเมลและโพสต์ Usenet
  • เครื่องมือของ reST ยังขาดความสามารถในการสร้างไฟล์ RST โดยอัตโนมัติ
  • Markdown ช่วยให้ทำงานง่าย ๆ ได้อย่างรวดเร็ว และยังแทรก raw HTML ได้เมื่อจำเป็น
  • MyST ช่วยให้ใช้ไวยากรณ์ Markdown พร้อมได้ความสามารถของ reStructuredText
  • การทำเอกสารสำหรับหน้าโปรเจกต์บน GitHub อาจซับซ้อน และการใช้ Sphinx ร่วมกับ Markdown ก็อาจมีประโยชน์
  • ผู้เขียนกล่าวถึง rST ในบริบทของการจัดพิมพ์หนังสือของตนเอง
  • reST ไม่ได้เป็นคู่แข่งของ Markdown แต่เป็นฟอร์แมตที่เกิดก่อน Markdown
  • Markdown และ reST มีเป้าหมายเดียวกันเป็นพื้นฐาน
  • ทั้ง Markdown และ reST ต่างก็อ่านง่ายและเขียนได้รวดเร็ว
  • Markdown ถูกใช้อย่างแพร่หลายมากกว่าเนื่องจากเหตุผลทางประวัติศาสตร์
  • Markdown สามารถกำหนด custom block type และแปลง document tree ได้
  • Jupyter Book เป็นตัวอย่างที่ดีว่าการใช้ Markdown สามารถเรนเดอร์ไปยังเป้าหมายอื่น เช่น PDF ได้