Markdown की तुलना में rST को प्राथमिकता देने का रुझान

मैं rST को क्यों पसंद करता हूँ

मैं यह बात कहना बंद नहीं करने वाला हूँ

• मैंने "Logic for Programmers" v0.2 का नया संस्करण प्रकाशित किया है। इस संस्करण में epub समर्थन, constraint solving, और formal specifications पर सामग्री शामिल है.
• दूसरी किताब "Learn TLA+" भी मैंने Sphinx में लिखी है। Sphinx, reStructured Text (rST) नामक एक विशिष्ट markup का उपयोग करता है.
• rST की learning curve markdown की तुलना में अधिक steep है। markdown में कुछ किताबें लिखने के बाद मुझे लगा कि मुझे कुछ बेहतर चाहिए, इसलिए मैं rST पर आ गया.

rST बेहतर क्यों है

• markdown, HTML का lightweight representation है, जबकि rST abstract document tree का medium-weight representation है.
• markdown में image बनाने का तरीका:

  ![alttext](example.jpg)
  

• rST में image बनाने का तरीका:

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

• rST extensible है। आप नए text object जोड़ सकते हैं.
• Sphinx cross-referencing संभाल सकता है। उदाहरण के लिए, एक document में foo anchor डालें और दूसरे document में :ref:image <foo>`` डालें, तो Sphinx सही URL insert कर देता है.
• rST build process के बाकी हिस्से के साथ transformation code को compose करने देता है.

एक उपयोग का मामला

• "Logic for Programmers" गणित से संबंधित किताब है, इसलिए पाठकों के लिए exercises की ज़रूरत है.
• मैं चाहता हूँ कि exercises और solutions document में साथ-साथ रहें, लेकिन पाठकों के लिए solutions किताब के पीछे दिखाई दें.
• इसके लिए मैंने अपना exercise extension लिखा.

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

• HTML में exercises और solutions को inline render किया जाता है.
• epub और latex में transformation के ज़रिए solution nodes को solutionlist के नीचे ले जाया जाता है, और हर exercise में reference node जोड़ा जाता है.

"लेकिन मुझे syntax पसंद नहीं है"

• बहुत से लोगों का मानना है कि rST का syntax बदसूरत है.
• यह समझा जा सकता है कि syntax पसंद न होने के कारण कोई अच्छा tool इस्तेमाल न करे.
• asciidoc, MyST, Typst, Pollen, pandoc-extended markdown जैसे दूसरे document builders भी हैं.
• markdown-आधारित document generators अक्सर नए use cases को support करने के लिए अपना preprocessing step जोड़ते हैं.
• markdown और rST के लिए LSP और treesitter हैं, लेकिन gitbook-markdown, md-markdown, या leanpub-markdown के लिए नहीं.

अगले हफ्ते newsletter नहीं होगा

• मैं Hong Kong में रहूँगा.

2024-07-31 अपडेट

• मैंने "Logic for Programmers" के बारे में एक छोटा विवरण जोड़ा है.
• यह किताब इस बारे में है कि formal logic रोज़मर्रा की software engineering में कैसे उपयोगी हो सकती है.
• इसमें बुनियादी गणित का overview और आठ अलग-अलग applications शामिल हैं.
• यह अभी alpha stage में है, लेकिन 20,000 से अधिक शब्द पहले ही लिखे जा चुके हैं और इसमें बहुत उपयोगी सामग्री है.

GN⁺ का सार

• rST, markdown की तुलना में अधिक शक्तिशाली document authoring tool है.
• Sphinx के साथ इसका उपयोग करने पर document tree को transform और extend करने की क्षमता मिलती है.
• "Logic for Programmers" जैसी किताब लिखने में यह उपयोगी है.
• बहुत से लोग rST के syntax को बदसूरत मानते हैं, लेकिन अन्य विकल्प भी मौजूद हैं.
• formal logic से जुड़ी software engineering में रुचि रखने वालों के लिए यह उपयोगी हो सकता है.

[GN⁺]

Hacker News राय

• Markdown का सबसे बड़ा फ़ायदा यह है कि इसे पढ़ना और लिखना आसान है
• Markdown किताब लिखने के लिए सबसे बेहतरीन टूल न भी हो, लेकिन जल्दी से formatted text लिखने के लिए यह बेहतरीन है
• किताब लिखने के लिए LaTeX का उपयोग किया जाएगा, और Markdown नोट्स लिखने, तेज़ documentation और comments लिखने के लिए उपयुक्त है
• reStructuredText(reST) अपने आप में थोड़ा खुरदुरा है, लेकिन Sphinx के साथ मिलकर यह बहुत शानदार हो जाता है
  • Sphinx बड़े पैमाने की, पेशेवर documentation sites के लिए उपयुक्त विकल्प है
  • Sphinx साइट के common elements को आसानी से customize करने देता है
  • यह सुनिश्चित करता है कि internal links हमेशा resolve हों
  • इसका extension और theme API अच्छी तरह परिभाषित है
  • PyPI पर कई तरह के extensions और themes मौजूद हैं
• Markdown, HTML का lightweight representation है, जबकि reST abstract document tree का medium-weight representation है
• Markdown को email messages और Usenet posts के formatted text को convert करने के लिए डिज़ाइन किया गया था
• reST tools में RST files को अपने-आप generate करने की क्षमता की कमी है
• Markdown साधारण काम जल्दी करने देता है, और ज़रूरत पड़ने पर raw HTML insert किया जा सकता है
• MyST, reStructuredText की सुविधाएँ देते हुए Markdown syntax का उपयोग करने देता है
• GitHub project pages की documentation जटिल हो सकती है, और Sphinx व Markdown को साथ में इस्तेमाल करना उपयोगी हो सकता है
• लेखक अपनी किताब की typesetting के संदर्भ में rST का उल्लेख कर रहा है
• reST, Markdown का competitor नहीं है, बल्कि Markdown से पहले आया हुआ format है
• Markdown और reST का मूल लक्ष्य लगभग एक ही है
• Markdown और reST, दोनों ही पढ़ने में आसान हैं और जल्दी लिखे जा सकते हैं
• ऐतिहासिक कारणों से Markdown का उपयोग अधिक व्यापक हो गया
• Markdown custom block types परिभाषित कर सकता है और document tree को transform कर सकता है
• Jupyter Book इसका अच्छा उदाहरण है कि Markdown का उपयोग PDF जैसे दूसरे targets में render करने के लिए किया जा सकता है