yodl(1) Your Own Document Language yodl(1)

yodl - مبدل اصلی Yodl

yodl [OPTION]... [FILE]...

بسته Yodl یک زبان پیش‌سند (pre-document language) و ابزارهایی برای پردازش آن پیاده‌سازی می‌کند. ایده Yodl این است که شما یک سند را در یک پیش‌زبان می‌نویسید، سپس از ابزارها (مانند yodl2html(1)) برای تبدیل آن به یک زبان سند نهایی استفاده می‌کنید. مبدل‌های فعلی برای HTML، man، LaTeX، متن و یک مبدل آزمایشی XML هستند. انواع اصلی اسناد شامل "article"، "report"، "book"، "manpage" و "letter" هستند. زبان سند Yodl به‌گونه‌ای طراحی شده است که استفاده از آن ساده و قابل گسترش باشد.

`-D, --define=NAME[=VALUE]’: نماد NAME را تعریف می‌کند. این گزینه مانند `DEFINESYMBOL(NAME)()’ عمل می‌کند. اگر `=VALUE’ اضافه شود، `NAME’ با مقدار `VALUE’ مقداردهی اولیه می‌شود (دقیقاً مشابه `DEFINESYMBOL(NAME)(VALUE)’).
`-d, --definemacro=NAME=EXPANSION’: `NAME’ را به‌عنوان ماکرویی تعریف می‌کند که به `EXPANSION’ بسط می‌یابد.
`-h, --help’: اطلاعات نحوه استفاده را در جریان خطای استاندارد می‌نویسد و تمام گزینه‌های Yodl را شرح می‌دهد.
`-i, --index[=file]’: `file’ نام فایل نمایه است. به‌طور پیش‌فرض از `<outputbase>.idx’ استفاده می‌شود. در صورتی که خروجی در stdout نوشته شود، مقدار پیش‌فرضی وجود ندارد. فایل نمایه توسط پس‌پردازشگر Yodl یعنی `yodlpost’ پردازش می‌شود.
`-I, --include=DIR’: این گزینه دایرکتوری سراسری include در سیستم را مشخص می‌کند که YODL در آن به دنبال فایل‌های ورودی خود می‌گردد. برای نمونه، دستوری برای گنجاندن یک فایل مشخص مانند: 
INCLUDEFILE(latex)
اکنون Yodl به دنبال فایل `latex’ در دایرکتوری جاری می‌گردد، و در صورت عدم موفقیت، در دایرکتوری سراسری include سیستم جستجو می‌کند. دایرکتوری سراسری include معمولاً مکانی است که نگه‌دارنده سیستم فایل‌های ماکروی Yodl را در آن ذخیره می‌کند. این فرآیند جستجو هم برای فایل‌هایی که در داخل یک سند گنجانده شده‌اند و هم برای نام‌فایل‌های خط فرمان هنگام فراخوانی برنامه YODL اعمال می‌شود.
نام فایل گنجانده‌شده (در مثال بالا `latex’) نام خالص فایل است؛ YODL در صورت لزوم پسوند پیش‌فرض (`.yo’) را اضافه می‌کند.
گزینه `-I’ نام پیش‌فرض تعبیه‌شده در Yodl را برای دایرکتوری سراسری include بازنویسی می‌کند. نام تعبیه‌شده در زمان کامپایل Yodl تعریف شده است، مانند `/usr/share/yodl’. افزون بر این، این تعریف می‌تواند حاوی $HOME باشد که در صورت تعریف متغیر محیطی `home’ یا `HOME’، با دایرکتوری خانگی کاربر جایگزین می‌شود. همچنین می‌تواند شامل $STD_INCLUDE باشد که با مسیر استاندارد include تعیین‌شده در زمان کامپایل جایگزین می‌گردد. مسیر استاندارد include می‌تواند (به همان ترتیب) توسط سوییچ خط فرمان `-I’ یا متغیر محیطی `YODL_INCLUDE_PATH’ بازنویسی شود. به‌طور پیش‌فرض، دایرکتوری جاری به مسیر استاندارد include افزوده می‌شود. با این حال، هنگامی که از `-I’ یا `YODL_INCLUDE_PATH’ استفاده شود، دایرکتوری جاری باید صریحاً ذکر گردد. نیازی نیست که دایرکتوری‌ها با نویسه / پایان یابند. در بسته‌های توزیع‌شده `.deb’، دایرکتوری استاندارد به‌صورت `/usr/share/yodl’ تعریف شده است (که دایرکتوری کاری جاری به ابتدای آن افزوده می‌شود).
`-k, --keep-ws’: از زمان انتشار نسخه 2.00 نرم‌افزار YODL، فاصله‌های خالی در ابتدا و انتهای خطوط، حتی بدون علامت \ در انتها، در صورتی که `سطح فاصله خالی (white space level)’ غیرصفر باشد نادیده گرفته می‌شوند. نسخه‌های پیشین این فاصله‌ها را حفظ می‌کردند. رفتار موروثی و قدیمی رسیدگی به فاصله‌های خالی در انتهای خطوط با استفاده از فلگ `-k’ قابل دستیابی است. توجه داشته باشید که فاصله‌های خالی هنگام رونوشت عین‌به‌عین (verbatim copying) و زمانی که سطح فاصله خالی صفر باشد، همواره حفظ می‌شوند.
`-m, --messages=SET’: به اصطلاح `سطح پیام‌ها (message level)’ را به ترکیبی از مجموعه `acdeinw’ تنظیم می‌کند. حروف این مجموعه معانی زیر را دارند:
`a’: هشدار بحرانی (alert). هنگامی که یک خطای alert رخ می‌دهد، Yodl خاتمه می‌یابد. در این حالت Yodl درخواستی از سیستم دارد (مانند `get_cwd()’)، اما سیستم با شکست مواجه می‌شود.
`c’: حیاتی (critical). هنگامی که یک خطای حیاتی رخ می‌دهد، Yodl پایان می‌یابد. نمایش خود پیام می‌تواند متوقف شود، اما از خروج برنامه نمی‌توان جلوگیری کرد. یک وضعیت حیاتی برای نمونه، جا انداختن پرانتز باز در مکانی است که آرگومان پرانتزی باید ظاهر شود، یا وجود فایل ناموجود در مشخصه `INCLUDEFILE’ (زیرا این فایل باید تجزیه شود). فایل ناموجود با مشخصه `NOEXPANDINCLUDE’ یک خطای عادی (غیرحیاتی) محسوب می‌شود.
`d’: اشکال‌زدایی (debug). اطلاعات زیاد و با جزئیات، مانند دریافت اطلاعات درباره تک‌تک نویسه‌های خوانده‌شده توسط Yodl.
`e’: خطا (error). یک خطا (مانند نمادهای دوباره تعریف‌شده). پس از مواجهه با یک خطا، باقی‌مانده ورودی همچنان تجزیه می‌شود (تا حداکثر تعداد خطا)، اما هیچ خروجی تولید نمی‌شود.
`i’: اطلاعات (info). با جزئیاتی کمتر از `debug’، اما همچنان اطلاعات زیاد، مانند اطلاعات درباره تغییر رسانه‌ها (media switches).
`n’: اعلان (notice). اطلاعاتی مانند فراخوانی توابع داخلی (builtin).
`w’: هشدار (warning). مواردی که باید از آن مطلع باشید، اما احتمالاً در عملکرد صحیح Yodl اختلالی ایجاد نمی‌کند. رسیدگی به پیام emergency (اضطراری) غیرقابل‌پیکربندی است. این پیام‌ها قابل سرکوب نیستند، اما نباید رخ دهند چرا که نشان‌دهنده یک خطای داخلی هستند. در صورت وقوع این پیام‌ها، ارسال گزارش و اطلاعات درباره آن‌ها مورد قدردانی خواهد بود.
`-n, --max-nested-files=NR’: این گزینه باعث می‌شود در صورتی که تعداد فایل‌های ورودی تودرتو از `NR’ (که به‌طور پیش‌فرض 20 است) فراتر رود، Yodl متوقف شود. فراتر رفتن از این تعداد معمولاً نشان‌دهنده یک تعریف حلقوی در جایی از سند است؛ مانند حالتی که فایل `a.yo’ شامل `b.yo’ باشد، در حالی که `b.yo’ نیز `a.yo’ را می‌گنجاند و غیره. این گزینه مانع جایگزینی‌های بازگشتی ماکرو یا subst نمی‌شود؛ برای آن منظور گزینه `-r’ (`--max-replacements’) در دسترس است.
`-o, --output=FILE’: این گزینه باعث می‌شود Yodl خروجی خود را در `FILE’ بنویسد. به‌طور پیش‌فرض، خروجی به جریان خروجی استاندارد ارسال می‌شود. برای نمونه، می‌توانید با دو دستور زیر از YODL برای خواندن فایل `input’ و نوشتن در `output’ استفاده کنید: 
yodl input > output
yodl -ooutput input
تفاوت در این است که در حالت دوم یک فایل نمایه تولید می‌شود، اما در حالت نخست خیر. توجه داشته باشید که با مشخص کردن گزینه `--index’، می‌توان تولید فایل نمایه را اجباری کرد.
`-p, --preload=CMD’: این گزینه رشته `cmd’ را پیش‌بارگذاری (pre-load) می‌کند. رفتار آن به گونه‌ای است که گویی `cmd’ نخستین دستور در اولین فایل ورودی پردازش‌شده توسط YODL بوده است.
بیش از یک گزینه `--preload=CMD’ می‌تواند در خط فرمان مشخص شود. در این صورت، هر یک از دستورات به نوبت، پیش از خواندن هرگونه فایل، پردازش می‌شوند.
`-r, --max-replacements=NR’: این گزینه باعث می‌شود در صورتی که تعداد فراخوانی‌های ماکرو یا جایگزینی‌های subst از `NR * 10,000’ فراتر رود، Yodl متوقف شود. به‌طور پیش‌فرض، `NR’ برابر 1 است. تنظیم `--max-replacements=0’ به این معنی است که هیچ بررسی برای جایگزینی‌های ماکرو یا subst انجام نمی‌شود.
`-t, --trace’: این گزینه ردیابی (tracing) را فعال می‌کند: در حین تجزیه، Yodl خروجی خود را در جریان خطای استاندارد می‌نویسد. همانند گزینه `-k’، این گزینه نیز صرفاً برای اهداف اشکال‌زدایی تعریف شده است.
`-V, --version’: این گزینه نسخه واقعی YODL را نمایش می‌دهد.
`-v, --verbose’: این گزینه `سطح پرگویی (verbosity level)’ برنامه Yodl را افزایش می‌دهد و ممکن است بیش از یک بار درج شود. به‌طور پیش‌فرض Yodl پیام‌های هشدار بحرانی (alerting)، حیاتی (critical)، اضطراری (emergency) و خطا (error) را نمایش می‌دهد. هر گزینه `--verbose’ سطح پیام بعدی را اضافه می‌کند. به ترتیب، پیام‌های warning، notice، info و debug به این مجموعه اضافه می‌شوند. همچنین سرکوب پیام‌ها امکان‌پذیر است؛ برای این کار می‌توان از تابع تعبیه‌شده `VERBOSITY’ استفاده کرد.
`-W, --warranty’: این گزینه سلب مسئولیت ضمانت‌نامه و اعلان حق نشر (کپی‌رایت) را نمایش می‌دهد.
`-w, --warn’: وجود این گزینه باعث می‌شود Yodl در مواردی مانند تعریف مجدد نمادها، هشدار دهد.

برنامه yodl به هیچ فایلی نیاز ندارد، اما استفاده `عادی’ از بسته Yodl به فایل‌های ماکرو نیاز دارد که به‌طور پیش‌فرض در `tmp/wip/macros’ نصب می‌شوند. فایل‌های موجود در این دایرکتوری توسط مبدل‌هایی مانند yodl2txt(1) و غیره فراخوانی و گنجانده می‌شوند.

yodlbuiltins(7), yodlconverters(1), yodlletter(7), yodlmacros(7), yodlmanpage(7), yodlpost(1), yodlstriproff(1), yodltables(7), yodlverbinsert(1).

-

Frank B. Brokken (f.b.brokken@rug.nl),

1996-2025 yodl_4.05.01