.\"
.\" Manual page for HTMLDOC, a HTML document processing program.
.\"
.\" Copyright 2011-2025 by Michael R Sweet.
.\" Copyright 1997-2010 by msweet.org.
.\"
.\" This program is free software.  Distribution and use rights are outlined
.\" in the file "COPYING".
.\"
.TH htmldoc 1 "HTMLDOC 1.9.22" "2025-12-23" "Michael R Sweet"
.SH "نام (NAME)"
htmldoc \- تبدیل فایل‌های مبدأ html به فرمت‌های html، postscript یا pdf
.SH "خلاصه دستور (SYNOPSIS)"
htmldoc [options] filename1.{html,md} [ ... filenameN.{html,md} ]
.LP
htmldoc [options] \-
.LP
htmldoc [filename.book]
.SH "توضیحات (DESCRIPTION)"
برنامه
.BR Htmldoc (1)
فایل‌های منبع HTML و Markdown را به فایل‌های نمایه شده HTML، PostScript یا قالب سند قابل حمل (PDF) که قابل مشاهده آنلاین یا چاپ هستند تبدیل می‌کند.
بدون مشخص کردن هیچ گزینه‌ای، یک سند HTML در خروجی استاندارد (stdout) تولید می‌شود.
.LP
شکل دوم دستور
.B htmldoc
ورودی HTML را از ورودی استاندارد (stdin) می‌خواند، که به شما امکان می‌دهد از
.B htmldoc
به عنوان یک فیلتر استفاده کنید.
.LP
شکل سوم دستور
.B htmldoc
یک رابط کاربری گرافیکی (GUI) را اجرا می‌کند که به شما امکان می‌دهد گزینه‌ها را به صورت تعاملی تغییر داده و اسناد را تولید نمایید.
.SH "اشتباهات رایج (COMMON MISTAKES)"
دو نوع فایل HTML وجود دارد - اسناد ساختاریافته با استفاده از سرآیندها (H1، H2 و غیره) که
.B htmldoc
آن‌ها را «کتاب» (books) می‌نامد، و اسناد بدون ساختار که از سرآیندها استفاده نمی‌کنند که
.B htmldoc
آن‌ها را «صفحات وب» (web pages) می‌نامد.
.LP
یک اشتباه بسیار متداول این است که تلاش شود یک صفحه وب با استفاده از دستور زیر تبدیل گردد:
.nf
    htmldoc \-f filename.pdf filename.html
.fi
که این کار احتمالاً یک فایل PDF فاقد هرگونه صفحه تولید خواهد کرد.
برای تبدیل فایل‌های صفحات وب، شما
.B باید
از گزینه‌های
.I \-\-webpage
یا
.I \-\-continuous
در خط فرمان استفاده کنید، یا در برگه ورودی رابط گرافیکی گزینه
.I Web Page
یا
.I Continuous
را انتخاب نمایید.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های خط فرمان زیر توسط
.BR htmldoc
پشتیبانی می‌شوند:
.TP 5
.BI \-\-batch " filename.book"
فایل کتاب مشخص‌شده را بدون باز کردن رابط گرافیکی تولید می‌کند.
.TP 5
.BI \-\-bodycolor " color"
رنگ پس‌زمینه را برای تمام صفحات تعیین می‌کند.
.TP 5
.BI \-\-bodyfont " {courier,helvetica,monospace,sans,serif,times}"
.TP 5
.BI \-\-textfont " {courier,helvetica,monospace,sans,serif,times}"
قلم پیش‌فرض را برای تمام متن‌های معمولی تعیین می‌کند.
.TP 5
.BI \-\-bodyimage " filename"
تصویر پس‌زمینه‌ای را که در تمام صفحات تکرار (tile) می‌شود تعیین می‌کند.
.TP 5
.B \-\-book
مشخص می‌کند که منابع HTML ساختاریافته هستند (سرآیندها، فصل‌ها و غیره).
.TP 5
.BI \-\-bottom " margin"
حاشیه پایین را بر حسب پوینت (بدون پسوند یا ##pt)، اینچ (##in)، سانتی‌متر (##cm)، یا میلی‌متر (##mm) تعیین می‌کند.
.TP 5
.BI \-\-charset " {cp-nnnn,iso-8859-1,...,iso-8859-15,utf-8}"
مجموعه نویسه (character set) مورد استفاده برای خروجی را مشخص می‌کند.
نکته: پشتیبانی از UTF-8 محدود به ۱۲۸ نویسه اول یونیکد یافت‌شده در ورودی است.
.TP 5
.B \-\-color
مشخص می‌کند که خروجی PostScript یا PDF باید رنگی باشد.
.TP 5
.B \-\-continuous
مشخص می‌کند که منابع HTML بدون ساختار هستند (صفحات وب ساده). هیچ شکست صفحه‌ای بین فایل‌ها یا URLها در خروجی درج نمی‌شود.
.TP 5
.BI \-\-datadir " directory"
محل فایل‌های داده
.B htmldoc
را مشخص می‌کند، که معمولاً
.I /usr/share/htmldoc
یا
.I C:/Program Files/HTMLDOC
است.
.TP 5
.B \-\-duplex
مشخص می‌کند که خروجی باید برای چاپ دورو قالب‌بندی شود.
.TP 5
.BI \-\-effectduration " {0.1...10.0}"
مدت زمان جلوه‌های انتقال صفحه PDF را بر حسب ثانیه مشخص می‌کند.
.TP 5
.B \-\-embedfonts
مشخص می‌کند که فونت‌ها باید در خروجی PDF و PostScript جاسازی (embed) شوند.
.TP 5
.B \-\-encryption
رمزنگاری فایل‌های PDF را فعال می‌کند.
.TP 5
.BI \-\-fontsize " size"
اندازه فونت پیش‌فرض متن بدنه را مشخص می‌کند.
.TP 5
.BI \-\-fontspacing " spacing"
فاصله خطوط پیش‌فرض متن بدنه را مشخص می‌کند. فاصله خطوط ضریبی از اندازه فونت است؛ بنابراین مقدار 1.2 فضای بین خطوط را ۲۰٪ افزایش می‌دهد.
.TP 5
.BI \-\-footer " fff"
پاورقی مورد استفاده در صفحات بدنه را تنظیم می‌کند. بخش
.B قالب‌های سربرگ/پاورقی (HEADER/FOOTER FORMATS)
در زیر را مشاهده کنید.
.TP 5
.BI \-\-format " format"
.TP 5
.BI \-t " format"
قالب خروجی را تعیین می‌کند: epub، html، htmlsep (فایل‌های HTML مجزا برای هر سرآیند در جدول فهرست)، ps یا ps2 (پست‌اسکریپت سطح ۲)، ps1 (پست‌اسکریپت سطح ۱)، ps3 (پست‌اسکریپت سطح ۳)، pdf11 (پی‌دی‌اف ۱.۱/Acrobat 2.0)، pdf12 (پی‌دی‌اف ۱.۲/Acrobat 3.0)، pdf یا pdf13 (پی‌دی‌اف ۱.۳/Acrobat 4.0)، یا pdf14 (پی‌دی‌اف ۱.۴/Acrobat 5.0).
.TP 5
.B \-\-gray
مشخص می‌کند که خروجی PostScript یا PDF باید سیاه و سفید (grayscale) باشد.
.TP 5
.BI \-\-header " fff"
سربرگ صفحه را برای استفاده در صفحات بدنه تعیین می‌کند. بخش
.B قالب‌های سربرگ/پاورقی (HEADER/FOOTER FORMATS)
در زیر را ببینید.
.TP 5
.BI \-\-header1 " fff"
سربرگ صفحه را برای اولین صفحه بدنه/فصل تعیین می‌کند. بخش
.B قالب‌های سربرگ/پاورقی (HEADER/FOOTER FORMATS)
در زیر را ببینید.
.TP 5
.BI \-\-headfootfont " font"
فونت مورد استفاده در سربرگ و پاورقی را تعیین می‌کند.
.TP 5
.BI \-\-headfootsize " size"
اندازه فونت مورد استفاده در سربرگ و پاورقی را تعیین می‌کند.
.TP 5
.BI \-\-headingfont " typeface"
نوع قلم مورد استفاده برای سرآیندها را مشخص می‌کند.
.TP 5
.B \-\-help
خلاصه‌ای از گزینه‌های خط فرمان را نمایش می‌دهد.
.TP 5
.BI \-\-helpdir " directory"
مسیر دایرکتوری راهنمای آنلاین
.B htmldoc
را مشخص می‌کند که معمولاً
.I /usr/share/doc/htmldoc
یا
.I C:/Program Files/HTMLDOC/DOC
است.
.TP 5
.BI \-\-hfimageN " filename"
تصویری را (شماره‌گذاری‌شده از ۱ تا ۱۰) برای استفاده در سربرگ یا پاورقی یک سند PostScript یا PDF مشخص می‌کند.
.TP 5
.BI \-\-jpeg [=quality]
سطح فشرده‌سازی JPEG را برای تصاویر بزرگ تنظیم می‌کند. مقدار 0 فشرده‌سازی JPEG را غیرفعال می‌سازد.
.TP 5
.BI \-\-left " margin"
حاشیه چپ را بر حسب پوینت (بدون پسوند یا ##pt)، اینچ (##in)، سانتی‌متر (##cm)، یا میلی‌متر (##mm) تعیین می‌کند.
.TP 5
.BI \-\-letterhead " filename"
تصویری را به عنوان سربرگ رسمی (letterhead) در هدر یا فوتر سند PostScript یا PDF مشخص می‌کند.
توجه داشته باشید که لازم است از گزینه‌های
.I \-\-header، \-\-header1
و/یا
.I \-\-footer
همراه با پارامتر
.I L
استفاده کنید یا از کامنت‌های متناظر در صفحه HTML بهره ببرید تا تصویر سربرگ رسمی نمایش داده شود.
.TP 5
.BI \-\-linkcolor " color"
رنگ پیوندها را تنظیم می‌کند.
.TP 5
.B \-\-links
تولید پیوندها را در فایل‌های PDF فعال می‌کند (پیش‌فرض).
.TP 5
.BI \-\-linkstyle " {plain,underline}"
سبک پیوندها را تعیین می‌کند.
.TP 5
.BI \-\-logoimage " filename"
تصویری را به عنوان نشان‌واره (لوگو) در سربرگ یا پاورقی سند PostScript یا PDF، و در نوار ناوبری سند HTML مشخص می‌کند.
توجه داشته باشید که باید از گزینه‌های
.I \-\-header، \-\-header1
و/یا
.I \-\-footer
همراه با پارامتر
.I l
استفاده نمایید یا از کامنت‌های متناظر در صفحه HTML بهره ببرید تا تصویر لوگو نمایش داده شود.
.TP 5
.B \-\-no-compression
فشرده‌سازی فایل‌های PostScript یا PDF را غیرفعال می‌کند.
.TP 5
.B \-\-no-duplex
چاپ دورو را غیرفعال می‌کند.
.TP 5
.B \-\-no-embedfonts
.br
مشخص می‌کند که فونت‌ها نباید در خروجی PDF و PostScript جاسازی شوند.
.TP 5
.B \-\-no-encryption
رمزنگاری سند را غیرفعال می‌کند.
.TP 5
.B \-\-no-jpeg
فشرده‌سازی JPEG تصاویر بزرگ را غیرفعال می‌کند.
.TP 5
.B \-\-no-links
تولید پیوندها را در سند PDF غیرفعال می‌کند.
.TP 5
.B \-\-no-numbered
شماره‌گذاری خودکار سرآیندها را غیرفعال می‌کند.
.TP 5
.B \-\-no-pscommands
تولید دستورات setpagedevice در PostScript را غیرفعال می‌کند.
.TP 5
.B \-\-no-strict
بررسی سخت‌گیرانه ورودی HTML را غیرفعال می‌کند.
.TP 5
.B \-\-no-title
تولید صفحه عنوان را غیرفعال می‌کند.
.TP 5
.B \-\-no-toc
تولید جدول فهرست مطالب را غیرفعال می‌کند.
.TP 5
.B \-\-numbered
تمام سرآیندهای سند را شماره‌گذاری می‌کند.
.TP 5
.BI \-\-nup " pages"
تعداد صفحاتی را که در هر صفحه خروجی قرار می‌گیرند تعیین می‌کند. مقادیر معتبر شامل 1، 2، 4، 6، 9 و 16 هستند.
.TP 5
.BI \-\-outdir " directory"
.TP 5
.BI \-d " directory"
مشخص می‌کند که خروجی باید در چندین فایل در یک دایرکتوری ذخیره شود (با خروجی PDF سازگار نیست).
.TP 5
.BI \-\-outfile " filename"
.TP 5
.BI \-f " filename"
مشخص می‌کند که خروجی باید در یک فایل واحد نوشته شود.
.TP 5
.BI \-\-owner-password " password"
رمز عبور مالک (owner password) را برای فایل‌های PDF رمزنگاری‌شده تعیین می‌کند.
.TP 5
.BI \-\-pageduration " {1.0...60.0}"
مدت زمان نمایش هر صفحه را در سند PDF تعیین می‌کند.
.TP 5
.BI \-\-pageeffect " effect"
جلوه انتقال صفحه را برای تمام صفحات مشخص می‌کند؛ این ویژگی توسط تمام برنامه‌های نمایش PDF شرکت Adobe نادیده گرفته می‌شود.
.TP 5
.BI \-\-pagelayout " {single,one,twoleft,tworight}"
چیدمان اولیه صفحات را برای فایل PDF تعیین می‌کند.
.TP 5
.BI \-\-pagemode " {document,outlines,fullscreen}"
حالت نمایش اولیه را برای فایل PDF مشخص می‌کند.
.TP 5
.BI \-\-path " \"dir1;dir2;dir3;...;dirN\""
مسیر جستجوی فایل‌ها در یک سند را مشخص می‌کند.
.TP 5
.BI \-\-permissions " permission[,permission,...]"
مجوزهای سند را برای فایل‌های PDF رمزنگاری‌شده تعیین می‌کند. مجوزهای شناخته‌شده عبارتند از: all، none، annotate، no-annotate، copy، no-copy، modify، no-modify، print و no-print. چند مجوز را با کاما جدا کنید.
.TP 5
.BI \-\-pre\-indent " distance"
میزان تورفتگی متن پیش‌فرمت‌شده را بر حسب پوینت (بدون پسوند یا ##pt)، اینچ (##in)، سانتی‌متر (##cm)، یا میلی‌متر (##mm) مشخص می‌کند.
.TP 5
.B \-\-pscommands
مشخص می‌کند که دستورات setpagedevice در PostScript باید در خروجی گنجانده شوند.
.TP 5
.B \-\-quiet
نمایش تمام پیام‌ها، حتی پیام‌های خطا را متوقف می‌کند.
.TP 5
.BI \-\-referer " url"
نشانی URL ارسال‌شده در فیلد Referer: در درخواست‌های HTTP را مشخص می‌کند.
.TP 5
.BI \-\-right " margin"
حاشیه راست را بر حسب پوینت (بدون پسوند یا ##pt)، اینچ (##in)، سانتی‌متر (##cm)، یا میلی‌متر (##mm) تعیین می‌کند.
.TP 5
.BI \-\-size " pagesize"
اندازه صفحه را با استفاده از نام‌های استاندارد یا بر حسب پوینت (بدون پسوند یا ##x##pt)، اینچ (##x##in)، سانتی‌متر (##x##cm)، یا میلی‌متر (##x##mm) تعیین می‌کند. اندازه‌های استاندارد شناخته‌شده عبارتند از "letter" (8.5x11in)، "legal" (8.5x14in)، "a4" (210x297mm) و "universal" (8.27x11in).
.TP 5
.B \-\-strict
بررسی سخت‌گیرانه ورودی HTML را فعال می‌کند.
.TP 5
.BI \-\-textcolor " color"
رنگ پیش‌فرض تمامی متون را تعیین می‌کند.
.TP 5
.B \-\-title
تولید صفحه عنوان را فعال می‌کند.
.TP 5
.BI \-\-titlefile " filename"
.TP 5
.BI \-\-titleimage " filename"
فایل مورد استفاده برای صفحه عنوان را مشخص می‌کند.
اگر فایل یک تصویر باشد، صفحه عنوان به طور خودکار با استفاده از متادیتای سند و تصویر عنوان تولید می‌شود.
.TP 5
.BI \-\-tocfooter " fff"
پاورقی مورد استفاده در صفحات فهرست مطالب را تعیین می‌کند. بخش
.B قالب‌های سربرگ/پاورقی (HEADER/FOOTER FORMATS)
در زیر را ببینید.
.TP 5
.BI \-\-tocheader " fff"
سربرگ مورد استفاده در صفحات فهرست مطالب را تعیین می‌کند. بخش
.B قالب‌های سربرگ/پاورقی (HEADER/FOOTER FORMATS)
در زیر را ببینید.
.TP 5
.BI \-\-toclevels " levels"
تعداد سطوح در فهرست مطالب را تنظیم می‌کند.
.TP 5
.BI \-\-toctitle " string"
عنوان فهرست مطالب را تعیین می‌کند.
.TP 5
.BI \-\-top " margin"
حاشیه بالا را بر حسب پوینت (بدون پسوند یا ##pt)، اینچ (##in)، سانتی‌متر (##cm)، یا میلی‌متر (##mm) تعیین می‌کند.
.TP 5
.BI \-\-user-password " password"
رمز عبور کاربر را برای رمزنگاری فایل‌های PDF تعیین می‌کند.
.TP 5
.B \-\-verbose
.TP 5
.B \-v
پیام‌ها را با جزئیات کامل نمایش می‌دهد.
.TP 5
.B \-\-version
شماره نسخه فعلی را نمایش می‌دهد.
.TP 5
.B \-\-webpage
مشخص می‌کند که منابع HTML بدون ساختار هستند (صفحات وب ساده). یک شکست صفحه بین هر فایل یا URL در خروجی درج می‌شود.
.SH "وضعیت خروج (EXIT STATUS)"
دستور
.B Htmldoc
در صورت مشاهده هرگونه خطا وضعیت خروج غیرصفر بازمی‌گرداند، و در غیر این صورت صفر برمی‌گرداند.
.SH "قالب‌های سربرگ/پاورقی (HEADER/FOOTER FORMATS)"
سربرگ و پاورقی هر صفحه می‌تواند شامل حداکثر سه مقدار از پیش قالب‌بندی‌شده باشد.
این مقادیر با استفاده از یک نویسه برای سمت چپ، وسط و راست صفحه مشخص می‌شوند که حاصل آن قالب
.I fff
است که پیش‌تر نشان داده شد.
.LP
هر نویسه می‌تواند یکی از موارد زیر باشد:
.TP 5
.B .
خالی
.TP 5
.B /
شماره صفحات n/N با ارقام هندی-عربی (1/3، 2/3، 3/3)
.TP 5
.B :
شماره صفحات فصل c/C با ارقام هندی-عربی (1/2، 2/2، 1/4، 2/4، ...)
.TP 5
.B 1
شماره‌های انگلیسی/هندی-عربی (1، 2، 3، ...)
.TP 5
.B a
حروف کوچک انگلیسی
.TP 5
.B A
حروف بزرگ انگلیسی
.TP 5
.B c
سرآیند فصل فعلی
.TP 5
.B C
شماره صفحه فصل فعلی (ارقام عادی)
.TP 5
.B d
تاریخ فعلی
.TP 5
.B D
تاریخ و زمان فعلی
.TP 5
.B h
سرآیند فعلی
.TP 5
.B i
اعداد رومی با حروف کوچک
.TP 5
.B I
اعداد رومی با حروف بزرگ
.TP 5
.B l
تصویر لوگو
.TP 5
.B L
تصویر لوگو به صورت سربرگ رسمی - تصویر در حداکثر اندازه خود درج می‌شود
.TP 5
.B t
متن عنوان
.TP 5
.B T
زمان فعلی
.TP 5
.B u
نام فایل یا URL فعلی

.SH "وضعیت خروج (EXIT STATUS)"
دستور
.B Htmldoc
با تعداد خطاهایی که رخ داده است خارج می‌شود.

.SH "متغیرهای محیطی (ENVIRONMENT)"
دستور
.B Htmldoc
چند متغیر محیطی را بررسی می‌کند که می‌توانند دایرکتوری‌های پیش‌فرض را لغو کرده، اطلاعات خطایابی اضافی نمایش دهند، و حالت CGI را غیرفعال کنند:
.TP 5
.B HTMLDOC_DATA
این متغیر محیطی محل دایرکتوری‌های داده و فونت‌های
.BR htmldoc
را مشخص می‌کند که معمولاً /usr/share/htmldoc یا C:/Program Files/HTMLDOC است.
.TP 5
.B HTMLDOC_DEBUG
این متغیر محیطی اطلاعات خطایابی ارسال‌شده به خروجی خطای استاندارد (stderr) را فعال می‌کند. مقدار آن فهرستی از کلمات کلیدی زیر است که با فاصله از هم جدا می‌شوند: "all"، "links"، "memory"، "remotebytes"، "table"، "tempfiles" و/یا "timing".
.TP 5
.B HTMLDOC_HELP
این متغیر محیطی محل دایرکتوری مستندات
.BR htmldoc
را مشخص می‌کند که معمولاً /usr/share/doc/htmldoc یا C:/Program Files/HTMLDOC/doc است.
.TP 5
.B HTMLDOC_NOCGI
این متغیر محیطی، در صورت مقداردهی (مقدار آن اهمیتی ندارد)، حالت CGI را غیرفعال می‌کند. این گزینه برای استفاده از
.B htmldoc
روی وب‌سرور از طریق یک زبان اسکریپت‌نویسی یا فراخوانی از یک برنامه بسیار مفید است.
.SH "مثال‌ها (EXAMPLES)"
ایجاد یک فایل PDF از یک وب‌سایت:
.nf
    htmldoc \-\-webpage -f example.pdf http://www.example.com
.fi
ایجاد یک کتاب PostScript از یک دایرکتوری شامل فایل‌های HTML:
.nf
    htmldoc \-\-book -f example.pdf *.html
.fi
.SH "همچنین ببینید (SEE ALSO)"
راهنمای کاربران HTMLDOC (Users Manual)
.LP
https://www.msweet.org/htmldoc
.SH "نویسنده (AUTHOR)"
Michael R Sweet
.SH "موارد قانونی (LEGAL STUFF)"
حق نشر HTMLDOC متعلق به Michael R Sweet است (\[co] 1997-2025).
.PP
این برنامه نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط مجوز عمومی همگانی گنو (GNU GPL) نسخه ۲ که توسط بنیاد نرم‌افزارهای آزاد منتشر شده، بازتوزیع کرده و/یا تغییر دهید.
.PP
این برنامه به این امید توزیع شده است که مفید واقع شود، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف خاص. برای جزئیات بیشتر به مجوز عمومی همگانی گنو مراجعه کنید.
.PP
شما باید نسخه‌ای از مجوز عمومی همگانی گنو را همراه با این برنامه دریافت کرده باشید؛ در غیر این صورت، به آدرس زیر مکاتبه کنید:
Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.