DVIPNG(1) User commands DVIPNG(1)

dvipng - مبدل پرونده‌های DVI به تصاویر PNG

dvipng [options] filename

dvipng [options] [filename] -

این برنامه از پرونده‌های DVI به‌دست‌آمده از TeX و نرم‌افزارهای مرتبط با آن، پرونده‌های گرافیکی PNG و/یا GIF تولید می‌کند.

در صورت فعال بودن پشتیبانی از GIF، خروجی GIF با استفاده از باینری dvigif یا با گزینهٔ --gif انتخاب می‌شود.

مزایای dvipng/dvigif عبارتند از:

  • سرعت. این برنامه دارای کدی بسیار سریع برای رندر بیت‌مپ (bitmap) از پرونده‌های DVI است، که آن را برای تولید درلحظهٔ (on-the-fly) حجم زیادی از تصاویر، آن‌گونه که در preview-latex، WeBWorK و غیره نیاز است، مناسب می‌سازد.
  • این برنامه بخش مؤخره (postamble) را نمی‌خواند، بنابراین می‌تواند حتی پیش از پایان کار TeX شروع به پردازش کند. یک گزینهٔ --follow وجود دارد که باعث می‌شود dvipng در انتهای پرونده برای دریافت خروجی‌های بیشتر منتظر بماند، مگر اینکه به نشانگر POST که نشان‌دهندهٔ پایان پروندهٔ DVI است، برسد.
  • پرس‌وجوی تعاملی گزینه‌ها. dvipng می‌تواند گزینه‌ها را به‌صورت تعاملی از طریق stdin بخواند و تمام گزینه‌ها در این حالت قابل استفاده هستند. حتی تغییر دادن پروندهٔ ورودی از طریق این رابط کاربری امکان‌پذیر است.
  • پشتیبانی از قلم‌های PK، VF، PostScript Type1 و TrueType، زیرقلم‌ها (یعنی آنچه در CJK-LaTeX استفاده می‌شود)، دستورهای ویژهٔ رنگ (color specials)، و درج تصاویر PostScript، PNG، JPEG یا GIF.
  • و موارد دیگر....SH "گزینه‌ها (OPTIONS)" بسیاری از گزینه‌های بدون آرگومان فهرست‌شده در اینجا را می‌توان با افزودن یک صفر (0) به انتهای گزینه غیرفعال کرد؛ برای مثال، برای غیرفعال کردن معکوس‌سازی صفحات، از -r0 استفاده کنید. این گزینه‌ها با یک * در انتها مشخص شده‌اند.
-
خواندن گزینه‌های اضافی از ورودی استاندارد پس از پردازش خط فرمان.
نمایش یک پیام راهنمای نحوهٔ استفاده و خروج.
نمایش شمارهٔ نسخه و خروج.
تنظیم پهنای پیکسل حاشیهٔ شفاف (پیش‌فرض 0 است). استفاده از این گزینه لبه‌های تصویر را شفاف می‌کند، اما تنها بر پیکسل‌های دارای رنگ پس‌زمینه اثر می‌گذارد. تعیین یک color_spec رنگ جایگزین را برای نمایشگرهایی که از شفافیت پشتیبانی نمی‌کنند تعیین می‌کند (پیش‌فرض همان رنگ پس‌زمینه است). مشخصات رنگ باید در نحو \special رنگ TeX باشد، مانند 'rgb 1.0 0.0 0.0'. تنظیم رنگ جایگزین، پهنای پیش‌فرض حاشیه را به 1 پیکسل تبدیل می‌کند.
این گزینه تنها هنگام استفاده از فونت‌های بیت‌مپ (PK) اثر دارد. این گزینه تفکیک‌پذیری پایه (Metafont) را، هم به‌صورت افقی و هم عمودی، روی num نقطه در اینچ (dpi) تنظیم می‌کند. این گزینه زمانی که حالت Metafont به‌صورت دستی با گزینهٔ --mode انتخاب شود ضروری است (به زیر مراجعه کنید).
انتخاب رنگ پس‌زمینه برای تصاویر. اگر یک \special رنگ پس‌زمینه در DVI وجود داشته باشد، این گزینه نادیده گرفته خواهد شد. مشخصات رنگ باید در نحو \special رنگ TeX باشد، مانند 'rgb 1.0 0.0 0.0'. همچنین می‌توانید 'Transparent' یا 'transparent' را مشخص کنید که یک پس‌زمینهٔ شفاف با پس‌زمینهٔ معمولی به عنوان رنگ جایگزین به شما ارائه می‌دهد. عبارت 'Transparent' با حرف نخست بزرگ شفافیت کامل آلفا (full-alpha) را ارائه می‌دهد، در حالی که 'transparent' با حروف تماماً کوچک یک پس‌زمینهٔ ساده کاملاً شفاف با پیکسل‌های ناصافی‌زدایی‌شدهٔ (antialiased) غیرشفاف ارائه می‌کند. دومی برای نمایشگرهایی مناسب است که نمی‌توانند کانال آلفای واقعی را پردازش کنند. تصاویر GIF از شفافیت کامل آلفا پشتیبانی نمی‌کنند، بنابراین در صورت خروجی GIF، هر دو حالت رفتار دوم را به کار خواهند گرفت.
تنظیم پرچم‌های اشکال‌زدایی (debug) که نشان می‌دهد dvipng (فکر می‌کند) در حال انجام چه کاری است. این قابلیت کار خواهد کرد مگر اینکه dvipng بدون گزینهٔ "DEBUG" کامپایل شده باشد (توصیه نمی‌شود). پرچم‌ها را بر اساس نیاز خود تنظیم کنید؛ از -d -1 به عنوان نخستین گزینه برای بیشترین مقدار خروجی استفاده کنید.
تنظیم تفکیک‌پذیری خروجی، هم به‌صورت افقی و هم عمودی، روی num نقطه در اینچ (dpi).

ممکن است شخصی بخواهد این مقدار را برای تطابق با اندازهٔ قلم یک متن خاص (برای مثال، در یک صفحهٔ وب) تنظیم کند؛ برای ارتفاع قلم متن به اندازهٔ font_px پیکسل (در Mozilla) فرمول صحیح عبارت است از:

<dpi> = <font_px> * 72.27 / 10 [px * TeXpt/in / TeXpt]

تقسیم نهایی بر ده به دلیل ارتفاع استاندارد قلم 10pt در سند شما است؛ اگر از 12pt استفاده می‌کنید، بر 12 تقسیم کنید. متأسفانه، برخی از مرورگرهای تجاری ارتفاع قلم را بر حسب pt (نقطه) در نظر می‌گیرند، نه پیکسل. شما باید با استفاده از تفکیک‌پذیری صفحه نمایش (که معمولاً به‌طور پیش‌فرض 96 dpi است) آن را به پیکسل تبدیل کنید که فرمول آن به این صورت خواهد بود:

<font_px> = <font_pt> * 96 / 72 [pt * px/in / (pt/in)]

در برخی از نمایشگرهای با تفکیک‌پذیری بالا، این مقدار در عوض 120 dpi است. موفق باشید!

گزارش عمق تصویر. این گزینه تنها زمانی به طور قابل اعتماد کار می‌کند که استایل LaTeX با نام preview.sty از بستهٔ preview-latex همراه با گزینهٔ active استفاده شده باشد. این مقدار، تعداد پیکسل‌ها از پایین تصویر تا خط کرسی (baseline) تصویر را گزارش می‌دهد. این را می‌توان برای موقعیت‌دهی عمودی تصویر، مثلاً در اسناد وب استفاده کرد، جایی که شخص می‌تواند بنویسد (Cascading StyleSheets 1): 
<IMG SRC="<filename.png>" STYLE="vertical-align: -<depth>px">

عمق در این حالت یک آفست منفی است، بنابراین علامت منفی لازم است، و واحد آن بر حسب پیکسل (px) می‌باشد.

این گزینه را تنظیم کنید تا شمارهٔ صفحهٔ خروجی به جای شمارهٔ فیزیکی صفحه، شماره‌های صفحهٔ TeX باشد. سوئیچ -o را ببینید.
انتخاب رنگ پیش‌زمینه برای تصاویر. اگر یک \special رنگ پیش‌زمینه در DVI وجود داشته باشد، این گزینه نادیده گرفته خواهد شد. مشخصات رنگ باید در نحو \special رنگ TeX باشد، مانند 'rgb 1.0 0.0 0.0'.
انتظار برای دریافت داده‌ها در پایان فایل (end-of-file). یکی از مزایای dvipng این است که postamble را نمی‌خواند، بنابراین می‌تواند پیش از پایان یافتن کار TeX شروع به پردازش کند. این سوئیچ باعث می‌شود dvipng در انتهای فایل منتظر خروجی‌های بعدی بماند، مگر اینکه نشانگر POST را که بیانگر پایان DVI است پیدا کند. این رفتار مشابه دستور tail -f است، اما برای تبدیل DVI به PNG.
فعال/غیرفعال کردن رندر قلم با FreeType (به‌طور پیش‌فرض فعال است). این گزینه در صورتی در دسترس است که کتابخانهٔ قلم FreeType2 در زمان کامپایل موجود بوده باشد. در این صورت، dvipng به جای استفاده از gsftopk برای رندر قلم‌ها، از قلم‌های PostScript Type1 و TrueType به‌طور مستقیم در ساختار داخلی خود پشتیبانی خواهد کرد. اگر نسخه‌های PostScript قلم Computer Modern را نصب داشته باشید، نیازی به تولید نسخه‌های بیت‌مپ (PK) آن‌ها روی دیسک نخواهد بود. سپس می‌توانید تصاویر را در تفکیک‌پذیری‌های مختلف (و غیرمعمول) بدون اشغال فضای دیسک با انبوهی از فونت‌های بیت‌مپ رندر کنید. یک دلیل برای غیرفعال کردن رندر قلم با FreeType، تولید خروجی یکسان در پلتفرم‌های مختلف است، زیرا FreeType از رندرکنندهٔ بومی سیستم‌عامل استفاده می‌کند و بنابراین ممکن است در هر پلتفرم خروجی کمی متفاوت ارائه دهد.
کنترل درون‌یابی رنگ‌ها در پالت رنگی ناصافی‌زدایی (anti-aliasing) مقیاس خاکستری (greyscale). مقدار پیش‌فرض 1.0 است. به ازای 0 < num < 1، قلم‌ها روشن‌تر خواهند بود (بیشتر شبیه به رنگ پس‌زمینه)، و به ازای num > 1، قلم‌ها تیره‌تر خواهند بود (بیشتر شبیه به رنگ پیش‌زمینه).
در صورتی که پشتیبانی از GIF فعال باشد، تصاویر در قالب GIF خروجی داده می‌شوند. این حالت پیش‌فرض برای باینری dvigif است که تنها در صورت فعال بودن پشتیبانی از GIF در دسترس خواهد بود. تصاویر GIF تصاویری مبتنی بر پالت هستند (گزینهٔ --palette را ببینید) و از کانال‌های آلفای واقعی پشتیبانی نمی‌کنند (گزینهٔ --bg را ببینید). همچنین گزینهٔ --png را ببینید.
گزارش ارتفاع تصویر. این گزینه تنها زمانی به طور قابل اعتماد کار می‌کند که استایل LaTeX با نام preview.sty از بستهٔ preview-latex همراه با گزینهٔ active استفاده شده باشد. این مقدار، تعداد پیکسل‌ها از بالای تصویر تا خط کرسی تصویر را گزارش می‌دهد. ارتفاع کل تصویر از مجموع مقادیر گزارش‌شده از --height و --depth به دست می‌آید.
آخرین صفحهٔ چاپ‌شده نخستین صفحه‌ای خواهد بود که شمارهٔ آن num باشد. پیش‌فرض، آخرین صفحه در سند است. اگر در ابتدای num علامت مساوی قرار داده شود، آنگاه این مقدار (و آرگومان گزینهٔ -p، در صورت تعیین شدن) به جای مقایسه با مقادیر \count0 ذخیره‌شده در فایل DVI، به عنوان شماره صفحهٔ فیزیکی (مطلق) در نظر گرفته می‌شود. بنابراین، استفاده از -l =9 بدون توجه به شماره‌گذاری واقعی صفحات، به صفحهٔ نهم سند ختم خواهد شد.
این گزینه تنها هنگام استفاده از فونت‌های بیت‌مپ (PK) اثر دارد. استفاده از mode به عنوان نام دستگاه Metafont برای فونت‌های PK (هم برای جستجوی مسیر و هم تولید فونت). این مقدار باید با تفکیک‌پذیری پایهٔ دستگاه که با گزینهٔ --bdpi مشخص می‌شود تکمیل شود. برای دیدن فهرستی از تفکیک‌پذیری‌ها و نام‌های حالت برای بیشتر دستگاه‌ها، فایل <ftp://ftp.tug.org/tex/modes.mf> را ببینید.
این گزینه تنها هنگام استفاده از فونت‌های بیت‌مپ (PK) اثر دارد. این گزینه تولید خودکار فونت PK (mktexpk) را غیرفعال می‌کند.
این سوئیچ فراخوانی داخلی GhostScript را برای نمایش دستورات ویژهٔ (specials) PostScript ممنوع می‌کند. گزینهٔ --nogs0 این فراخوانی را مجدداً فعال می‌کند.
به‌طور معمول، اگر از GhostScript برای رندر دستورات ویژهٔ PostScript استفاده شود، مفسر GhostScript با گزینهٔ -dSAFER اجرا می‌شود. گزینهٔ --nogssafer نرم‌افزار GhostScript را بدون -dSAFER اجرا می‌کند. گزینهٔ -dSAFER در Ghostscript عملگرهای PostScript نظیر deletefile را غیرفعال می‌کند تا از ایجاد هرگونه اثر نامطلوب توسط برنامه‌های بالقوه مخرب PostScript جلوگیری کند..IP --norawps* 4 برخی بسته‌ها دستورهای ویژهٔ (specials) خام PostScript تولید می‌کنند، حتی دستورهای ویژه‌ای از این دست که رسم نمی‌شوند. این سوییچ فراخوانی درونی به GhostScript را که برای نمایش این دستورهای ویژهٔ خام PostScript در نظر گرفته شده است غیرفعال می‌کند. --norawps0 این فراخوانی را دوباره فعال می‌کند.
ارسال خروجی به فایل name. یک بار رخداد %d یا %01d، ...، %09d با شماره صفحهٔ فیزیکی جایگزین خواهد شد (این رفتار قابل تغییر است، سوییچ --dvinum را ببینید). نام فایل خروجی پیش‌فرض file%d.png است که در آن فایل DVI ورودی file.dvi بوده است.
مبدأ را به اندازهٔ x-offset,y-offset جابه‌جا می‌کند، که یک جفت بُعد جداشده با کاما مانند .1in,-.3cm است. مبدأ صفحه به این اندازه از موقعیت پیش‌فرض (یک اینچ به سمت پایین، یک اینچ به سمت راست از گوشهٔ بالا-چپ کاغذ) جابه‌جا می‌شود.
نخستین صفحهٔ چاپ‌شده، اولین صفحه‌ای خواهد بود که شمارهٔ آن num باشد. پیش‌فرض، نخستین صفحهٔ سند است. اگر پیشوندِ num یک علامت مساوی باشد، با آن (و در صورت تعیین، با آرگومان گزینهٔ -l) به عنوان یک شماره صفحهٔ فیزیکی (مطلق) رفتار می‌شود، نه مقداری برای مقایسه با مقادیر \count0 مربوط به TeX که در فایل DVI ذخیره شده است. بنابراین، استفاده از -p =3، بدون توجه به این که شمارهٔ واقعی صفحات چیست، از سومین صفحهٔ سند آغاز خواهد کرد.
هنگامی که یک تصویر خارجی اضافه می‌شود، dvipng به طور خودکار به حالت رنگ واقعی (truecolor) می‌رود تا از تأخیر غیرضروری و کاهش کیفیت جلوگیری کند، و به مترجم EPS امکان دهد روی پس‌زمینهٔ شفاف و خارج از کادر محصورکننده (boundingbox) نقاشی کند. این سوییچ خروجی را به حالت پالت (۲۵۶ رنگ) وامی‌دارد و باعث می‌شود dvipng به حالت گنجاندن تصویر ماتِ برش‌خورده بازگردد. همچنین این سوییچ در صورت وجود، سوییچ --truecolor را لغو (override) می‌کند.
هنگام وقوع هشدار، هیچ تصویری خروجی داده نمی‌شود. در حالت عادی، dvipng با وجود هشدار، تصویر را خروجی می‌دهد، اما ممکن است نقصی در این تصویر وجود داشته باشد. یک دلیل برای استفاده از این گزینه زمانی است که یک مبدل پشتیبانِ (fallback) کامل‌تر اما کندتر در اختیار داشته باشید. این گزینه عمدتاً برای گنجاندن‌های ناموفق تصاویر و رخدادهای ناشناختهٔ \special کاربرد دارد، اما هشدارها برای مشخصات رنگیِ ناموجود یا ناشناخته و فونت‌های PK مفقود نیز رخ خواهند داد.
تصاویر در قالب PNG خروجی داده می‌شوند. این حالت پیش‌فرض برای باینری dvipng است. همچنین گزینهٔ --gif را ببینید.
صفحات firstpage تا lastpage را چاپ می‌کند؛ اما نه کاملاً معادل با -p firstpage -l lastpage. برای نمونه، هنگام رندر کردن یک کتاب، ممکن است چندین مورد از یک شماره صفحه در فایل DVI وجود داشته باشد (یکی در "\frontmatter"، یکی در "\mainmatter" و یکی در "\backmatter"). در صورت تطابق چند صفحه، -pp firstpage-lastpage همهٔ صفحاتی را که با محدودهٔ مشخص‌شده مطابقت دارند رندر می‌کند، در حالی که -p firstpage -l lastpage صفحات را از نخستین رخدادِ firstpage تا نخستین رخدادِ lastpage رندر خواهد کرد. این رفتار (مستندنشدهٔ) dvips است. در dvipng می‌توانید هر دو نوع گزینه را مشخص کنید، که در این حالت همهٔ صفحاتی را دریافت خواهید کرد که با محدودهٔ درون -pp بین صفحاتِ -p تا -l مطابقت دارند. همچنین برخلاف -p و -l، چند گزینهٔ -pp با یکدیگر تجمیع می‌شوند. جداکنندهٔ - می‌تواند : نیز باشد. توجه داشته باشید که -pp -1 به عنوان «همهٔ صفحات تا و خودِ ۱» تفسیر می‌شود؛ اگر صفحه‌ای با شمارهٔ -1 را می‌خواهید (مثلاً تنها فهرست مطالب)، -pp -1--1 یا برای خوانایی بهتر، -pp -1:-1 را قرار دهید.
اجرا در حالت ساکت. اطلاعاتی دربارهٔ صفحات تبدیل‌شده و غیره به خروجی استاندارد ارسال نمی‌کند؛ هیچ هشداری (فقط خطاها) را به خطای استاندارد گزارش نمی‌دهد.
کیفیت را روی num تنظیم می‌کند. بدین معنا که تعداد سطوح هموارسازی (antialiasing) برای فونت‌های نقشه‌بیتی (PK) را به میزان num*num+1 انتخاب می‌کند. مقدار پیش‌فرض 4 است که 17 سطح هموارسازی برای فونت‌های هموارشده ارائه می‌دهد. در صورت در دسترس بودن FreeType، رندر آن تحت تأثیر این گزینه قرار نمی‌گیرد.
تغییر وضعیت خروجی صفحات به ترتیب معکوس/مستقیم. به طور پیش‌فرض، نخستین صفحه در DVI ابتدا خروجی داده می‌شود.
برنامه هنگام وقوع یک هشدار خارج می‌شود. در حالت عادی، dvipng با وجود هشدار تصویری خروجی می‌دهد، اما ممکن است نقصی در این تصویر وجود داشته باشد. یک دلیل برای استفاده از این گزینه زمانی است که یک تبدیل‌کنندهٔ پشتیبانِ کامل‌تر اما کندتر در اختیار داشته باشید. برای فهرستی از مواردی که هشدار رخ می‌دهد، گزینهٔ --picky در بالا را ببینید.
اندازهٔ تصویر را روی image_size تنظیم می‌کند که می‌تواند یکی از مقادیر bbox، tight، یا یک جفت بُعدِ جداشده با کاما به صورت hsize,vsize مانند .1in,.3cm باشد. مقدار پیش‌فرض bbox است که یک تصویر PNG تولید می‌کند شامل تمام جوهر درج‌شده روی صفحه و علاوه بر آن مبدأ DVI، واقع در 1 اینچی از بالا و 1 اینچی از لبهٔ چپ کاغذ. این حالت معمولاً در تصویر تولیدشده فضای خالی در بالا و سمت چپ ایجاد می‌کند. مقدار tight سبب می‌شود dvipng تنها جوهر درج‌شده روی صفحه را در بر گیرد و تصاویری جمع‌وجور و مرتب تولید کند.
این سوییچ باعث می‌شود dvipng خروجی رنگ واقعی (truecolor) تولید کند. توجه داشته باشید که اگر یک تصویر خارجی را در DVI خود بگنجانید، مثلاً از طریق دستور ویژهٔ PostScript (یعنی بستهٔ graphics یا graphicx)، خروجیِ رنگ واقعی خودکار خواهد بود. این سوییچ توسط سوییچ --palette لغو و نادیده گرفته می‌شود.
فعال‌سازی عملیات پرگو (verbose). این گزینه در حال حاضر علاوه بر خروجی همیشگی، فونت‌های استفاده‌شده را نیز مشخص می‌کند.
عرض تصویر را گزارش می‌کند. همچنین --height و --depth را ببینید.
این گزینه منسوخ شده است و نباید استفاده شود. انتخاب مستقیم تفکیک‌پذیری خروجی با استفاده از گزینهٔ -D بسیار بهتر است. این گزینه نسبت بزرگ‌نمایی را روی num/1000 تنظیم کرده و بزرگ‌نمایی مشخص‌شده در فایل DVI را لغو می‌کند. مقدار باید بین 10 و 100000 باشد. پیشنهاد می‌شود از مقادیر استاندارد magstep (مانند 1095، 1200، 1440، 1728، 2074، 2488، 2986 و غیره) استفاده کنید تا به کاهش تعداد کل فایل‌های PK تولیدشده کمک شود. برای افزایش دقت، num می‌تواند به جای عدد صحیح، یک عدد حقیقی باشد.
سطح فشرده‌سازی PNG را روی num تنظیم می‌کند. اگر کتابخانهٔ libgd شما به اندازهٔ کافی جدید باشد، این گزینه فعال است. سطح فشرده‌سازی پیش‌فرض 1 است، که بیشترین سرعت را به بهای ایجاد فایل‌های PNG کمی بزرگ‌تر انتخاب می‌کند. برای نسخه‌های قدیمی‌تر libgd، مقدار ثابت 5 استفاده می‌شود. فایل سرآیند png.h بیان می‌کند: «در حال حاضر مقادیر معتبر بین 0 تا 9 هستند، که مستقیماً متناظر با سطوح فشرده‌سازی 0 تا 9 در zlib می‌باشند (0 برای بدون فشرده‌سازی، 9 برای فشرده‌سازی «حداکثری»). توجه داشته باشید که آزمایش‌ها نشان داده‌اند سطوح فشرده‌سازی 3 تا 6 در zlib معمولاً برای تصاویر PNG به خوبی سطح 9 عمل می‌کنند و محاسبات بسیار کمتری انجام می‌دهند. در آینده ممکن است این مقادیر مستقیماً متناظر با سطوح فشرده‌سازی zlib نباشند.».SH "نکات (NOTES)" راهنمای کامل در قالب info و در بیشتر سامانه‌ها با وارد کردن دستور زیر در دسترس است:
info dvipng

این برنامه تحت مجوز GNU Lesser General Public License نگارش ۳ منتشر شده است؛ فایل COPYING در توزیع dvipng یا http://www.gnu.org/licenses/gpl.html را ببینید.

کپی‌رایت (c) 2002-2015, 2019 متعلق به Jan-AAke Larsson

2025-02-02 dvipng 1.18