Typst टेम्पलेट के लिए फ़ॉर्म

Typst टेम्पलेट अक्सर अपने फ़ंक्शन साथ लाता है: कवर पेज, इन्फ़ो बॉक्स, साइन-ऑफ़ ब्लॉक। रिपोर्ट लिखने वाला उन्हें कॉल करता है, जैसे #info-box(title: "Supply risk", tone: "risk")[...]। अगर आप टेम्पलेट सँभालते हैं, तो हर फ़ंक्शन के आर्ग्युमेंट एक बार बता सकते हैं। फिर Visual mode उस फ़ंक्शन की हर कॉल को एक फ़ॉर्म की तरह दिखाता है: लेबल वाले फ़ील्ड, तय विकल्पों के लिए सूची, हाँ या नहीं के लिए स्विच। किसी फ़ील्ड को बदलने पर .typ फ़ाइल में केवल वही एक आर्ग्युमेंट दोबारा लिखा जाता है, इसलिए रिपोर्ट साधारण Typst सोर्स रहती है जो उसी तरह कंपाइल होता है।

पाठक को क्या दिखता है

अपनी अलग लाइनों में लिखी कॉल एक कार्ड बन जाती है। कार्ड का हेडर फ़ॉर्म का नाम दिखाता है और, अगर आप चुनें, तो एक छोटा सारांश, जैसे बॉक्स का शीर्षक। हर आर्ग्युमेंट को उसके लेबल और एक कंट्रोल वाली पंक्ति मिलती है।

वाक्य के भीतर की कॉल, जैसे #badge("review"), टेक्स्ट की लाइन में एक चिप बन जाती है। चिप पर क्लिक करने से वही फ़ील्ड एक छोटे पॉपओवर में खुलते हैं।

टेक्स्ट फ़ील्ड और मार्कअप फ़ील्ड तब सहेजे जाते हैं जब आप Enter दबाते हैं (कई लाइन वाले फ़ील्ड में ⌘ Enter या Ctrl Enter) या फ़ील्ड छोड़ देते हैं। Esc पुरानी वैल्यू लौटा देता है। सूचियाँ और स्विच तुरंत सहेजे जाते हैं। हर बदलाव एक undo चरण है।

कर्सर को किसी कॉल में ले जाने पर उसका सोर्स दिखता है, Visual mode के किसी भी दूसरे एलिमेंट की तरह। कार्ड पर Edit in source भी यही करता है।

फ़ॉर्म कहाँ घोषित करें

दो जगहें हैं, फ़ॉर्मैट एक ही है:

• पैकेज में। पैकेज की typst.toml में [tool.oleafly] सेक्शन जोड़ें। Typst [tool.*] सेक्शन दूसरे टूल के लिए रखता है, इसलिए पैकेज फिर भी हर जगह इंस्टॉल और कंपाइल होता है। यह @local पैकेज के लिए और Typst Universe के @preview पैकेज के लिए काम करता है।
• प्रोजेक्ट में। प्रोजेक्ट के भीतर साधारण .typ फ़ाइलों के रूप में रखे टेम्पलेट के लिए, प्रोजेक्ट के रूट पर oleafly-forms.toml बनाएँ। हर फ़ॉर्म module से उस फ़ाइल का नाम भी बताता है जो फ़ंक्शन को परिभाषित करती है।

पैकेज का एक फ़ॉर्म:

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
function = "info-box"
label = "Info box"
summary = "title"

  [[tool.oleafly.forms.fields]]
  arg = "title"
  kind = "text"
  label = "Heading"
  placeholder = "Short heading"
  required = true

  [[tool.oleafly.forms.fields]]
  arg = "tone"
  kind = "choice"
  label = "Tone"
  default = "note"
  options = [{ value = "note", label = "Note" }, { value = "risk", label = "Risk" }, "neutral"]

  [[tool.oleafly.forms.fields]]
  arg = 0
  kind = "content"
  label = "Text"

प्रोजेक्ट का एक फ़ॉर्म, oleafly-forms.toml में:

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
module = "template/memo.typ"
function = "memo-header"
label = "Memo header"
fields = [
  { arg = "to", kind = "text", label = "To" },
  { arg = "subject", kind = "text", label = "Subject" },
]

कुंजियाँ

schema = 1 ज़रूरी है। जिस फ़ाइल में यह न हो, या कोई और संख्या हो, उसे नज़रअंदाज़ कर दिया जाता है।

हर [[tool.oleafly.forms]] प्रविष्टि में ये होते हैं:

कुंजी	ज़रूरी	मतलब
function	हाँ	फ़ंक्शन का नाम, एक Typst आइडेंटिफ़ायर के रूप में। हाइफ़न चलते हैं।
module	केवल oleafly-forms.toml में	वह प्रोजेक्ट फ़ाइल जो फ़ंक्शन को परिभाषित करती है, प्रोजेक्ट रूट के सापेक्ष, फ़ोल्डरों के बीच / के साथ।
label	नहीं	कार्ड और चिप पर फ़ॉर्म का नाम। डिफ़ॉल्ट फ़ंक्शन का नाम है।
summary	नहीं	वह आर्ग्युमेंट जिसकी वैल्यू लेबल के बगल में दिखती है, फ़ील्ड के arg की तरह लिखा जाता है।
fields	हाँ	एक या अधिक फ़ील्ड।

हर फ़ील्ड में ये होते हैं:

कुंजी	ज़रूरी	मतलब
arg	हाँ	नामित आर्ग्युमेंट के लिए एक नाम ("title"), या पोज़िशनल आर्ग्युमेंट के लिए एक संख्या (0 पहला है)। अंत का [...] ब्लॉक कोष्ठक वाले आर्ग्युमेंट के बाद का एक पोज़िशनल आर्ग्युमेंट गिना जाता है।
kind	हाँ	text, content, choice, number या toggle।
label	हाँ	फ़ील्ड का लेबल।
help	नहीं	फ़ील्ड के नीचे एक छोटा नोट।
placeholder	नहीं	खाली फ़ील्ड में ग्रे टेक्स्ट।
required	नहीं	true खाली फ़ील्ड को गायब चिह्नित करता है और उसका Clear बटन छिपा देता है। Oleafly आर्ग्युमेंट खुद कभी नहीं जोड़ता।
default	नहीं	वह वैल्यू जो आपका फ़ंक्शन तब इस्तेमाल करता है जब आर्ग्युमेंट छोड़ दिया जाए। वह दिखाई जाती है, कभी लिखी नहीं जाती।

प्रकार और उनकी अतिरिक्त कुंजियाँ:

• text एक Typst स्ट्रिंग लिखता है। बड़े बॉक्स के लिए multiline = true जोड़ें।
• content Typst मार्कअप संपादित करता है और उसे [...] ब्लॉक के रूप में लिखता है। स्ट्रिंग आर्ग्युमेंट स्ट्रिंग ही रहता है।
• choice को options चाहिए: स्ट्रिंग की सूची, या { value, label } टेबल जब लेबल वैल्यू से अलग हो। वैल्यू स्ट्रिंग के रूप में लिखी जाती हैं।
• number में integer, min, max और step होते हैं। संख्याओं की कोई इकाई नहीं होती।
• toggle true या false लिखता है।

किन कॉल को फ़ॉर्म मिलता है

Oleafly फ़ाइल के टॉप लेवल पर रिपोर्ट की अपनी #import और #let लाइनों का पालन करता है:

• #import "@local/acme-report:0.1.0" as acme #acme.info-box(...) को फ़ॉर्म बनाता है।
• #import "@local/acme-report:0.1.0": info-box, status-badge as badge #info-box(...) और #badge(...) को फ़ॉर्म बनाता है।
• #import "@local/acme-report:0.1.0": * पैकेज जिस हर फ़ंक्शन के लिए फ़ॉर्म घोषित करता है, उसे फ़ॉर्म बनाता है।
• #import "template/memo.typ": memo-header उस प्रोजेक्ट फ़ॉर्म से मेल खाता है जिसका module template/memo.typ है। पाथ रिपोर्ट के अपने फ़ोल्डर से पढ़े जाते हैं, या प्रोजेक्ट रूट से जब वे / से शुरू हों।

पैकेज का संस्करण ठीक-ठीक मेल खाना चाहिए। फ़ाइल में बाद में आने वाला उसी नाम का #let उस बिंदु से आगे फ़ॉर्म को बदल देता है। जिन कॉल तक कोई दूसरी फ़ाइल पहुँचती है जो पैकेज को दोबारा इम्पोर्ट करती है, वे अपना सोर्स टेक्स्ट बनाए रखती हैं।

ऐसा फ़ंक्शन जिसका नाम किसी ऐसे Typst एलिमेंट जैसा हो जिसे Visual mode पहले से बनाता है, जैसे table या figure, अपने सादे नाम से कॉल होने पर बिल्ट-इन रूप बनाए रखता है। #acme.table(...) या नाम बदला हुआ इम्पोर्ट फिर भी फ़ॉर्म पाता है।

रीड-ओनली दिखने वाले फ़ील्ड

कुछ आर्ग्युमेंट फ़ॉर्म से सुरक्षित रूप से संपादित नहीं किए जा सकते। उनकी पंक्ति कारण के साथ सोर्स दिखाती है, और Edit in source उस तक ले जाता है:

• Computed in the source: वैल्यू एक एक्सप्रेशन है, जैसे title: data.title।
• Written as a different kind of value: उदाहरण के लिए जहाँ फ़ॉर्म टेक्स्ट की उम्मीद करता है वहाँ संख्या।
• Not one of the choices: ऐसी वैल्यू जो आपके options में नहीं है।
• स्प्रेड आर्ग्युमेंट से सेट: ..args वाली कॉल ऐसी वैल्यू देती है जो फ़ॉर्म नहीं देख सकता, इसलिए हर फ़ील्ड रीड-ओनली है।

जब किसी फ़ील्ड को उसकी जगह पर नहीं जोड़ा जा सकता, उदाहरण के लिए किसी गायब आर्ग्युमेंट के बाद का पोज़िशनल आर्ग्युमेंट, तो फ़ॉर्म यह बता देता है और Add in source देता है।

परिभाषा में गलतियाँ

oleafly-forms.toml, या वेंडर किए पैकेज की typst.toml, को Oleafly में खोलें और हर समस्या अपनी लाइन पर एक मार्कर के रूप में दिखती है: अज्ञात प्रकार, गायब लेबल, डुप्लिकेट फ़ॉर्म, प्रोजेक्ट के बाहर का module। टूटा हुआ फ़ॉर्म छोड़ दिया जाता है और बाकी काम करते रहते हैं। 256 KB से बड़ी फ़ाइल नहीं पढ़ी जाती।

टेम्पलेट साझा करना

Oleafly पैकेज फ़ॉर्म उन्हीं फ़ोल्डरों से पढ़ता है जिन्हें कंपाइलर इस्तेमाल करता है। जिस सहयोगी के पास @local पैकेज नहीं है, उसे सादा सोर्स दिखता है और कोई त्रुटि नहीं। प्रोजेक्ट पर सभी के साथ फ़ॉर्म साझा करने के लिए, Typst packages डायलॉग खोलें, Use packages from the project folder चालू करें और Vendor packages into project चुनें। तब पैकेज, और उसके फ़ॉर्म, प्रोजेक्ट के typst-packages फ़ोल्डर में साथ चलते हैं (Typst प्रोजेक्ट देखें)।