.\" Automatically generated by Pandoc
.\"
.TH "CTWILL" "1" "February 3, 2026." "Web2c 2026" "General Commands Manual"
.SH "نام (NAME)"
ctwill, ctwill-proofsort, ctwill-refsort, ctwill-twinx \- تبدیل کدهای CWEB به مستندات TeX با قابلیت نمایه‌سازی پیشرفته دوکلمه‌ای
.SH "خلاصه دستور (SYNOPSIS)"
\f[B]ctwill\f[R] [\f[I]گزینه‌ها\f[R]] \f[I]webfile\f[R][.w]
[{\f[I]changefile\f[R][.ch]|\-} [\f[I]outfile\f[R][.tex]]]
.PD 0
.P
.PD
( \f[B]ctwill-proofsort\f[R] < \f[I]texfile\f[R].tex ) 1<>
\f[I]texfile\f[R].tex
.PD 0
.P
.PD
\f[B]ctwill-refsort\f[R] < \f[I]indexfile\f[R].ref > \f[I]indexfile\f[R].sref
.PD 0
.P
.PD
\f[B]ctwill-twinx\f[R] \f[I]outfile\f[R].tex [\f[I]outfile\f[R].tex \&...]
> index.tex
.SH "توضیحات (DESCRIPTION)"
برنامه
\f[B]ctwill\f[R]
یک سند منبع CWEB را به یک فایل TeX تبدیل می‌کند که می‌تواند به روش معمول قالب‌بندی و چاپ شود.
این برنامه به جزئیات نگارشی مانند صفحه‌آرایی و استفاده از تورفتگی،
\f[I]حروف مورب (ایتالیک)\f[R]،
\f[B]حروف توپر (بولد)\f[R]
و غیره توجه لازم را دارد و اطلاعات جامع ارجاع‌متقابل (نمایه‌سازی) را که به طور خودکار جمع‌آوری می‌کند، ارائه می‌دهد.
.PP
سیستم CWEB به شما امکان می‌دهد سندی واحد آماده کنید که حاوی تمام اطلاعات لازم برای تولید یک برنامه C/C++ قابل کامپایل و همچنین تولید سندی خوش‌قالب باشد که برنامه را با هر میزان جزئیات که نویسنده مایل باشد توصیف کند.
کاربر CWEB باید با TeX و همچنین با C/C++ آشنا باشد.
.SH "نحوه استفاده (USAGE)"
خط فرمان باید شامل یک، دو یا سه نام باشد.
نام نخست به عنوان فایل ورودی CWEB در نظر گرفته می‌شود (و در صورت نداشتن پسوند،
\f[B].w\f[R]
به آن اضافه می‌شود).
اگر نام دومی وجود داشته باشد، یک فایل تغییرات (change file) است (و در صورت نداشتن پسوند،
\f[B].ch\f[R]
به آن افزوده می‌شود).
فایل تغییرات همان‌طور که در مستندات آمده است، بخش‌هایی از فایل CWEB را بازنویسی و جایگزین می‌کند.
اگر نام سومی وجود داشته باشد، نام پیش‌فرض فایل خروجی را بازنویسی می‌کند، که معمولاً همان نام فایل ورودی (اما در دایرکتوری جاری) با پسوند
\f[B].tex\f[R]
است.
اگر فقط می‌خواهید نام فایل خروجی را تغییر دهید اما فایل تغییراتی برای اعمال ندارید، می‌توانید از
`\f[B]\-\f[R]'
به عنوان آرگومان دوم استفاده کنید.
.PP
برنامه
\f[B]ctwill\f[R]
دقیقاً مانند
\f[B]cweave\f[R]
است، با این تفاوت که مستندات بسیار بهتری تولید می‌کند و در ازای آن باید بسیار بیشتر تلاش کنید.
شما باید
\f[B]ctwill\f[R]
را دو بار اجرا کنید؛ یک بار برای راه‌اندازی اولیه و یک بار برای دریافت نتایج مناسب و دقیق.
علاوه بر این، باید خروجی را دو بار از طریق TeX پردازش کنید.
.PP
پس از اجرای
\f[B]tex foo\f[R]
خروجی شما مشابه صفحات نهایی خواهد بود، با این تفاوت که مدخل‌های نمایه‌های کوچک (mini-indexes) به ترتیب الفبایی نخواهند بود.
اجرای اول فایلی عجیب به نام
\f[B]foo.ref\f[R]
تولید می‌کند.
دستور
\f[B]ctwill-refsort < foo.ref > foo.sref\f[R]
را اجرا کنید و سپس اجرای مجدد
\f[B]tex foo\f[R]
خروجی مرتب‌شده بر اساس الفبا تولید خواهد کرد.
.PP
برنامه
\f[B]ctwill-twinx\f[R]
یک نمایه اصلی برای مجموعه‌ای از برنامه‌های مرتبط که توسط
\f[B]ctwill\f[R]
(توجه داشته باشید که
\f[I]نه\f[R]
توسط
\f[B]cweave\f[R]!)
پردازش شده‌اند، گردآوری و کامپایل می‌کند.
برنامه‌های مجزا باید نام خود را با خطی به شکل
\f[B]\(rsdef\(rstitle{NAME}\f[R]
تعریف کنند.
برای راحتی کار،
\f[B]ctwill-twinx\f[R]
نخستین «کلمه» در
\f[B]\(rstitle\f[R]
را گرفته و آن را به حروف بزرگ تبدیل می‌کند.
باید فایل
\f[B]twinx-startup.tex\f[R]
را برای صفحه نخست نمایه اصلی تنظیم و منطبق کنید.
.PP
نمایه‌های کوچک شناسه‌هایی را فهرست می‌کنند که در هر صفحه دوگانه استفاده شده‌اند اما تعریف نشده‌اند.
در پایان هر بخش،
\f[B]ctwill\f[R]
فهرستی از شناسه‌های استفاده‌شده در آن بخش و اطلاعات مربوط به محل تعریف آن‌ها را به TeX ارائه می‌دهد.
.PP
معنای جاری هر شناسه در ابتدا
\f[B]\(rsuninitialized\f[R]
است.
سپس
\f[B]ctwill\f[R]
فایل
\f[B].aux\f[R]
مربوط به کار شما را (در صورت وجود) می‌خواند.
.PP
پیش از خواندن فایل
\f[B].aux\f[R]،
برنامه
\f[B]ctwill\f[R]
در واقع به دنبال فایلی به نام
\f[B]system.bux\f[R]
می‌گردد که در صورت وجود خوانده می‌شود.
و پس از
\f[B]foo.aux\f[R]،
احتمال سوم فایل
\f[B]foo.bux\f[R]
است.
قرارداد عمومی این است که تعاریف توابع و رویه‌های سیستمی مانند
\f[I]printf\f[R]
در
\f[B]system.bux\f[R]
قرار داده شوند، و تعاریف موجود در فایل‌های سربرگ مختص برنامه در
\f[B]foo.bux\f[R]
گذاشته شوند.
مشابه فایل‌های
\f[B].aux\f[R]،
فایل‌های
\f[B].bux\f[R]
نیز باید فقط حاوی مشخصات
\f[B]\(at$\f[R]
باشند.
.PP
معنای مشخص‌شده توسط
\f[B]\(at$\&...\(at>\f[R]
عموماً شامل چهار جزء است: یک شناسه (به همراه فاصله)، نام برنامه (درون آکولاد)، شماره بخش (به همراه فاصله)، و یک بخش TeX.
.PP
یک حالت آزمایشی ویژه به نام
\f[I]proofmode\f[R]
فراهم شده است تا بتوانید نتایج و نتیجه‌گیری‌های
\f[B]ctwill\f[R]
را درباره ارجاعات متقابل بررسی کنید.
برنامه
\f[B]ctwill\f[R]
را با فلگ
\f[B]+P\f[R]
اجرا کنید تا TeX سندی با قالب‌بندی ویژه و حاوی نمایه‌های کوچک برای هر بخش تولید کند، تا بتوانید صحت مشخصات خود را بررسی نمایید.
.PP
این قالب
\f[I]proofmode\f[R]
در ترکیب با
\f[B]pdfctproofmac.tex\f[R]
استفاده می‌شود که هایپرلینک‌های فعال در خروجی‌های PDF و HINT ایجاد می‌کند.
می‌توانید از
\f[B]ctwill-proofsort\f[R]
برای مرتب‌سازی الفبایی مدخل‌های نمایه استفاده کنید؛ فقط کافی است دستور زیر را اجرا کنید:
.PP
( \f[B]ctwill-proofsort\f[R] < \f[I]texfile\f[R].tex ) 1<>
\f[I]texfile\f[R].tex
.PP
پس از اجرای
\f[B]ctwill\f[R]
(دو بار)، اما پیش از اجرای TeX (یک بار).
.PP
جزئیات بیشتر درباره نحوه استفاده از
\f[B]ctwill\f[R]
را می‌توان در بخش‌های نخستین کد منبع آن و به ترتیب در فایل تغییرات
\f[B]cweav-twill.ch\f[R]
قابل اعمال روی منبع
\f[B]cweave.w\f[R]
یافت.
یک مثال کامل با تمامی جزئیات و امکانات در
\f[B]Mini-Indexes for Literate Programs\f[R]،
صفحات ۲۲۵ تا ۲۴۵ از کتاب
\f[B]Digital Typography\f[R]
اثر دانلد کنوت (\f[I]CSLI\f[R]، ۱۹۹۹) شرح داده شده است.
.SH "تفاوت‌ها با CTWILL اصلی (DIFFERENCES TO ORIGINAL CTWILL)"
نسخه کنونی
\f[B]ctwill\f[R]
و ابزارهای کمکی آن تلاش فراوان دارند تا جایگزینی مستقیم و سازگار برای بسته اصلی باشند.
با این حال، چند تفاوت شایان ذکر وجود دارد:
.IP \(bu 2
این نسخه مبتنی بر جدیدترین نسخه CWEB (4.12.2) است.
.IP \(bu 2
در TeX Live به دلایل فنی، پیشوند
\f[B]ctwill\-\f[R]
به برنامه‌های کمکی و پیشوند
\f[B]ct\f[R]
به فایل‌های ماکرو اضافه شده است.
.IP \(bu 2
گزینه‌های
\f[B]\-\-help\f[R]،
\f[B]\-\-quiet\f[R]،
\f[B]\-\-verbose\f[R]،
\f[B]\-\-version\f[R]
و فلگ‌های
\f[B]+c\f[R]،
\f[B]\-i\f[R]،
\f[B]\-o\f[R]
و
\f[B]+lX\f[R]
در CWEBbin و TeX Live جدید هستند.
.IP \(bu 2
گزینه
\f[B]+lX\f[R]
همراه با فایل‌های بسته‌بندی نمونه برای
\f[B]ctwimac.tex\f[R]
و
\f[B]ctproofmac.tex\f[R]
با زیرنویس‌ها و توضیحات ترجمه‌شده برای زبان آلمانی (\f[B]+ld\f[R]) ارائه می‌شود.
.IP \(bu 2
گزینه
\f[B]+lX\f[R]
همچنین با یک فایل گسترش‌یافته
\f[B]pdfctwimac.tex\f[R]
برای تولید خروجی PDF و HINT با پیوندهای فعال (\f[B]+lpdf\f[R]) همراه است.
.IP \(bu 2
جستجوی فایل با متغیر محیطی CWEBINPUTS گسترش یافته است تا مسیرهای متعددِ جداشده با دونقطه (:) را مجاز کند؛ بخش «محیط» را در ادامه ببینید.
.IP \(bu 2
در صورت پیکربندی مناسب، برنامه اصلی
\f[B]ctwill\f[R]
با استفاده از ابزارهای gettext گنو بومی‌سازی (ترجمه) می‌شود.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌ها در خط فرمان می‌توانند با `\f[B]\-\f[R]' غیرفعال شوند (اگر به طور پیش‌فرض فعال باشند) یا با `\f[B]+\f[R]' فعال شوند (اگر به طور پیش‌فرض غیرفعال باشند).
در واقع گزینه‌ها از چپ به راست پردازش می‌شوند، بنابراین ترتیبی مانند
\f[B]\-\-verbose \-h\f[R]
تنها
\f[B]خط بنر\f[R]
(\f[B]+b\f[R])
و
\f[B]گزارش پیشرفت\f[R]
(\f[B]+p\f[R])
را نمایش می‌دهد، اما
\f[B]پیام موفقیت\f[R]
(\f[B]\-h\f[R])
را حذف می‌کند.
.IP \(bu 2
\f[B]+b\f[R]: چاپ خط بنر (اطلاعات برنامه) در ترمینال
.IP \(bu 2
\f[B]+h\f[R]: چاپ پیام موفقیت در پایان کار
.IP \(bu 2
\f[B]+p\f[R]: چاپ پیام‌های گزارش پیشرفت کار
.IP \(bu 2
\f[B]+q\f[R]/\f[B]\-q\f[R]: میان‌بر برای \f[B]\-bhp\f[R]؛ همچنین \f[B]\-\-quiet\f[R]
.IP \(bu 2
\f[B]+v\f[R]/\f[B]\-v\f[R]: میان‌بر برای \f[B]+bhp\f[R]؛ همچنین \f[B]\-\-verbose\f[R] (پیش‌فرض)
.IP \(bu 2
\f[B]+c\f[R]: بررسی خروجی موقت برای تغییرات
.IP \(bu 2
\f[B]\-e\f[R]: عدم قرار دادن کدهای C/C++ درون \f[B]\(rsPB{\&...}\f[R]
.IP \(bu 2
\f[B]\-f\f[R]: عدم اجبار به رفتن به خط جدید پس از هر عبارت C/C++ در خروجی
.IP \(bu 2
\f[B]\-F\f[R]: عدم اجبار به شروع عبارت مرکب (compound statement) در خط جدید
.IP \(bu 2
\f[B]\-i\f[R]: جلوگیری از ایجاد تورفتگی در اعلان پارامترها
.IP \(bu 2
\f[B]\-o\f[R]: جلوگیری از جداسازی اعلان‌ها و عبارات
.IP \(bu 2
\f[B]\-x\f[R]: حذف نمایه‌ها، نام بخش‌ها و فهرست مطالب
.IP \(bu 2
\f[B]+P\f[R]: استفاده از \f[B]\(rsinput ctproofmac.tex\f[R] به جای \f[B]ctwimac.tex\f[R]
.IP \(bu 2
\f[B]+lX\f[R]/\f[B]\-lX\f[R]: استفاده از ماکروها برای زبان \f[I]X\f[R] از \f[I]X\f[R]{\f[B]ctwimac\f[R]|\f[B]ctproofmac\f[R]}\f[B].tex\f[R]
.IP \(bu 2
\f[B]+s\f[R]: چاپ آمار میزان مصرف و استفاده
.IP \(bu 2
\f[B]+t\f[R]: رفتار با \f[B]typename\f[R] در قالب‌ها (templates) مشابه \f[B]typedef\f[R]
.IP \(bu 2
\f[B]\-\-help\f[R]: نمایش پیام راهنما و خروج
.IP \(bu 2
\f[B]\-\-version\f[R]: نمایش اطلاعات نسخه و خروج
.SH "محیط (ENVIRONMENT)"
متغیر محیطی CWEBINPUTS برای جستجوی فایل‌های ورودی استفاده می‌شود، یا در صورت تنظیم نبودن آن، از پیش‌فرض سیستم استفاده می‌گردد.
برای جزئیات نحوه جستجو به tex(1) مراجعه کنید.
برای جلوگیری از تداخل با برنامه‌های دیگری که از متغیر CWEBINPUTS استفاده می‌کنند، می‌توانید دقیق‌تر باشید و از متغیر CWEBINPUTS_cweb برای نیازمندی‌های ویژه CWEB استفاده نمایید.
.PP
در صورت آماده‌سازی برای پشتیبانی از NLS، برنامه
\f[B]ctwill\f[R]
مانند
\f[B]ctangle\f[R]
و
\f[B]cweave\f[R]
از متغیر محیطی TEXMFLOCALEDIR برای پیکربندی دایرکتوری والد که ابزارهای gettext گنو در آن کاتالوگ‌های ترجمه را جستجو می‌کنند، استفاده می‌کند.
.PP
این متغیرها از پیش در
\f[B]texmf.cnf\f[R]
مربوط به TeX Live پیکربندی شده‌اند.
.SH "فایل‌ها (FILES)"
محل قرارگیری فایل‌های ذکرشده در زیر در سیستم‌های مختلف متفاوت است.
از ابزار کمکی
\f[B]kpsewhich\f[R]
برای یافتن مکان آن‌ها استفاده کنید.
.IP \(bu 2
\f[B]ctwimac.tex\f[R]: ماکروهای پیش‌فرض TeX که با دستور \f[B]\(rsinput\f[R] در سطر نخست فایل خروجی درج می‌شوند.
.IP \(bu 2
\f[B]ctproofmac.tex\f[R]: اگر \f[B]ctwill\f[R] با گزینه \f[B]+P\f[R] اجرا شود، سطر نخست فایل خروجی را به \f[B]\(rsinput ctproofmac.tex\f[R] تغییر می‌دهد.
.PP
در هر دو حالت می‌توانید پیشوند
\f[I]X\f[R]
را با گزینه
\f[B]+lX\f[R]
درخواست کنید؛ به عنوان مثال،
\f[B]+ld\f[R]
دستور
\f[B]\(rsinput dctwimac.tex\f[R]
و
\f[B]+Pld\f[R]
دستور
\f[B]\(rsinput dctproofmac.tex\f[R]
را درج خواهد کرد.
یک کاربرد ویژه، استفاده از گزینه
\f[B]+lpdf\f[R]
است که دستور
\f[B]\(rsinput pdfctwimac.tex\f[R]
یا
\f[B]\(rsinput pdfctproofmac.tex\f[R]
را برای تولید خروجی PDF و HINT با هایپرلینک‌های فعال درج می‌کند.
.IP \(bu 2
\f[I]webfile\f[R]\f[B].bux\f[R]: تعاریف مراجع برای تفکیک و حل‌وفصل از سایر ماژول‌ها.
.IP \(bu 2
\f[B]system.bux\f[R]: تعاریف مراجع برای تفکیک از فایل‌های سربرگ کتابخانه استاندارد C/C++ مانند \f[B]<stdio.h>\f[R].
.PP
سایر فایل‌های کمکی (\f[B]aux\f[R]iliary) حاوی مراجع به طور خودکار توسط
\f[B]ctwill\f[R]
ساخته می‌شوند و فایل‌های نمایه واقعی توسط TeX ایجاد می‌گردند.
.IP \(bu 2
\f[B]cwebman.tex\f[R]: راهنمای کاربری CWEB، موجود به صورت PDF از \c
.UR https://ctan.org/pkg/cweb
CTAN
.UE \c
\&.
.SH "همچنین ببینید (SEE ALSO)"
.IP \(bu 2
The CWEB System of Structured Documentation: نوشته Donald E.\ Knuth و Silvio Levy (نسخه چاپی \f[B]cwebman.tex\f[R] و فهرست‌های کد منبع \f[B]common.w\f[R]، \f[B]ctangle.w\f[R] و \f[B]cweave.w\f[R]).
.IP \(bu 2
کد منبع برنامه CTWILL، بخش ۲۸۷:
.RS 2
.PP
https://mirror.ctan.org/info/knuth-pdf/cweb/ctwill.pdf
.RE
.IP \(bu 2
Digital Typography: نوشته D.\ E.\ Knuth (\f[I]CSLI\f[R]، ۱۹۹۹).
.IP \(bu 2
Literate Programming: نوشته D.\ E.\ Knuth (\f[I]CSLI\f[R]، ۱۹۹۲).
.IP \(bu 2
Weaving a Program: نوشته Wayne Sewell.
.PP
cweb(1), tex(1), cc(1)
.SH "نویسندگان (AUTHORS)"
دان کنوت (Don Knuth) برنامه \f[B]ctwill\f[R] را بر پایه \f[B]cweave\f[R] اثر Silvio Levy و کنوت نوشت.
.PD 0
.P
.PD
توسعه معاصر در https://github.com/ascherer/cwebbin انجام می‌شود.