نام (NAME)

jw, docbook2dvi, docbook2html, docbook2man, docbook2pdf, docbook2ps, docbook2rtf, docbook2tex, docbook2texi, docbook2txt - پرونده‌های SGML را به فرمت‌های دیگر تبدیل می‌کند (پوشش‌دهنده Jade)

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

jw [ -f frontend | --frontend frontend ]
[ -b backend | --backend backend ]
[ -c file | --cat file ]
[ -n | --nostd ]
[ -d file|default|none | --dsl file|default|none ]
[ -l file | --dcl file ]
[ -s path | --sgmlbase path ]
[ -p program | --parser program ]
[ -o directory | --output directory ]
[ -V variable[=value] ]
[ -u | --nochunks ] [ -i section | --include section ]
[ -w type|list | --warning type|list ]
[ -e type|list | --error type|list ]
[ -h | --help ] [ -v | --version ]
SGML-file

docbook2dvi SGML-file

docbook2html SGML-file

docbook2man SGML-file

docbook2pdf SGML-file

docbook2ps SGML-file

docbook2rtf SGML-file

docbook2tex SGML-file

docbook2texi SGML-file

docbook2txt SGML-file

توضیحات (DESCRIPTION)

اسکریپت شل jw امکان تبدیل یک پرونده DocBook (یا سایر قالب‌های مبتنی بر SGML) را به فرمت‌های دیگر (از جمله HTML، RTF، PS و PDF) با نحو ساده و قابل فهم فراهم می‌کند. این ابزار بخش عمده‌ای از پیچیدگی‌های Jade یا OpenJade را پنهان کرده و ویژگی‌های کارآمدی به آن اضافه می‌نماید.

اسکریپت‌های دیگر مانند docbook2html، docbook2rtf یا docbook2ps روش‌های دیگری برای فراخوانی jw فراهم می‌کنند که ممکن است به خاطر سپردن آن‌ها ساده‌تر باشد.

در حال حاضر، jw پرونده‌های XML را پشتیبانی نمی‌کند و فقط SGML را مدیریت می‌نماید.

این ابزار فرض می‌کند که چندین مؤلفه دیگر از قبل روی سیستم نصب هستند. این فهرست شامل موارد زیر است:

•

موجودیت‌های کاراکتری ISO برای SGML

•

موتور DSSSL مربوط به James Clark با نام jade یا یک پارسر معادل مانند OpenJade

•

تعریف نوع سند (DocBook DTD) از کنسرسیوم OASIS

•

شیوه‌نامه‌های مدولار DocBook متعلق به Norman Walsh (یا مجموعه‌ای دیگر از شیوه‌نامه‌های DSSSL)

•

مجموعه ماکروهای TeX برای jade نوشته Sebastian Rahtz به نام jadetex (برای موتورهای خروجی فرمت‌های چاپی مانند PDF، RTF یا PostScript)

•

مفسر perl (برای بک‌اندهایی که از perl استفاده می‌کنند)

•

ماژول SGMLSpm از CPAN (برای بک‌اندهایی که از sgmls استفاده می‌کنند)

•

مرورگر متنی Lynx HTML (برای بک‌اند txt)

اسکریپت jw در حالت پایه به صورت زیر فراخوانی می‌شود:

jw mydoc.sgml

که در آن mydoc.sgml یک پرونده SGML است.

خط فرمان بالا از گزینه‌های پیش‌فرض استفاده می‌کند: تبدیل از DocBook (فرانت‌اند پیش‌فرض) به HTML (بک‌اند پیش‌فرض)، نتیجه را در زیرپوشه قرار نمی‌دهد (مگر اینکه در شیوه‌نامه‌ها طور دیگری مشخص شده باشد)، و غیره.

در این مثال، نام پرونده "mydoc" و پسوند ".sgml" می‌توانند با هر نام دیگری جایگزین شوند. پسوندهای رایج برای پرونده‌های SGML DocBook شامل ".sgml"، ".sgm"، ".docbook" و ".db" است. پرونده پردازش‌شده mydoc.sgml می‌تواند در هر پوشه‌ای غیر از پوشه جاری قرار داشته باشد.

در اینجا تولید خروجی HTML انتخاب شده است. در عمل می‌توان از هر یک از بک‌اندهای موجود در زیرپوشه backends/ از پوشه توزیع DocBook-utils (معمولاً /usr/share/sgml/docbook/utils-0.6.15) استفاده کرد. به همین ترتیب، می‌توانید از هر فرانت‌اند تعریف‌شده در زیرپوشه frontends/ برای تبدیل از یک قالب ورودی دیگر استفاده کنید.

این دستور نمونه یک یا چند پرونده HTML با نام‌های دلخواه در پوشه جاری ایجاد می‌کند. این رفتار پیش‌فرض را می‌توان از طریق گزینه‌های خط فرمان یا شیوه‌نامه‌های سفارشی‌سازی تغییر داد.

گزینه‌ها (OPTIONS)

گزینه‌های زیر برای اسکریپت تبدیل معتبر هستند:

-f frontend | --frontend frontend

امکان تعیین فرانت‌اندی غیر از مقدار پیش‌فرض docbook را فراهم می‌کند. فهرست فرانت‌اندهای موجود در حال حاضر عبارت است از:

-b backend | --backend backend

امکان تعیین بک‌اندی غیر از مقدار پیش‌فرض HTML را فراهم می‌کند. فهرست بک‌اندهای موجود در حال حاضر عبارت است از:

-c file | --cat file

امکان استفاده از یک کاتالوگ باز SGML اضافی (SGML Open Catalog) را فراهم می‌کند که پرونده‌های دیگری مانند شیوه‌نامه‌های سفارشی، تطبیق‌های مربوط به تعاریف نوع سند DocBook، موجودیت‌های کاراکتری خاص و غیره را فهرست می‌نماید. این کاتالوگ به فهرست کاتالوگ‌های تعیین‌شده توسط اسکریپت افزوده می‌شود (گزینه --nostd در زیر را ببینید).

-n | --nostd

از کاتالوگ‌های استاندارد SGML Open استفاده نمی‌کند. در حالت عادی، فهرست کاتالوگ‌های استاندارد به این صورت تعیین می‌شود:

-d file|default|none | --dsl file|default|none

امکان استفاده از یک شیوه‌نامه سفارشی به جای شیوه‌نامه پیش‌فرض را فراهم می‌کند.

می‌توان یک «هدف» (target) با پیشوند علامت هش "#" به انتهای نام پرونده اضافه کرد. در نتیجه، تنها بخش متناظر از شیوه‌نامه اجرا می‌شود («مشخصه شیوه»ای که «شناسه» آن برابر با نام هدف باشد). کاربرد رایج این سازوکار، تعریف اهداف "#html" و "#print" برای فعال‌سازی بخش مربوطه در یک شیوه‌نامه جایگزین مشترک برای تبدیل‌های HTML و چاپی است.

با جایگزینی نام پرونده با "default"، از شیوه‌نامه پیش‌فرض ارائه‌شده توسط فرانت‌اند استفاده می‌شود. برای مثال، فرانت‌اند docbook مسیر ./docbook.dsl#html (یا ./docbook.dsl#print) را در پوشه پایه SGML برمی‌گرداند.

با جایگزینی نام پرونده با "none"، هیچ شیوه‌نامه جایگزینی (حتی شیوه‌نامه پیش‌فرض) استفاده نمی‌شود. شیوه‌نامه‌ای که در این حالت استفاده می‌شود نیز توسط فرانت‌اند تعیین می‌گردد. برای مثال، فرانت‌اند docbook پرونده html/docbook.dsl (یا print/docbook.dsl) متعلق به Norman Walsh را از زیرپوشه‌های پایه SGML پیدا کرده و برمی‌گرداند.

اگر هیچ گزینه --dsl مشخص نشود، مقدار پیش‌فرض "--dsl default"; اعمال خواهد شد.

-l file | --dcl file

امکان استفاده از یک اعلان SGML سفارشی به جای اعلان پیش‌فرض را فراهم می‌کند. نام پرونده اعلان پیش‌فرض SGML برای پرونده‌های SGML تنظیم نشده و برای پرونده‌های XML برابر با xml.dcl در پوشه پایه SGML است.

-s path | --sgmlbase path

امکان تعیین مسیر دیگری برای پوشه پایه SGML را فراهم می‌کند. این پوشه‌ای است که تمام DTDها، شیوه‌نامه‌ها، موجودیت‌ها و سایر فایل‌های SGML در زیر آن نصب شده‌اند. مقدار پیش‌فرض آن /usr/share/sgml است.

-p program | --parser program

در صورت نصب چند پردازشگر، پردازشگر مورد استفاده (Jade یا OpenJade) را مشخص می‌کند. اگر این گزینه تعیین نشود، اسکریپت ابتدا Jade و سپس OpenJade را امتحان می‌کند.

-o directory | --output directory

پوشه خروجی را برای ذخیره تمامی پرونده‌های تولیدشده تنظیم می‌کند. اگر شیوه‌نامه‌ها زیرپوشه‌ای برای ذخیره پرونده‌های خروجی تعریف کرده باشند، زیرپوشه تعریف‌شده درون پوشه مشخص‌شده با این گزینه قرار خواهد گرفت.

-V variable=[value]

یک متغیر را تنظیم می‌کند (در صورت مشخص شدن مقدار، مقداردهی می‌شود).

-u | --nochunks

تنها یک پرونده بزرگ خروجی تولید می‌کند. این گزینه فقط هنگام تولید خروجی HTML مفید است، زیرا خروجی HTML معمولاً به چندین پرونده تقسیم می‌شود. این گزینه تنظیمات احتمالی انجام‌شده در شیوه‌نامه‌ها را بازنویسی (override) می‌کند.

-i section | --include section

یک بخش نشانه‌گذاری‌شده (marked section) در SGML را به عنوان "include" علامت‌گذاری می‌کند. یک بخش نشانه‌گذاری‌شده SGML نوعی بخش شرطی در سند است. اگر به صورت "ignore" تعریف شود نادیده گرفته می‌شود و در غیر این صورت پردازش خواهد شد. نمونه‌ای از چنین بخش نشانه‌گذاری‌شده‌ای:

<DOCTYPE mydoc [
  <!ENTITY % confidential "ignore">
]>
<mydoc>
  ...
  <![ %confidential [ Some confidential text... ]]>
  ...
</mydoc>

-w type|list | --warning type|list

نمایش انواع هشدارهای مشخص‌شده را فعال یا غیرفعال می‌کند. می‌توان چندین گزینه -w را در خط فرمان وارد کرد. انواع هشدارهایی که با "no-" شروع می‌شوند هشدارهای مربوطه را غیرفعال کرده و سایر انواع، آن‌ها را فعال می‌نمایند.

اگر نوع هشدار با "list" جایگزین شود، فهرستی از انواع هشدارهای مجاز نمایش داده می‌شود.

-e type|list | --error type|list

انواع خطاهای مشخص‌شده را غیرفعال می‌کند. می‌توان چندین گزینه -e را در خط فرمان وارد کرد. تمام انواع خطاها با "no-" شروع می‌شوند.

اگر نوع خطا با "list" جایگزین شود، فهرستی از انواع خطاهای مجاز نمایش داده می‌شود.

-h | --help

یک پیام راهنمای کوتاه نمایش داده و خارج می‌شود.

-v | --version

شناسه نگارش برنامه را چاپ کرده و خارج می‌شود.

فایل‌ها (FILES)

/etc/sgml/sgml-docbook.cat

کاتالوگ باز متمرکز SGML. اگر فرانت‌اندی غیر از docbook استفاده شود، ممکن است این نام تغییر کند.

/usr/share/sgml/docbook/utils-0.6.15 /backends

بک‌اندهای مختلف

/usr/share/sgml/docbook/utils-0.6.15 /frontends

فرانت‌اندهای مختلف

/usr/share/sgml/docbook/utils-0.6.15 /helpers

اسکریپت‌های کمکی مختلف مانند docbook2man یا docbook2texi

نویسندگان (AUTHORS)

Eric Bischoff (اسکریپت شل jw و تعدادی از بک‌اندها)، Jochem Huhmann (بک‌اندهای man و texi)

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

docbook2man-spec.pl(1), docbook2texi-spec.pl(1), install-catalog(8), nsgmls(1), وبگاه docbook-utils به نشانی <URL:http://sources.redhat.com/docbook-tools>.