نام (NAME)

bundledoc - بسته‌بندی تمام فایل‌های مورد نیاز یک سند LaTeX

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

bundledoc [--version] [--help] [--[no]verbose] [--texfile=file.tex] [--directory=directory] [--[no]localonly] [--exclude=string] [--include=filespec] [--manifest=file] [--listdeps=[yes|no|only|rel]...] [--[no]keepdirs] [--config=file.cfg] file.dep.SH "توضیحات (DESCRIPTION)" bundledoc یک پس‌پردازشگر برای بستهٔ snapshot است که تمام کلاس‌ها، بسته‌ها و فایل‌های مورد نیاز برای ساخت یک سند LaTeX مشخص را گرد هم می‌آورد و بسته‌بندی می‌کند. این ابزار فایل .dep را که snapshot تولید می‌کند می‌خواند، هر یک از فایل‌های ذکرشده در آن را می‌یابد و آن‌ها را در یک فایل آرشیو واحد (مثلاً یک فایل .tar.gz) بسته‌بندی می‌کند که برای انتقال میان سیستم‌ها، ارسال به یک همکار و غیره مناسب است.

به‌عنوان ساده‌ترین مثال ممکن، یک فایل LaTeX را، مثلاً به نام hello.tex، در نظر بگیرید:

\RequirePackage{snapshot}       % Needed by bundledoc
\documentclass[11pt]{article}
\begin{document}
Hello, world!
\end{document}

دستور "\RequirePackage{snapshot}" باعث تولید یک فایل hello.dep می‌شود. هنگامی که سپس "hello.dep" به‌عنوان آرگومان به bundledoc داده شود، این ابزار فایل‌های وابسته -- snapshot.sty، article.cls، و size11.clo -- را پیدا کرده و آن‌ها را همراه با hello.tex و یک فایل MANIFEST (که در بخش «گزینه‌ها (OPTIONS)» در ادامه شرح داده شده) در یک فایل آرشیو واحد بسته‌بندی می‌کند.

گزینه‌ها (OPTIONS)

در توضیحات زیر، somefile به نام سند اصلی LaTeX شما (بدون پسوند) اشاره دارد.

bundledoc به نام فایل وابستگی تولید شده توسط snapshot نیاز دارد (که معمولاً somefile.dep است). (برای راحتی، می‌توان این فایل را بدون پسوند .dep آن نیز مشخص کرد.) گزینه‌های زیر را نیز می‌توان تعیین کرد:

--version: شماره نسخهٔ اسکریپت bundledoc را در خروجی نمایش می‌دهد. این گزینه بر تمام گزینه‌های دیگر اولویت دارد (آن‌ها را نادیده می‌گیرد).
--help: پیام کوتاهی دربارهٔ نحوهٔ استفاده ارائه می‌دهد. این گزینه بر تمام گزینه‌های دیگر اولویت دارد.
--[no]verbose (پیش‌فرض: "noverbose"): bundledoc در حالت عادی به‌جز پیام‌های خطا هیچ خروجی دیگری تولید نمی‌کند. با گزینهٔ "--verbose"، پیام‌های وضعیت متعددی را در خروجی نمایش می‌دهد.
--texfile=main .tex file (پیش‌فرض: somefile.tex): فایل وابستگیِ snapshot، فایل اصلی LaTeX (فایلی که به latex ارسال می‌شود) را فهرست نمی‌کند. برای اینکه bundledoc بتواند آن فایل را بیابد و بسته‌بندی کند، فرض می‌کند که آن فایل همنام با فایل وابستگی snapshot ولی با پسوند .tex است. اگر چنین نیست، از "--texfile" برای مشخص کردن نام فایل صحیح استفاده کنید.
--directory=archive directory (پیش‌فرض: somefile): هنگامی که bundledoc آرشیوی (مانند یک فایل .tar یا .zip) حاوی فایل‌های سند ایجاد می‌کند، همهٔ آن‌ها را در یک دایرکتوری قرار می‌دهد تا از شلوغ شدن دایرکتوری جاری با فایل‌ها جلوگیری کند. اگر فایل وابستگی داده‌شده somefile.dep باشد، آرشیو حاصل به‌طور پیش‌فرض همهٔ فایل‌های وابسته را در دایرکتوری somefile ذخیره می‌کند. برای تغییر نام دایرکتوری، از گزینهٔ "--directory" استفاده کنید.
--[no]localonly (پیش‌فرض: "nolocalonly"): اگرچه bundledoc در حالت عادی تمام فایل‌های نام‌برده در فایل .dep را آرشیو می‌کند، گزینهٔ "--localonly" به bundledoc دستور می‌دهد تا تمام فایل‌هایی را که در دایرکتوری‌هایی به‌جز دایرکتوری فایل .tex یا یکی از زیردایرکتوری‌های آن قرار دارند، حذف (مستثنی) کند.
--exclude=string (پیش‌فرض: none): در حالی که "--localonly" باعث می‌شود فایل‌های خارج از درخت دایرکتوریِ فایل .tex از آرشیو حذف شوند، "--exclude" کنترل دقیق‌تری روی فایل‌های حذفی فراهم می‌کند. گزینهٔ "--exclude" که می‌تواند به‌طور مکرر در خط فرمان مشخص شود، باعث حذف تمام فایل‌هایی از آرشیو می‌شود که نامشان شامل string است.
--include=filespec (پیش‌فرض: none): گزینهٔ "--include" که می‌تواند به‌طور مکرر در خط فرمان مشخص شود، به bundledoc دستور می‌دهد که تمام فایل‌های منطبق با filespec را در آرشیو بگنجاند، حتی اگر در فایل .dep به آن‌ها ارجاعی داده نشده باشد.
--manifest=manifest file (پیش‌فرض: MANIFEST): علاوه بر فایل‌های وابسته، bundledoc یک فایل اضافی را که به‌طور پیش‌فرض «MANIFEST» نام دارد در فایل آرشیو قرار می‌دهد. MANIFEST یک فایل متنی است که نام فایل‌های اصلی همهٔ وابستگی‌ها را فهرست می‌کند. برای تغییر نام فایل از «MANIFEST» به چیزی دیگر، از گزینهٔ "--manifest" استفاده کنید. به‌عنوان یک حالت خاص، "--manifest=""" به bundledoc می‌گوید که اصلاً هیچ فایل مانیفستی را در آرشیو نگنجاند.
--listdeps=[yes|no|only|rel]...] (پیش‌فرض: "no"): "--listdeps" یک یا چند مورد از مقادیر "yes"، "no"، "only" یا "rel" را به‌صورت فهرستی جداشده با کاما می‌پذیرد. تا زمانی که "no" در این فهرست نباشد، bundledoc تمام وابستگی‌های فایل اصلی LaTeX را در خروجی می‌آورد. اگر فهرست حاوی "rel" باشد، آن‌گاه bundledoc فهرست وابستگی‌ها را با نام مسیرهای نسبی خروجی می‌دهد. اگر فهرست حاوی "only" باشد، آن‌گاه bundledoc پس از نمایش فهرست، بدون تولید هیچ آرشیوی خارج می‌شود.
--[no]keepdirs (پیش‌فرض: "nokeepdirs"): به‌طور معمول، فایل آرشیوی که bundledoc ایجاد می‌کند حاوی یک دایرکتوری واحد است -- و زیردایرکتوری‌هایی، در صورتی که سند صریحاً به آن‌ها ارجاع داده باشد -- که تمام فایل‌های وابسته در آن قرار می‌گیرند. اگر "--keepdirs" مشخص شود، همهٔ فایل‌های وابسته با نام مسیرهای اصلی خود ذخیره می‌شوند. برای مثال، اگر somefile.tex به figures/somefigure.eps، article.cls و snapshot.sty وابسته باشد، آرشیو somefile به‌طور معمول شامل فایل‌های زیر خواهد بود:

somefile/somefile.tex
somefile/figures/somefigure.eps
somefile/article.cls
somefile/snapshot.sty
somefile/MANIFEST

با این حال، "--keepdirs" باعث می‌شود آرشیو somefile در عوض شامل نام‌فایل‌هایی از این دست باشد:

home/me/mydocs/somefile.tex
home/me/mydocs/figures/somefigure.eps
usr/share/texmf/tex/latex/base/article.cls
usr/share/texmf/tex/latex/snapshot/snapshot.sty

هنگامی که "--keepdirs" اعمال شده باشد، "--directory" استفاده نمی‌شود. علاوه‌بر این، هیچ فایل مانیفستی در فایل آرشیو نوشته نمی‌شود زیرا حاوی اطلاعات زاید است.

--config=configuration file (پیش‌فرض: <none>): گزینهٔ "--config" برای هدایت bundledoc به فایل پیکربندی مناسب (.cfg) برای توزیع TeX و سیستم‌عامل شما به کار می‌رود. bundledoc همراه با چند فایل پیکربندی ارائه می‌شود و نوشتن فایل‌های بیشتر نیز آسان است. برای شرح ساختار فایل پیکربندی، بخش «فایل‌های پیکربندی (CONFIGURATION FILES)» (در ادامه) را ببینید. برای راحتی، این فایل را می‌توان بدون پسوند .cfg آن مشخص کرد..SH "فایل‌های پیکربندی (CONFIGURATION FILES)"

قالب (Format)

فایل‌های پیکربندی از قالب نسبتاً ساده‌ای پیروی می‌کنند. خطوطی که با "#" آغاز می‌شوند، توضیح هستند. خطوط خالی نادیده گرفته می‌شوند. بقیه خطوط به شکل زیر هستند:

variable: value

نسخه کنونی bundledoc متغیرهای زیر را شناسایی می‌کند:

bundle: دستوری که برای بسته‌بندی مجموعه‌ای از فایل‌ها در یک فایل آرشیو واحد به کار می‌رود
sink: پسوندی برای یک دستور جهت دور ریختن خروجی آن
find: دستوری برای یافتن یک فایل در درخت(های) TeX.

مقدارهایی که برای یک خط بیش از حد طولانی هستند، می‌توانند با استفاده از "\" به عنوان نماد ادامه‌دهنده خط، در چند خط شکسته شوند.

دو متغیر محیطی وجود دارد که bundledoc آن‌ها را برای استفاده توسط دستورهای فایل پیکربندی در دسترس قرار می‌دهد: "BDBASE"، که روی somefile تنظیم شده است (همان‌طور که در بخش «گزینه‌ها (OPTIONS)» آمده)، و "BDINPUTS"، که روی فهرستی از فایل‌ها با فاصله‌گذاری تنظیم شده است که یک دستور باید روی آن‌ها عمل کند. بدین معنا که هنگامی که دستور مرتبط با "bundle" در حال اجرا است، "BDINPUTS" شامل فهرستی از تمام فایل‌هایی است که باید آرشیو شوند. در مقابل، هنگامی که دستور مرتبط با "find" در حال اجرا است، "BDINPUTS" شامل نام فایلی است که باید جستجو شود.

مثال‌ها (Examples)

فایل پیکربندی زیر مشابه مقادیر پیش‌فرض bundledoc برای متغیرهای گوناگون فایل پیکربندی است، که نشان‌دهنده یک توزیع TeX مبتنی بر kpathsea در حال اجرا روی یک سیستم عمومی Unix است؛ سیستمی که لزوماً هیچ‌یک از ابزارهای GNU، مانند gzip یا tar نسخه GNU را ندارد:

# "Default" configuration file
# By Scott Pakin <scott+bdoc@pakin.org>
bundle: (tar -cvf - $BDINPUTS | compress > $BDBASE.tar.Z)
sink:   > /dev/null 2>&1
find:   kpsewhich -progname=latex $BDINPUTS

پرانتزها در خط "bundle:" به پوسته Unix می‌گویند که دستور را در یک زیرپوسته اجرا کند. این کار برای اطمینان از عملکرد درست پسوند "sink:" است (یعنی تا دو عملگر ">" در یک دستور یکسان وجود نداشته باشد).

دقت کنید که چگونه این دستورها با "BDBASE" و "BDINPUTS" مانند هر متغیر محیطی دیگری در پوسته Unix رفتار می‌کنند و از "$" برای دریافت مقدار آن‌ها استفاده می‌نمایند. سایر سیستم‌های عامل از قراردادهای متفاوتی برای ارجاع به متغیرهای محیطی استفاده می‌کنند. برای نمونه، یک فایل پیکربندی برای یک توزیع TeX مبتنی بر Windows به جای آن از "%BDBASE%" و "%BDINPUTS%" استفاده می‌کند.

مقدار تعیین‌شده برای "sink:" وابسته به سیستم عامل است. مقدار "find:" وابسته به توزیع TeX است. "bundle:" جایی است که بیشترین امکان برای سفارشی‌سازی وجود دارد. می‌توانید از "bundle:" برای تعیین قالب آرشیو دلخواه خود استفاده کنید. برای نمونه، می‌توانید یک فایل shar در Unix با دستوری شبیه به این تولید کنید:

bundle: (shar --archive-name="$BDBASE" $BDINPUTS > $BDBASE.sh)

یا یک فایل CAB در Microsoft Windows با دستوری مانند:

bundle: cabarc -r -p N %BDBASE%.cab %BDINPUTS%

مثال‌ها (EXAMPLES)

فرض کنید myfile.dep بر اساس دستورالعمل‌های بخش توضیحات از روی myfile.tex تولید شده باشد. دستور زیر یک فایل .zip را با توزیع TeX میک‌تک (MikTeX) در حال اجرا روی Microsoft Windows تولید می‌کند:

bundledoc --config=miktex.cfg myfile.dep

این فرمان را می‌توان به این صورت خلاصه کرد:

bundledoc --config=miktex myfile

دستور زیر یک آرشیو .tar.gz را با توزیع TeX Live در حال اجرا روی یک سیستم عامل شبه‌یونیکس می‌سازد. bundledoc خروجی پرجزئیاتی (verbose) در شرح عملیات خود ارائه می‌دهد. تمام فایل‌هایی که در درخت دایرکتوری یکسانی با myfile.tex قرار ندارند و تمام فایل‌هایی که نامشان حاوی «.fd» یا «.cfg» است نادیده گرفته می‌شوند. با این حال، تمام فایل‌های .bib موجود در دایرکتوری جاری در آرشیو گنجانده می‌شوند، حتی اگر در myfile.dep به هیچ‌کدام از آن‌ها ارجاع داده نشده باشد. در نهایت، هیچ فایل MANIFEST تولید نخواهد شد.

    bundledoc --config=texlive-unix.cfg --verbose --localonly \
      --exclude=.fd --exclude=.cfg --include="*.bib" --manifest="" \
      myfile.dep
کاربر باید از قبل snapshot.sty را نصب کرده و از آن برای تولید یک فایل وابستگی برای سند خود استفاده کرده باشد. گذشته از این، مجموعهٔ فایل‌های خارجی مورد نیاز bundledoc وابسته به سیستم است و به فایل پیکربندیِ استفاده‌شده بستگی دارد. (بخش «فایل‌های پیکربندی (CONFIGURATION FILES)» در بالا را ببینید.)

در حال حاضر bundledoc همراه با دو فایل پیکربندی ارائه می‌شود:

texlive-unix.cfg

فایل پیکربندی برای نصب‌های TeX Live در Unix یا Linux. توزیع TeX Live یک توزیع TeX مبتنی بر kpathsea است که روی انواع مختلف Unix و Microsoft Windows اجرا می‌شود. texlive-unix.cfg فرض می‌کند که شما gzip را دارید و از آن برای تولید فایل آرشیو .tar.gz استفاده می‌کند. این فایل پیکربندی به bundledoc می‌گوید که از kpsewhich برای یافتن فایل‌های LaTeX استفاده کند.

miktex.cfg

فایل پیکربندی برای نصب‌های MikTeX. برنامهٔ MikTeX یک توزیع پرطرفدار TeX برای Microsoft Windows است. miktex.cfg فرض می‌کند که شما zip را دارید و از آن برای تولید یک فایل آرشیو .zip استفاده می‌کند. این فایل پیکربندی اکنون به bundledoc می‌گوید که از kpsewhich برای یافتن فایل‌های LaTeX استفاده کند؛ نسخه‌های قدیمی‌تر MikTeX برای این منظور نیازمند ابزار نسبتاً غیر استاندارد initexmf بودند.

texlive-unix-arlatex.cfg

این یک نگارش دیگر از texlive-unix.cfg است که به‌جای gzip از arlatex برای آرشیو کردن فایل‌ها استفاده می‌کند. arlatex اسکریپتی گنجانده‌شده در توزیع bundledoc است که یک فایل .tex خود‌استخراج‌گر بر پایهٔ محیط "filecontents" در LaTeX ایجاد می‌کند.

نکات (NOTES)

شامل‌سازی و مستثنی‌کردن فایل‌ها (Including and excluding files)

گزینه‌های "--localonly"، "--exclude" و "--include" امکان کنترل بر محتوای آرشیو را فراهم می‌کنند. گزینه‌های "--exclude" و "--include" را می‌توان مکرراً در خط فرمان مشخص کرد. ترتیبی که این گزینه‌ها مشخص می‌شوند اهمیتی ندارد؛ bundledoc گنجاندن و حذف فایل‌ها را به ترتیب زیر پردازش می‌کند:

1.: تمام فایل‌های ارجاع‌داده‌شده توسط فایل .dep به فهرست فایل‌های آرشیو افزوده می‌شوند.
2.: اگر "--localonly" مشخص شده باشد، تمام فایل‌هایی که در دایرکتوری فایل .tex یافت نشوند از فهرست حذف می‌شوند.
3.: به ازای هر رشتهٔ "--exclude" مشخص‌شده، تمام فایل‌های حاوی آن رشته از فهرست حذف می‌شوند.
4.: به ازای هر مشخصهٔ فایل در "--include"، مجموعه فایل‌های حاصل از بسط آن به فهرست افزوده می‌شوند.

مشکلات هنگام اجرا در Microsoft Windows (Issues When Running Under Microsoft Windows)

نخست، از آنجا که bundledoc یک اسکریپت Perl است، برای اجرای آن در Windows باید یکی از کارهای زیر را انجام دهید:

"perl bundledoc"
تغییر نام bundledoc به bundledoc.pl و اجرای "bundledoc.pl". (با این فرض که ارتباط پسوند فایل برای .pl تنظیم شده باشد.)
اجرای اسکریپت pl2bat (در صورت موجود بودن) برای تبدیل bundledoc به bundledoc.bat، و سپس اجرای "bundledoc".

دوم، ویندوز از یک سیستم فایل چندریشه‌ای (یعنی چندین حرف درایو) استفاده می‌کند. اگر فایل‌های مورد نظر برای بسته‌بندی در درایوهای مختلف پراکنده باشند، رخ دادن رفتارهای غیرمنتظره دور از انتظار نیست. علاوه بر این، Windows از نام‌فایل‌های “UNC” پشتیبانی می‌کند که اصلاً شناسهٔ درایو ندارند و فقط شامل نام ماشین و اشتراک هستند. نام‌فایل‌های UNC نیز برای bundledoc حوزه‌ای آزمایش‌نشده به شمار می‌روند. احتیاط کنید!

وضعیت آزمایش (Testing Status)

من bundledoc را فقط با Perl نسخهٔ v5.6.0 و جدیدتر و تنها روی بسترهای زیر آزمایش کرده‌ام:

Linux + TeX Live
Linux + teTeX
Windows NT + MiKTeX
Solaris + ؟؟؟ (محیطی مبتنی بر kpathsea)

امیدوارم که bundledoc روی بسترهایی بسیار فراتر از این موارد نیز کار کند. من تلاش کردم تا خود برنامه تا حد امکان مستقل از سیستم‌عامل باشد؛ برای اجرای bundledoc روی یک سیستم متفاوت، تنها فایل‌های پیکربندی باید تغییر کنند..SS "کارهای آینده (Future Work)" مایلم bundledoc روی طیف هرچه گسترده‌تری از توزیع‌های TeX کار کند. اگر پلتفرم شما تفاوت چشمگیری با موارد فهرست‌شده در «Testing Status» دارد (برای نمونه، اگر OS X را اجرا می‌کنید) و نیاز دارید یک فایل پیکربندی بسازید که تفاوت اساسی با texlive-unix.cfg و miktex.cfg دارد، لطفاً آن را به نشانی ذکرشده در بخش «AUTHOR» برای من بفرستید تا بتوانم آن را در نسخه‌های آیندهٔ bundledoc بگنجانم (البته، هیچ قولی نمی‌دهم).

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

در نهایت، بسیار کاربردی خواهد بود اگر bundledoc فونت‌ها را نیز در فایل آرشیو بگنجاند. در کمترین حالت، باید شامل فایل‌های .tfm باشد، اما اگر فایل‌های .mf، .pfb، .ttf و دیگر قالب‌های متداول فونت را نیز شامل شود، حتی بهتر خواهد بود.

سپاسگزاری‌ها (Acknowledgments)

با سپاس از Fabien Vignes-Tourneret برای پیشنهاد گزینه‌ای که به "--localonly" تبدیل شد و برای گفتگویی که به گزینه‌های "--exclude" و "--include" انجامید؛ از Marius Kleiner برای به‌روزرسانی bundledoc جهت مدیریت صحیح زیردایرکتوری‌های سند؛ و از Frank Mittelbach برای پیشنهاد به‌کارگیری Kpathsea جهت کمک به یافتن فایل‌های .cfg و الحاق خودکار پسوندهای .cfg و .dep در صورت لزوم.

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

arlatex(1)، gzip(1)، kpsewhich(1)، latex(1)، perl(1)، zip(1)، مستندات snapshot

نویسنده (AUTHOR)

Scott Pakin, scott+bdoc@pakin.org