STY2DTX(1) مستندات پرل ارائه‌شده توسط کاربر STY2DTX(1)

sty2dtx - تبدیل فایل .sty لاتک به یک فایل .dtx مستندسازی‌شده

نسخه: v2.4 - 2022/10/18

CTAN: https://ctan.org/pkg/sty2dtx

مخزن: https://github.com/MartinScharrer/sty2dtx

گزارش اشکالات: https://github.com/MartinScharrer/sty2dtx/issues

حق نشر (c) 2010-2022 Martin Scharrer <martin.scharrer@web.de>

این برنامه یک نرم‌افزار آزاد است: شما می‌توانید آن را تحت شرایط «پروانه عمومی همگانی گنو» (GNU General Public License) همان‌طور که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، چه نسخه ۳ پروانه و چه (به انتخاب خودتان) هر نسخهٔ متأخرتری بازتوزیع کنید یا تغییر دهید.

این برنامه به این امید توزیع شده است که مفید واقع شود، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا تناسب برای یک هدف خاص. برای جزئیات بیشتر به «پروانه عمومی همگانی GNU» مراجعه کنید.

شما باید همراه با این برنامه یک نسخه از «پروانه عمومی همگانی GNU» را دریافت کرده باشید. در غیر این صورت، https://www.gnu.org/licenses را ببینید.

یک فایل .sty (بسته LaTeX) را با احاطه کردن تعریف‌های ماکرو درون محیط‌های 'macro' و 'macrocode'، به قالب .dtx (منبع مستندسازی‌شدهٔ LaTeX) تبدیل می‌کند. نام ماکرو به‌طور خودکار به عنوان یک آرگومان در محیط 'macro' وارد می‌شود. خطوط کد خارج از تعاریف ماکرو، تنها درون محیط‌های 'macrocode' قرار می‌گیرند. خطوط خالی حذف می‌شوند. این اسکریپت لزوماً خطاناپذیر و ۱۰۰٪ بی‌نقص طراحی نشده است، بلکه نقطهٔ شروع مناسبی برای تبدیل فایل‌های شیوه (style) فاقد مستندات به فایل‌های .dtx به شمار می‌رود.

perl sty2dtx.pl infile [infile ...] outfile

یا

perl sty2dtx.pl < file.sty > file.dtx

تعریف‌های ماکروی زیر زمانی که در آغاز یک خط باشند شناسایی می‌شوند (می‌توانند پیشوندهای \global، \long، \protected و/یا \outer داشته باشند):

\def   \edef   \gdef   \xdef
\newcommand{\name}     \newcommand*{\name}
\newcommand\name       \newcommand*\name
\renewcommand{\name}   \renewcommand*{\name}
\renewcommand\name     \renewcommand*\name
\providecommand{\name} \providecommand*{\name}
\providecommand\name   \providecommand*\name
\@namedef{\name}       \@namedef\name

تعریف‌های محیطی زیر زمانی که در ابتدای یک خط باشند شناسایی می‌شوند:

\newenvironment{name}  \renewenvironemnt{name}  \provideenvironment{name}

تعریف ماکرو و محیط باید یا در همان خط پایان یابد یا به یک '"}"' به تنهایی در یک خط ختم شود.

sty2dtx [<options>] [--<VAR>=<VALUE> ...] [--] [<infile(s)>] [<outfile>]

  • می‌تواند برای STDIN یا STDOUT برابر با '"-"' باشد، که در صورت تعیین نشدن هیچ فایلی، حالت پیش‌فرض است
  • چندین فایل ورودی در یک فایل خروجی ادغام می‌شوند.SS "متغیرها (Variables)" متغیرها را می‌توان با استفاده از
--<VAR>=<VALUE>

یا

--<VAR> <VALUE>

تعریف کرد و برای جایگزینی‌ها در فایل الگو استفاده خواهند شد.

متغیرهای رایج:

author, email, maintainer, year (برای حق تکثیر),
version, date, description (برای بسته/کلاس),
type (یا پیش‌فرض 'package' یا 'class'),
filebase (تنظیم خودکار از روی نام فایل ورودی یا خروجی),

یک فایل پیکربندی پیش‌فرض با نام 'sty2dtx.cfg' یا '.sty2dtx.cfg' به‌ترتیب در دایرکتوری جاری، دایرکتوری خانگی کاربر و دایرکتوری این اسکریپت جستجو می‌شود. نخستین فایل یافت‌شده بارگذاری می‌شود. اگر هیچ فایلی پیدا نشود، درخت 'texmf' برای یافتن فایل پیکربندی 'sty2dtx.cfg' جستجو خواهد شد. همانند فایل‌های -F، فایل پیکربندی باید در هر سطر شامل یک گزینه یا متغیر باشد. سطرهایی که با '"%"' یا '"#"' آغاز می‌شوند نادیده گرفته می‌شوند.

تولید 'file.dtx' از 'file.sty':

sty2dtx.pl < file.sty > file.dtx

یا

sty2dtx.pl file.sty file.dtx

یا

sty2dtx.pl -B file.sty

تولید 'file.dtx' و 'file.ins' از 'file.sty':

sty2dtx.pl -I file.sty file.dtx

یا

sty2dtx.pl file.sty -i file.sty file.dtx

یا

sty2dtx.pl -IB file.sty

تنظیم مقادیر سفارشی برای متغیرها:

sty2dtx.pl --author Me --email me@there.com mypkg.sty mypkg.dtx

تولید فایل DTX برای یک کلاس:

    sty2dtx.pl --type class mycls.sty mycls.dtx
Martin Scharrer
رایانامه: martin.scharrer@web.de
وبگاه: <http://www.scharrer-online.de>
2022-10-18 perl v5.30.0