เหตุผลที่ผมชอบ rST มากกว่า Markdown

 (buttondown.email)
1 คะแนน โดย GN⁺ 2024-08-02 | 1 ความคิดเห็น | แชร์ทาง WhatsApp
  • reStructured Text(rST) ของ Sphinx เรียนรู้ยากกว่า Markdown แต่ช่วยควบคุมโครงสร้างและรูปแบบเอาต์พุตได้ละเอียดกว่าในเอกสารขนาดใหญ่อย่างหนังสือ
  • Markdown มีลักษณะใกล้เคียงกับสัญกรณ์เบา ๆ สำหรับเขียน HTML ส่วน rST ยึด abstract document tree เป็นศูนย์กลาง และสามารถเพิ่มอ็อบเจ็กต์เอกสารใหม่ได้ด้วยการผสมผสาน directive, node และ renderer
  • Sphinx แปลง doctree ก่อนเรนเดอร์ จึงจัดการงานอย่าง cross-reference, การประมวลผลตามรูปแบบเอาต์พุต และการแปลงในขั้นตอน build เฉพาะภายในระบบเอกสารได้
  • ใน Logic for Programmers ผู้เขียนวางแบบฝึกหัดและเฉลยไว้ใกล้กับต้นฉบับตอนเขียน แล้วใช้ ส่วนขยายแบบกำหนดเอง เพื่อเปลี่ยนตำแหน่งและวิธีแสดงผลในเอาต์พุต EPUB และ LaTeX
  • Markdown แบบเรียบง่ายขาดไวยากรณ์ส่วนขยายที่เป็นหนึ่งเดียวและการรองรับการแปลงก่อนเรนเดอร์ ทำให้ยิ่งเครื่องมือสร้างเอกสารเลี่ยงไปใช้ preprocessing แยกต่างหาก การรองรับจากเครื่องมือและความสามารถในการขยายก็ยิ่งอ่อนลง

เหตุผลที่เลือก rST

  • เวอร์ชันใหม่ของ Logic for Programmers เป็นหนังสือเล่มที่สองที่เขียนด้วย Sphinx และงานก่อนหน้านี้คือ Learn TLA+ เวอร์ชันใหม่ก็ใช้ Sphinx เช่นกัน
  • Sphinx ใช้ reStructured Text และ rST มี learning curve ชันกว่า Markdown
  • หลังจากเขียนหนังสือหลายเล่มด้วย Markdown แล้ว ผู้เขียนต้องการเครื่องมือที่ดีกว่า จึงเปลี่ยนมาใช้ rST
  • ตัว rST เองเป็นอิสระจาก Sphinx แต่ในทางปฏิบัติหลายคนใช้ rST เพราะ Sphinx จึงกล่าวถึงทั้งสองร่วมกัน

ความแตกต่างด้านโครงสร้างระหว่าง Markdown กับ rST

  • ความแตกต่างที่ใหญ่ที่สุดคือ Markdown ใกล้เคียงกับ สัญกรณ์ HTML แบบเบา ส่วน rST เป็นสัญกรณ์ระดับกลางที่สร้าง abstract document tree
  • ไวยากรณ์รูปภาพของ Markdown สามารถแปลงอย่างง่ายเป็น HTML เช่น <img alt="alttext" src="example.jpg"/> ได้
    • แม้เอนจิน Markdown สมัยใหม่จำนวนมากจะ parse เป็น representation ขั้นกลาง แต่ลักษณะพื้นฐานก็ยังใกล้เคียงกับสัญกรณ์ HTML แบบเบา
  • รูปภาพใน rST แสดงด้วย directive .. image::
    • Sphinx จะค้นหา handler ของ directive ที่ลงทะเบียนไว้ แล้วเรียกใช้ ImageDirective.run
    • ผลลัพธ์การทำงานจะกลายเป็นอ็อบเจ็กต์ node เช่น image_node ที่มีฟิลด์ alt
    • เมื่อประมวลผล doctree ทั้งหมดเสร็จแล้ว HTML Writer จะค้นหาฟังก์ชันเรนเดอร์ของ image_node แล้วส่งออกแท็ก HTML
  • วิธีของ rST มีการ implement และไวยากรณ์ที่ซับซ้อนกว่า และมี boilerplate มากกว่า Markdown แต่รูปภาพก็ถูกจัดการด้วยกลไกส่วนขยายเดียวกับ directive อื่น ๆ

วิธีเพิ่มอ็อบเจ็กต์เอกสารใหม่

  • ใน rST/Sphinx สามารถเพิ่ม text object ใหม่เป็นส่วนขยายได้
  • เช่น หากต้องการสร้าง <figure> และ <figcaption> แทน <image> ใน Markdown พื้นฐานต้องแทรก HTML โดยตรง
  • ใน Sphinx จัดการได้ด้วยการลงทะเบียน directive ใหม่ชื่อ figure
    • FigureDirective อาจสืบทอดจาก ImageDirective เพื่อใช้การประมวลผลรูปภาพส่วนใหญ่ซ้ำได้
  • รูปแบบการลงทะเบียน directive, การสร้าง node และการลงทะเบียน renderer แยกตาม builder ถูกใช้เหมือนกันกับทุกส่วนขยาย

การแปลง doctree ก่อนเรนเดอร์

  • Sphinx สามารถทำ การแปลง doctree ก่อนเรนเดอร์ได้
  • การ cross-reference ระหว่างเอกสารก็จัดการด้วยฟีเจอร์นี้
    • หากเอกสารหนึ่งมี anchor foo และอีกเอกสารมี :ref:\image <foo>`` Sphinx จะใส่ URL ที่ถูกต้องในขั้นตอน post-processing
  • โค้ดแปลงถูกปฏิบัติราวกับเป็นฟีเจอร์ชั้นหนึ่งภายในกระบวนการ build
    • สามารถใช้การแปลงเฉพาะเมื่อเป็นเอาต์พุต HTML เท่านั้น
    • สามารถรันการแปลงในขั้นตอน build เฉพาะได้
    • สามารถลบการแปลง built-in ที่ไม่ต้องการให้ทำงานได้ด้วย
  • ไม่ใช่เอกสารทุกแบบที่ต้องการพลังระดับนี้ และ Markdown ก็ถูกใช้อย่างแพร่หลายเพราะเบาและพกพาได้ดี

กรณีส่วนขยายแบบฝึกหัดและเฉลย

  • Logic for Programmers เป็นหนังสือที่ค่อนข้างใกล้เคียงคณิตศาสตร์ จึงต้องมี แบบฝึกหัด สำหรับผู้อ่าน
  • ตอนเขียน การวางแบบฝึกหัดและเฉลยไว้ใกล้กันในเอกสารทำได้ง่ายกว่า แต่สำหรับผู้อ่าน เฉลยควรปรากฏท้ายเล่ม
  • ข้อกำหนดแตกต่างกันไปตามรูปแบบเอาต์พุต
    • แบบฝึกหัดและเฉลยต้องลิงก์ถึงกัน
    • เมื่อคำนึงถึงการพิมพ์ PDF ก็ต้องมีการอ้างอิงเลขหน้าด้วย
    • วิธีเรนเดอร์ในเอาต์พุต LaTeX/PDF และ EPUB ต้องแตกต่างกัน
  • เพื่อทำสิ่งนี้ ผู้เขียนสร้าง ส่วนขยาย Sphinx แบบกำหนดเอง สำหรับจัดการ exercise, solution, solutionlist
  • ในเอาต์พุต HTML สำหรับดีบัก จะเรนเดอร์แบบฝึกหัดและเฉลยแบบ inline
  • ในการสร้าง EPUB และ LaTeX จะสร้าง doctree ทั้งหมดก่อน แล้วจึงรันการแปลง
    • ย้าย solution_node ทั้งหมดจากตำแหน่งเดิมไปไว้ใต้ solutionlist
    • เพิ่ม reference node ไปยังตำแหน่งเฉลยใหม่ให้กับแบบฝึกหัดแต่ละข้อ
    • เพิ่ม reference node กลับไปยังแบบฝึกหัดเดิมให้กับเฉลยแต่ละข้อ
  • LaTeX builder ครอบแบบฝึกหัดและเฉลยด้วย answers environment
  • EPUB builder เรนเดอร์เฉลยเป็น popup footnote
  • โครงสร้างนี้ยังช่วยตอนสร้าง ตัวอย่างฟรี ของหนังสือด้วย
    • ตอนท้ายของตัวอย่างฟรีจะมีเฉลยเฉพาะส่วนที่อยู่ในตัวอย่าง ไม่ใช่เฉลยของทั้งเล่ม

ความชอบด้านไวยากรณ์และทางเลือก

  • ข้อคัดค้านที่พบบ่อยที่สุดต่อ rST คือ ไวยากรณ์ดูไม่สวย
  • การไม่ใช้เครื่องมือเพราะไม่ชอบหน้าตาก็เป็นทางเลือกที่เป็นไปได้ และเหตุผลที่บางคนรับ Lisp ได้ยากก็อาจมองว่าเป็นเรื่องรสนิยมแบบเดียวกัน
  • ทางเลือกอื่นมี asciidoc, MyST, Typst, Pollen, pandoc-extended markdown
  • ประเด็นหลักไม่ใช่ว่า Sphinx/rST ดีเป็นพิเศษสำหรับเอกสารขนาดใหญ่ แต่คือ Markdown แบบเรียบง่าย ไม่เหมาะเป็นพิเศษสำหรับเอกสารขนาดใหญ่

ข้อจำกัดของตัวสร้างเอกสารบน Markdown

  • Markdown แบบเรียบง่ายไม่มีไวยากรณ์ส่วนขยายที่เป็นหนึ่งเดียว หรือการรองรับแบบ native สำหรับการแปลงก่อนเรนเดอร์
  • เครื่องมือสร้างเอกสารบน Markdown จำนวนมากเพิ่ม ขั้นตอน preprocessing ของตัวเองเพื่อรองรับ use case ใหม่
  • วิธีนี้โดยทั่วไปใช้งานได้ แต่กลายเป็นโครงสร้างที่เลี่ยงอยู่รอบ ๆ Markdown ไม่ใช่การประมวลผลภายใน Markdown
  • ผลคือความทรงพลังของฟีเจอร์มีขีดจำกัด และเครื่องมือสำหรับโปรแกรมเมอร์ก็เข้าใจรูปแบบดัดแปลงเหล่านั้นได้ยาก
    • มี LSP และ treesitter สำหรับ Markdown และ rST แต่คาดหวังเครื่องมือระดับเดียวกันสำหรับ gitbook-markdown, md-markdown, leanpub-markdown ได้ยาก
  • ไวยากรณ์ที่ดูไม่สวยของ rST อาจกลับกลายเป็นข้อดี เพราะมี syntax tree ที่มั่งคั่งกว่า
    • สามารถเขียน treesitter query ที่แก้เฉพาะ body ของ directive todo บางตัวได้
    • สิ่งนี้เป็นไปได้เพราะ syntax tree ของ rST มีข้อมูลมากกว่า syntax tree ของ Markdown

อัปเดต Logic for Programmers

  • Logic for Programmers เป็นหนังสือที่ว่าด้วยตรรกะเชิงรูปนัยมีประโยชน์ต่อวิศวกรรมซอฟต์แวร์ในชีวิตประจำวันอย่างไร
  • หนังสือเริ่มจากภาพรวมคณิตศาสตร์พื้นฐาน แล้วต่อด้วย 8 แอปพลิเคชัน เช่น property testing, database constraint และ decision table
  • แม้ยังอยู่ในขั้น alpha แต่มีความยาว 20,000 คำ และกำลังรับ feedback จากผู้อ่าน

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

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

 
GN⁺ 2024-08-02
ความคิดเห็นจาก Hacker News

  • ถ้าถามว่า “จะไม่ใช้เครื่องมือดี ๆ เพราะแค่เห็นแล้วรู้สึกอยากอาเจียนหรือ” ผมก็คงตอบว่าใช่ จุดแข็งที่สุดของ Markdown คืออ่านง่าย และจุดแข็งอันดับสองคือเขียนง่าย
    เรื่องว่าพาร์สง่ายแค่ไหน หรือขยายความสามารถง่ายแค่ไหน แทบไม่สำคัญเลย ไม่ว่าจะมองว่า Markdown เหมาะที่สุดสำหรับการเขียนหนังสือหรือไม่ก็ตาม สำหรับการเขียนข้อความที่มีรูปแบบอย่างรวดเร็วในแบบที่แม้คนไม่ค่อยรู้ไวยากรณ์ก็อ่านได้ง่าย Markdown คือดีที่สุดแล้ว เราไม่ได้จะเขียนหนังสือ แค่ต้องจดโน้ต ทำเอกสารอย่างรวดเร็ว หรือเขียนคอมเมนต์เท่านั้น และถ้าจะเขียนหนังสือ ผมคงใช้ LaTeX ก่อน RST

    • ตอนที่ Markdown เริ่มได้รับความนิยมในหมู่นักพัฒนา มันดูเป็นตัวเลือกที่ค่อนข้างน่าขำ ตอนนั้นก็มีตัวเลือกที่ดีกว่ามากมายสำหรับแปลงข้อความธรรมดาเป็นเอกสารที่มีการจัดรูปแบบอยู่แล้ว แต่นักพัฒนากลับกำลังสร้าง CMS, แอปเพิ่มผลิตภาพ, เครื่องมือจัดการเอกสาร และปลั๊กอินต่าง ๆ โดยมี Markdown เป็นศูนย์กลาง
      แต่พอได้ลองใช้ในแอปจริง ๆ ก็พบว่าแก่นของ Markdown ไม่ใช่เรื่องนั้น จุดประสงค์คือให้มีแค่ การจัดรูปแบบขั้นต่ำ เพื่อให้แม้อยู่ในสภาพข้อความธรรมดาก็อ่านได้เป็นธรรมชาติเกือบเท่าตอนเรนเดอร์เป็น HTML รูปแบบที่รองรับถูกตั้งใจให้มีน้อย จึงจำได้ขึ้นใจและใช้ได้โดยไม่ต้องมีแถบเครื่องมือ มันเหมาะกับช่องใส่คอมเมนต์ แชต ข้อความคอมมิต หรืออาจรวมถึงบทความบล็อก แต่ไม่เหมาะสำหรับเขียนเอกสารผลิตภัณฑ์ระดับองค์กร ทุกวันนี้มีการใช้ Markdown แม้ในที่ที่จะไม่ได้ถูกเรนเดอร์เป็น HTML เพราะตัวมันเองอ่านง่าย และผมก็อยากให้ HN รองรับด้วย
    • เคยเขียนหนังสือด้วย Markdown มาแล้ว และไม่มีปัญหาอะไร ถึงจะเป็นนิยายไม่ใช่เอกสารเทคนิค แต่ก็ไม่มีอะไรที่แก้ไม่ได้ด้วยการแทรก HTML บ้างเป็นครั้งคราวใน Markdown
      เอกสารเทคนิคก็เคยทำด้วย Markdown มาค่อนข้างเยอะ และถ้าใช้ ส่วนขยาย Pandochttps://pandoc.org/MANUAL.html ก็ใส่รูปแบบที่ต้องการได้เกือบทั้งหมด รวมถึงสมการซับซ้อนและบล็อกโค้ดพร้อม syntax highlighting Markdown นั้นสามารถแปลงเป็น HTML, เอกสาร Word, ePub, PDF และอื่น ๆ ได้ หากจะหยิบอย่างอื่นที่ไม่ใช่ Markdown มาใช้ ต้องมีเหตุผลที่โน้มน้าวใจได้มากจริง ๆ
    • ถ้าวัดจากผู้ใช้ TeX ผมน่าจะอยู่ประมาณท็อป 10% แต่ผมมองว่ายากที่จะมีพื้นที่มากนักให้ภาษา typesetting อีกตัวมาอยู่ระหว่าง Markdown กับ TeX Markdown นั้นง่ายแต่มีข้อจำกัด ส่วน TeX นั้นยากขึ้นเล็กน้อยแต่ยืดหยุ่นได้แทบไร้ขีดจำกัด
      ปัญหาใหญ่ที่สุดที่ผมเห็นใน TeX ไม่ใช่ตัวภาษา แต่เป็นปัญหาของคน ผู้คนมักเขียน TeX แบบสปาเกตตีที่มีสไตล์แย่มาก แต่ถ้าเขียนด้วยแนวคิดว่า “เอกสารคือโค้ด” ก็จะได้ผลลัพธ์ที่ค่อนข้างสะอาด ปัญหาใหญ่อันดับสองคือไม่มีคอมไพเลอร์ TeX → HTML ที่ดี
    • การบอกว่า “ถ้าจะเขียนหนังสือ ผมจะใช้ LaTeX” ดูเป็นตัวเลือกที่แย่มากในขั้นตอนการเขียนและจัดโครงสร้างเนื้อหา ผมคงเขียนด้วย Markdown แทน โดยไม่ต้องสนใจเรื่องการจัดหน้า แล้วค่อยแปลงเป็น LaTeX เฉพาะตอนเข้าสู่ขั้นตอนตีพิมพ์
      ผมไม่ถึงกับเชี่ยวชาญ LaTeX แต่ตอนที่เคยพยายามเรียน รู้สึกเหมือนกำลังเรียนภาษาของอารยธรรมมนุษย์ต่างดาวหน้าตาแบบแมลง มันไม่เป็นธรรมชาติเอาเสียเลย และแทบเป็นไปไม่ได้ที่จะทำอะไรใหม่ ๆ หากไม่ใช้วิธีคัดลอกสิ่งที่คนอื่นทำไว้แล้ว แล้วเอาข้อความของตัวเองยัดเข้าไปแทน เท่าที่จำได้ ตอนนั้นก็ยังไม่มี การรองรับ Unicode แบบ first-class ด้วย
    • ผมเห็นด้วยยากกับคำกล่าวที่ว่า Markdown เป็น “เครื่องมือที่ดีที่สุดสำหรับเขียนข้อความที่มีรูปแบบอย่างรวดเร็วในแบบที่แม้คนไม่ค่อยรู้ไวยากรณ์ก็อ่านได้ง่าย” แค่ดูพื้นฐานก็ยังไม่ใช่ดีที่สุดแล้ว
      การใช้ดอกจันหรือขีดล่างสำหรับตัวเอียงก็ต้องอาศัยความคุ้นเคย และยังมีวิธีที่ตรงตามสัญชาตญาณกว่ามากอย่าง /italic slashes/ พอออกนอกส่วนพื้นฐาน ตาราง เมทาดาทา และแท็กต่าง ๆ ก็บังข้อความจนเขียนและอ่านได้ไม่ง่ายหากไม่มีเครื่องมือที่เหมาะสม ถ้าขยายความสามารถได้ง่าย ก็จะแก้ปัญหาพื้นฐานเหล่านี้ได้ด้วย ดังนั้น ความสามารถในการขยาย จึงเกี่ยวข้องเช่นกัน

  • ผมทำงานเป็นนักเขียนเอกสารเทคนิคมาประมาณ 12 ปี และช่วงต้นอาชีพเคยย้ายเอกสารของสตาร์ทอัปจาก Word ไปเป็น Sphinx หลังจากนั้นก็ทำงานกับ CMS/แพลตฟอร์มเอกสารสำหรับนักพัฒนาของ Google ที่พัฒนาขึ้นเอง, เว็บไซต์ที่ใช้ Eleventy และในช่วง 2 ปีล่าสุดกลับมาทำงานกับไซต์ที่ใช้ Sphinx อีกครั้งคือ pigweed.dev ผมยังเคยทำงานกับสตาร์ทอัปที่ใช้ readme.com และได้แตะ Docusaurus, Astro, Hugo มาบ้างเล็กน้อย
    reStructuredText เพียงอย่างเดียว อาจดูหยาบ ๆ ได้ แต่ reST เมื่อใช้ร่วมกับ Sphinx นั้นยอดเยี่ยมมาก จุดแข็งของ Sphinx เหนือกว่าจุดอ่อนของ reST มาก สำหรับไซต์เอกสารเชิงวิชาชีพขนาดใหญ่ที่มี 100 หน้าขึ้นไปและมีผู้ร่วมเขียนมากกว่า 10 คน ผมค่อนข้างเชื่ออย่างหนักแน่นว่าในระยะยาว Sphinx เป็นตัวเลือกที่รับผิดชอบที่สุด ตัวอย่างเช่น ที่ Pigweed เราทำให้แค่เขียน :bug:\59385981`` ก็แปลงเป็นลิงก์ https://pwbug.dev/59385981 และต่อให้ภายหลังต้องย้ายลิงก์บั๊กจำนวนมากก็ทำได้ง่าย ลิงก์ภายในก็รับประกันได้เสมอว่าถูก resolve และถ้าลิงก์ไปยังที่ที่ไม่มีอยู่จริงก็จะมีคำเตือนหรือข้อผิดพลาดขึ้นมา ผมเคยเขียนไว้ที่ https://technicalwriting.dev/src/link-text-automation.html ว่าแปลกที่สิ่งนี้ไม่ใช่มาตรฐานของไซต์เอกสาร Sphinx ยังมี API สำหรับส่วนขยายและธีมที่กำหนดไว้ดี และมี ecosystem บน PyPI ที่ค่อนข้างใหญ่ ช่วงนี้ผมเรียก Sphinx ว่าเป็นยักษ์หลับของระบบเอกสาร และถ้าร่วมแรงกันอีกสักหน่อย มันจะยอดเยี่ยมขึ้นได้อีกมาก

    • ประเด็นนี้สำคัญมากจริง ๆ ในบรรดา CMS หรือ static site generator มีระบบจำนวนมากเกินไปที่บังคับให้ใส่ URL สุดท้าย โดยตรงตอนเขียน
      ถ้า slug เปลี่ยนหรือจัดโครงสร้างไซต์ใหม่ ก็ต้องค้นหาและแทนที่ทั้งไซต์ ทั้งที่ static site generator สามารถให้ลิงก์แบบ [Hello](../hello.md) แล้วค่อย resolve ตอน build ได้ แต่เครื่องมือที่ผมใช้หรือเคยดูมาหลายตัวกลับให้พิมพ์ [Hello](/why/hello/) โดยตรง ฟีเจอร์นี้ดูเหมือนจะมีคนชอบและไม่ชอบปะปนกัน ผมเคยคุยกับสมาชิกทีม static site generator ก็ได้คำตอบว่า “ทำไมถึงอยากได้สิ่งนั้นล่ะ” และถึงอธิบายไปก็ไม่เข้าใจ ไม่รู้ว่าต้องเคยเจอปัญหาก่อนถึงจะเห็นคุณค่าของวิธีแก้ หรือว่าเคยชินกับการเขียนครั้งเดียวแล้วไม่ต้องบำรุงรักษาเกิน 10 ปี แต่ผมอยากให้รองรับกันกว้างกว่านี้
    • Sphinx ยอดเยี่ยม แต่ถูกประเมินค่าต่ำเกินไปอย่างมาก เท่าที่ผมรู้ Sphinx เป็นเฟรมเวิร์กเอกสารเพียงตัวเดียวที่มีโครงสร้างแข็งแรง ขยายได้ และใช้งานกันแพร่หลาย
      ecosystem ของปลั๊กอินยอดเยี่ยมมาก จึงเป็นแรงทวีคูณมหาศาลในการปรับปรุงเอกสารของทีมและโปรเจกต์ ผมไม่ได้ชอบ reStructuredText เองนัก แต่ทุกวันนี้ด้วย MyST-Parser งานส่วนใหญ่ที่เมื่อก่อน Sphinx ผูกติดกับ RST อย่างแน่นหนา ก็ทำด้วย Markdown ได้แล้ว: https://github.com/executablebooks/MyST-Parser
    • การปรับแต่งองค์ประกอบร่วมของทั้งไซต์ก็ทำได้ง่ายมากด้วย Markdown+Pandoc เช่นกัน ผมจัดการเปลี่ยนแท็กรูปภาพที่มีลิงก์ YouTube ให้เป็นแท็กวิดีโอและภาพ thumbnail พร้อมข้อความทดแทน และเชื่อมแท็กรูปภาพของไฟล์วิดีโอในเครื่องเข้ากับ ffmpeg เพื่อ optimize และ resize ได้ด้วยโค้ดไม่กี่บรรทัด
    • ก่อนจะเห็นคอมเมนต์นี้ ผมไม่รู้จัก Sphinx เลย ผมเขียนเอกสารเทคนิคควบคู่กับงานพัฒนามานานกว่า 20 ปี และที่ผ่านมาใกล้เคียงกับฝั่ง TeX กับ XSL แบบกำหนดเองมากกว่า
      ผมเพิ่งย้าย หนังสือกว่า 200 หน้า ที่อธิบายภาษา/VM/เลเยอร์ abstraction ภายใน ไปยัง Sphinx และมันเป็นระบบที่เปลี่ยนชีวิตจริง ๆ ผมอยากให้เอกสารของ Sphinx เองมีอุปสรรคในการเริ่มต้นต่ำกว่านี้หรือมีตัวอย่างมากกว่านี้ แต่ตอนนี้รู้สึกเหมือนอยู่ในช่วงฮันนีมูนอย่างแรง สิ่งที่สนใจหลักคือวิธีสร้างหนังสือ PDF ที่ดูดี และระบบสำหรับตัดหนังสือออกเป็น man page ที่เข้ากันได้กับ POSIX ตามบทและหัวข้อย่อย
    • ถ้าอยากให้ Sphinx ประสบความสำเร็จในวงกว้าง สิ่งสำคัญอันดับแรกคือการมี ธีมคุณภาพสูงและสวยงาม
      เวลาจะเลือก site generator ความสวยงามเป็นปัจจัยที่ค่อนข้างสำคัญ Hugo และ Gatsby มีธีมเริ่มต้นที่ยอดเยี่ยม และผมก็เคยเลือกใช้ในโปรเจกต์ด้วยเหตุผลนั้นเพียงอย่างเดียวจริง ๆ คอลเลกชันธีมของ Sphinx อย่าง https://sphinx-themes.org/ และ https://sphinxthemes.com/#featured-themes โดยรวมค่อนข้างจืด เมื่อเทียบธีมมาตรฐาน Sphinx RTD https://sphinx-rtd-theme.readthedocs.io/en/stable/ กับเอกสารของ Apple https://developer.apple.com/documentation/swift/array หรือ Fluent UI https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--default แล้วมันดูเก่า

  • ผมมองว่าประโยค “Markdown คือรูปแบบเบาของ HTML” เป็นปัญหาใหญ่ที่สุดในบทความนี้ มันไม่ถูกต้องอย่างชัดเจน
    Markdown ถูกออกแบบมาเป็นเครื่องมือสำหรับแปลงธรรมเนียมการจัดรูปแบบข้อความที่ใช้กันเหมือนมาตรฐานโดยพฤตินัยในอีเมลและโพสต์ Usenet ช่วงต้นทศวรรษ 1990 เนื่องจากข้อจำกัดของ ASCII แบบ 7 บิต จึงต้องใช้สัญลักษณ์พิเศษเพื่อแสดงการจัดรูปแบบอย่างการเน้นหรือหัวข้อ และ HTML เองก็มีหลายอย่างคล้ายกับธรรมเนียมที่ไม่มีชื่อนั้น ดังนั้นในปี 2004 John Gruber จึงเขียนสคริปต์พื้นฐาน https://daringfireball.net/projects/markdown/ เพื่อแปลงมันเป็น HTML แต่เขาคงไม่ได้คาดว่ามันจะกลายเป็นมาตรฐานจริงที่แพร่หลายขนาดนี้

    • ประโยคแรกของลิงก์นั้นก็คือ “Markdown is a text-to-HTML conversion tool for web writers.”
      Gruber ไม่ได้เอามาตรฐานโดยพฤตินัยของ Usenet มาแล้วทำแค่ตัวแปลงเป็น HTML แต่เขายืมมาจาก Usenet และธรรมเนียมอื่น ๆ แล้วออกแบบมาร์กอัปของตัวเองขึ้นมา ส่วน “Acknowledgements” ด้านล่างของลิงก์ก็แสดงข้อเท็จจริงนั้น Markdown ตั้งใจให้เป็นไวยากรณ์มาร์กอัปสำหรับเว็บ CMS ตั้งแต่แรก และจะพูดว่าเป็น รูปแบบเบาของ HTML ก็ถูกแล้ว แก่นของมันคือทำให้ทุกส่วนของไวยากรณ์สร้าง HTML ที่แมปกันโดยตรงได้
    • ไม่เห็นด้วย Markdown เกี่ยวข้องกับ HTML มาโดยตลอด ถึงขั้นที่ parser ของ Markdown รองรับการ ผสมแท็ก HTML จริง ๆ ด้วย
      การที่มันได้รับแรงบันดาลใจจากธรรมเนียมอีเมลไม่ได้ทำให้คำพูดว่า “Markdown คือรูปแบบเบาของ HTML” ถูกต้องน้อยลง
    • อยากให้เลิกถกเถียงเชิงความหมายแบบนี้ได้แล้ว มันทำให้บทสนทนาน่าเบื่อและยังขัดกับแนวทางของ HN ด้วย
      มีกฎว่าให้ตอบต่อการตีความคำพูดของอีกฝ่ายในแบบที่สมเหตุสมผลและแข็งแรงที่สุด ไม่ใช่หยิบการตีความที่อ่อนแอซึ่งวิจารณ์ง่าย และยังมีกฎว่าอย่าหยิบแค่ประโยคที่ยั่วยุมากที่สุดในบทความมาบ่น แต่ให้ตอบต่อส่วนที่น่าสนใจ: https://news.ycombinator.com/newsguidelines.html
      ถ้าไม่เห็นด้วยกับแก่นของบทความ ก็บอกว่าชอบ Markdown มากกว่า rST และอธิบายว่าทำไม การทะเลาะกันเรื่องประโยคเดียวว่า Markdown คืออะไรกันแน่นั้นไร้สาระ
    • ตัว Markdown เองแยกจากการจัดรูปแบบของอีเมลและ Usenet Markdown เป็นไวยากรณ์เฉพาะ และนิยามไว้ไม่ดีนัก ต่อมาจึงขยายเป็นตระกูลไวยากรณ์หลายแบบที่โดยรวมคล้ายกัน
      มันได้รับแรงบันดาลใจจากธรรมเนียมอย่างอีเมลหรือ Usenet จริง และบางส่วนมีมาก่อนคอมพิวเตอร์ด้วยซ้ำ เช่นผมเหมือนเคยเห็นเอกสารพิมพ์ดีดเก่า ๆ ใช้ดอกจันคล้ายตัวเอียง แต่ Markdown เชื่อมโยงกับ HTML อย่างแน่นแฟ้น ไวยากรณ์ก็ถูกจำกัดโดย HTML มาก และความพยายามจะแยกมันออกจาก HTML โดยทั่วไปย่อมล้มเหลว
    • ถูกทั้งคู่ การใช้งานดั้งเดิมเป็น superset ของ HTML สิ่งที่พบบ่อยคือใช้ไวยากรณ์เบา ๆ กับสิ่งทั่วไป และส่วนที่เหลือก็เขียนเป็น HTML

  • ผมคิดว่าแก่นของ Markdown คือการทำงานที่ง่ายกว่า HTML ดิบให้เร็วขึ้น แต่ยังให้ ผสม HTML ดิบได้ เมื่อจำเป็น
    ในโปรเจกต์ที่ต้องใช้พลังของ RST มากกว่า Markdown ผมกลับรู้สึกว่าเขียน HTML โดยตรงสะดวกกว่า

    • ถ้าเขียนแบบผู้เขียนว่า “สามารถขยาย Sphinx เพื่อสร้างออบเจ็กต์ข้อความใหม่ได้ ใน Markdown พื้นฐานต้องใส่ HTML โดยตรง” ผมก็สงสัยว่าเมื่อจำเป็นต้องใช้ฟีเจอร์แบบนั้น แค่ เขียน HTML แล้วมันมีปัญหาอะไร ทำไมต้องเพิ่มอีกชั้นหนึ่ง

  • ตอนสร้างระบบเอกสารที่มีความซับซ้อนใกล้เคียงกัน ผมเคยพิจารณา RST เพราะต้องการมาร์กอัปที่มีความหมายชัดเจนอย่างมาก เพื่อเก็บโครงสร้างของไฟล์ RST ลงฐานข้อมูลและผสมผลลัพธ์จากฐานข้อมูลเข้ากับเนื้อหา
    ปัญหาที่เจอมีสองอย่าง อย่างแรก เครื่องมือ RST ไม่มี unparser สำหรับส่งออกกลับเป็น RST ผมอยากรวมไฟล์ RST หลายไฟล์กับแหล่งข้อมูลอื่น ๆ เพื่อสร้างไฟล์ RST อัตโนมัติและจัดการผ่าน API เอกสาร แต่ไม่รองรับ อย่างที่สอง เครื่องมือ RST คาดหวังชุดบล็อกที่นิยามไว้สำหรับเอกสารหนึ่ง ๆ ถ้ามีการแทนบล็อกแบบทั่วไป ก็น่าจะมีเครื่องมือที่แปลงเอกสารได้โดยไม่ต้องรู้คำจำกัดความบล็อกภายใน แต่มันไม่เป็นแบบนั้น เรื่องนี้เป็นปัญหาของเครื่องมือมากกว่าตัว RST เอง แต่ทุกครั้งที่ต้องรื้อโค้ดลงไปถึงฐานราก ก็ทำให้นึกถึงระบบมาร์กอัปอื่น ๆ เช่นแบบที่อิง HTML

    • สามารถใช้ XML เขียนเอกสารเชิงโครงสร้างแทน HTML ได้ XML ให้คุณนิยามแท็กกำหนดเองที่ต้องการได้ และถ้าต้องการก็ตรวจสอบกับสคีมาได้ด้วย
      ข้อดีของวิธีนี้คือควบคุมสคีมาอินพุตและเอาต์พุตได้ทั้งหมด ส่วนข้อเสียคือเสียงรบกวนทางไวยากรณ์มากกว่า Markdown หรือ RST อย่างมาก และต้องมีสคริปต์สำหรับ parse และแปลงเป็นรูปแบบเอาต์พุตที่ต้องการ
    • ใน Python, rST เป็นเพียงหนึ่งในรูปแบบอินพุตหลายแบบที่ docutils รองรับ: https://docutils.sourceforge.io/README.html#purpose
      เป้าหมายทั้งหมดของ docutils คือการ parse รูปแบบและแปลงเป็น API: https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers
    • rST กับ AsciiDoc ดูเหมือนจะใกล้เคียงกันคร่าว ๆ ในแง่ฟังก์ชัน อยากรู้ว่าจุดอ่อนและฟีเจอร์ที่ขาดไปก็ใกล้เคียงกันหรือเปล่า
    • ผมเคยเป็น committer ของ docutils ซึ่งเป็นเครื่องมือหลักของ rST เหตุผลหนึ่งที่ย้ายเครื่องมือไปเป็น Markdown คือ การจัดการกับ docutils เจ็บปวดเกินไป แค่ดูการปฏิเสธที่จะย้ายไปที่อย่าง GitHub ก็เห็นแล้วว่าการทำงานร่วมกันไม่เป็นมิตรแค่ไหน
    • ตอนนี้ไม่มีคอมพิวเตอร์ เลยทดสอบไม่ได้ แต่คิดว่าน่าจะทำสิ่งที่ต้องการได้ด้วย include directive

  • เมื่อไม่กี่ปีก่อน ผมเคยรวบรวม subset ของ reStructuredText ที่น่าจดจำไว้: https://simonwillison.net/2018/Aug/25/restructuredtext/
    ช่วงหลังในโปรเจกต์ต่าง ๆ เริ่มใช้ MyST ซึ่งให้ฟีเจอร์อ้างอิงและสารบัญที่ผมให้ความสำคัญใน reStructuredText ขณะเดียวกันก็ใช้ไวยากรณ์ Markdown ที่ผู้ร่วมพัฒนาเขียนได้ง่าย

    • จุดเด่นเรื่องลิงก์ โดยเฉพาะลิงก์ภายนอก มีมากทีเดียว เพราะในเว็บไซต์เอกสาร เราอาจอ้างถึงลิงก์ภายนอกเดียวกันจากหลายที่ และถ้ามันเปลี่ยนก็อยากอัปเดตแค่ครั้งเดียว
      สิ่งที่เปลี่ยนเกมจริง ๆ คือ rST+Sphinx กับ directive :ref:, :doc: สำหรับลิงก์ภายใน เวลาอ้างถึง anchor หรือลิงก์เอกสารภายในเนื้อหาเดียวกัน ไม่ต้องพิมพ์ header เอง และหลีกเลี่ยงปัญหาที่ header ที่พิมพ์ไว้เองล้าสมัยไปในที่สุดได้: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role
      เป็นหนึ่งในฟีเจอร์ที่คิดถึงที่สุดเวลาเขียนด้วย rST

  • ไม่ได้ตั้งใจจะเบี่ยงบทสนทนาเรื่อง ReStructuredText แต่ถ้ากำลังมองหาภาษา markup ที่ให้อะไรมากกว่า Markdown ก็อยากแนะนำให้ดู AsciiDoc มากกว่า ReStructuredText ผมเขียนเอกสารเทคนิคด้วยทั้งสามแบบมาหลายปี และคิดว่า AsciiDoc ดีกว่า ReStructuredText กับ Markdown
    ตัวอย่างเช่น การรองรับตารางของ Markdown และ ReStructuredText นั้นยุ่งยากมาก รูปแบบตารางของ AsciiDoc อ่าน เขียน และดูแลรักษาง่ายกว่า และยังทรงพลังกว่า เพราะรองรับ header, caption, ขนาดกำหนดเองของตารางและแถว รวมถึงการจัดรูปแบบซับซ้อนภายในตารางด้วย เป็นรูปแบบมาตรฐานเดียว ไม่ได้มีหลาย dialect แบบ Markdown ไวยากรณ์กระชับและอ่านง่าย เส้นโค้งการเรียนรู้ก็ชันน้อยกว่า ReStructuredText ตัวเลือกด้าน styling ของ output ดีกว่า toolchain ก็ดีกว่า และมีฟีเจอร์ด้านเอกสารในตัวมาก ทำให้ไม่ต้องพึ่งปลั๊กอิน third-party มากนัก AsciiDoc ถูกออกแบบมาตั้งแต่แรกเพื่อเอกสารเทคนิค ส่วนอีกสองตัวเป็นเหมือนการนำมาดัดให้เข้ากับบทบาทนั้น

  • ถ้าจัดรูปเอกสาร Markdown สัก 5–10 หน้าให้ดูดี แล้วให้ตัวมันถูก render จาก Jinja template ที่ dynamic กว่า ก็เริ่มต้นได้ค่อนข้างน่าพอใจ มี build process สำหรับเอกสารอัตโนมัติด้วย และใหญ่เกินกว่าจะเป็น GitHub README ไฟล์เดียวแล้ว แต่ความปวดหัวเริ่มจากตรงนั้น
    เอกสารบน GitHub project pages ไม่ค่อยเข้ากันดี เริ่มสับสนว่าต้องมีไฟล์ .nojekyl ไหม หรือยังต้องใช้ branch gh-pages อยู่หรือเปล่า ไม่รู้ว่าเป็นเพราะตั้งค่า repository ผิดหรือแค่การเปลี่ยนแปลงยังไม่ถูกนำไปใช้ พอลอง GitHub Actions ผ่านไปหลายชั่วโมงก็เริ่มไม่สมเหตุสมผล กลับไปดู Read the Docs อีกครั้งก็ดูเหมือนจะต้องการ Sphinx เลยเอา Markdown มาต่อกับ Sphinx build ผ่าน แต่พอ deploy แล้วความกว้างของหน้าพัง ทั้งที่ local ทำซ้ำไม่ได้ เลยเดาว่าอาจเป็นเพราะการแทรกโฆษณาของ community tier เรื่องนี้ทำงานได้ดีในหลายโปรเจกต์และเคยทำเองมาแล้ว แต่ก่อนจะทำให้มันรันได้จริง มันจุกจิกอย่างไม่น่าเชื่อ สุดท้าย Markdown ปะทะ RST ไม่ใช่ประเด็นที่สนใจเลย แก่นสำคัญคือการหาชุดเครื่องมือที่เหมาะกับ โปรเจกต์เอกสารขนาดกลางและ static hosting

    • สงสัยว่าเคยลองดู mdBook ไหม ผมยังไม่เคยใช้เอง แต่เคยเห็นเอกสารของหลายโปรเจกต์ที่ใช้ mdBook แล้วรู้สึกดี และดูค่อนข้างเหมาะเมื่อเริ่มเกินขอบเขตของไฟล์ README เดี่ยว
      คู่มือ deploy อัตโนมัติก็ทำไว้ดี: https://github.com/rust-lang/mdBook

  • ดูเหมือนจะพลาดประเด็นไปว่าผู้เขียนพูดในบริบทของการจัดรูปเล่มหนังสือของตัวเอง ไม่ได้กำลังอ้างว่าโดยทั่วไป rST ดีกว่า Markdown
    ในกรณีทั่วไป ความเรียบง่ายของ Markdown คือเหตุผลที่มันถูกใช้กันแพร่หลาย แต่สิ่งที่ผู้เขียนพูดถึงไม่ใช่กรณีนั้น

  • น่าสนใจที่หลายคนตอบสนองเหมือน reST ถูกสร้างมาเป็นคู่แข่งของ Markdown จริง ๆ แล้วเกือบจะตรงกันข้าม reST คือพัฒนาการต่อจาก StructuredText ในปี 2002 ส่วน Markdown เปิดตัวครั้งแรกในปี 2004
    เป้าหมายของทั้งสองคล้ายกันมาก และในข้อความพื้นฐานที่สุด ทั้งคู่ก็อ่านเขียนได้เหมือน plain text ช่วงเวลานั้นทุกคนเริ่มต้องการสิ่งแบบนี้ จึงมีหลายรูปแบบเกิดขึ้น ผมคิดว่าเหตุผลที่ Markdown ชนะไม่ได้เกี่ยวข้องมากนักกับการที่มัน “เรียบง่ายกว่า” หรือ “อ่านง่ายกว่า” สำหรับเนื้อหาที่แสดงได้ง่ายด้วย ASCII ล้วนและ whitespace โดยรวมก็แทบใช้แทนกันได้ ใครจะบอกได้หรือว่าเอกสาร reST ในตัวอย่างเป็นข้อความลึกลับที่อ่านไม่ออกถ้าไม่มี parser? ผมไม่ค่อยเห็นว่า variant ของ Markdown ดีกว่าตรงไหนในเรื่องนี้ มันเป็นเรื่องของความบังเอิญทางประวัติศาสตร์มากกว่าที่ตัวหนึ่งขึ้นนำ ทั้งสองดีพอสำหรับเป้าหมายหลักของตัวเอง

    • เพราะยกตัวอย่างที่เรียบง่ายมาก Markdown และ reST จึงจัดการได้ง่ายทั้งคู่
      reST มีฟีเจอร์จัดรูปแบบเพิ่มเติมที่มีประโยชน์มากเมื่อจำเป็น แต่ถ้าไม่จำเป็นก็กลายเป็นส่วนเกิน ผมเริ่มใช้ GitHub-flavored Markdown ราวปี 2010 ตอนสมัคร GitHub และก็เคยใช้ reStructuredText อยู่สองสามครั้งเพราะเอกสาร Python อย่างหลังมีเส้นโค้งการเรียนรู้สูงกว่ามาก และหลังจากนั้นก็ไม่มีเหตุผลให้ใช้อีก
    • ถ้าถามว่าอ่านไม่ออกไหม ก็ไม่ แต่ถ้าถามว่าพิมพ์แล้วอึดอัดไหม ใช่ หัวข้อแบบขีดเส้นใต้ น่ารำคาญตอนแก้ไข และถึงแม้ไม่จำเป็นต้องทำความยาวให้ตรงกันเป๊ะ ๆ ก็ยังรู้สึกกดดันว่าควรต้องทำให้ตรง
      backtick คู่ก็เป็นไวยากรณ์ที่ชวนหงุดหงิดเกินสัดส่วนเมื่อเทียบกับเวลาที่ต้องใช้จริง