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

 (buttondown.email)
1 पॉइंट द्वारा GN⁺ 2024-08-02 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • Sphinx का reStructured Text(rST), Markdown की तुलना में सीखना कठिन है, लेकिन किताब जैसी बड़े पैमाने की दस्तावेज़ीकरण में संरचना और output format को बारीकी से नियंत्रित करना आसान बनाता है
  • Markdown, हल्के HTML लेखन के करीब है, जबकि rST abstract document tree के इर्द-गिर्द directives, nodes और renderers को जोड़कर नए document objects जोड़े जा सकते हैं
  • Sphinx rendering से पहले doctree को transform करता है, इसलिए cross-reference, output format के अनुसार processing, और build के किसी खास चरण में transformation जैसे काम documentation system के भीतर संभाले जा सकते हैं
  • Logic for Programmers में अभ्यास प्रश्न और उनके हल मूल पाठ के पास लिखे जाते हैं, फिर EPUB और LaTeX output में उनकी स्थिति और प्रदर्शन बदलने के लिए custom extension का उपयोग किया जाता है
  • साधारण Markdown में एकीकृत extension syntax और pre-render transform support की कमी है, इसलिए जैसे-जैसे documentation generator अलग preprocessing से workaround करते हैं, tool support और extensibility कमजोर होती जाती है

rST को चुनने का कारण

  • Logic for Programmers का नया संस्करण Sphinx में लिखी गई दूसरी किताब है, और पिछला काम नया Learn TLA+ भी Sphinx का उपयोग करता है
  • Sphinx, reStructured Text का उपयोग करता है, और rST की learning curve Markdown से अधिक कठिन है
  • Markdown में कई किताबें लिखने के बाद बेहतर tooling की ज़रूरत महसूस हुई, इसलिए rST पर स्विच किया गया
  • rST स्वयं Sphinx से स्वतंत्र है, लेकिन व्यवहार में अक्सर Sphinx की वजह से rST इस्तेमाल किया जाता है, इसलिए दोनों की चर्चा साथ की गई है

Markdown और rST की संरचनात्मक भिन्नता

  • सबसे बड़ा अंतर यह है कि Markdown हल्के HTML notation के अधिक करीब है, जबकि rST abstract document tree बनाने वाली मध्यम-स्तरीय notation है
  • Markdown का image syntax इतना सरल है कि उसे सीधे <img alt="alttext" src="example.jpg"/> जैसे HTML में बदला जा सकता है
    • आधुनिक Markdown engines भी अक्सर intermediate representation में parse करते हैं, लेकिन उसका मूल स्वभाव अभी भी हल्के HTML notation के करीब है
  • rST में image को .. image:: directive से व्यक्त किया जाता है
    • Sphinx registered directive handler ढूंढकर ImageDirective.run चलाता है
    • उसके परिणामस्वरूप alt field वाला image_node जैसा node object बनता है
    • पूरी doctree processing के बाद HTML Writer, image_node के rendering function को ढूंढकर HTML tag output करता है
  • rST का तरीका implementation और syntax, दोनों में अधिक जटिल है और Markdown की तुलना में boilerplate भी ज़्यादा है, लेकिन image को भी बाकी directives की तरह उसी extension mechanism से संभाला जाता है

नए document object जोड़ने का तरीका

  • rST/Sphinx में extension के माध्यम से नए text object जोड़े जा सकते हैं
  • उदाहरण के लिए, अगर <image> की बजाय <figure> और <figcaption> बनाना हो, तो सामान्य Markdown में HTML सीधे insert करना पड़ता है
  • Sphinx में इसे नया figure directive register करके संभाला जाता है
    • FigureDirective, ImageDirective inherit करके image processing का अधिकांश हिस्सा reuse भी कर सकता है
  • directive registration, node creation और builder-specific renderer registration का यही pattern सभी extensions पर समान रूप से लागू होता है

rendering से पहले doctree transform

  • Sphinx, rendering से पहले doctree transform चला सकता है
  • दस्तावेज़ों के बीच cross-reference भी इसी feature से संभाले जाते हैं
    • अगर एक document में foo anchor हो और दूसरे में :ref:\image <foo>`` हो, तो Sphinx post-processing चरण में सही URL insert कर देता है
  • transform code को build process के भीतर first-class feature की तरह माना जाता है
    • केवल HTML output होने पर ही किसी विशेष transform को apply किया जा सकता है
    • build के किसी विशेष चरण में transform चलाया जा सकता है
    • और जिन built-in transforms को चलाना न हो, उन्हें हटाया भी जा सकता है
  • हर दस्तावेज़ को इतनी शक्ति की ज़रूरत नहीं होती; Markdown हल्का और portable है, इसलिए उसका व्यापक उपयोग स्वाभाविक है

अभ्यास प्रश्न और हल extension का उदाहरण

  • Logic for Programmers गणित के करीब की किताब है, इसलिए पाठकों के लिए अभ्यास प्रश्न ज़रूरी हैं
  • लिखते समय अभ्यास प्रश्न और उनके हल को दस्तावेज़ में पास-पास रखना आसान होता है, लेकिन पाठक के लिए हल किताब के पीछे आने चाहिए
  • output format के अनुसार आवश्यकताएँ अलग थीं
    • अभ्यास प्रश्न और हल एक-दूसरे से link होने चाहिए
    • print को ध्यान में रखते हुए PDF में page reference भी चाहिए
    • LaTeX/PDF output और EPUB output में rendering अलग होनी चाहिए
  • इसके लिए exercise, solution, solutionlist को संभालने वाला custom Sphinx extension लिखा गया
  • HTML debugging output में अभ्यास प्रश्न और हल inline render किए जाते हैं
  • EPUB और LaTeX generation में पूरी doctree बनने के बाद transform चलाया जाता है
    • मूल स्थान पर मौजूद सभी solution_node को solutionlist के नीचे स्थानांतरित किया जाता है
    • हर अभ्यास प्रश्न में नए हल-स्थान की ओर जाने वाला reference node जोड़ा जाता है
    • हर हल में मूल अभ्यास प्रश्न पर वापस जाने वाला reference node जोड़ा जाता है
  • LaTeX builder, अभ्यास प्रश्न और हल को answers environment में wrap करता है
  • EPUB builder, हलों को popup footnote के रूप में render करता है
  • यह संरचना किताब का free sample बनाने में भी काम आती है
    • free sample के पीछे पूरी किताब के सभी हल नहीं, बल्कि sample में शामिल हिस्सों के हल ही जाते हैं

syntax पसंद और विकल्प

  • rST के खिलाफ सबसे आम आपत्ति यह है कि उसका syntax बदसूरत लगता है
  • केवल इसलिए किसी tool का उपयोग न करना कि वह देखने में अच्छा नहीं लगता, बिल्कुल वैध पसंद है; Lisp को अपनाना कठिन लगना भी इसी तरह की रुचि का मामला माना जा सकता है
  • विकल्प के रूप में asciidoc, MyST, Typst, Pollen, pandoc-extended markdown मौजूद हैं
  • मुख्य बात यह नहीं है कि Sphinx/rST बड़े पैमाने की documentation के लिए असाधारण रूप से अच्छा है, बल्कि यह है कि साधारण Markdown बड़े पैमाने की documentation के लिए असाधारण रूप से अनुपयुक्त है

Markdown-आधारित generators की सीमाएँ

  • साधारण Markdown में एकीकृत extension syntax या pre-render transform के लिए native support नहीं है
  • कई Markdown-आधारित documentation generators नए use case को support करने के लिए अपनी preprocessing stage जोड़ते हैं
  • यह तरीका आमतौर पर काम करता है, लेकिन processing Markdown के भीतर नहीं बल्कि Markdown के आसपास workaround के रूप में होती है
  • नतीजतन feature की शक्ति सीमित हो जाती है, और programmers के tools के लिए उन परिवर्तनों को अच्छी तरह समझना मुश्किल होता है
    • Markdown और rST के लिए LSP और treesitter मौजूद हैं, लेकिन gitbook-markdown, md-markdown, leanpub-markdown के लिए उसी स्तर के tools की उम्मीद करना कठिन है
  • rST का बदसूरत syntax उल्टा एक फ़ायदा भी बन सकता है, क्योंकि उसका syntax tree अधिक समृद्ध होता है
    • किसी विशेष todo directive के body को ही बदलने वाली treesitter query लिखी जा सकती है
    • यह इसलिए संभव है क्योंकि rST का syntax tree, Markdown के syntax tree की तुलना में अधिक समृद्ध है

Logic for Programmers अपडेट

  • Logic for Programmers एक ऐसी किताब है जो बताती है कि formal logic रोज़मर्रा की software engineering में कैसे उपयोगी हो सकती है
  • किताब एक बुनियादी mathematics overview से शुरू होती है और फिर property testing, database constraints, decision tables जैसी 8 applications तक जाती है
  • यह अभी alpha चरण में है, लेकिन लगभग 20,000 शब्दों की हो चुकी है और पाठकों से feedback लिया जा रहा है

संबंधित पढ़ाई

1 टिप्पणियां

 
GN⁺ 2024-08-02
Hacker News की राय

  • अगर पूछा जाए, “क्या आप सिर्फ इसलिए कोई अच्छा टूल नहीं इस्तेमाल करेंगे क्योंकि उसे देखते ही उल्टी आने जैसी feeling होती है”, तो मेरा जवाब हां होगा। Markdown का सबसे बड़ा फायदा यह है कि इसे पढ़ना आसान है, और दूसरा फायदा यह है कि इसे लिखना आसान है
    इसे parse करना कितना आसान है, या extend करना कितना आसान है, यह लगभग मायने नहीं रखता। किताब लिखने के लिए Markdown सबसे अच्छा है या नहीं, यह अलग बात है; लेकिन जिन लोगों को syntax अच्छी तरह नहीं आती, उनके लिए भी पढ़ने में आसान तरीके से जल्दी formatted text लिखने के काम में Markdown सबसे बेहतर है। मैं किताब लिखने नहीं जा रहा, बस notes, quick documentation और comments लिखने हैं; और अगर किताब लिखनी हो, तो RST से पहले LaTeX इस्तेमाल करूंगा

    • जब Markdown developers के बीच लोकप्रिय होना शुरू हुआ, तो यह काफी अजीब चुनाव लगता था। उस समय भी plain text को formatted documents में बदलने के लिए कई बेहतर विकल्प मौजूद थे, लेकिन developers Markdown के इर्द-गिर्द CMS, productivity apps, document management tools और plugins तक बना रहे थे
      लेकिन असल apps में इस्तेमाल करके देखा तो Markdown का मूल उद्देश्य वह नहीं था। इसका मकसद सिर्फ न्यूनतम formatting देना है, ताकि plain text रूप में भी यह HTML में render हुए रूप जितना ही स्वाभाविक रूप से पढ़ा जा सके। supported formatting जानबूझकर छोटी रखी गई है, इसलिए वह दिमाग में बैठ जाती है और toolbar के बिना इस्तेमाल की जा सकती है। यह comment boxes, chat, commit messages, और शायद blog posts के लिए ठीक है, लेकिन enterprise-grade product documentation लिखने के लिए नहीं। आजकल Markdown उन जगहों पर भी इस्तेमाल होता है जहां HTML में render नहीं होना है, क्योंकि यह अपने-आप में पढ़ने में अच्छा है, और मेरी इच्छा है कि HN भी इसे support करे
    • मैंने Markdown में किताब लिखी है और कोई खास समस्या नहीं आई। वह technical document नहीं बल्कि novel थी, लेकिन Markdown में कभी-कभी HTML मिलाने भर से जो हल न हो सके, ऐसा कुछ नहीं था
      मैंने काफी technical documentation भी Markdown में बनाई है, और Pandoc extensionshttps://pandoc.org/MANUAL.html इस्तेमाल करें तो complex equations और syntax-highlighted code blocks सहित लगभग सारी जरूरी formatting डाली जा सकती है। वह Markdown HTML, Word document, ePub, PDF आदि में convert किया जा सकता है। Markdown के बजाय कुछ और निकालने के लिए बहुत convincing वजह चाहिए
    • TeX users में शायद मैं top 10% के आसपास होऊंगा, लेकिन Markdown और TeX के बीच एक और typesetting language के लिए बहुत जगह है, ऐसा मुझे नहीं लगता। Markdown आसान है लेकिन limited है, और TeX थोड़ा कठिन है लेकिन व्यवहार में लगभग असीमित रूप से flexible है
      TeX में मुझे सबसे बड़ी समस्या language की नहीं, लोगों की लगती है। लोग अक्सर खराब style वाला spaghetti TeX लिखते हैं। लेकिन अगर “documents are code” वाली सोच से लिखा जाए, तो काफी साफ-सुथरा result मिलता है। दूसरी सबसे बड़ी समस्या यह है कि कोई अच्छा TeX → HTML compiler नहीं है
    • “अगर किताब लिखनी हो तो LaTeX इस्तेमाल करूंगा” वाली बात writing और structuring के चरण में बहुत खराब चुनाव लगती है। इसके बजाय मैं Markdown में लिखूंगा, typesetting की चिंता नहीं करूंगा, और सिर्फ publishing stage पर LaTeX में convert करूंगा
      मैं LaTeX में माहिर नहीं हूं, लेकिन जब इसे सीखने की कोशिश की थी तो ऐसा लगा जैसे किसी कीट-नुमा alien civilization की language सीख रहा हूं। यह बिल्कुल intuitive नहीं था, और दूसरों ने जो पहले से किया था उसे copy करके अपनी writing डालने के तरीके के अलावा नया कुछ करना लगभग असंभव लगता था। जहां तक याद है, इसमें first-class Unicode support भी नहीं था
    • Markdown को “syntax अच्छी तरह न जानने वाले लोगों के लिए भी पढ़ने में आसान तरीके से जल्दी formatted text लिखने का सबसे अच्छा tool” कहना मुझे सही नहीं लगता। सिर्फ basics देखें तो भी यह सबसे अच्छा नहीं है
      italics के लिए asterisk या underscore इस्तेमाल करने में भी familiarity चाहिए, और /italic slashes/ जैसे कहीं ज्यादा intuitive तरीके मौजूद हैं। basics से आगे जाएं तो tables, metadata और tags text को ढक देते हैं, जिससे सही tool के बिना लिखना और पढ़ना भी आसान नहीं रहता। अगर extension आसान हो तो ऐसी basic problems भी सुधारी जा सकती हैं, इसलिए extensibility भी relevant है

  • मैंने तकनीकी दस्तावेज़ लेखक के तौर पर करीब 12 साल काम किया है, और करियर की शुरुआत में एक startup के दस्तावेज़ों को Word से Sphinx पर माइग्रेट किया था। उसके बाद Google के अपने CMS/developer docs platform, Eleventy-आधारित साइटों, और पिछले 2 साल से फिर Sphinx-आधारित साइट pigweed.dev पर काम किया है। readme.com-आधारित startup का काम भी किया, और Docusaurus, Astro, Hugo को भी थोड़ा इस्तेमाल करके देखा है
    सिर्फ reStructuredText थोड़ा खुरदुरा हो सकता है, लेकिन Sphinx के साथ जुड़ा reST बहुत अच्छा है। Sphinx की खूबियां reST की कमियों से कहीं ज्यादा भारी पड़ती हैं। 100+ पेज और 10+ contributors वाली बड़ी पेशेवर documentation site के लिए, लंबे समय में Sphinx सबसे जिम्मेदार विकल्प है—मैं इसे लेकर काफी आश्वस्त हूं। उदाहरण के लिए Pigweed में हमने ऐसा किया कि सिर्फ :bug:\59385981`` लिखने पर वह https://pwbug.dev/59385981 link में बदल जाता था, और बाद में अगर bug links को bulk में migrate करना पड़े तो भी आसान रहता। Internal links के हमेशा resolve होने की गारंटी रहती है, और अगर किसी non-existent जगह पर link किया जाए तो warning या error मिलता है। मुझे अजीब लगता है कि यह documentation sites में standard नहीं है; इस बारे में पहले मैंने https://technicalwriting.dev/src/link-text-automation.html पर लिखा था। Sphinx में extensions और theme APIs भी अच्छी तरह defined हैं, और PyPI पर इसका ecosystem काफी बड़ा है। आजकल मैं Sphinx को documentation systems का सोया हुआ दिग्गज कहता हूं; थोड़ा-सा सामूहिक प्रयास हो तो यह कहीं ज्यादा शानदार बन सकता है

    • यह हिस्सा सच में बहुत महत्वपूर्ण है। CMS या static site generators में बहुत सारे systems ऐसे हैं जो लिखते समय final URL सीधे डालने को कहते हैं
      slug बदल जाए या site structure फिर से व्यवस्थित किया जाए, तो पूरी site में find-and-replace करना पड़ता है। Static site generators [Hello](../hello.md) की तरह link करवाकर build के समय उसे resolve कर सकते हैं, फिर भी जिन tools को मैंने काफी इस्तेमाल किया या देखा, वे [Hello](/why/hello/) सीधे टाइप करवाते हैं। लगता है इस feature को लेकर लोगों की पसंद-नापसंद बंटी हुई है। Static site generator team के एक सदस्य से बात की तो जवाब मिला, “तुम्हें यह क्यों चाहिए”, और समझाने पर भी बात नहीं बनी। पता नहीं समस्या झेलने के बाद ही समाधान की कीमत समझ आती है, या लोग एक बार लिखकर 10+ साल maintain न करने के आदी हैं, लेकिन अच्छा होगा अगर इसका support ज्यादा व्यापक हो
    • Sphinx शानदार है, लेकिन बहुत ज्यादा underrated है। मेरी जानकारी में Sphinx ही अकेला documentation framework है जो structurally मजबूत, extensible और व्यापक रूप से इस्तेमाल किया जाता है
      इसका plugin ecosystem बेहतरीन है, जिससे teams और projects की documentation सुधारने में जबरदस्त leverage मिलता है। reStructuredText खुद मुझे पसंद नहीं है, लेकिन आजकल MyST-Parser की वजह से वे ज्यादातर काम, जिनके लिए पहले Sphinx मजबूती से RST से बंधा था, Markdown में भी किए जा सकते हैं: https://github.com/executablebooks/MyST-Parser
    • site-wide common elements को customize करना Markdown+Pandoc से भी बहुत आसान था। YouTube link वाले image tags को video tag और alt text वाले thumbnail में बदलना, और local video file image tags को ffmpeg से जोड़कर optimize और resize करना—ये सब कुछ lines of code से हो गया
    • इस comment को देखने से पहले मैं Sphinx के बारे में नहीं जानता था। 20 साल से ज्यादा समय से development work के साथ-साथ technical documentation लिखता रहा हूं, और अब तक मेरा झुकाव TeX और custom XSL की तरफ ज्यादा था
      internal language/VM/abstraction layer को समझाने वाली 200+ पेज की किताब अभी-अभी Sphinx पर शिफ्ट की है, और यह सच में जिंदगी बदल देने वाला system है। काश Sphinx की अपनी documentation की entry barrier कम होती या examples ज्यादा होते, लेकिन अभी तो काफी मजबूत honeymoon phase जैसा लग रहा है। मेरी मुख्य दिलचस्पी अच्छे दिखने वाली PDF book बनाने के तरीके में है, और ऐसी system में है जो किताब को chapters/sections के आधार पर POSIX-compatible man pages में अच्छी तरह काट सके
    • अगर Sphinx को mainstream में बड़ी सफलता दिलानी है, तो पहली प्राथमिकता high-quality, खूबसूरत themes हासिल करना है
      site generator चुनते समय aesthetics काफी महत्वपूर्ण factor होता है। Hugo और Gatsby के default themes बहुत अच्छे हैं, और सच में सिर्फ इसी वजह से मैंने उन्हें projects में चुना भी है। Sphinx theme collections https://sphinx-themes.org/ और https://sphinxthemes.com/#featured-themes कुल मिलाकर फीकी लगती हैं। Standard Sphinx RTD theme https://sphinx-rtd-theme.readthedocs.io/en/stable/ की तुलना Apple documentation https://developer.apple.com/documentation/swift/array या Fluent UI https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--default से करें तो यह पुरानी लगती है

  • मुझे लगता है इस लेख की सबसे बड़ी समस्या यह वाक्य है कि “Markdown, HTML का हल्का-फुल्का representation है।” यह निश्चित रूप से गलत है
    Markdown को 1990 के दशक की शुरुआत में ईमेल और Usenet पोस्ट्स में de facto standard की तरह इस्तेमाल होने वाली text formatting conventions को बदलने के लिए एक tool के रूप में design किया गया था। 7-bit ASCII की सीमा की वजह से emphasis या headings जैसी formatting को special symbols से दिखाया जाने लगा, और HTML में भी उन बिना-नाम वाली conventions से काफी समानताएँ थीं। इसलिए John Gruber ने 2004 में उसे HTML में बदलने वाला basic script https://daringfireball.net/projects/markdown/ लिखा, लेकिन शायद उन्होंने अनुमान नहीं लगाया होगा कि यह इतना सार्वभौमिक वास्तविक standard बन जाएगा

    • उस link का पहला वाक्य ही है “Markdown is a text-to-HTML conversion tool for web writers.”
      Gruber ने Usenet के de facto standard को उठाकर सिर्फ HTML converter नहीं बनाया था; उन्होंने Usenet और दूसरी conventions से उधार लेकर अपना markup design किया था। link के नीचे “Acknowledgements” भी यही दिखाता है। Markdown शुरू से web CMS के लिए markup syntax के रूप में intended था, और इसे HTML का हल्का representation कहना सही है। syntax के हर हिस्से से सीधे corresponding HTML बनना ही इसका core था
    • सहमत नहीं हूँ। Markdown हमेशा HTML से जुड़ा रहा है, यहाँ तक कि Markdown parser actual HTML tag mixing भी support करते हैं
      यह तथ्य कि inspiration email conventions से आया था, “Markdown, HTML का हल्का representation है” वाली बात को कम सही नहीं बनाता
    • इस तरह की semantic बहसें बंद होनी चाहिए। ये उबाऊ conversation बनाती हैं और HN guidelines के भी खिलाफ हैं
      नियम है कि सामने वाले की बात की सबसे plausible और मजबूत interpretation का जवाब दें, और criticize करने में आसान कमजोर interpretation न पकड़ें। यह भी नियम है कि लेख के सबसे provocative वाक्य को चुनकर शिकायत न करें, बल्कि interesting हिस्सों का जवाब दें: https://news.ycombinator.com/newsguidelines.html
      अगर आप लेख के core से सहमत नहीं हैं, तो कहें कि आप rST की बजाय Markdown पसंद करते हैं और क्यों, यह समझाएँ। Markdown असल में क्या है, इस पर सिर्फ एक वाक्य पकड़कर लड़ना बेवकूफी है
    • Markdown खुद email और Usenet formatting से अलग चीज़ है। Markdown एक specific syntax था, जिसकी definition अच्छी नहीं थी, और बाद में यह कई syntax families में फैल गया जो आपस में broadly similar हैं
      यह email या Usenet जैसी conventions से inspired जरूर था, और उनमें से कुछ तो computers से भी पहले की थीं। उदाहरण के लिए, मुझे लगता है पुराने typewritten documents में asterisks को italics की तरह इस्तेमाल किए हुए भी देखा है। लेकिन Markdown, HTML से strongly जुड़ा है, उसका syntax भी HTML से बहुत constrained है, और HTML से अलग करने की कोशिशें ज्यादातर असफल होना तय हैं
    • दोनों सही हैं। original implementation HTML का superset था। common चीज़ें हल्के syntax से लिखो, बाकी HTML में लिखो—यही तरीका था

  • मुझे लगता है Markdown का core यह है कि raw HTML के मुकाबले simple काम तेजी से किए जाएँ, लेकिन जरूरत पड़ने पर raw HTML मिलाने की सुविधा रहे
    जिन projects में मुझे Markdown से ज्यादा RST की शक्ति चाहिए थी, वहाँ सीधे HTML लिखना ही ज्यादा सुविधाजनक लगा

    • जब लेखक की तरह लिखा जाता है कि “Sphinx को extend करके नए text objects बनाए जा सकते हैं। basic Markdown में सीधे HTML डालना पड़ता है,” तो जब ऐसी functionality चाहिए हो, तब बस HTML लिखने में दिक्कत क्या है—यह सवाल उठता है। समझ नहीं आता कि एक और layer क्यों रखी जाए

  • similar complexity का document system बनाते समय, मैंने RST पर विचार किया था क्योंकि RST file की structure को database में store करना और database results को content के साथ मिलाना था, इसलिए स्पष्ट meaning वाला markup बहुत जरूरी था
    दो समस्याएँ सामने आईं। पहली, RST tools में RST को फिर से output करने वाला unparser नहीं है। मैं कई RST files और अन्य sources को merge करके RST file auto-generate करना और document API से handle करना चाहता था, लेकिन support नहीं था। दूसरी, RST tools किसी specific document के लिए defined blocks के set की अपेक्षा करते हैं। अगर blocks को generally represent किया जाए, तो internal block definitions जाने बिना document transform करने वाला tool बन सकता था, लेकिन ऐसा नहीं था। यह RST खुद से ज्यादा tooling की समस्या है, लेकिन हर बार जब code को जड़ तक हटाना पड़े, तो HTML-based जैसे दूसरे markup systems के बारे में सोचने लगता हूँ

    • HTML की जगह structured documents के लिए XML इस्तेमाल कर सकते हैं। XML में आप अपने जरूरी custom tags define कर सकते हैं और चाहें तो schema validation भी कर सकते हैं
      इस approach का फायदा यह है कि input schema और output पर आपका पूरा control होता है, और नुकसान यह है कि Markdown या RST की तुलना में syntax noise बहुत ज्यादा है, और desired output format में parse/convert करने के लिए script चाहिए
    • Python में rST, docutils द्वारा support किए जाने वाले कई input formats में से सिर्फ एक है: https://docutils.sourceforge.io/README.html#purpose
      docutils का पूरा purpose formats को parse करके API में convert करना है: https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers
    • rST और AsciiDoc functionality के लिहाज से लगभग similar लगते हैं। सोचता हूँ कि weaknesses और missing features भी लगभग similar हैं या नहीं
    • मैं rST के main tool docutils में committer था। tools को Markdown पर move करने की एक वजह यह थी कि docutils के साथ काम करना बेहद painful था। GitHub जैसी जगहों पर move करने से इनकार करना ही दिखा देता है कि उनके साथ काम करना कितना unfriendly है
    • अभी computer नहीं है इसलिए test नहीं कर सकता, लेकिन लगता है include directive से आप जो चाहते हैं वह किया जा सकता है

  • कुछ साल पहले मैंने reStructuredText के याद रखने लायक subset को整理 किया था: https://simonwillison.net/2018/Aug/25/restructuredtext/
    हाल की परियोजनाओं में मैंने MyST इस्तेमाल करना शुरू किया है; यह reStructuredText में मेरे लिए अहम रहे reference और table of contents फीचर देता है, साथ ही contributors के लिए लिखने में आसान Markdown syntax इस्तेमाल करने देता है

    • links, खासकर external links के मामले में इसका बड़ा फायदा है। documentation site में एक ही external link को कई जगहों से reference किया जा सकता है, और बदलने पर उसे सिर्फ एक बार update करना चाहेंगे
      असली game-changer internal links में rST+Sphinx और :ref:, :doc: directives हैं। उसी content के भीतर anchors या document links को reference करते समय headers खुद type नहीं करने पड़ते, और खुद type किए headers के आखिरकार outdated हो जाने से बचा जा सकता है: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role
      rST में लिखते समय यह उन features में से एक है जिसकी सबसे ज्यादा कमी महसूस होती है

  • ReStructuredText की बातचीत को hijack करने का इरादा नहीं है, लेकिन अगर आप Markdown से ज्यादा देने वाली markup language ढूंढ रहे हैं, तो मैं ReStructuredText की बजाय AsciiDoc देखने की सलाह दूंगा। मैंने कई सालों तक तीनों में technical documentation लिखी है, और मुझे AsciiDoc, ReStructuredText और Markdown से बेहतर लगता है
    उदाहरण के लिए Markdown और ReStructuredText में tables का support बहुत झंझट भरा है। AsciiDoc का table format पढ़ने, लिखने और maintain करने में आसान है, और headers, captions, tables और rows के custom sizes, table के अंदर complex formatting तक support करके ज्यादा powerful है। यह Markdown की तरह कई dialects वाला नहीं, बल्कि एक single standard format है; syntax concise और readable है; और learning curve ReStructuredText से कम steep है। output styling के विकल्प भी बेहतर हैं, toolchain भी अच्छा है, और built-in documentation features भरपूर हैं, इसलिए third-party plugins पर कम निर्भर रहना पड़ता है। AsciiDoc शुरू से technical documentation के लिए design किया गया था, जबकि बाकी दो को उस role में fit किया गया है

  • करीब 5–10 पेज की Markdown document को अच्छी तरह structure करके, और उसे खुद किसी ज्यादा dynamic Jinja template से render करवाकर शुरुआत काफी संतोषजनक लगती है। automated docs के लिए build process भी होता है, और यह single GitHub README से ज्यादा बड़ा हो चुका होता है। लेकिन वहीं से दर्द शुरू होता है
    GitHub project pages documentation ठीक से fit नहीं बैठती, और यह confusing होता है कि .nojekyl file चाहिए या नहीं, gh-pages branch अभी भी चाहिए या नहीं। समझ नहीं आता कि repository settings गलत हैं या changes reflect नहीं हो रहे, और GitHub Actions आजमाते-आजमाते कुछ घंटे बाद सब irrational लगने लगता है। Read the Docs को फिर देखा तो लगता है वह Sphinx चाहता है, इसलिए Markdown और Sphinx को जोड़ा; build तो हो जाता है, लेकिन deploy के बाद page width टूट जाती है, जबकि local में reproduce नहीं होती, तो शायद community tier ad injection की वजह से हो। कई projects में यह अच्छी तरह चलता है और मैंने खुद भी किया है, लेकिन चलने से पहले तक यह अविश्वसनीय रूप से छोटी-छोटी बातों में picky होता है। आखिर में Markdown बनाम RST मुद्दा ही नहीं है; असल बात medium-size documentation project और static hosting के लिए अच्छी fit वाली combination ढूंढना है

    • क्या आपने mdBook देखा है? मैंने खुद इस्तेमाल नहीं किया, लेकिन mdBook इस्तेमाल करने वाले कई projects की docs मुझे अच्छी लगीं, और single README file से आगे बढ़ने पर यह काफी अच्छा दिखता है
      automatic deployment की guide भी अच्छी है: https://github.com/rust-lang/mdBook

  • लगता है लोग यह बात miss कर रहे हैं कि लेखक अपनी किताब की typesetting के context में बात कर रहा है। वह सामान्य तौर पर यह दावा नहीं कर रहा कि rST, Markdown से बेहतर है
    आम cases में Markdown की simplicity ही उसके व्यापक इस्तेमाल की वजह है, लेकिन लेखक जिस चीज की बात कर रहा है, वह यह नहीं है

  • यह देखना दिलचस्प है कि लोग reST पर ऐसे react कर रहे हैं जैसे वह Markdown का competitor बनकर बनाया गया हो। असल में मामला लगभग उलटा है। reST, 2002 में StructuredText का विकसित रूप था, और Markdown पहली बार 2004 में release हुआ था
    दोनों के goals बहुत समान हैं, और सबसे basic text में दोनों को plain text की तरह पढ़ा और लिखा जा सकता है। उस दौर में सबको ऐसी चीज चाहिए होने लगी थी, इसलिए कई formats सामने आए। मुझे नहीं लगता कि Markdown के जीतने की वजह “ज्यादा simple” या “ज्यादा readable” होना था। pure ASCII और whitespace से आसानी से व्यक्त की जा सकने वाली चीजों में ये आम तौर पर एक-दूसरे की जगह इस्तेमाल किए जा सकते हैं। क्या कोई कहेगा कि example का reST document parser के बिना पढ़ा न जा सकने वाला उलझा हुआ text है? Markdown variant इससे किस मायने में बेहतर है, यह मुझे साफ नहीं दिखता; historical accident की तरह एक format dominate कर गया, बस। दोनों अपने core goals के लिए पर्याप्त अच्छे हैं

    • क्योंकि बहुत simple example दिया गया था, इसलिए Markdown और reST दोनों उसे आसानी से handle कर सकते हैं
      reST जरूरत पड़ने पर कई उपयोगी extra formatting features देता है, लेकिन जब जरूरत न हो तो वे clutter हैं। 2010 के आसपास GitHub join करने पर मैंने GitHub-flavored Markdown इस्तेमाल करना शुरू किया, और Python docs की वजह से reStructuredText भी कुछ बार इस्तेमाल किया। बाद वाले की learning curve काफी ज्यादा थी, और उसके बाद उसे इस्तेमाल करने की वजह नहीं मिली
    • क्या यह unreadable है? नहीं। लेकिन क्या इसे type करना frustrating है? हां। underline-style headings edit करते समय परेशान करती हैं, और length को बिल्कुल match करना जरूरी न हो तब भी ऐसा करने का pressure महसूस होता है
      double backticks भी ऐसी syntax है जो असल में लगने वाले time की तुलना में जरूरत से ज्यादा annoying लगती है