نام (NAME)

memoize-extract.pl, memoize-extract.py - استخراج صفحه‌های بیرونی (extern) از فایل PDF

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

memoize-extract.pl [OPTIONS] document.mmz

memoize-extract.py [OPTIONS] document.mmz

توضیحات (DESCRIPTION)

memoize-extract یک اسکریپت همراه Memoize است؛ یک بسته TeX که به نویسنده امکان می‌دهد نتایج کدهای نیازمند کامپایل سنگین (مانند تصاویر TikZ) را دوباره استفاده کند.

Memoize موارد extern ایجادشده (باکس‌های حاوی محتوای حروف‌چینی‌شده برای استفاده مجدد) را در صفحه‌های اختصاصی خود در فایل PDF تولیدشده ذخیره می‌کند. وظیفه memoize-extract استخراج این صفحه‌های extern در فایل‌های PDF جداگانه است. در کامپایل‌های بعدی، Memoize آن فایل‌های extern را بدون کامپایل مجدد سورس آن‌ها، در سند درج می‌کند.

ارتباط Memoize با memoize-extract از طریق فایل document.mmz انجام می‌شود. هنگامی که document.tex برای تولید document.pdf کامپایل می‌شود، Memoize فایل document.mmz را ایجاد می‌کند که ثبت می‌کند کدام صفحه‌ها در سند تولیدشده صفحه‌های extern هستند و باید در کدام فایل‌های extern استخراج شوند. بنابراین، پس از کامپایل document.tex، موارد extern باید توسط memoize-extract document.mmz استخراج شوند.

document.mmz ممکن است به‌صورت document* یا document.tex نیز داده شود. هنگامی که متغیر محیطی TEXMF_OUTPUT_DIRECTORY تنظیم شده باشد، این نام فایل نسبت به دایرکتوری خروجی مشخص‌شده توسط این متغیر در نظر گرفته می‌شود.

فایل document.mmz همچنین عرض و ارتفاع مورد انتظار هر extern را ثبت می‌کند. در صورت عدم تطابق، memoize-extract از استخراج صفحه خودداری کرده و اگر فایل extern از قبل وجود داشته باشد آن را حذف می‌کند، و یک پیام هشدار در خروجی خطای استاندارد چاپ می‌کند. این اسکریپت همچنین در صورتی که یک (c)c-memo مرتبط با extern وجود نداشته باشد، از استخراج صفحه خودداری می‌کند. همچنین بخش «امنیت (SECURITY)» را ببینید.

نسخه‌های Perl (.pl) و Python (.py) این اسکریپت از نظر عملکردی معادل یکدیگر هستند. اسکریپت Perl به کتابخانه PDF::API2و اسکریپت Python به کتابخانه pdfrw2 نیاز دارد.

گزینه‌ها (OPTIONS)

-P, --pdf filename.pdf: موارد extern از filename.pdf استخراج خواهند شد. به‌طور پیش‌فرض، آن‌ها از document.pdf استخراج می‌شوند.
-p, --prune: حذف صفحه‌های extern از فایل PDF پس از استخراج.
-k, --keep: فایل document.mmz را برای علامت‌گذاری externها به‌عنوان استخراج‌شده تغییر نده. به‌طور پیش‌فرض، برای جلوگیری از استخراج مجدد، آن‌ها کامنت می‌شوند.
-F, --format latex|plain|context: هنگامی که این گزینه داده می‌شود، اسکریپت فرض می‌کند که از درون یک کامپایل TeX سندی با قالب داده‌شده فراخوانی شده است: نام اسکریپت را به عنوان پیشوند همه خروجی‌ها قرار می‌دهد و یک فایل لاگ document.mmz.log ایجاد می‌کند که تمامی هشدارها و خطاهای مرتبط با استخراج را دریافت می‌کند.
-f, --force: استخراج extern حتی اگر بررسی اندازه (size-check) ناموفق باشد.
-q, --quiet: توضیح ندادن اتفاقات در حال وقوع (حالت بی‌صدا).
-m, --mkdir: یک دستور mkdir -p بسیار محتاطانه (paranoid). (هیچ استخراجی صورت نمی‌گیرد، document.mmz به عنوان نام یک دایرکتوری تفسیر می‌شود که ممکن است با هر پسوندی ختم شود؛ هیچ دستکاری روی پسوند انجام نمی‌شود.)
-V, --version: نمایش شماره نسخه Memoize و خروج.
-h, --help: نمایش راهنما و خروج.

امنیت (SECURITY)

این اسکریپت محدودیت‌های ورودی و خروجی فایل اعمال‌شده توسط پیکربندی TeX، به‌طور دقیق‌تر، متغیرهای openin_any و openout_any از کتابخانه kpathsea (https://tug.org/kpathsea) را رعایت می‌کند. می‌توانید مقادیر این متغیرها را با اجرای دستورهای kpsewhich -var-value=openin_any و kpsewhich -var-value=openout_any بررسی کنید. تفسیر آن‌ها به شرح زیر است:

a (یا y یا 1) any: اجازه باز شدن هر فایلی را می‌دهد.
r (یا n یا 0) restricted: به معنای غیرمجاز دانستن نام‌های خاص فایل است.
p (یا هر مقدار دیگر) paranoid: به معنای بسیار محتاط بودن است: غیرمجاز دانستن نام‌های خاص فایل و محدود کردن فایل‌های ورودی/خروجی به دایرکتوری کاری جاری یا زیرمجموعه آن، یا دایرکتوری مشخص‌شده توسط TEXMFOUTPUT یا TEXMF_OUTPUT_DIRECTORY. متغیر TEXMFOUTPUT ممکن است در texmf.cnf (مثلاً توسط tlmgr) یا به عنوان یک متغیر محیطی تنظیم شود. متغیر TEXMF_OUTPUT_DIRECTORY تنها می‌تواند به عنوان یک متغیر محیطی تنظیم شود؛ این متغیر هنگام فراخوانی TeX با گزینه -output-directory (از نسخه TeXLive 2024 به بعد) به‌طور خودکار توسط TeX تنظیم می‌شود.

وضعیت خروج (EXIT STATUS)

0: موارد extern با موفقیت استخراج شدند. این کد خروج حتی اگر هیچ externای نیازمند استخراج نباشد یا فایل document.mmz وجود نداشته باشد نیز برگردانده می‌شود.
10: یک هشدار که در صورت ارائه گزینه --format به کامپایل نیز گزارش می‌شود. در حال حاضر یکی از موارد زیر است: (۱) عدم تطابق اندازه؛ (۲) عدم وجود فایل (c)c-memo مرتبط؛ یا (۳) در دسترس نبودن kpsewhich.
11: یک خطا که در صورت ارائه گزینه --format به کامپایل نیز گزارش می‌شود. در حال حاضر یکی از موارد زیر است: (۱) یک PDF سند خراب، یا (۲) خطای دسترسی kpathsea.

سایر کدهای خروج مطابق کدهای تولیدشده توسط زبان اسکریپت‌نویسی پایه (Perl یا Python) هستند.

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

راهنمای Memoize، بخش 6.6.1.