نام (NAME)

ctangle, cweave - تبدیل CWEB به C/C++ و/یا TeX

خلاصه دستور (SYNOPSIS)

ctangle [options] webfile[.w] [{changefile[.ch]|-} [outfile[.c]]]

cweave [options] webfile[.w] [{changefile[.ch]|-} [outfile[.tex]]]

توضیحات (DESCRIPTION)

برنامه ctangle یک سند منبع CWEB را به یک برنامه C/C++ تبدیل می‌کند که می‌تواند به شیوه معمول کامپایل شود. فایل خروجی شامل مشخصات #line است تا اشکال‌زدایی بتواند بر اساس فایل منبع CWEB انجام پذیرد.

برنامه cweave همان فایل CWEB را به یک فایل TeX تبدیل می‌کند که می‌تواند به روش معمولی قالب‌بندی و چاپ شود. این برنامه به جزئیات تایپوگرافی مانند صفحه‌آرایی و استفاده از تورفتگی، ایتالیک، پررنگ، و غیره توجه مناسب دارد و اطلاعات جامع نمایه‌سازی متقابل را که به‌طور خودکار جمع‌آوری می‌کند، ارائه می‌دهد.

ابزار CWEB به شما امکان می‌دهد یک سند منفرد حاوی تمامی اطلاعات لازم، هم برای تولید یک برنامه C/C++ قابل‌کامپایل و هم برای تولید سندی خوش‌قالب که برنامه را با هر میزان از جزئیات مدنظر نویسنده توصیف می‌کند، آماده کنید. کاربر CWEB باید هم با C/C++ و هم با TeX آشنایی داشته باشد.

نحوه استفاده (USAGE)

خط فرمان باید شامل یک، دو یا سه نام باشد. نام اول به‌عنوان فایل ورودی CWEB در نظر گرفته می‌شود (و در صورت نداشتن پسوند، .w اضافه می‌شود). اگر نام دومی وجود داشته باشد، فایل تغییرات است (و در صورت نداشتن پسوند، .ch افزوده می‌شود). فایل تغییرات همان‌طور که در مستندات توضیح داده شده، بخش‌هایی از فایل CWEB را بازنویسی می‌کند. اگر نام سومی وجود داشته باشد، نام پیش‌فرض فایل خروجی را بازنویسی می‌کند؛ این نام در حالت عادی همان نام فایل ورودی (اما در دایرکتوری جاری) با پسوند .tex است. اگر صرفاً می‌خواهید نام فایل خروجی را تغییر دهید اما فایل تغییراتی برای اعمال ندارید، می‌توانید از «-» به‌عنوان آرگومان دوم استفاده کنید.

تفاوت‌ها با CWEB اصلی (DIFFERENCES TO ORIGINAL CWEB)

ابزار CWEBbin بسیار تلاش می‌کند تا جایگزینی بی‌دردسر برای CWEB باشد، بنابراین در حالت کلی نباید هیچ تفاوتی در نحوه فراخوانی برنامه‌ها یا در خروجی حاصل مشاهده کنید. با این حال، چند تفاوت شایان ذکر وجود دارد:

• گزینه‌های --help، --quiet، --verbose، --version، و پرچم‌های +c، -i، -o، +u و +lX در CWEBbin و TeX Live جدید هستند.
• گزینه +lX با چندین فایل پوششی برای cwebmac.tex همراه است که حاوی عناوین ترجمه‌شده برای زبان‌های آلمانی (+ld)، فرانسوی (+lf) و ایتالیایی (+li) است.
• جستجوی فایل با متغیر محیطی CWEBINPUTS گسترش یافته است تا چندین مسیر جداشده با دونقطه را بپذیرد؛ بخش «محیط (ENVIRONMENT)» در زیر را ببینید.
• در صورت پیکربندی مناسب، برنامه‌های اصلی ctangle و cweave با “GNU gettext utilities” بومی‌سازی شده‌اند.

گزینه‌ها (OPTIONS)

گزینه‌ها در خط فرمان می‌توانند با «-» غیرفعال شوند (اگر به‌طور پیش‌فرض فعال باشند) یا با «+» فعال گردند (اگر به‌طور پیش‌فرض غیرفعال باشند). در عمل، گزینه‌ها از چپ به راست پردازش می‌شوند، بنابراین دنباله‌ای مانند --verbose -h تنها خط اعلان (+b) و گزارش پیشرفت (+p) را نمایش می‌دهد، اما از پیام موفقیت‌آمیز بودن (-h) صرف‌نظر می‌کند.

دسته‌ی اول گزینه‌ها بین هر دو برنامه ctangle و cweave مشترک هستند:

• +b: چاپ خط اعلان در ترمینال
• +h: چاپ پیام موفقیت در زمان اتمام کار
• +p: چاپ پیام‌های گزارش پیشرفت
• +q/-q: میان‌بر برای -bhp؛ همچنین --quiet
• +v/-v: میان‌بر برای +bhp؛ همچنین --verbose (پیش‌فرض)
• +c: بررسی خروجی موقت برای تغییرات
• +s: چاپ آمار استفاده
• --help: نمایش پیام راهنما و خروج
• --version: نمایش اطلاعات نسخه و خروج

دو گزینه دیگر وجود دارد که تنها برای ctangle قابل اعمال هستند:

• +k: نگه‌داشتن جداکننده‌ها در مقادیر عددی در خروجی
• +u: نویسه‌گردانی نویسه‌های UTF-8 در کد C

هشت گزینه دیگر وجود دارد که تنها برای cweave قابل اعمال هستند:

• -e: قرار ندادن بخش‌های C/C++ در داخل \PB{...}
• -f: اجبار نکردن به رفتن به سطر جدید بعد از هر دستور C/C++ در خروجی
• -F: اجبار نکردن عبارت مرکب به شروع در یک خط جدید
• -i: جلوگیری از تورفتگی در اعلان پارامترها
• -o: جلوگیری از جداسازی اعلان‌ها و دستورها
• -x: حذف نمایه‌ها، نام بخش‌ها و فهرست مطالب
• +lX/-lX: استفاده از ماکروها برای زبان X مطابق با Xcwebmac.tex
• +t: رفتار با typename در یک قالب مانند typedef

محیط (ENVIRONMENT)

متغیر محیطی CWEBINPUTS برای جستجوی فایل‌های ورودی استفاده می‌شود، یا در صورت تنظیم نبودن CWEBINPUTS از پیش‌فرض سیستم استفاده می‌شود. برای جزئیات نحوه جستجو به tex(1) مراجعه کنید. جهت جلوگیری از تداخل با برنامه‌های دیگری که از متغیر محیطی CWEBINPUTS استفاده می‌کنند، می‌توانید دقیق‌تر عمل کرده و از CWEBINPUTS_cweb برای نیازمندی‌های خاص CWEB استفاده کنید.

در صورت آماده‌سازی برای پشتیبانی از NLS، برنامه‌های ctangle و cweave از متغیر محیطی TEXMFLOCALEDIR برای پیکربندی دایرکتوری بالادستی استفاده می‌کنند که در آن “GNU gettext utilities” به جستجوی کاتالوگ‌های ترجمه می‌پردازد.

این متغیرها از قبل در texmf.cnf مربوط به TeX Live پیکربندی شده‌اند.

فایل‌ها (FILES)

محل فایل‌های ذکرشده در زیر از سیستمی به سیستم دیگر متفاوت است. از ابزار kpsewhich برای یافتن مکان آن‌ها استفاده کنید.

• cwebmac.tex: ماکروهای پیش‌فرض TeX که در خط اول فایل خروجی cweave به‌صورت \input فراخوانی می‌شوند.
• cwebman.tex: کتابچه راهنمای کاربری CWEB، موجود در قالب PDF از CTAN.

همچنین ببینید (SEE ALSO)

• The CWEB System of Structured Documentation: نوشته Donald E. Knuth و Silvio Levy (نسخه چاپی cwebman.tex و فهرست کدهای منبع common.w، ctangle.w و cweave.w).
• Literate Programming: نوشته D. E. Knuth.
• Weaving a Program: نوشته Wayne Sewell.

cweb(1), tex(1), cc(1)

نویسندگان (AUTHORS)

Don Knuth سیستم WEB را برای TeX و Pascal نوشت.

Silvio Levy با انطباق قراردادهای WEB با C و بازنویسی همه‌چیز در CWEB، سیستم CWEB را طراحی و توسعه داد. Knuth استفاده از CWEB را آغاز کرد و بهبودهای بیشتری اعمال نمود.

از بسیاری از همکاران دیگر در راهنمای CWEB قدردانی شده است.

توسعه امروزی در https://github.com/ascherer/cweb در حال انجام است.