| RUBBER(1) | General Commands Manual | RUBBER(1) |
نام (NAME)
rubber - یک سامانه ساخت برای اسناد LaTeX
خلاصه دستور (SYNOPSIS)
rubber
[گزینهها]
sources ...
rubber-pipe
[گزینهها]
توضیحات (DESCRIPTION)
برنامهٔ Rubber یک پوشش (wrapper) برای LaTeX و برنامههای جانبی آن است. هدف آن، پردازش یک منبع LaTeX و کامپایل کردن آن به تعداد دفعات کافی برای حل تمام ارجاعات است، که احتمالاً شامل اجرای برنامههای اقماری مانند BibTeX، makeindex، Metapost و غیره برای تولید فایلهای دادهٔ مناسب نیز میشود.
دستور rubber اسناد مشخصشده را به طور کامل میسازد. فایلهای منبع میتوانند منابع LaTeX باشند (که در این صورت پسوند .tex میتواند حذف شود) یا اسنادی با قالبی باشند که Rubber نحوهٔ تبدیل آن به LaTeX را میداند. اگر یکی از کامپایلها با شکست مواجه شود، کل فرایند متوقف میشود، از جمله کامپایل اسناد بعدی موجود در خط فرمان، و rubber یک کد خروج غیرصفر برمیگرداند.
دستور rubber-pipe همین کار را برای یک سند انجام میدهد، اما منبع LaTeX را از ورودی استاندارد میخواند و سند کامپایلشده را در خروجی استاندارد میریزد.
برخی از اطلاعات را نمیتوان از منابع LaTeX استخراج کرد. به عنوان مثال، مسیرهای جستوجو (که میتوانند در متغیرهای محیطی مانند TEXINPUTS مشخص شوند)، یا شیوهنامهای که باید با Makeindex استفاده شود، از این جملهاند. برای رفع این مشکل، میتوان اطلاعات مورد نظر Rubber را در توضیحات (کامنتهای) منابع LaTeX قرار داد؛ به بخش DIRECTIVES مراجعه کنید.
گزینهها (OPTIONS)
گزینهها برای انتخاب عملیاتی که باید انجام شود یا برای پیکربندی فرایند ساخت به کار میروند. این گزینهها عمدتاً در rubber و rubber-pipe مشابه هستند. گزینهها با استفاده از قراردادهای GNU Getopt تجزیه میشوند.
- -b, --bzip2
- سند نهایی را فشرده میکند (در قالب bzip2). این گزینه معادل قید کردن -o bzip2 پس از تمام گزینههای دیگر است.
- --clean
- به جای ساخت سند، تمام فایلهای تولیدشده توسط کامپایل را حذف میکند. این گزینه فقط در rubber وجود دارد. این کار بر اساس کامپایلی اعمال میشود که با گزینههای خط فرمان مشخص شده است؛ یعنی اجرای "rubber --clean foo" فایل foo.ps را حذف نخواهد کرد، در حالی که اجرای "rubber --ps --clean foo" آن را حذف میکند.
- -c, --command <command>
- دستور (یا رهنمود) مشخصشده را پیش از تجزیهٔ فایلهای ورودی اجرا میکند. برای جزئیات بیشتر به بخش DIRECTIVES مراجعه کنید.
- -e, --epilogue <command>
- دستور (یا رهنمود) مشخصشده را پس از تجزیهٔ فایلهای ورودی اجرا میکند. برای جزئیات بیشتر به بخش DIRECTIVES مراجعه کنید.
- -f, --force
- اجرای حداقل یک بار کامپایل منبع را اجباری میکند. این گزینه زمانی مفید است که برای نمونه، وابستگی نامعمولی تغییر کرده باشد (مانند بستهای در یک دایرکتوری سیستمی). این گزینه در rubber-pipe کاربردی ندارد.
- -z, --gzip
- سند نهایی را فشرده میکند (در قالب gzip). این معادل قید کردن -o gz پس از تمام گزینههای دیگر است.
- -h, --help
- فهرست تمام گزینههای موجود را نمایش داده و خارج میشود.
- --inplace
- پیش از کامپایل به دایرکتوری فایلهای منبع میرود، تا نتایج کامپایل در همان محل منابع قرار گیرند.
- --into <directory>
- پیش از کامپایل به دایرکتوری مشخصشده میرود، تا تمام فایلها در آنجا تولید شوند و نه در دایرکتوری جاری.
- --jobname <name>
- نام کاری (job name) متفاوتی نسبت به نام پایهٔ فایل تعیین میکند. این گزینه نام فایلهای خروجی را تغییر میدهد و تنها بر روی اولین هدف اعمال میشود.
- -k, --keep
- این گزینه تنها در rubber-pipe استفاده میشود. با این گزینه، فایلهای موقت پس از کامپایل سند و ریختن نتایج در خروجی استاندارد حذف نخواهند شد. سند موقت rubtmpX.tex نامگذاری میشود، که در آن X عددی است به گونهای که در ابتدا هیچ فایلی با این نام وجود نداشته باشد.
- -n, --maxerr <num>
- حداکثر تعداد خطاهای نمایشی را تعیین میکند. به طور پیشفرض، تا ۱۰ خطا گزارش میشود؛ تعیین -n -1 تمام خطاها را نمایش میدهد.
- -m, --module <module>[:<args>]
- علاوه بر بستههای سند، از ماژول مشخصشده استفاده میکند. میتوان آرگومانها را با افزودن پس از دونقطه (:) به بسته فرستاد؛ این مقادیر با گزینههای بسته در LaTeX مطابقت دارند. ماژول پیش از تجزیهٔ منابع سند بارگذاری میشود.
- --only <sources>
- سند را به صورت جزئی کامپایل میکند، بهطوریکه تنها منابع مشخصشده لحاظ میشوند. این کار با درج فراخوانی \includeonly در خط فرمان عمل میکند. آرگومان ورودی فهرستی از نامهای فایل است که با کاما از هم جدا شدهاند.
- -o, --post <module>[:<args>]
- از ماژول مشخصشده به عنوان پسپردازشگر (post-processor) استفاده میکند. این مورد مشابه گزینهٔ -m است با این تفاوت که ماژول پس از تجزیهٔ سند بارگذاری میشود.
- -d, --pdf
- خروجی PDF تولید میکند. هنگامی که این گزینه پس از --ps بیاید (مثلاً به شکل -pd)، مترادفی برای -o ps2pdf است، در غیر این صورت مانند -m pdftex عمل میکند تا از pdfLaTeX به جای LaTeX استفاده شود.
- -p, --ps
- فایل DVI تولیدشده توسط فرایند را از طریق dvips(1) پردازش میکند تا یک سند PostScript تولید شود. این گزینه مترادفی برای -o dvips است و نمیتواند پس از --pdf بیاید.
- -q, --quiet
- میزان پرگویی (verbosity) را کاهش میدهد. این گزینه معکوس -v است.
- -r, --read <file>
- رهنمودهای اضافی را از فایل مشخصشده میخواند (همچنین به رهنمود "read" مراجعه کنید).
- -S, --src-specials
- در صورت پشتیبانی کامپایلر، تولید source specials را فعال میکند. این معادل تنظیم متغیر src-specials روی yes است.
- -s, --short
- پیامهای خطای LaTeX را به شکل فشرده نمایش میدهد (یک خطا در هر خط).
- -I, --texpath <directory>
- دایرکتوری مشخصشده را به مسیر جستوجوی TeX اضافه میکند.
- --synctex
- پشتیبانی از SyncTeX را در اجرای LaTeX فعال میکند.
- --unsafe
- به سند اجازه میدهد برنامههای خارجی دلخواه را فراخوانی کند. این کار بالقوه خطرناک است؛ تنها برای اسنادی که از یک منبع قابل اعتماد میآیند از این گزینه استفاده کنید..TP -v, --verbose افزایش سطح پرگویی (verbosity). سطوح بین 0 و 4 وجود دارند؛ سطح پیشفرض برای rubber برابر 1 و برای rubber-pipe برابر 0 است. توجه داشته باشید که استفاده از -vvv باعث خروجی بسیار مفصل Rubber میشود.
- --version
- چاپ شماره نسخه و خروج موفقیتآمیز.
- -W, --warn <type>
- گزارش اطلاعات مربوط به نوع مشخصشده در صورتی که در حین کامپایل خطایی رخ نداده باشد. انواع موجود عبارتند از: boxes (جعبههای overfull و underfull)، refs (ارجاعات تعریفنشده یا چندبار تعریفشده)، misc (سایر هشدارها) و all برای گزارش تمام هشدارها.
پیمانهها (MODULES)
عملکرد Rubber تحت تأثیر پیمانهها قرار دارد. پیمانهها به ویژگیهای خاص بستهها و برنامههای خارجی رسیدگی میکنند.
بستهها (Packages)
به ازای هر بستهای که یک سند استفاده میکند، Rubber به دنبال پیمانهای با همان نام میگردد تا کارهایی را که ممکن است این بسته جدا از کامپایل توسط LaTeX نیاز داشته باشد، انجام دهد. میتوان پیمانههایی را به موارد ارائهشده بهطور پیشفرض افزود تا قابلیتهای جدید اضافه شوند (هدف سامانه پیمانهای نیز همین است). پیمانههای استاندارد عبارتند از:
- asymptote
- پردازش فایلهای .asy تولیدشده توسط بسته LaTeX، و سپس اجرای کامپایل مجدد.
- beamer
- این پیمانه با فایلهای اضافی Beamer همانند سایر فهرستهای مطالب رفتار میکند.
- bibtex, biblatex
- رسیدگی به پردازش کتابشناسی سند با BibTeX در صورت نیاز. این پیمانه در صورتی که سند شامل ماکروی \bibliography باشد بهطور خودکار بارگذاری میشود (همچنین برای گزینهها به DIRECTIVES مراجعه کنید).
- combine
- بسته combine برای گردآوری چندین سند LaTeX در یک سند واحد استفاده میشود، و این پیمانه وابستگیها را در این حالت مدیریت میکند.
- epsfig
- این پیمانه درج تصاویر را برای اسنادی که از ماکروی سبک قدیمی \psfig استفاده میکنند مدیریت میکند. این پیمانه در واقع یک رابط برای پیمانه graphics است؛ برای جزئیات به آن مراجعه کنید.
- glossaries
- اجرای makeglossaries و کامپایل مجدد هنگام تغییر فایل .glo.
- graphics, graphicx
- این پیمانهها تصاویر گنجاندهشده در سند را شناسایی کرده و آنها را به عنوان وابستگیهای کامپایل در نظر میگیرند. آنها همچنین از قوانین استاندارد برای ساخت این فایلها با برنامههای خارجی استفاده میکنند. برای جزئیات به مستندات info مراجعه کنید.
- hyperref
- مدیریت فایلهای اضافی که این بسته در برخی موارد تولید میکند.
- index, makeidx, nomencl
- پردازش نمایهها و فهرست واژگان سند با makeindex(1) در صورت نیاز (برای گزینهها به بخش DIRECTIVES مراجعه کنید).
- ltxtable
- افزودن وابستگیها برای فایلهای واردشده از طریق بسته LaTeX به نام ltxtable.
- minitoc, minitoc-hyper
- در هنگام پاکسازی، حذف فایلهای اضافی که برای ساخت فهرستهای مطالب جزئی تولید شدهاند.
- moreverb, verbatim
- افزودن فایلهای واردشده با \verbatiminput و ماکروهای مشابه به فهرست وابستگیها.
- multibib
- مدیریت کتابشناسیهای اضافی که این بسته ایجاد میکند، و حذف فایلهای اضافی در هنگام پاکسازی.
- xr
- افزودن فایلهای .aux اضافی استفادهشده برای ارجاعات خارجی به فهرست وابستگیها، تا کامپایل مجدد هنگام تغییر اسناد ارجاعشده بهصورت خودکار انجام شود.
پیشپردازش (Pre-processing)
پیمانههای زیر برای استفاده از برنامههایی ارائه شدهاند که یک منبع LaTeX را از قالب فایلی متفاوت تولید میکنند:
- cweb
- هدف این پیمانه، اجرای cweave(1) در صورت نیاز قبل از فرآیند کامپایل به منظور تولید منبع LaTeX است. این پیمانه در صورتی که فایل مشخصشده در خط فرمان پسوند .w داشته باشد، بهصورت خودکار بارگذاری میشود.
- lhs2TeX
- این پیمانه از پیشپردازنده lhs2TeX برای تولید منبع LaTeX از یک برنامه Literate Haskell استفاده میکند. در صورتی که نام فایل ورودی به .lhs ختم شود، بهصورت خودکار فعال میشود.
ماژولهای زیر برای پشتیبانی از انواع مختلف پسپردازش ارائه شدهاند. توجه داشته باشید که هنگام استفاده از این ماژولها ترتیب اهمیت دارد: اگر میخواهید از یک زنجیره پردازش مانند زیر استفاده کنید:
- bzip2
- نسخهای از فایل نهایی فشردهشده با bzip2(1) را تولید میکند.
- dvipdfm
- در پایان کامپایل، dvipdfm(1) را برای تولید یک سند PDF اجرا میکند.
- dvips
- در پایان کامپایل، dvips(1) را برای تولید یک سند PostScript اجرا میکند. این ماژول همچنین با گزینه خط فرمان --ps بارگذاری میشود.
- expand
- با جایگزینی ماکروهای \input با فایلهای ضمیمهشده، ماکروهای کتابشناسی با کتابشناسی تولیدشده توسط bibtex(1)، و کلاسها و بستههای محلی با سورس آنها، یک سورس گسترشیافته LaTeX تولید میکند. اگر فایل اصلی foo.tex باشد، فایل گسترشیافته foo-final.tex نامیده خواهد شد. برای جزئیات به مستندات info مراجعه کنید.
- gz
- نسخهای از فایل نهایی فشردهشده با gzip(1) را تولید میکند.
- ps2pdf
- با این فرض که کامپایل یک سند PostScript تولید میکند (برای نمونه با استفاده از ماژول dvips)، این سند را با استفاده از ps2pdf(1) به PDF تبدیل میکند.
انتخاب کامپایلر (Compiler choice)
ماژولهای زیر برای تغییر کامپایلر LaTeX استفاده میشوند:
- aleph
- استفاده از کامپایلر Aleph به جای TeX، یعنی کامپایل سند با استفاده از lamed(1) به جای latex.
- omega
- استفاده از کامپایلر Omega به جای TeX، یعنی کامپایل سند با استفاده از lambda(1) به جای latex. اگر ماژول dvips نیز استفاده شود، از odvips(1) برای تبدیل فایل DVI استفاده خواهد کرد. توجه داشته باشید که این ماژول هنگامی که سند از بسته omega استفاده کند، بهطور خودکار فراخوانی میشود.
- pdftex
- به Rubber دستور میدهد که برای کامپایل سند به جای latex(1) از pdflatex(1) استفاده کند. بهطور پیشفرض، این کار به جای DVI یک فایل PDF تولید میکند، اما هنگام بارگذاری ماژول با گزینه dvi (برای نمونه با ذکر -m pdftex:dvi) سند با استفاده از pdflatex به DVI کامپایل میشود. این ماژول همچنین با گزینه خط فرمان --pdf بارگذاری میشود.
- vtex
- به Rubber دستور میدهد از کامپایلر VTeX استفاده کند. بهطور پیشفرض این ماژول از vlatex به عنوان کامپایلر برای تولید خروجی PDF استفاده میکند. با گزینه ps (برای نمونه با ذکر “rubber -m vtex:ps foo.tex”) کامپایلر مورد استفاده vlatexp بوده و نتیجه یک فایل PostScript خواهد بود.
- xelatex
- به Rubber دستور میدهد که به جای latex از xelatex(1) استفاده کند.
دستورالعملها (DIRECTIVES)
رفتار خودکار Rubber بر پایه جستجوی ماکروها در سورسهای LaTeX است. هنگامی که این کافی نباشد، میتوان دستورالعملهایی را در کامنتهای سورس اضافه کرد. یک دستورالعمل خطی مانند زیر است:
- alias <name1> <name2>
- چنین فرض میکند که ماکروی LaTeX به نام name1 معادل name2 است. این کار هنگام تعریف پوششها (wrappers) پیرامون ماکروهای پشتیبانیشده میتواند مفید باشد.
- clean <file>
- مشخص میکند که فایل تعیینشده باید هنگام پاکسازی با استفاده از --clean حذف شود.
- depend <file>
- فایل مشخصشده را به عنوان یک وابستگی در نظر میگیرد تا زمان آخرین تغییرات آن بررسی شود.
- make <file> [<options>]
- اعلام میکند که فایل مشخصشده باید تولید شود. گزینهها میتوانند نحوهٔ تولید آن را مشخص کنند؛ گزینههای موجود عبارتند از from <file> برای تعیین منبع و with <rule> برای تعیین قاعدهٔ تبدیل. برای مثال، عبارت «make foo.pdf from foo.eps» نشان میدهد که foo.pdf باید از foo.eps، با هر قاعدهٔ تبدیلی که قادر به انجام آن باشد تولید شود. برای جزئیات دربارهٔ تبدیل فایل، مستندات info را ببینید.
- module <module> [<options>]
- ماژول مشخصشده را احتمالاً به همراه گزینهها بارگذاری میکند. این معادل گزینهٔ خط فرمان --module است.
- onchange <file> <command>
- اگر محتویات فایل مشخصشده پس از کامپایل تغییر کرده باشد، دستور پوستهٔ تعیینشده را اجرا میکند. نام فایل با اولین فاصله خاتمه مییابد.
- path <directory>
- دایرکتوری مشخصشده را به مسیر جستجوی TeX (و Rubber) اضافه میکند. نام دایرکتوری، تمام چیزی است که پس از فاصلههای بعد از «path» میآید.
- produce <file>
- اعلام میکند که اجرای LaTeX، فایل(های) مشخصشده را ایجاد یا بهروزرسانی خواهد کرد.
- read <file>
- فایل مشخصشدهٔ حاوی دستورالعملها را میخواند. فایل باید در هر خط شامل یک دستورالعمل باشد. خطوط خالی و خطوطی که با «%» شروع میشوند نادیده گرفته میشوند.
- rules <file>
- قواعد تبدیل اضافی را از فایل مشخصشده میخواند. قالب این فایل مشابه قالب rules.ini است؛ برای جزئیات مستندات info را ببینید.
- set <name> <value>
- مقدار یک متغیر را به صورت یک رشته تنظیم میکند. برای جزئیات دربارهٔ متغیرهای موجود و معانی آنها، مستندات info را ببینید.
- setlist <name> <values>
- مقدار یک متغیر را به صورت فهرستی از رشتهها (که با فاصله از هم جدا شدهاند) تنظیم میکند. برای جزئیات دربارهٔ متغیرهای موجود و معانی آنها، مستندات info را ببینید.
- shell_escape
- سند را به عنوان سندی که به برنامههای خارجی (shell-escape یا write18) نیاز دارد مشخص میکند. Rubber در عمل این مورد را فعال نمیکند مگر اینکه با گزینهٔ --unsafe فراخوانی شود.
- synctex
- پشتیبانی از SyncTeX را در اجرای LaTeX فعال میکند.
- watch <file>
- فایل مشخصشده را برای تغییرات زیر نظر میگیرد. اگر محتویات این فایل پس از یک کامپایل تغییر کرده باشد، کامپایل دیگری راهاندازی میشود. این مورد برای مثال در رابطه با فهرست مطالب مفید است.
دستورالعملهای مختص ماژول (Module-specific directives)
اگر دستوری به فرم foo.bar باشد، به عنوان دستور bar برای ماژول foo در نظر گرفته میشود. اگر این ماژول هنگام یافتن دستورالعمل ثبت نشده باشد، دستور بدون هشدار یا اعلان نادیده گرفته میشود. برای ماژولهای استاندارد، دستورالعملها به شرح زیر هستند:
- biblatex.path <directory>
- دایرکتوری مشخصشده را به مسیر جستجو برای پایگاههای دادهٔ BibTeX (فایلهای .bib) اضافه میکند.
- bibtex.crossrefs <number>
- حداقل تعداد crossref لازم برای گنجاندن خودکار مدخل ارجاعشده در فهرست مراجع را تعیین میکند. این دستورالعمل، گزینهٔ -min-crossrefs را هنگام فراخوانی bibtex(1) تنظیم میکند.
- bibtex.path <directory>
- دایرکتوری مشخصشده را به مسیر جستجو برای پایگاههای دادهٔ BibTeX (فایلهای .bib) اضافه میکند.
- bibtex.stylepath <directory>
- دایرکتوری مشخصشده را به مسیر جستجو برای شیوهنامههای BibTeX (فایلهای .bst) اضافه میکند.
- bibtex.tool <command>
- استفاده از یک ابزار کتابشناسی دیگر به جای BibTeX.
- dvipdfm.options <options>
- سوئیچهای خط فرمان مشخصشده را به dvipdfm ارسال میکند.
- dvips.options <options>
- سوئیچهای خط فرمان مشخصشده را به dvips ارسال میکند.
- index.tool (index) <name>
- مشخص میکند که چه ابزاری برای پردازش نمایه باید استفاده شود. ابزارهای پشتیبانیشدهٔ کنونی عبارتند از makeindex(1) (انتخاب پیشفرض) و xindy(1). آرگومان index اختیاری است؛ میتوان از آن برای تعیین فهرستی از نمایهها که دستور بر آنها اعمال میشود استفاده کرد. در صورت وجود، باید درون پرانتز قرار گیرد؛ فهرست با کاما جدا میشود. هنگامی که این آرگومان ارائه نشود، دستور بر تمام نمایهها اعمال میگردد.
- index.language (index) <language>
- زبان مورد استفاده برای مرتبسازی نمایه را انتخاب میکند. این دستورالعمل تنها زمانی اعمال میشود که از xindy(1) به عنوان ابزار نمایهسازی استفاده شود. آرگومان اختیاری دارای همان معنا و مفهوم ذکرشده در بالاست.
- index.modules (index) <module>...
- مشخص میکند هنگام پردازش نمایه با xindy(1) از کدام ماژولها استفاده شود. آرگومان اختیاری دارای همان معنا و مفهوم ذکرشده در بالاست.
- index.order (index) <options>
- گزینههای مرتبسازی نمایهها را تغییر میدهد. آرگومانها کلماتی (جداشده با فاصله) از میان standard، german و letter هستند. این مورد تنها هنگام استفاده از makeindex(1) اعمال میشود. آرگومان اختیاری دارای همان معنا و مفهوم ذکرشده در بالاست.
- index.path (index) <directory>
- دایرکتوری مشخصشده را به مسیر جستجو برای شیوهنامههای نمایه (فایلهای .ist) اضافه میکند. آرگومان اختیاری دارای همان معنا و مفهوم ذکرشده در بالاست.
- index.style (index) <style>
- شیوهنامهٔ نمایهٔ مورد استفاده را تعیین میکند. آرگومان اختیاری دارای همان معنا و مفهوم ذکرشده در بالاست.
- makeidx.language, .modules, .order, .path, .style, .tool
- این دستورالعملها مشابه دستورالعملهای ماژول index هستند، با این تفاوت که آرگومان اختیاری را نمیپذیرند.
- multibib.crossrefs, .path, .stylepath, .tool
- این دستورالعملها همانند دستورالعملهای ماژول bibtex هستند، اما بر کتابشناسیهای مدیریتشده توسط بستهٔ multibib اعمال میشوند. آنها یک آرگومان اختیاری نخست با همان قواعد دستورالعملهای ماژول index میگیرند، که میتواند برای مشخص کردن فهرست کتابشناسیهایی که دستور بر آنها اعمال میشود به کار رود.
قطعاً مواردی وجود دارد...
این صفحه Rubber نسخه 1.6.7 را مستند میکند. این برنامه و این صفحه راهنما توسط Florian Schmaus <flo@geekplace.eu> نگهداری میشوند. صفحه اصلی Rubber در https://gitlab.com/latex-rubber/rubber در دسترس است.
همچنین ببینید (SEE ALSO)
مستندات کامل برای rubber بهعنوان یک راهنمای Texinfo نگهداری میشود. اگر برنامههای info و rubber بهدرستی روی سیستم شما نصب شده باشند، دستور
- info rubber
باید دسترسی به راهنمای کامل را برای شما فراهم کند.