نام (NAME)

ctwill, ctwill-proofsort, ctwill-refsort, ctwill-twinx - تبدیل کدهای CWEB به مستندات TeX با قابلیت نمایه‌سازی پیشرفته دوکلمه‌ای

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

ctwill [گزینه‌ها] webfile[.w] [{changefile[.ch]|-} [outfile[.tex]]]

( ctwill-proofsort < texfile.tex ) 1<> texfile.tex

ctwill-refsort < indexfile.ref > indexfile.sref

ctwill-twinx outfile.tex [outfile.tex ...] > index.tex

توضیحات (DESCRIPTION)

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

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

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

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

برنامه ctwill دقیقاً مانند cweave است، با این تفاوت که مستندات بسیار بهتری تولید می‌کند و در ازای آن باید بسیار بیشتر تلاش کنید. شما باید ctwill را دو بار اجرا کنید؛ یک بار برای راه‌اندازی اولیه و یک بار برای دریافت نتایج مناسب و دقیق. علاوه بر این، باید خروجی را دو بار از طریق TeX پردازش کنید.

پس از اجرای tex foo خروجی شما مشابه صفحات نهایی خواهد بود، با این تفاوت که مدخل‌های نمایه‌های کوچک (mini-indexes) به ترتیب الفبایی نخواهند بود. اجرای اول فایلی عجیب به نام foo.ref تولید می‌کند. دستور ctwill-refsort < foo.ref > foo.sref را اجرا کنید و سپس اجرای مجدد tex foo خروجی مرتب‌شده بر اساس الفبا تولید خواهد کرد.

برنامه ctwill-twinx یک نمایه اصلی برای مجموعه‌ای از برنامه‌های مرتبط که توسط ctwill (توجه داشته باشید که نه توسط cweave!) پردازش شده‌اند، گردآوری و کامپایل می‌کند. برنامه‌های مجزا باید نام خود را با خطی به شکل \def\title{NAME} تعریف کنند. برای راحتی کار، ctwill-twinx نخستین «کلمه» در \title را گرفته و آن را به حروف بزرگ تبدیل می‌کند. باید فایل twinx-startup.tex را برای صفحه نخست نمایه اصلی تنظیم و منطبق کنید.

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

معنای جاری هر شناسه در ابتدا \uninitialized است. سپس ctwill فایل .aux مربوط به کار شما را (در صورت وجود) می‌خواند.

پیش از خواندن فایل .aux، برنامه ctwill در واقع به دنبال فایلی به نام system.bux می‌گردد که در صورت وجود خوانده می‌شود. و پس از foo.aux، احتمال سوم فایل foo.bux است. قرارداد عمومی این است که تعاریف توابع و رویه‌های سیستمی مانند printf در system.bux قرار داده شوند، و تعاریف موجود در فایل‌های سربرگ مختص برنامه در foo.bux گذاشته شوند. مشابه فایل‌های .aux، فایل‌های .bux نیز باید فقط حاوی مشخصات @$ باشند.

معنای مشخص‌شده توسط @$...@> عموماً شامل چهار جزء است: یک شناسه (به همراه فاصله)، نام برنامه (درون آکولاد)، شماره بخش (به همراه فاصله)، و یک بخش TeX.

یک حالت آزمایشی ویژه به نام proofmode فراهم شده است تا بتوانید نتایج و نتیجه‌گیری‌های ctwill را درباره ارجاعات متقابل بررسی کنید. برنامه ctwill را با فلگ +P اجرا کنید تا TeX سندی با قالب‌بندی ویژه و حاوی نمایه‌های کوچک برای هر بخش تولید کند، تا بتوانید صحت مشخصات خود را بررسی نمایید.

این قالب proofmode در ترکیب با pdfctproofmac.tex استفاده می‌شود که هایپرلینک‌های فعال در خروجی‌های PDF و HINT ایجاد می‌کند. می‌توانید از ctwill-proofsort برای مرتب‌سازی الفبایی مدخل‌های نمایه استفاده کنید؛ فقط کافی است دستور زیر را اجرا کنید:

( ctwill-proofsort < texfile.tex ) 1<> texfile.tex

پس از اجرای ctwill (دو بار)، اما پیش از اجرای TeX (یک بار).

جزئیات بیشتر درباره نحوه استفاده از ctwill را می‌توان در بخش‌های نخستین کد منبع آن و به ترتیب در فایل تغییرات cweav-twill.ch قابل اعمال روی منبع cweave.w یافت. یک مثال کامل با تمامی جزئیات و امکانات در Mini-Indexes for Literate Programs، صفحات ۲۲۵ تا ۲۴۵ از کتاب Digital Typography اثر دانلد کنوت (CSLI، ۱۹۹۹) شرح داده شده است.

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

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

• این نسخه مبتنی بر جدیدترین نسخه CWEB (4.12.2) است.
• در TeX Live به دلایل فنی، پیشوند ctwill- به برنامه‌های کمکی و پیشوند ct به فایل‌های ماکرو اضافه شده است.
• گزینه‌های --help، --quiet، --verbose، --version و فلگ‌های +c، -i، -o و +lX در CWEBbin و TeX Live جدید هستند.
• گزینه +lX همراه با فایل‌های بسته‌بندی نمونه برای ctwimac.tex و ctproofmac.tex با زیرنویس‌ها و توضیحات ترجمه‌شده برای زبان آلمانی (+ld) ارائه می‌شود.
• گزینه +lX همچنین با یک فایل گسترش‌یافته pdfctwimac.tex برای تولید خروجی PDF و HINT با پیوندهای فعال (+lpdf) همراه است.
• جستجوی فایل با متغیر محیطی CWEBINPUTS گسترش یافته است تا مسیرهای متعددِ جداشده با دونقطه (:) را مجاز کند؛ بخش «محیط» را در ادامه ببینید.
• در صورت پیکربندی مناسب، برنامه اصلی ctwill با استفاده از ابزارهای gettext گنو بومی‌سازی (ترجمه) می‌شود.

گزینه‌ها (OPTIONS)

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

• +b: چاپ خط بنر (اطلاعات برنامه) در ترمینال
• +h: چاپ پیام موفقیت در پایان کار
• +p: چاپ پیام‌های گزارش پیشرفت کار
• +q/-q: میان‌بر برای -bhp؛ همچنین --quiet
• +v/-v: میان‌بر برای +bhp؛ همچنین --verbose (پیش‌فرض)
• +c: بررسی خروجی موقت برای تغییرات
• -e: عدم قرار دادن کدهای C/C++ درون \PB{...}
• -f: عدم اجبار به رفتن به خط جدید پس از هر عبارت C/C++ در خروجی
• -F: عدم اجبار به شروع عبارت مرکب (compound statement) در خط جدید
• -i: جلوگیری از ایجاد تورفتگی در اعلان پارامترها
• -o: جلوگیری از جداسازی اعلان‌ها و عبارات
• -x: حذف نمایه‌ها، نام بخش‌ها و فهرست مطالب
• +P: استفاده از \input ctproofmac.tex به جای ctwimac.tex
• +lX/-lX: استفاده از ماکروها برای زبان X از X{ctwimac|ctproofmac}.tex
• +s: چاپ آمار میزان مصرف و استفاده
• +t: رفتار با typename در قالب‌ها (templates) مشابه typedef
• --help: نمایش پیام راهنما و خروج
• --version: نمایش اطلاعات نسخه و خروج

محیط (ENVIRONMENT)

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

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

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

فایل‌ها (FILES)

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

• ctwimac.tex: ماکروهای پیش‌فرض TeX که با دستور \input در سطر نخست فایل خروجی درج می‌شوند.
• ctproofmac.tex: اگر ctwill با گزینه +P اجرا شود، سطر نخست فایل خروجی را به \input ctproofmac.tex تغییر می‌دهد.

در هر دو حالت می‌توانید پیشوند X را با گزینه +lX درخواست کنید؛ به عنوان مثال، +ld دستور \input dctwimac.tex و +Pld دستور \input dctproofmac.tex را درج خواهد کرد. یک کاربرد ویژه، استفاده از گزینه +lpdf است که دستور \input pdfctwimac.tex یا \input pdfctproofmac.tex را برای تولید خروجی PDF و HINT با هایپرلینک‌های فعال درج می‌کند.

• webfile.bux: تعاریف مراجع برای تفکیک و حل‌وفصل از سایر ماژول‌ها.
• system.bux: تعاریف مراجع برای تفکیک از فایل‌های سربرگ کتابخانه استاندارد C/C++ مانند <stdio.h>.

سایر فایل‌های کمکی (auxiliary) حاوی مراجع به طور خودکار توسط ctwill ساخته می‌شوند و فایل‌های نمایه واقعی توسط TeX ایجاد می‌گردند.

•

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).
• کد منبع برنامه CTWILL، بخش ۲۸۷:

• Digital Typography: نوشته D. E. Knuth (CSLI، ۱۹۹۹).
• Literate Programming: نوشته D. E. Knuth (CSLI، ۱۹۹۲).
• Weaving a Program: نوشته Wayne Sewell.

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

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

دان کنوت (Don Knuth) برنامه ctwill را بر پایه cweave اثر Silvio Levy و کنوت نوشت.

توسعه معاصر در https://github.com/ascherer/cwebbin انجام می‌شود.