इस पृष्ठ पर

Guidedog / दस्तावेज़ 0.2.0

त्रुटि संदेश

रिपोर्ट समस्या का नाम, स्थान और उपयोगी अगला कदम बताए। Guidedog यह जानकारी संरचित डेटा में रखता है। टर्मिनल रंग और स्रोत चिह्न जोड़ता है। JSON बिना टर्मिनल सजावट के डेटा रखता है।

रिपोर्ट पढ़ना

UNDEFINED SUBSTITUTION                              rst.substitution.undefined

  guide/page.rst:4: See |logo| here.
                        ^^^^^^

The substitution "|logo|" is not defined.
No output was written.

Add a definition, e.g. ".. |name| replace:: text".

रिपोर्ट के चार भाग हमेशा इसी क्रम में होते हैं:

1. शीर्षक पट्टी। शीर्षक समस्या का प्रकार बड़े अक्षरों में बताता है। चेतावनी और सूचना WARNING: और NOTE: से शुरू होती हैं। दाईं ओर rst.substitution.undefined जैसा रिपोर्ट कोड है: खोजने के लिए स्थिर नाम।
2. स्थान। फ़ाइल और पंक्ति, मूल पंक्ति और समस्या वाले पाठ के नीचे चिह्न दिखता है। किसी एक पंक्ति से न जुड़ी समस्या, जैसे लापता फ़ोल्डर या फ़्लैग, में केवल पथ दिखता है या स्थान नहीं दिखता।
3. क्या हुआ। पहले कारण की व्याख्या होती है। ज़रूरत हो तो आउटपुट पर असर बताया जाता है: यहाँ कुछ भी नहीं लिखा गया।
4. क्या करें। रंगीन टर्मिनल में हरे रंग का संकेत ठोस दिशा देता है। कई उपाय हों तो सबसे उपयोगी लगने वाला पहले आता है।

रंग केवल शब्दों की बात पर ज़ोर देते हैं। --color=never रंग बंद करता है। --color=always गैर-टर्मिनल आउटपुट में भी रंग रखता है।

हर संकेत आगे की राह बताता है

Guidedog अपने संदेशों पर भी यह नियम लागू करता है। संकेत पहले क्रिया ("Add", "Pass", "Set", "Rename", "Run") और उसका लक्ष्य बताता है, जैसे --budget=MIB, conf.toml का root_doc या निर्देश का विकल्प। tests/hints_test.odin हर संभव संदेश पढ़ता है। खाली संकेत, संदेश की पुनरावृत्ति या बिना ज़रूरी विवरण के केवल "report this" कहने पर टेस्ट विफल होता है। दो अन्य रूप स्वीकार हैं: सुधार सुझाना ("Did you mean numfig?") और कार्रवाई-रहित नोट में "Nothing to do:" के साथ कारण देना।

समस्या Guidedog की हो तो संकेत साफ़ बताता है। रिपोर्ट के साथ चलाया कमांड, समस्या वाला इनपुट और guidedog --version का आउटपुट माँगता है।

प्रोग्राम के लिए रिपोर्ट

--diagnostics=json हर रिपोर्ट को मानक त्रुटि पर एक पंक्ति में एक JSON ऑब्जेक्ट के रूप में लिखता है, ताकि संपादक और निरंतर एकीकरण पढ़ सकें:

{"schema":1,"code":"rst.substitution.undefined","severity":"error",
 "title":"UNDEFINED SUBSTITUTION","message":"The substitution \"|logo|\" is not defined.",
 "hint":"Add a definition, e.g. \".. |name| replace:: text\".","path":"guide/page.rst",
 "line":4,"column":5,"end_line":4,"end_column":11,"source":"See |logo| here.",
 "category":""}

यहाँ पाठ मोड़ा गया है; वास्तव में हर ऑब्जेक्ट एक पंक्ति में है। schema प्रारूप का संस्करण है, जो फ़ील्ड बदलने पर ही बदलता है। बाकी पढ़ने से पहले इसे जाँचें। कॉलम 1 से Unicode स्केलर गिनते हैं, बाइट या टर्मिनल खाने नहीं। source पूरी मूल पंक्ति है। टर्मिनल त्रुटि के आसपास सीमित हिस्सा दिखाता है और नियंत्रण अक्षर एस्केप करने तथा चौड़े अक्षर मापने के बाद निशान मिलाता है। category suppress_warnings वाली चेतावनी श्रेणी है, या खाली है।

मेमोरी कम पड़ने पर

मेमोरी कम पड़ना भी रिपोर्ट है, क्रैश नहीं। दो प्रकार हैं:

host.budget (मेमोरी बजट पूरा)

बिल्ड अपनी मेमोरी सीमा तक पहुँचा (--budget=MIB, डिफ़ॉल्ट 1 GiB)। रिपोर्ट चरण और टेम्पलेट में मेमोरी माँगने वाली पंक्ति बताती है। टर्मिनल पर एक बार चुनाव मिलता है: पर्याप्त बजट बढ़ाएँ, कार्यशील मेमोरी डिस्क पर रखकर चलें, या रुकें। दूसरे वातावरण में बिल्ड रुकता है। --budget या --memory=disk से पहले चुनाव कर सकते हैं। संकेत बजट का अंक भी देता है, जैसे:

Build again with --budget=256, or with --memory=disk to keep working memory on
disk (slower); or split the work into smaller files.

संख्या वर्तमान उपयोग में अस्वीकृत चरण की माँग का चार गुना जोड़ती है (चरण आउटपुट और लिखने की प्रति भी रखता है), या पुराने बजट का दोगुना लेती है—जो बड़ा हो। इसे 64 MiB तक ऊपर गोल किया जाता है। चरण खाली मेमोरी में समा सके तो सीमा उपलब्ध मेमोरी से अधिक नहीं। न समाए तो संकेत बताकर पहले --memory=disk सुझाता है:

Build again with --memory=disk to keep working memory on disk (slower): the step
needs a budget of about 1408 MiB, more than the 900 MiB this machine has free. Or
free that memory and build with --budget=1408, or split the document.

host.memory (मेमोरी उपलब्ध नहीं)

सिस्टम ने बजट के भीतर की मेमोरी माँग ठुकराई। कमांड उस मेमोरी को छुए बिना रुकता है: बिल्ड कुछ प्रकाशित नहीं करता, GDS बदलाव पूरा होता है या बिल्कुल नहीं, और convert पूरा पेज लिखता है या कुछ नहीं। मेमोरी खाली करें या थ्रेड घटाएँ (-j 1), फिर चलाएँ। प्रकाशन का निर्णय हो जाने पर आउटपुट बदलने को मेमोरी नहीं चाहिए; अस्वीकृति से अधूरा प्रकाशन नहीं होता। पुराने प्रकाशन को पूरा करने की योजना हेतु मेमोरी न हो तो उसे अगली बिल्ड के लिए जस का तस छोड़ा जाता है।

दोनों स्टेटस 3 पर समाप्त होते हैं।

एग्ज़िट स्टेटस

हर कमांड इनमें से एक स्टेटस पर समाप्त होता है, जिससे स्क्रिप्ट विफलता के प्रकार पहचान सकती हैं:

स्थिति	अर्थ
0	सफलता। आउटपुट लिखा गया और बिल्ड में प्रकाशित हुआ।
1	इनपुट में समस्या: दस्तावेज़ त्रुटि, नीति से अस्वीकृति (--raw के बिना raw सामग्री), न पढ़ा जा सकने वाला दस्तावेज़, या -W अथवा --strict से त्रुटि मानी गई चेतावनी।
2	कमांड का गलत उपयोग: अज्ञात फ़्लैग या कमांड, लापता या अमान्य मान, अथवा conf.toml या -D में अमान्य विकल्प।
3	सीमा पूरी हुई: मेमोरी बजट (--budget), नेस्टिंग गहराई (--max-depth), नोड संख्या (--max-nodes), स्टैक (--stack-kib), बहुत बड़ा स्रोत या सिस्टम से न मिल सकी मेमोरी।
4	फ़ाइल या बाहरी प्रोग्राम विफल हुआ: न पढ़ा या लिखा जा सकने वाला पथ, पढ़ते समय बदली फ़ाइल, या Typst का शुरू या पूरा न होना।
5	Guidedog में आंतरिक विफलता हुई और रिपोर्ट इसे बताने को कहती है।
70	Guidedog क्रैश होने पर GUIDEDOG CRASHED (internal error), चला कमांड, दोष और guidedog --version का आउटपुट देता है। रिपोर्ट की जगह बिल्ड का इश्यू ट्रैकर, या बिल्ड देने वाला व्यक्ति है। प्रकाशन अंत में होने से क्रैश पर पुराना आउटपुट बना रहता है।
130	कमांड Ctrl+C से रोका गया; प्रकाशित फ़ाइलें बदली नहीं गईं।

किसी भी कारण से बिल्ड विफल हो तो पिछला आउटपुट और बिल्ड रिकॉर्ड वैसे ही रहते हैं। समस्या सुधारें और फिर बिल्ड करें।