.TH grohtml 1 "2026-03-15" "groff 1.24.1"
.SH "نام (NAME)"
grohtml, post\-grohtml, pre\-grohtml \- درایور خروجی groff برای HTML
.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
.\" Copyright (C) 1999-2024 Free Software Foundation, Inc.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of
.\" this manual under the conditions for verbatim copying, provided that
.\" the entire resulting derived work is distributed under the terms of
.\" a permission notice identical to this one.
.\"
.\" Permission is granted to copy and distribute translations of this
.\" manual into another language, under the above conditions for
.\" modified versions, except that this permission notice may be
.\" included in translations approved by the Free Software Foundation
.\" instead of in the original English.
.
.
.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
.do nr *groff_grohtml_1_man_C \n[.cp]
.cp 0
.
.\" Define fallback for groff 1.23's MR macro if the system lacks it.
.nr do-fallback 0
.if !\n(.f           .nr do-fallback 1 \" mandoc
.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
.if \n[do-fallback]  \{\
.  de MR
.    ie \\n(.$=1 \
.      I \%\\$1
.    el \
.      IR \%\\$1 (\\$2)\\$3
.  .
.\}
.rr do-fallback
.
.
.\" ====================================================================
.SH "خلاصه دستور (SYNOPSIS)"
.\" ====================================================================
.
.SY pre\-grohtml
.RB [ \-epV ]
.RB [ \-a\~\c
.IR anti-aliasing-text-bits ]
.RB [ \-D\~\c
.IR image-directory ]
.RB [ \-F\~\c
.IR font-directory ]
.RB [ \-g\~\c
.IR anti-aliasing-graphic-bits ]
.RB [ \-i\~\c
.IR resolution ]
.RB [ \-I\~\c
.IR image-stem ]
.RB [ \-o\~\c
.IR image-vertical-offset ]
.RB [ \-x\~\c
.IR  html-dialect ]
.I troff-command
.I troff-argument
\&.\|.\|.
.YS
.
.
.P
.SY pre\-grohtml
.B \-\-help
.YS
.
.
.P
.SY pre\-grohtml
.B \-v
.YS
.
.SY pre\-grohtml
.B \%\-\-version
.YS
.
.
.P
.SY post\-grohtml
.RB [ \-bCGhlnrVy ]
.RB [ \-F\~\c
.IR font-directory ]
.RB [ \-j\~\c
.IR output-stem ]
.RB [ \-k\~\c
.IR encoding ]
.RB [ \-s\~\c
.IR base-point-size ]
.RB [ \-S\~\c
.IR heading-level ]
.RB [ \-x\~\c
.IR html-dialect ]
.RI [ file\~ .\|.\|.]
.YS
.
.
.P
.SY post\-grohtml
.B \-\-help
.YS
.
.
.P
.SY post\-grohtml
.B \-v
.YS
.
.SY post\-grohtml
.B \%\-\-version
.YS
.
.
.\" ====================================================================
.SH "توضیحات (DESCRIPTION)"
.\" ====================================================================
.
پشتیبانی سامانه
.I GNU roff
از HTML شامل یک پیش‌پردازنده به نام
.IR \%pre\-grohtml
و یک درایور خروجی به نام
.IR \%post\-grohtml
است؛ این دو ابزار در کنار یکدیگر، اسناد
.MR roff 7
را به HTML تبدیل می‌کنند.
.
از آنجا که این درایور خروجی (به‌طور منحصربه‌فرد) نیازمند یک پیش‌پردازنده است، کاربران باید
.I \%grohtml
را از طریق دستور
.MR groff 1
با گزینه‌های
.B \-Thtml
یا
.B \%\-Txhtml
فراخوانی نمایند.
.
(در این پیکربندی نصب،
.B \%ps
دستگاه خروجی پیش‌فرض است.)
.
از گزینه
.B \-P
در
.I groff
برای ارسال هر یک از گزینه‌های نشان‌داده‌شده در بالا به
.I \%grohtml
استفاده کنید.
.
اگر هیچ عملوندی مشخص نشود، یا اگر
.I file
برابر با
.RB \[lq] \- \[rq]
باشد،
.I \%grohtml
جریان ورودی استاندارد را می‌خواند.
.
این برنامه در جریان خروجی استاندارد می‌نویسد.
.
.
.P
دستور
.I \%grohtml
برنامه
.I groff
را دو بار فراخوانی می‌کند.
.
در دور نخست، پیش‌پردازنده
.I \%pre\-grohtml
تصاویر، معادلات و جدول‌ها را به شکل تصاویری در قالب PostScript با استفاده از دستگاه خروجی
.B ps
رندر می‌کند.
.
در دور دوم، درایور خروجی
.I \%post\-grohtml
خروجی
.MR \%troff 1
را به HTML ترجمه می‌نماید.
.
.
.P
دستور
.I \%grohtml
خروجی با کدگذاری \%UTF-8 تولید می‌کند
(البته گزینه
.B \-k
را نیز ببینید)
و برای بیشتر نویسه‌های یونیکد غیرترکیبی و فراتر از لاتین پایه، ارجاعات نویسه‌ای HTML ایجاد می‌نماید.
.\" XXX: Exception: degree sign (U+00B0).  Why?
.
با وجود این، ممکن است
.I groff
در صورتی که نویسه‌های خاص ناشناخته در طول دور نخست پیدا نشوند، هشدارهایی صادر کند.
.
می‌توانید این هشدارها را نادیده بگیرید، مگر اینکه نویسه‌های خاص درون یک جدول یا معادله قرار داشته باشند.
.\" XXX: or pic(1) description?
.
.
.\" ====================================================================
.SS "قلم‌ها (Typefaces)"
.\" ====================================================================
.
دستور
.I \%grohtml
از چهار سبک استاندارد پشتیبانی می‌کند:
.B R
(معمولی یا roman)،
.B I
.RI ( مورب یا italic )،
.B B
.RB ( توپر یا bold )
و
.B BI
(\f[BI]توپر و مورب یا bold-italic\f[]).
.
قلم‌ها در خانواده‌های
.B T
و
.B C
دسته‌بندی شده‌اند که برای هر سبک عضوی دارند.
.
.
.RS
.TP
.B TR
قلم Times معمولی (Times roman)
.
.TQ
.B TI
قلم Times مورب (Times italic)
.
.TQ
.B TB
قلم Times توپر (Times bold)
.
.TQ
.B TBI
قلم Times توپر و مورب (Times bold-italic)
.
.TQ
.B CR
قلم Courier معمولی (Courier roman)
.
.TQ
.B CI
قلم Courier مورب (Courier italic)
.
.TQ
.B CB
قلم Courier توپر (Courier bold)
.
.TQ
.B CBI
قلم Courier توپر و مورب (Courier bold-italic)
.RE
.
.
.P
یک قلم ویژه به نام
.BR S
نیز برای سازگاری با اسناد
.I roff
که انتظار دارند این قلم همواره در دسترس باشد فراهم شده است.
.
.
.P
علاوه بر این،
.I \%grohtml
از یک طرح نام‌گذاری برای قلم‌های آسیای شرقی پشتیبانی می‌کند که میان
.MR gropdf 1 ،
.MR grops 1
و
.MR grotty 1
مشترک است.
.
.
.RS
.TP
.B CSH
چینی ساده‌شده، سبک Hei
.
.TQ
.B CSS
چینی ساده‌شده، سبک Song
.
.TQ
.B CTH
چینی سنتی، سبک Hei
.
.TQ
.B CTS
چینی سنتی، سبک Song
.
.TQ
.B JPG
ژاپنی، سبک گوتیک (Gothic)
.
.TQ
.B JPM
ژاپنی، سبک مینچو (Mincho)
.
.TQ
.B KOG
کره‌ای، سبک گوتیک (Gothic)
.
.TQ
.B KOM
کره‌ای، سبک مینچو (Mincho)
.RE
.
.
.\" ====================================================================
.SS "فایل‌های توصیف قلم (Font description files)"
.\" ====================================================================
.
فایل‌های توصیف قلم مورد استفاده در
.I \%grohtml
مجموعه گلیف یکسانی را در بخش‌های
.B charset
خود ارائه می‌دهند.
.
نگاه کنید به
.MR groff_font 5 .
.
.
.\" ====================================================================
.SS "وابستگی‌ها (Dependencies)"
.\" ====================================================================
.
پیش‌پردازنده
.I \%pre\-grohtml
هر زمان که در ورودی با یک معادله
.IR \%eqn ،
یک جدول
.I \%tbl
یا یک تصویر
.I \%pic
مواجه شود، تصویری ایجاد می‌کند.
.
بنابراین
.I \%grohtml
ممکن است به عنوان بخشی از عملیات خود چندین دستور را اجرا کند.
.
این دستورات شامل ابزارهای \%Netpbm مانند
.IR \%pamcut ،
.IR \%pnmcrop
و
.IR \%pnmtopng ،
و همچنین ابزارهای \%Ghostscript مانند
.I \%gs
و
.IR \%ps2ps
هستند.
.
.
.\" ====================================================================
.SH "گزینه‌ها (OPTIONS)"
.\" ====================================================================
.
گزینه
.B \-\-help
پیام راهنمای استفاده را نمایش می‌دهد، در حالی که گزینه‌های
.B \-v
و
.B \%\-\-version
اطلاعات نسخه را نشان می‌دهند؛ تمامی این گزینه‌ها پس از نمایش خارج می‌شوند.
.
.
.TP
.BI \-a \~anti-aliasing-text-bits
تعداد بیت‌های اطلاعات هموارسازی (antialiasing) مورد استفاده برای متن هنگام تولید تصاویر PNG.
.
مقدار پیش‌فرض
.RB برابر\~ 4
است، اما مقادیر
.BR 0 ،
.BR 1
و
.B 2
نیز معتبر هستند.
.
نسخه
.I gs
سیستم شما باید از گزینه
.B \%\-dTextAlphaBits
پشتیبانی کند تا بتوان از هموارسازی بهره برد.
.\" XXX: How antiquated are the ones that don't?  Get rid of this?
.
مقدار
.RB برابر\~ 0
مانع ارسال دستورات هموارسازی از سوی
.I \%grohtml
به
.I gs
می‌شود.
.
.
.TP
.B \-b
رنگ پس‌زمینه را روی سفید مقداردهی اولیه می‌کند.
.
.
.TP
.B \-C
از تولید کامنت HTML مربوط به \[lq]CreationDate:\[rq] جلوگیری می‌کند.
.
.
.TP
.BI \-D \~image-directory
به
.I \%grohtml
دستور می‌دهد تمام فایل‌های تصویری را در پوشه
.I image-directory
قرار دهد.
.
.
.TP
.B \-e
به
.I \%eqn
هدایت می‌کند تا MathML تولید نماید.
.
.
.IP
این گزینه نباید به صورت دستی تعیین شود؛
این گزینه بسته به اینکه آیا به
.I groff
گزینه
.B \-Thtml
داده شده یا
.BR \%\-Txhtml ،
توسط
.I groff
تنظیم و ایجاد می‌شود.
.
.
.TP
.BI \-F \~font-directory
پوشه
.RI font-directory /dev name
را به ابتدای مسیر جستجو برای فایل‌های توصیف قلم و دستگاه اضافه می‌کند؛
در اینجا
.I name
نام دستگاه است که معمولاً
.B html
می‌باشد.
.
.
.TP
.BI \-g \~anti-aliasing-graphic-bits
تعداد بیت‌های اطلاعات هموارسازی مورد استفاده برای بخش‌های گرافیکی هنگام تولید تصاویر PNG.
.
مقدار پیش‌فرض
.RB برابر\~ 4
است، اما مقادیر
.BR 0 ،
.BR 1
و
.B 2
نیز معتبر هستند.
.
نسخه
.I gs
سیستم شما باید از گزینه
.B \%\-dGraphicAlphaBits
پشتیبانی کند تا بتوان از هموارسازی بهره برد.
.\" XXX: How antiquated are the ones that don't?  Get rid of this?
.
مقدار
.RB برابر\~ 0
مانع ارسال دستورات هموارسازی از سوی
.I \%grohtml
به
.I gs
می‌شود.
.
.
.TP
.B \-G
از تولید کامنت HTML مربوط به \[lq]Creator:\[rq] جلوگیری می‌کند.
.
.
.TP
.B \-h
عناوین بخش‌ها را به جای استفاده از عناصر
.B H
در HTML، با استفاده از عناصر
.B B
و افزایش اندازه قلم تولید می‌کند.
.
.
.TP
.BI \-i \~resolution
وضوح تصویر (رزولوشن) را بر حسب پیکسل بر اینچ تنظیم می‌کند؛ مقدار پیش‌فرض
.RB برابر\~ 100
است.
.
.
.TP
.BI \-I \~image-stem
پیشوند (ریشه) نام فایل‌های تصویری را مشخص می‌کند.
.
در صورت عدم تعیین،
.I \%grohtml
از
.IR \%grohtml\- XXXXX
(که در آن
.I XXXXX
شناسه فرایند است) استفاده می‌کند.
.
یک خط تیره به انتهای ریشه افزوده می‌شود تا آن را از شماره تصویر پس از خود جدا سازد.
.
.
.TP
.BI \-j \~output-stem
به
.I \%grohtml
دستور می‌دهد خروجی HTML را به چند فایل تقسیم کند.
.
خروجی در هر عنوان بخش
(البته گزینه
.B \-S
در زیر را ببینید)
در یک فایل جدید با نام
.IR output-stem\- n .html
نوشته می‌شود.
.
.
.br
.ne 4v
.TP
.BI \-k \~encoding
کدگذاری نویسه مورد استفاده در سند تولید‌شده را انتخاب می‌کند که بر کدگذاری اعلام‌شده در مقدمه و همچنین ساختار ارجاعات موجودیت‌های نویسه‌ای تأثیر می‌گذارد.
.
.\" XXX: Don't present "mixed" until we know what it's for.
مقادیر معتبر شامل \[lq]ASCII\[rq] و \[lq]UTF\-8\[rq] هستند.
.
مقدار پیش‌فرض \[lq]UTF-8\[rq] است.
.
.
.TP
.B \-l
تولید خودکار پیوندهای بخش‌ها در بالای سند را غیرفعال می‌کند.
.
.
.TP
.B \-n
هر زمان که یک عنوان بخش یا عنوان شماره‌دار پیدا شود، لنگرهای (anchors) ساده برای آن عنوان تولید می‌کند.
.
بدون این گزینه، مقدار لنگر همان متن عنوان خواهد بود.
.
اگر یک عنوان حاوی کاراکتر \[lq]?\[rq] باشد، این موضوع در نسخه‌های قدیمی برخی از مرورگرها می‌تواند مشکل ایجاد کند.
.
در صورتی که یک عنوان حاوی تصویر باشد، این ویژگی به طور خودکار فعال می‌شود.
.
.
.TP
.BI \-o \~image-vertical-offset
میزان جابجایی (آفست) عمودی تصاویر را بر حسب پوینت مشخص می‌کند.
.
.
.TP
.B \-p
پیشرفت رندر صفحه را در جریان خطای استاندارد نمایش می‌دهد.
.
دستور
.I \%grohtml
تنها زمانی شماره صفحه را نمایش می‌دهد که نیاز به تولید تصویر باشد.
.
.
.TP
.B \-r
خط افقی سربرگ و پاورقی خودکار
(خط افقی یا rule در HTML)
را غیرفعال می‌کند.
.
.
.TP
.BI \-s \~base-type-size
اندازه پایه قلم سند را بر حسب پوینت تنظیم می‌کند.
.
هنگامی که این اندازه در سند مبدأ استفاده شود، مطابق با اندازه پایه قلم در HTML خواهد بود.
.
هر دو پوینت افزایش در اندازه سند مبدأ، یک عنصر
.RB \[lq] big \[rq]
تولید می‌کند و برعکس با دو پوینت کاهش، یک عنصر
.RB \[lq] small \[rq]
تولید می‌شود.
.
.
.TP
.BI \-S \~heading-level
هنگام تقسیم خروجی HTML
(گزینه
.B \-j
در بالا را ببینید)،
خروجی را در هر سطح عنوان تو در تو که توسط
.I heading-level
یا بالاتر تعریف شده است تقسیم می‌کند.
.
مقدار پیش‌فرض
.B 1
است.
.
.
.TP
.B \-V
یک دکمه اعتبارسنجی XHTML یا HTML در پایین هر صفحه از سند ایجاد می‌کند.
.
.
.TP
.BI \-x \~html-dialect
گویش HTML را انتخاب می‌کند.
.
در حال حاضر،
.I html-dialect
باید یا رقم
.RB \~ 4
یا حرف
.RB \~ x
باشد که به ترتیب نشان می‌دهد
.I \%grohtml
باید HTML\~4 تولید کند یا XHTML.
.
.
.IP
این گزینه نباید به صورت دستی تعیین شود؛
این گزینه بسته به اینکه آیا به
.I groff
گزینه
.B \-Thtml
داده شده یا
.BR \%\-Txhtml ،
توسط
.I groff
تنظیم و ایجاد می‌شود.
.
.
.TP
.B \-y
یک امضای راست‌چین
.I groff
در انتهای سند ایجاد می‌کند
(تنها در صورتی که گزینه
.B \-V
نیز مشخص شده باشد).
.
.
.\" ====================================================================
.SH "وضعیت خروج (EXIT STATUS)"
.\" ====================================================================
.
برنامه‌های
.I \%pre\-grohtml
و
.I \%post\-grohtml
هر یک در صورت اجرای موفقیت‌آمیز با وضعیت
.RB \~ 0 ،
در صورتی که نتوانند آرگومان‌های خط فرمان خود را تفسیر کنند با وضعیت
.RB \~ 2
و در صورت مواجهه با خطا در طول عملیات با وضعیت
.RB \~ 1
خارج می‌شوند.
.
.
.\" ====================================================================
.SH "محیط (ENVIRONMENT)"
.\" ====================================================================
.
.TP
.I GROFF_FONT_PATH
دایرکتوری‌هایی را فهرست می‌کند که باید در آن‌ها به دنبال
.IR devhtml ،
دایرکتوری فایل‌های توصیف قلم و دستگاه متعلق به
.IR grohtml ،
جستجو شود.
.
نگاه کنید به
.MR \%troff 1
و
.MR groff_font 5 .
.
.
.TP
.I SOURCE_DATE_EPOCH
یک برچسب زمانی
(بیان‌شده بر حسب ثانیه‌های سپری‌شده از مبدأ یونیکس یا Unix epoch)
جهت استفاده به عنوان برچسب زمانی ایجاد خروجی به جای زمان فعلی.
.
این زمان با استفاده از
.MR gmtime 3
و
.MR asctime 3
به قالبی خوانا برای انسان تبدیل شده و در یک کامنت HTML ذخیره می‌شود.
.
.
.TP
.I TZ
منطقه زمانی مورد استفاده هنگام تبدیل زمان فعلی به قالبی خوانا برای انسان؛
نگاه کنید به
.MR tzset 3 .
اگر
.I SOURCE_DATE_EPOCH
استفاده شود، همیشه با استفاده از UTC به قالبی خوانا برای انسان تبدیل می‌شود.
.
.
.\" ====================================================================
.SH "فایل‌ها (FILES)"
.\" ====================================================================
.
.TP
.I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devhtml/\:DESC
دستگاه خروجی
.B html
را توصیف می‌کند.
.
.
.TP
.IR /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devhtml/ F
قلم شناخته‌شده با عنوان
.RI \~ F
را در دستگاه
.B html
توصیف می‌کند.
.
.
.TP
.I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:html\:.tmac
نگاشت‌های قلم، نویسه‌های خاص و رنگ‌ها را برای استفاده با دستگاه خروجی
.B html
تعریف می‌کند.
.
این فایل هنگام انتخاب هر یک از دستگاه‌های خروجی
.B html
یا
.B xhtml
به صورت خودکار توسط
.I \%troffrc
بارگذاری می‌شود.
.
.
.TP
.I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:html\-end\:.tmac
پیکربندی و راه‌اندازی دستگاه خروجی
.B html
را نهایی می‌کند.
.
این فایل هنگام انتخاب هر یک از دستگاه‌های خروجی
.B html
یا
.B xhtml
به صورت خودکار توسط
.I \%troffrc\-end
بارگذاری می‌شود.
.
.
.P
دستور
.I \%grohtml
از فایل‌های موقت استفاده می‌کند.
.
برای آگاهی از جزئیات مربوط به محل ایجاد این فایل‌ها، به
.MR groff 1
مراجعه کنید.
.
.
.\" ====================================================================
.SH "اشکالات (BUGS)"
.\" ====================================================================
.
دستور
.I \%grohtml
همچنان یک کد در مرحله بتا (آزمایشی) است.
.
.
.PP
دستور
.I \%grohtml
به‌طور واقعی از خط‌تیره‌گذاری (hyphenation) پشتیبانی نمی‌کند، اما می‌توانید آن را فریب دهید تا خطوط ورودی طولانی را خط‌تیره‌گذاری کند که در این صورت ممکن است در خروجی HTML کلمه‌ای خط‌تیره‌دار به همراه یک فاصله اما بدون شکست خط ظاهر شود.
.
.
.\" ====================================================================
.SH "همچنین ببینید (SEE ALSO)"
.\" ====================================================================
.
.\" IR afmtodit (1),
.MR groff 1 ,
.MR \%troff 1 ,
.\" IR psbb (1), \" XXX: what is this?
.\" IR groff_out (5),
.\" IR groff_char (7),
.MR groff_font 5
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
.cp \n[*groff_grohtml_1_man_C]
.do rr *groff_grohtml_1_man_C
.
.
.\" Local Variables:
.\" fill-column: 72
.\" mode: nroff
.\" End:
.\" vim: set filetype=groff textwidth=72: