نام (NAME)

grohtml, post-grohtml, pre-grohtml - درایور خروجی groff برای HTML

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

pre-grohtml [-epV] [-a anti-aliasing-text-bits] [-D image-directory] [-F font-directory] [-g anti-aliasing-graphic-bits] [-i resolution] [-I image-stem] [-o image-vertical-offset] [-x html-dialect] troff-command troff-argument ...

pre-grohtml --help

pre-grohtml -v

pre-grohtml --version

post-grohtml [-bCGhlnrVy] [-F font-directory] [-j output-stem] [-k encoding] [-s base-point-size] [-S heading-level] [-x html-dialect] [file ...]

post-grohtml --help

post-grohtml -v

post-grohtml --version

توضیحات (DESCRIPTION)

پشتیبانی سامانه GNU roff از HTML شامل یک پیش‌پردازنده به نام pre-grohtml و یک درایور خروجی به نام post-grohtml است؛ این دو ابزار در کنار یکدیگر، اسناد roff(7) را به HTML تبدیل می‌کنند. از آنجا که این درایور خروجی (به‌طور منحصربه‌فرد) نیازمند یک پیش‌پردازنده است، کاربران باید grohtml را از طریق دستور groff(1) با گزینه‌های -Thtml یا -Txhtml فراخوانی نمایند. (در این پیکربندی نصب، ps دستگاه خروجی پیش‌فرض است.) از گزینه -P در groff برای ارسال هر یک از گزینه‌های نشان‌داده‌شده در بالا به grohtml استفاده کنید. اگر هیچ عملوندی مشخص نشود، یا اگر file برابر با “-” باشد، grohtml جریان ورودی استاندارد را می‌خواند. این برنامه در جریان خروجی استاندارد می‌نویسد.

دستور grohtml برنامه groff را دو بار فراخوانی می‌کند. در دور نخست، پیش‌پردازنده pre-grohtml تصاویر، معادلات و جدول‌ها را به شکل تصاویری در قالب PostScript با استفاده از دستگاه خروجی ps رندر می‌کند. در دور دوم، درایور خروجی post-grohtml خروجی troff(1) را به HTML ترجمه می‌نماید.

دستور grohtml خروجی با کدگذاری UTF-8 تولید می‌کند (البته گزینه -k را نیز ببینید) و برای بیشتر نویسه‌های یونیکد غیرترکیبی و فراتر از لاتین پایه، ارجاعات نویسه‌ای HTML ایجاد می‌نماید. با وجود این، ممکن است groff در صورتی که نویسه‌های خاص ناشناخته در طول دور نخست پیدا نشوند، هشدارهایی صادر کند. می‌توانید این هشدارها را نادیده بگیرید، مگر اینکه نویسه‌های خاص درون یک جدول یا معادله قرار داشته باشند.

قلم‌ها (Typefaces)

دستور grohtml از چهار سبک استاندارد پشتیبانی می‌کند: R (معمولی یا roman)، I (موربیاitalic)، B (توپریاbold) و BI (توپر و مورب یا bold-italic). قلم‌ها در خانواده‌های T و C دسته‌بندی شده‌اند که برای هر سبک عضوی دارند.

TR: قلم Times معمولی (Times roman)
TI: قلم Times مورب (Times italic)
TB: قلم Times توپر (Times bold)
TBI: قلم Times توپر و مورب (Times bold-italic)
CR: قلم Courier معمولی (Courier roman)
CI: قلم Courier مورب (Courier italic)
CB: قلم Courier توپر (Courier bold)
CBI: قلم Courier توپر و مورب (Courier bold-italic)

یک قلم ویژه به نام S نیز برای سازگاری با اسناد roff که انتظار دارند این قلم همواره در دسترس باشد فراهم شده است.

علاوه بر این، grohtml از یک طرح نام‌گذاری برای قلم‌های آسیای شرقی پشتیبانی می‌کند که میان gropdf(1)، grops(1) و grotty(1) مشترک است.

CSH: چینی ساده‌شده، سبک Hei
CSS: چینی ساده‌شده، سبک Song
CTH: چینی سنتی، سبک Hei
CTS: چینی سنتی، سبک Song
JPG: ژاپنی، سبک گوتیک (Gothic)
JPM: ژاپنی، سبک مینچو (Mincho)
KOG: کره‌ای، سبک گوتیک (Gothic)
KOM: کره‌ای، سبک مینچو (Mincho)

فایل‌های توصیف قلم (Font description files)

فایل‌های توصیف قلم مورد استفاده در grohtml مجموعه گلیف یکسانی را در بخش‌های charset خود ارائه می‌دهند. نگاه کنید به groff_font(5).

وابستگی‌ها (Dependencies)

پیش‌پردازنده pre-grohtml هر زمان که در ورودی با یک معادله eqn، یک جدول tbl یا یک تصویر pic مواجه شود، تصویری ایجاد می‌کند. بنابراین grohtml ممکن است به عنوان بخشی از عملیات خود چندین دستور را اجرا کند. این دستورات شامل ابزارهای Netpbm مانند pamcut، pnmcrop و pnmtopng، و همچنین ابزارهای Ghostscript مانند gs و ps2ps هستند.

گزینه‌ها (OPTIONS)

گزینه --help پیام راهنمای استفاده را نمایش می‌دهد، در حالی که گزینه‌های -v و --version اطلاعات نسخه را نشان می‌دهند؛ تمامی این گزینه‌ها پس از نمایش خارج می‌شوند.

-a anti-aliasing-text-bits: تعداد بیت‌های اطلاعات هموارسازی (antialiasing) مورد استفاده برای متن هنگام تولید تصاویر PNG. مقدار پیش‌فرض برابر 4 است، اما مقادیر 0، 1 و 2 نیز معتبر هستند. نسخه gs سیستم شما باید از گزینه -dTextAlphaBits پشتیبانی کند تا بتوان از هموارسازی بهره برد. مقدار برابر 0 مانع ارسال دستورات هموارسازی از سوی grohtml به gs می‌شود.
-b: رنگ پس‌زمینه را روی سفید مقداردهی اولیه می‌کند.
-C: از تولید کامنت HTML مربوط به “CreationDate:” جلوگیری می‌کند.
-D image-directory: به grohtml دستور می‌دهد تمام فایل‌های تصویری را در پوشه image-directory قرار دهد.
-e: به eqn هدایت می‌کند تا MathML تولید نماید.

: این گزینه نباید به صورت دستی تعیین شود؛ این گزینه بسته به اینکه آیا به groff گزینه -Thtml داده شده یا -Txhtml، توسط groff تنظیم و ایجاد می‌شود.

-F font-directory: پوشه font-directory/devname را به ابتدای مسیر جستجو برای فایل‌های توصیف قلم و دستگاه اضافه می‌کند؛ در اینجا name نام دستگاه است که معمولاً html می‌باشد.
-g anti-aliasing-graphic-bits: تعداد بیت‌های اطلاعات هموارسازی مورد استفاده برای بخش‌های گرافیکی هنگام تولید تصاویر PNG. مقدار پیش‌فرض برابر 4 است، اما مقادیر 0، 1 و 2 نیز معتبر هستند. نسخه gs سیستم شما باید از گزینه -dGraphicAlphaBits پشتیبانی کند تا بتوان از هموارسازی بهره برد. مقدار برابر 0 مانع ارسال دستورات هموارسازی از سوی grohtml به gs می‌شود.
-G: از تولید کامنت HTML مربوط به “Creator:” جلوگیری می‌کند.
-h: عناوین بخش‌ها را به جای استفاده از عناصر H در HTML، با استفاده از عناصر B و افزایش اندازه قلم تولید می‌کند.
-i resolution: وضوح تصویر (رزولوشن) را بر حسب پیکسل بر اینچ تنظیم می‌کند؛ مقدار پیش‌فرض برابر 100 است.
-I image-stem: پیشوند (ریشه) نام فایل‌های تصویری را مشخص می‌کند. در صورت عدم تعیین، grohtml از grohtml-XXXXX (که در آن XXXXX شناسه فرایند است) استفاده می‌کند. یک خط تیره به انتهای ریشه افزوده می‌شود تا آن را از شماره تصویر پس از خود جدا سازد.
-j output-stem: به grohtml دستور می‌دهد خروجی HTML را به چند فایل تقسیم کند. خروجی در هر عنوان بخش (البته گزینه -S در زیر را ببینید) در یک فایل جدید با نام output-stem-n.html نوشته می‌شود.
-k encoding: کدگذاری نویسه مورد استفاده در سند تولید‌شده را انتخاب می‌کند که بر کدگذاری اعلام‌شده در مقدمه و همچنین ساختار ارجاعات موجودیت‌های نویسه‌ای تأثیر می‌گذارد. مقادیر معتبر شامل “ASCII” و “UTF-8” هستند. مقدار پیش‌فرض “UTF-8” است.
-l: تولید خودکار پیوندهای بخش‌ها در بالای سند را غیرفعال می‌کند.
-n: هر زمان که یک عنوان بخش یا عنوان شماره‌دار پیدا شود، لنگرهای (anchors) ساده برای آن عنوان تولید می‌کند. بدون این گزینه، مقدار لنگر همان متن عنوان خواهد بود. اگر یک عنوان حاوی کاراکتر “?” باشد، این موضوع در نسخه‌های قدیمی برخی از مرورگرها می‌تواند مشکل ایجاد کند. در صورتی که یک عنوان حاوی تصویر باشد، این ویژگی به طور خودکار فعال می‌شود.
-o image-vertical-offset: میزان جابجایی (آفست) عمودی تصاویر را بر حسب پوینت مشخص می‌کند.
-p: پیشرفت رندر صفحه را در جریان خطای استاندارد نمایش می‌دهد. دستور grohtml تنها زمانی شماره صفحه را نمایش می‌دهد که نیاز به تولید تصویر باشد.
-r: خط افقی سربرگ و پاورقی خودکار (خط افقی یا rule در HTML) را غیرفعال می‌کند.
-s base-type-size: اندازه پایه قلم سند را بر حسب پوینت تنظیم می‌کند. هنگامی که این اندازه در سند مبدأ استفاده شود، مطابق با اندازه پایه قلم در HTML خواهد بود. هر دو پوینت افزایش در اندازه سند مبدأ، یک عنصر “big” تولید می‌کند و برعکس با دو پوینت کاهش، یک عنصر “small” تولید می‌شود.
-S heading-level: هنگام تقسیم خروجی HTML (گزینه -j در بالا را ببینید)، خروجی را در هر سطح عنوان تو در تو که توسط heading-level یا بالاتر تعریف شده است تقسیم می‌کند. مقدار پیش‌فرض 1 است.
-V: یک دکمه اعتبارسنجی XHTML یا HTML در پایین هر صفحه از سند ایجاد می‌کند.
-x html-dialect: گویش HTML را انتخاب می‌کند. در حال حاضر، html-dialect باید یا رقم 4 یا حرف x باشد که به ترتیب نشان می‌دهد grohtml باید HTML 4 تولید کند یا XHTML.

: این گزینه نباید به صورت دستی تعیین شود؛ این گزینه بسته به اینکه آیا به groff گزینه -Thtml داده شده یا -Txhtml، توسط groff تنظیم و ایجاد می‌شود.

-y: یک امضای راست‌چین groff در انتهای سند ایجاد می‌کند (تنها در صورتی که گزینه -V نیز مشخص شده باشد).

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

برنامه‌های pre-grohtml و post-grohtml هر یک در صورت اجرای موفقیت‌آمیز با وضعیت 0، در صورتی که نتوانند آرگومان‌های خط فرمان خود را تفسیر کنند با وضعیت 2 و در صورت مواجهه با خطا در طول عملیات با وضعیت 1 خارج می‌شوند.

محیط (ENVIRONMENT)

GROFF_FONT_PATH: دایرکتوری‌هایی را فهرست می‌کند که باید در آن‌ها به دنبال devhtml، دایرکتوری فایل‌های توصیف قلم و دستگاه متعلق به grohtml، جستجو شود. نگاه کنید به troff(1) و groff_font(5).
SOURCE_DATE_EPOCH: یک برچسب زمانی (بیان‌شده بر حسب ثانیه‌های سپری‌شده از مبدأ یونیکس یا Unix epoch) جهت استفاده به عنوان برچسب زمانی ایجاد خروجی به جای زمان فعلی. این زمان با استفاده از gmtime(3) و asctime(3) به قالبی خوانا برای انسان تبدیل شده و در یک کامنت HTML ذخیره می‌شود.
TZ: منطقه زمانی مورد استفاده هنگام تبدیل زمان فعلی به قالبی خوانا برای انسان؛ نگاه کنید به tzset(3). اگر SOURCE_DATE_EPOCH استفاده شود، همیشه با استفاده از UTC به قالبی خوانا برای انسان تبدیل می‌شود.

فایل‌ها (FILES)

/usr/share/groff/1.24.1/font/devhtml/DESC: دستگاه خروجی html را توصیف می‌کند.
/usr/share/groff/1.24.1/font/devhtml/F: قلم شناخته‌شده با عنوان F را در دستگاه html توصیف می‌کند.
/usr/share/groff/1.24.1/tmac/html.tmac: نگاشت‌های قلم، نویسه‌های خاص و رنگ‌ها را برای استفاده با دستگاه خروجی html تعریف می‌کند. این فایل هنگام انتخاب هر یک از دستگاه‌های خروجی html یا xhtml به صورت خودکار توسط troffrc بارگذاری می‌شود.
/usr/share/groff/1.24.1/tmac/html-end.tmac: پیکربندی و راه‌اندازی دستگاه خروجی html را نهایی می‌کند. این فایل هنگام انتخاب هر یک از دستگاه‌های خروجی html یا xhtml به صورت خودکار توسط troffrc-end بارگذاری می‌شود.

دستور grohtml از فایل‌های موقت استفاده می‌کند. برای آگاهی از جزئیات مربوط به محل ایجاد این فایل‌ها، به groff(1) مراجعه کنید.

اشکالات (BUGS)

دستور grohtml همچنان یک کد در مرحله بتا (آزمایشی) است.

دستور grohtml به‌طور واقعی از خط‌تیره‌گذاری (hyphenation) پشتیبانی نمی‌کند، اما می‌توانید آن را فریب دهید تا خطوط ورودی طولانی را خط‌تیره‌گذاری کند که در این صورت ممکن است در خروجی HTML کلمه‌ای خط‌تیره‌دار به همراه یک فاصله اما بدون شکست خط ظاهر شود.

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

groff(1), troff(1), groff_font(5)