LINUXDOC(1) General Commands Manual LINUXDOC(1)

linuxdoc - مبدل LinuxDoc DTD SGML به سایر قالب‌های خروجی

linuxdoc --backend=format
[--papersize=size] [--language=lang] [--charset=char] [--style=file] [--debug] [--define attribute=value] [--include entity] [backend-options...] file(.sgml)

یا (کاربرد قدیمی و منسوخ‌شده)
sgmlxxxx [generic-options...] [backend-options...]   file(.sgml)

مجموعه linuxdoc کلکسیونی از قالب‌بندهای متن است که فایل‌های منبع SGML مبتنی بر LinuxDoc DTD را درک می‌کند. هر قالب‌بند (یا «پشتوانه» - back-end) فایل منبع را به انواع گوناگونی از قالب‌های خروجی تبدیل می‌کند، از جمله HTML، TeX، DVI، PostScript، متن ساده، و منبع groff(1) در قالب صفحه راهنما (man-page). مجموعه linuxdoc برای سازگاری رو به عقب (backward compatibility) فراهم شده است، زیرا هنوز مستندات مفید بسیاری وجود دارند که به صورت منبع sgml با LinuxDoc DTD نوشته شده‌اند.

زبان(های) نشانه‌گذاری پذیرفته‌شده توسط این قالب‌بندها در Linuxdoc-Tools User's Guide شرح داده شده‌اند. آن‌ها انواعی از یک تعریف نوع سند (DTD) برای SGML هستند که در ابتدا توسط Matt Welsh برای مستندسازی لینوکس طراحی شده بود.

بیشتر گزینه‌های خط فرمان توسط همه پشتوانه‌ها پذیرفته می‌شوند. برخی پشتوانه‌ها گزینه‌های خاص دیگری برای کنترل تبدیل به قالب خروجی ویژه خود دارند. گزینه‌های مشترک در اینجا آمده‌اند:

پشتوانه را برای قالب مشخص‌شده تعیین می‌کند. مقدار پیش‌فرض هیچ‌کدام از قالب‌های واقعی نیست، بلکه تنها نحوه استفاده از این مجموعه را نمایش می‌دهد. قالب‌های موجود عبارتند از: html، info، latex، lyx، rtf، txt، check.
اندازه کاغذ را تنظیم می‌کند. پیش‌فرض «a4» (کاغذ اروپایی ۲۹۷x۲۱۰ میلی‌متر) است. همچنین می‌توانید اندازه «letter» را مشخص کنید.
زبان سند را مشخص می‌کند (این گزینه ممکن است تعیین کند که کدام فایل‌های سبک برای قالب‌بندی توسط یک پشتوانه استفاده شوند). زبان پیش‌فرض انگلیسی است. یکی از دستورهای LinuxDoc-tools را بدون آرگومان اجرا کنید تا فهرست کدهای زبان معتبر را ببینید.
کدگذاری نویسه‌های خروجی را مشخص می‌کند. پیش‌فرض «ascii» است که مجموعه نویسه‌های ASCII را برمی‌گزیند؛ می‌توانید «latin» را برای تعیین مجموعه نویسه‌های ISO 8859-1 (Latin-1) مشخص کنید. همچنین «nippon» و «euc-kr» برای مدیریت فایل‌های sgml با کدگذاری euc-jp و euc-kr لازم است. «utf-8» نیز پذیرفته می‌شود، اگرچه تنها به صورت جزئی پشتیبانی می‌گردد.
یک DTD (تعریف نوع سند) کمکی را از مسیر /usr/share/linuxdoc-tools/dtd ضمیمه می‌کند.
فاصله‌گذاری تب (tab) مفروض برای تولید سند خروجی را تعیین می‌کند. فاصله‌گذاری تب پیش‌فرض ۸ است.
فایل‌های میانی را حذف نمی‌کند (مانند فایل‌های .TeX که در مسیر ساخت .dvi تولید می‌شوند، یا فایل‌های .man که در مسیر تبدیل به متن ساده حذف می‌شوند).
جفت‌های صفت/مقدار (attribute/value) را برای تطبیق با عبارات شرطی «if» و «unless» ارسال می‌کند. برای توضیحات جامع‌تر پیرامون این ویژگی به راهنمای کاربر (User's Guide) مراجعه کنید. این شرطی‌سازی‌ها توسط دستور sgmlpre مدیریت می‌شوند. به sgmlpre(1) و همچنین User's Guide مراجعه کنید.
یک گزینه -i را به nsgmls(1) ارسال می‌کند. این گزینه می‌تواند برای گنجاندن شرطی (conditional inclusion) استفاده شود. برای جزئیات به صفحه راهنمای nsgmls(1) مراجعه کنید.
یک رشته گزینه را به پشتوانه (back end) ارسال می‌کند. معنای دقیق این گزینه وابسته به پشتوانه بوده و باید در صفحات راهنمای اختصاصی مربوط به هر یک شرح داده شده باشد.
فایل منبع SGML با پسوند .sgml که با نام file یا file.sgml مشخص می‌شود. این فایل باید از linuxdoc DTD استفاده کند. سایر DTDها پشتیبانی نمی‌شوند.

اجرای یک پشتوانه بدون هیچ آرگومانی باعث می‌شود تمام گزینه‌هایش فهرست شوند (پیام خطای «no filenames given» در این حالت بدون خطر قابل چشم‌پوشی است). پشتوانه‌های موجود عبارتند از (نام‌های داخل قلاب شکل‌های قدیمی و منسوخ هستند):

تبدیل به HTML
تبدیل به GNU info
تبدیل به ماکروهای Lyx
تبدیل به LaTeX 2e
تبدیل به Microsoft Rich Text Format
تبدیل به متن ساده یا نشانه‌گذاری صفحه راهنمای یونیکس

همچنین ابزار linuxdoc-Bcheck
(sgmlcheck) برای بررسی نحو Linuxdoc DTD SGML در فایل‌های منبع، بدون تولید واقعی یک نسخه تبدیل‌شده، در دسترس است..SH "درایورهای بک‌اند (BACKEND-DRIVERS)" در اینجا توضیحات مربوط به هر یک از درایورهای بک‌اند آمده است:


****************************************************

linuxdoc -B html (sgml2html) یک فایل منبع SGML مبتنی بر LinuxDoc DTD را به خروجی HTML تبدیل می‌کند. خروجی در فایل سطح بالای file.html و برای هر بخش در file-n.html قرار می‌گیرد (عملکرد پیش‌فرض، اما با گزینه قابل تغییر است)، که در آن file نام فایل منبع SGML و n نام بخش است.

جفت مشخصه/مقدار «output=html» برای شرطی‌ها تنظیم می‌شود.

دستور linuxdoc -B html گزینه‌های زیر را می‌پذیرد: [--split 0|1|2 ] [--dosnames] [--imagebuttons] [--toc 0|1|2 ]

معانی آن‌ها عبارتند از:

سطحی که اسناد منبع در آن تفکیک شوند. 0 = تفکیک نشود، 1 = تفکیک بر اساس بخش‌های اصلی، 2 = تفکیک بر اساس زیربخش‌ها.
سطحی که فهرست مطالب (toc) در آن تولید شود.
0 = اصلاً فهرست مطالب تولید نشود،
1 = بخش‌های اصلی (/فصل‌ها/قسمت‌ها) را شامل شود،
2 = زیربخش‌ها را شامل شود.
استفاده از «.htm» به جای «.html» به عنوان پسوند فایل‌های html.
استفاده از آیکون‌های تصویری فلش «next»،‏ «previous» و «contents» موجود در /usr/share/linuxdoc-tools به عنوان دکمه‌های ناوبری.
استفاده از فایل مشخص‌شده به عنوان پاورقی در هر فایل html حاصل. پاورقی پیش‌فرض تنها متن سادهٔ زیر است: 
</BODY>\n </HTML>\n
استفاده از فایل مشخص‌شده به عنوان بخش بالایی سرآیند در هر فایل html حاصل. توجه داشته باشید که این تمام بخش سرآیند نیست، یعنی عنوان و پیوندها (next،‏ previous،‏ contents) در سرآیند پیش‌فرض حفظ می‌شوند. پیش‌فرض عبارت است از: 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\n
<HTML>\n <HEAD>\n
تنظیم جهت راست‌به‌چپ در فایل html.


****************************************************

linuxdoc -B info (sgml2info) یک فایل منبع SGML مبتنی بر LinuxDoc DTD را به قالب GNU info تبدیل می‌کند. خروجی در file.info ظاهر خواهد شد، که در آن file نام فایل منبع SGML است.

جفت مشخصه/مقدار «output=info» برای شرطی‌ها تنظیم می‌شود.

دستور linuxdoc -B info هیچ گزینهٔ خاصی برای این بک‌اند ندارد.


****************************************************

linuxdoc -B latex (sgml2latex) یک فایل منبع SGML مبتنی بر LinuxDoc DTD را با استفاده از تجزیه‌کنندهٔ nsgmls(1) یا onsgmls(1) و مترجم sgmlsasp(1) به خروجی LaTeX تبدیل می‌کند. با استفاده از خروجی LaTeX و قالب‌بندی‌کنندهٔ متن latex(1)، می‌توانید خروجی DVI ایجاد کرده و با استفاده از مبدل dvips(1) خروجی PostScript بسازید. خروجی در file.tex برای خروجی LaTeX، در file.dvi برای خروجی DVI، یا در file.ps برای خروجی PostScript قرار می‌گیرد، که در آن file نام فایل منبع SGML است.

با استفاده از خروجی LaTeX و قالب‌بندی‌کنندهٔ متن pdflatex(1)، می‌توانید یک خروجی PDF تمیز ایجاد کنید که برای مشاهده با نمایش‌دهنده‌های PDF مانند xpdf(1)، acroread(1) یا ghostview(1) مناسب است.

جفت مشخصه/مقدار «output=latex2e» برای شرطی‌ها تنظیم می‌شود.

دستور linuxdoc -B latex گزینه‌های ویژهٔ بک‌اند زیر را می‌پذیرد: [--output=tex|dvi|ps|pdf] [--bibtex] [--makeindex] [--pagenumber=n] --quick [--latex=latex|hlatexp|platex|jlatex] [--dvips=dvips|dvi2ps] [--verbosity=n]

معانی آن‌ها عبارتند از:

قالب خروجی مورد نظر را مشخص می‌کند. مشخص‌کنندهٔ fmt می‌تواند «tex»،‏ «dvi»،‏ «ps» یا «pdf» باشد.

نکته: این نسخه فایل‌های میانی را بازنویسی/حذف نمی‌کند: فایل tex برای خروجی dvi، یا فایل‌های tex/dvi برای خروجی ps. این رفتار با SGML-Tools 1.0.9 اصلی تفاوت دارد، بنابراین در اینجا به شما هشدار داده می‌شود.

پردازش TeX تولیدشده با bibtex(1).
تولید یک فایل نمایهٔ TeX مناسب برای پردازش با makeindex(1) از تگ‌های <idx> و <cdx> موجود در منبع SGML.
تنظیم شماره صفحهٔ آغازین در فایل خروجی DVI یا PS.
فقط یک دور قالب‌بندی LaTeX انجام می‌دهد. این کار اغلب برای تولید خروجی نهایی کافی نیست (به دلیل ارجاعات و غیره)، اما برای یافتن خطاهای TeX و مشکلات ترازبندی مفید است.
آرگومان گزینهٔ pass دقیقاً پس از دیباچهٔ LaTeX که توسط برچسب نوع سند (document-type) ایجاد شده است، درج می‌شود. قالب خروجی دلخواه را مشخص می‌کند. مشخص‌کنندهٔ fmt می‌تواند «tex»،‏ «dvi»،‏ «ps» یا «pdf» باشد.
این گزینه در حال حاضر برای کره‌ای و ژاپنی است. alternate_latex_command می‌تواند «latex» (پیش‌فرض)، «hlatexp» (برای کره‌ای)، «platex» یا «jlatex» (برای ژاپنی) باشد. این گزینه می‌تواند برای رندر کردن سند کره‌ای با استفاده از HLaTeXp، یا برای رندر کردن سند ژاپنی با استفاده از pLaTeX/jLaTeX به کار رود. در غیر این صورت، برای رندر سند کره‌ای باید HLaTeX نصب باشد. از سوی دیگر، سند ژاپنی را می‌توان با jLaTeX رندر کرد (که در صورت مشخص شدن «-c nippon» حالت پیش‌فرض است)، بنابراین اگر در حال حاضر jLaTeX را دارید، ممکن است نیازی به نصب pLaTeX نداشته باشید.
این گزینه در حال حاضر برای ژاپنی است. alternate_dvips_command می‌تواند «dvips» یا «dvi2ps» باشد. اگر از این موضوع اطلاع ندارید، احتمالاً به آن نیازی نخواهید داشت..IP "--verbosity, -V" میزان پرگویی (verbosity) را تنظیم می‌کند. مقدار '0' (پیش‌فرض) تنها در صورت بروز خطا اطلاعات اجرای LaTeX را نمایش می‌دهد. مقدار '1' همواره اطلاعات آخرین اجرا را نشان می‌دهد. مقدار '2' اطلاعات همهٔ اجراها را نمایش خواهد داد.


****************************************************

دستور linuxdoc -B lyx (sgml2lyx) یک فایل منبع SGML مبتنی بر LinuxDoc DTD را به خروجی LyX تبدیل می‌کند. خروجی در فایل file.lyx قرار خواهد گرفت که در آن file نام فایل منبع SGML است.

جفت صفت/مقدار «output=lyx» برای شرط‌ها تنظیم می‌شود.

دستور linuxdoc -B lyx فاقد گزینه‌های اختصاصی برای موتور پسین است.


****************************************************

دستور linuxdoc -B rtf (sgml2rtf) یک فایل منبع SGML مبتنی بر LinuxDoc DTD را به RTF (قالب متن غنی یا Rich Text Format) که در سامانهٔ راهنمای Microsoft Windows به کار می‌رود تبدیل می‌کند. خروجی در فایل سطح بالا با نام file.rtf و فایل‌های file-n.rtf به ازای هر بخش ظاهر خواهد شد، که در آن file نام فایل منبع SGML است. خروجی RTF برای ترجمه و همگردانی توسط Windows Help Compiler (hc31.exe) آماده و سفارشی‌سازی شده است.

جفت صفت/مقدار «output=rtf» برای شرط‌ها تنظیم می‌شود.

دستور linuxdoc -B rtf گزینهٔ [--twosplit] را به عنوان یک گزینهٔ اختصاصی موتور پسین می‌پذیرد. مفهوم این گزینه در ادامه آمده است:

فایل‌ها را هم در بخش‌های .n و هم در زیربخش‌های .n.m تکه‌تکه (تقسیم) می‌کند.


****************************************************

دستور linuxdoc -B txt (sgml2txt) یک فایل منبع SGML مبتنی بر LinuxDoc DTD را به خروجی ASCII، ISO-8859-1 یا EUC-JP تبدیل می‌کند. خروجی در فایل file.txt نمایان خواهد شد که در آن file نام فایل منبع SGML است.

جفت صفت/مقدار «output=txt» برای شرط‌ها تنظیم می‌شود.

دستور linuxdoc -B txt گزینه‌های اختصاصی موتور پسین زیر را می‌پذیرد: [--manpage] [--filter] [--blanks=n]

معانی این گزینه‌ها عبارتند از:

یک فایل منبع groff خروجی می‌دهد که برای قالب‌بندی با groff -man جهت تولید صفحات راهنما (man pages) مناسب است.
کاراکترهای روی‌هم‌افتاده با پس‌بر (backspace-overstrikes) را از شکل میانی تولید شده توسط groff(1) حذف می‌کند.
آرگومان گزینهٔ pass به گزینه‌های خط فرمانی که به groff(1) تحویل داده می‌شوند، افزوده می‌شود.
بیشینهٔ تعداد خط‌های خالی متوالی را برای تولید سند خروجی تعیین می‌کند. حد پیش‌فرض ۳ است. اگر ۰ (صفر) مشخص شود، خروجی می‌تواند خطوط خالی متوالی متعددی داشته باشد.


****************************************************

دستور linuxdoc -B check (sgmlcheck) یک تجزیهٔ نحوی SGML را روی منبع سند مشخص‌شده اجرا می‌کند. هرگونه خطایی به خروجی استاندارد گزارش می‌شود. هیچ نسخهٔ قالب‌بندی‌شده‌ای از منبع تولید نمی‌شود.

توجه داشته باشید که linuxdoc -B check منبع SGML مبتنی بر LinuxDoc DTD را پیش‌پردازش کرده و شرطی‌سازی‌های توصیف‌شده توسط برچسب‌های <#if></#if> و <#unless></#unless> را انجام می‌دهد. منابع اسنادی که دارای این برچسب‌ها باشند، یک تجزیه‌کنندهٔ مستقل SGML را دچار سردرگمی خواهند کرد. دستور linuxdoc -B check هیچ گزینهٔ اختصاصی برای موتور پسین ندارد.
****************************************************.SH "فایل‌ها (FILES)" فایل‌ها و برنامه‌های اجرایی متعددی در /usr/share/linuxdoc-tools و /usr/bin مورد استفاده قرار می‌گیرند.

شاید هنوز مواردی باقی مانده باشد. در صورت تمایل گزارش‌های خود را برای نگه‌دارنده فعلی ارسال کنید.

این پروژه پیش‌تر توسط Cees de Groot <cg@cdegroot.com> در SGML-Tools (v1) و Taketoshi Sano <sano@debian.org> برای Linuxdoc-Tools نگه‌داری شده است. در حال حاضر توسط Agustin Martin <agustin6martin AT gmail com> نگه‌داری می‌شود.

2025-04-02