Afficher des carrés colorés dans AsciiDoc : Guide pratique

Table of Contents

تعارف
مسئلہ
- استعمال کا سیاق
- ممکن طریقے
حل: HTML انجیکشن کے ساتھ
بهتر بنانے کے طریقے اور اچھی رویć
حل کی معماری
فوائد اور محدودیتیں
مثال واقعی: موضوعات کی دستاویز
نتیجہ
منابع

تعارف

فنّی دستاویزات کی ترتیب کرتے وقت، خاص طور پر اسٹائل گائیڈز یا یوزر انٹرфейس کی سبسفیKS کے لیے، رنگوں کی پالیٹ دکھانا عام طور پر ضروری ہوتا ہے۔ AsciiDoc، گرچہ دستاویزات کے لیے بہت طاقتور ہے، لیکن رنگوں کے نمونے دکھانے کے لیے نیٹیو سینٹکس فراہم نہیں کرتا۔ یہ مضمون مسئلے کی تفتیش کرتا ہے اور HTML انجیکشن پر مبنی یک خوشگوار حل پیش کرتا ہے۔

مسئلہ

استعمال کا سیاق

تصور کریں کہ آپ ویب ایپلیکیشن کے تھیم کی CSS متغیرات کی دستاویزات تیار کر رہے ہیں۔ آپ کو درکار ہے:

ہیکسیڈسیمل رنگ کے کوڈز فہرست بنائیں
ہر رنگ کا بصری پیشنمائش دکھائیں
دستاویز کی پڑھنے کی آسانی برقرار رکھیں
استاتیک سائٹ جنریٹرز 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 : کاراکٹرز یونیکوڈ

یونیکوڈ حروف استعمال کرنے کی طرح`■`(■) سادہ ہے لیکن محدود :

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

Limitations : رنگ پر کوئی کنٹرول نہیں، سسٹم فونت پر مشتمل ہے۔

اختيار 2: باہری تصاویر

ہر رنگ کے لیے PNG یا SVG تصاویر بنائیں :

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

حدود : ثقيلة الصيانة، تكاثر الملفات، لا مزامنة تلقائية

اختیار 3 : وظائف CSS مخصص

CSS کلاسوں کو تعریف کریں اور انہیں AsciiDoc کے رولز کے ذریعے استعمال کریں :

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

Limitations : باہر کا اسٹائل شیٹ ضروری ہے، تمام ممکن رنگوں کی پہلے سے تعریف.

اختیار 4 : انجیکشن HTML (منتخب شدہ حل)

میکرو استعمال کریں``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 انجیکشن کے ساتھ

کام کرنے کا اصول

ماکرو``d’AsciiDoc خام مواد داخل کرنے کی اجازت دیتا ہے جو AsciiDoc پروسيسر tarafından تفسیر نہیں کیا جائے گا. یہ ہم HTML کو inline CSS styles کے ساتھ سیدھی طرح inject کرنے کی اجازت دیتا ہے.

@startuml
participant "Document\nAsciiDoc" as doc
participant "Processeur\nAsciiDoc" as processor
participant "pass:[] macro" as pass
participant "HTML\nfinal" 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 ki tareef karne ki ijazat deta hai, inline flow mein rehke
`width:1em; height:1em`	مربے کا سائز فوانٹ کے سائز کے منسوب میں (responsive)
`background:#7952b3`	دکھانے والا رنگ (آپ کی ضرورت کے متغیر)
`vertical-align:middle`	مربع کو مجاور متن کے ساتھ منظم کریں
`margin-right:0.5em`	چوکور اور متن کے درمیان فاصلہ

display:inline-block

width/height ki tareef karne ki ijazat deta hai, inline flow mein rehke

width:1em; height:1em

مربے کا سائز فوانٹ کے سائز کے منسوب میں (responsive)

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) سفید مربع کو سفید پس‌منظر پر محدود کرنے کی اجازت دیتا ہے۔

چورhay کا سائز ملائیں

آپ مربعوں کے سائز کو اپنی ضرورت کے مطابق بدل سکتے ہیں:

* 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`یہ یقین دلاتا ہے کہ مربع فونٹ کے سائز کے ساتھ ایڈجسٹ ہوتے ہیں۔

محتوا بنائیں

خاص ضرورت کے لیے، آپ مختلف شکلیں بنا سکتے ہیں:

رنگین دائرہ

* 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
ان ٹیگز پر مشتمل ہے
`pass:[]` ان لائن HTML کے ساتھ
end note

note right of jbake
HTML کو محفوظ رکھیں
pass:[] میں
end note

note right of browser
اسٹائلز لاگو کریں
inline CSS
end note
@enduml

فوائد اور محدودیتیں

فوائد

✓ Autonomie : باہر کے فائلز پر کوئی انحصار نہیں
✓ Portabilité : AsciiDoc کے تمام پروسیسرز کے ساتھ کام کرتا ہے
✓ ہم آہنگی : رنگ کا کوڈ HTML میں مستقیماً موجود ہے
✓ Flexibilité : اسلوب کی مکمل شخصیتی
✓ مرمت : سادہ Hexadecimal کوڈ میں ترمیم
✓ جبییک کی سازگاری : مکمل طور پر سٹیٹیک سائٹ جنریٹرز کے ساتھ کام کرتا ہے

محدودیت

✗ لفاظی : HTML کوڈ تکراری AsciiDoc کے源 میں
✗ Source ki parhnay ki aasani : Source document ziyādah saaf nahi
✗ قابل رسائی : کوئی فطری متبادل متن نہیں (Manual طور پر شامل کرنا)

امکان پذیری میں بہتری

اسکرین ریڈرز کے لیے مربع کو رسائی پذیر بنانے کے لیے:

* 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 انjekشن ماکرو کے ذریعے``AsciiDoc ٹیکنیکی دسکاری میں رنگ کے نمونے دکھانے کے لیے ایک شاندار اور عملی حل فراہم کرتا ہے۔ اگرچہ تھوڑا سیاپی ہے، یہ طریقہ حداکثر قابلحمل اور سادہ مرمت فراہم کرتا ہے۔

یہ تکنیک کسی بیرونی تنظیم کی ضرورت نہیں ہے، کوئی اضافی ستائل شیٹ نہیں، اور JBake اور تمام معيار AsciiDoc پروسيسرز کے ساتھ فوراً کام کرتی ہے۔

جب آپ اپنی پہلی رنگین مربع بنا لیتے ہیں، تو صرف HTML کوڈ کاپی پیسٹ کریں اور ہیکسیڈسیمل کوڈ تبدیل کر کے جلدی سے مکمل پیلٹ بنائیں۔

یہ تکنیک کسی بھی کاسٹوم وائسوال رینڈرنگ کی ضرورت ہونے والی دیگر استعمال کے مواقع پر کشادی گئی جا سکتی ہے: آئیکن، بیج، سادے چارٹس، یا کوئی بھی وائسوال جس میں سٹائل پر واضح کنٹرول کی ضرورت ہو۔

منابع

منتشر شدہ مضمون 2025-11-01 کو