परिचय

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

समस्या

उपयोग का संदर्भ

कल्पना कीजिए कि आप एक वेब एप्लिकेशन थीम के CSS चर को दस्तावेज़ कर रहे हैं। आपको चाहिए :

हेक्साडेसिमल रंग कोडों को सूचीबद्ध करें
प्रत्येक रंग का दृश्य पूर्वावलोकन दिखाएँ
Maintenir la lisibilité du document source
JBake जैसे स्थिर साइट जेनरेटर्स के साथ संगतता सुनिश्चित करें

@startuml
left to right direction
skinparam packageStyle rectangle

actor "तकनीकी लेखक" as writer
actor "पाठक" as reader

rectangle "AsciiDoc दस्तावेज़ीकरण" {
  usecase "रंग पैलेट का दस्तावेज़ीकरण करें" as UC1
  usecase "हेक्साडेसिमल कोड प्रदर्शित करें" as UC2
  usecase "रंग देखें" as UC3
  usecase "स्थिर साइट जेनरेट करें" as UC4
  usecase "दस्तावेज़ीकरण देखें" as UC5
}

writer --> UC1
UC1 ..> UC2 : include
UC1 ..> UC3 : include
UC1 --> UC4
UC4 --> UC5
UC5 <-- reader
@enduml

संभावित दृष्टिकोण

एक AsciiDoc दस्तावेज़ में रंग दिखाने के कई समाधान पर विचार किया जा सकता है :

@startuml
skinparam componentStyle rectangle

package "संभावित समाधान" {
  component "यूनिकोड वर्ण" as unicode
  component "बाहरी चित्र" as images
  component "कस्टम CSS भूमिकाएं" as css
  component "HTML इंजेक्शन" as html
}

package "मूल्यांकन मानदंड" {
  component "सादगी" as simple
  component "पोर्टेबिलिटी" as portable
  component "अनुकूलन" as custom
  component "रखरखाव" as maintain
}

unicode -down-> simple : ✓
unicode -down-> portable : ✓
unicode -down-> custom : ✗

images -down-> simple : ✗
images -down-> portable : ✗
images -down-> custom : ✓

css -down-> simple : ~
css -down-> portable : ✗
css -down-> custom : ✓

html -down-> simple : ✓
html -down-> portable : ✓
html -down-> custom : ✓✓
html -down-> maintain : ✓

note right of html
अनुशंसित समाधान
end note
@enduml

विकल्प 1 : यूनिकोड अक्षर

यूनिकोड अक्षरों के उपयोग के रूप में`■`# JBake CLI Commands ` # Initialize a new JBake project jbake -i

Bake (generate) the site jbake -b

Bake and serve locally jbake -b -s

Bake and watch for changes jbake -b --reset

Specify source and destination jbake source_folder output_folder

Clear the output directory before baking jbake -b . output --reset `

(■) सरल लेकिन सीमित है :

* ■ --accent-color: #7952b3 (violet Bootstrap)

Limitations : रंग पर कोई नियंत्रण नहीं, सिस्टम फ़ॉन्ट पर निर्भर।

Option 2 : बाहरी चित्र

प्रत्येक रंग के लिए PNG या SVG छवियाँ बनाएँ:

* image:colors/violet.svg[width=16] --accent-color: #7952b3

सीमाएँ : भारी रखरखाव, फ़ाइलों की वृद्धि, स्वचालित समन्वय नहीं।

विकल्प 3 : CSS की कस्टम भूमिकाएँ

CSS क्लासेस परिभाषित करें और उन्हें AsciiDoc भूमिकाओं के माध्यम से लागू करें :

* [.color-violet]##■## --accent-color: #7952b3

सीमाएँ : बाहरी स्टाइलशीट की आवश्यकता होती है, सभी संभव रंगों की पूर्व परिभाषा।

@startuml
participant "दस्तावेज़\nAsciiDoc" as doc
participant "प्रोसेसर\nAsciiDoc" as processor
participant "`pass:[]` मैक्रो" as pass
participant "HTML\nअंतिम" as html

doc -> processor : Analyse document
processor -> pass : Détecte pass:[]
pass -> processor : Retourne HTML brut
processor -> html : Insère sans transformation
html -> html : Navigateur applique styles
@enduml

मैक्रो का उपयोग करें``इंलाइन शैली के साथ HTML इंजेक्ट करने के लिए :

* pass:[<span style="display:inline-block;width:1em;height:1em;
background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: #7952b3 (violet Bootstrap)

समाधान: HTML इन्जेक्शन के साथ

कार्य करने का सिद्धांत

मैक्रो``AsciiDoc कच्ची सामग्री डालने की अनुमति देता है जिसे AsciiDoc प्रोसेसर द्वारा ज्याख्या नहीं की जाएगी। इससे हमें सीधे HTML को इन्लाइन CSS शैलियों के साथ इंजेक्ट करने की अनुमति मिलती है।

@startuml
participant "दस्तावेज़\nAsciiDoc" as doc
participant "प्रोसेसर\nAsciiDoc" as processor
participant "पास:[] मैक्रो" as pass
participant "HTML\nअंतिम" as html

doc -> processor : Analyse document
processor -> pass : Détecte pass:[]
pass -> processor : Retourne HTML brut
processor -> html : Insère sans transformation
html -> html : Navigateur applique styles
@enduml

कार्यान्वयन

यहाँ HTML संरचना डालने के लिए है :

<span style="display:inline-block;
             width:1em;
             height:1em;
             background:#7952b3;
             vertical-align:middle;
             margin-right:0.5em">
</span>

CSS गुणों की व्याख्या

सम्पत्ति फ़ंक्शन

सम्पत्ति	फ़ंक्शन
`display:inline-block`	इंलाइन प्रवाह में बने रहते हुए width/height सेट करने की अनुमति देता है
`width:1em; height:1em`	फ़ॉन्ट के आकार के सापेक्ष वर्ग का आकार (प्रतिक्रियाशील)
`background:#7952b3`	दिखाने वाला रंग (आपकी आवश्यकतानुसार परिवर्तनीय) (आपकी)
`vertical-align:middle`	वर्ग को सन्निहित पाठ के साथ संरेखित करें
`margin-right:0.5em`	वर्ग और टेक्स्ट के बीच की दूरी

display:inline-block

इंलाइन प्रवाह में बने रहते हुए width/height सेट करने की अनुमति देता है

width:1em; height:1em

फ़ॉन्ट के आकार के सापेक्ष वर्ग का आकार (प्रतिक्रियाशील)

background:#7952b3

दिखाने वाला रंग (आपकी आवश्यकतानुसार परिवर्तनीय) (आपकी)

vertical-align:middle

वर्ग को सन्निहित पाठ के साथ संरेखित करें

margin-right:0.5em

वर्ग और टेक्स्ट के बीच की दूरी

उदाहरण पूरा

यहाँ एक उदाहरण है जो एक थीम पैलेट का दस्तावेज़ीकरण करता है :

== Thème Clair

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span>] --accent-hover: `#61428f` (violet plus foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --card-bg: `#ffffff` (blanc)

निम्नलिखित रेंडर कौन उत्पन्न करता है:

लाइट थीम

--bg-primary:`#f8f9fa`(ऑफ़ व्हाइट)
--text-primary:`#212529`(बहुत गहरा काला)
--accent-color:`#7952b3`(Bootstrap बैंगनी)
--accent-hover:`#61428f`(गहरा बैंगनी)
--card-bg:`#ffffff`(सफ़ेद)

अनुकूलन और सर्वोत्तम प्रथाएँ

हल्के रंगों को प्रबंधित करें

बहुत हल्के रंगों (सफेद, बहुत हल्का ग्रे) के लिए, उन्हें सफेद पृष्ठभूमि पर दृश्यमान बनाने के लिए एक सीमा जोड़ें :

<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>

ग्रे बॉर्डर (border:1px solid #ccc) सफेद पृष्ठभूमि पर सफेद वर्ग को सीमा निर्धारित करने की अनुमति देता है।

वर्गों के आकार को समायोजित करें

आप अपनी आवश्यकताओं के अनुसार वर्गों के आकार को समायोजित कर सकते हैं :

* pass:[<span style="display:inline-block;width:1.5em;height:1.5em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Grand carré
* pass:[<span style="display:inline-block;width:0.8em;height:0.8em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Petit carré

इकाई का उपयोग`em`यह सुनिश्चित करता है कि वर्ग फ़ॉन्ट के आकार के अनुसार अनुकूलित हो जाते हैं।

वैरिएंट बनाएँ

@startuml
package "दस्तावेज़ीकरण वर्कफ़्लो" {
  [Document AsciiDoc\navec pass macro] as asciidoc
  [Processeur JBake] as jbake
  [Site HTML statique] as html
  [Navigateur Web] as browser
}

asciidoc --> jbake : 1. Compilation
jbake --> html : 2. Génération
html --> browser : 3. Affichage
browser --> browser : 4. Rendu CSS

note right of asciidoc
इसमें टैग शामिल हैं
`pass:[]` इनलाइन HTML के साथ
end note

note right of jbake
HTML सुरक्षित रखें
pass:[] में
end note

note right of browser
इनलाइन CSS स्टाइल लागू करें
end note
@enduml

रंगीन वृत्त

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violet

रंगीन सीमा वाला वर्ग

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:3px solid #7952b3;vertical-align:middle;margin-right:0.5em"></span>] Bordure violette

समाधान आर्किटेक्चर

@startuml
package "दस्तावेज़ीकरण वर्कफ़्लो" {
  [Document AsciiDoc\navec pass macro] as asciidoc
  [Processeur JBake] as jbake
  [Site HTML statique] as html
  [Navigateur Web] as browser
}

asciidoc --> jbake : 1. Compilation
jbake --> html : 2. Génération
html --> browser : 3. Affichage
browser --> browser : 4. Rendu CSS

note right of asciidoc
  Contient les balises
  pass:[] avec HTML inline
end note

note right of jbake
  Préserve le HTML
  dans pass:[]
end note

note right of browser
  Applique les styles
  inline CSS
end note
@enduml

फ़ायदे और सीमाएँ

फ़ायदे

✓ स्वायत्तता : बाहरी फ़ाइलों पर कोई निर्भरता नहीं
✓ Portabilité : सभी AsciiDoc प्रोसेसर के साथ काम करता है
✓ सिंक्रोनाइज़ेशन : रंग कोड HTML में सीधे है
�✓ लचीलापन : पूर्ण शैली अनुकूलन
�✓ Maintenance : हेक्साडेसीमल कोड का सरल संशोधन
✓ JBake संगतता : पूरी तरह से स्थिर साइट जनरेटरों के साथ काम करता है

सीमाएँ

�✗ वाचालता : पुनरावृत्तिपूर्ण HTML कोड AsciiDoc स्रोत में
�✗ स्रोत की पठनीयता : स्रोत दस्तावेज़ कम परिष्कृत है
एक्सेसिबिलिटी : कोई मूल वैकल्पिक पाठ नहीं (हाथ से जोड़ना होगा)

सुलभता में सुधार

स्क्रीन रीडर्स के लिए वर्गों को सुलभ बनाने के लिए :

* pass:[<span role="img" aria-label="Couleur violet Bootstrap"
style="display:inline-block;width:1em;height:1em;background:#7952b3;
vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: `#7952b3` (violet Bootstrap)

विशेषताएँ`role="img"` et `aria-label`वे सहायक प्रौद्योगिकियों को दृश्य सामग्री को समझने और वर्णित करने की अनुमति देते हैं।

वास्तविक उदाहरण : विषयों का दस्तावेज़

यहाँ कई विषयों का दस्तावेज़ करने वाला एक पूर्ण उदाहरण है :

= Guide des couleurs de l'application

== Thème Clair (`:root`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)

== Thème Sombre (`[data-bs-theme="dark"]`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #999;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#0d6efd;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#0d6efd` (bleu Bootstrap)

== Thème Contraste Élevé (`[data-bs-theme="high-contrast"]`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#000000;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#000000` (noir)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #000;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#00ff00;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#00ff00` (vert vif)

निष्कर्ष

मैक्रो के माध्यम से HTML इंजेक्शन``AsciiDoc एक सुंदर और व्यावहारिक समाधान प्रदान करता है तकनीकी दस्तावेज़ीकरण में रंग के नमूनों को प्रदर्शित करने के लिए। यद्यपि यह थोड़ा शब्दजालपूर्ण है, इस तरीके से अधिकतम पोर्टेबिलिटी और सरलीकृत रखरखाव की गारंटी मिलती है।

AsciiDoc में रंगीन वर्ग प्रदर्शित करना: एक व्यावहारिक मार्गदर्शिका