db2x_texixml(1) docbook2X db2x_texixml(1)

db2x_texixml - ساخت فایل‌های Texinfo از Texi-XML


db2x_texixml
[گزینه‌ها]... [xml-document]

دستور db2x_texixml یک سند Texi-XML را به یک یا چند سند Texinfo تبدیل می‌کند.

اگر xml-document مشخص نشود، سندی که باید تبدیل شود از ورودی استاندارد خوانده خواهد شد.

نام فایل‌های اسناد Texinfo توسط نشانه‌گذاری‌های موجود در منبع Texi-XML تعیین می‌شود. (اگر نام فایل‌ها در نشانه‌گذاری مشخص نشده باشد، db2x_texixml تلاش می‌کند آن‌ها را از نام فایل ورودی استنتاج کند. با این حال، منبع Texi-XML باید نام فایل را مشخص کند، زیرا در صورت وجود چندین فایل خروجی یا زمانی که منبع Texi-XML از ورودی استاندارد تأمین شود، این روش کار نخواهد کرد.)

کدگذاری نویسهٔ مورد استفاده برای فایل‌های خروجی را انتخاب می‌کند. کدگذاری‌های دردسترس همان موارد iconv(1) هستند. کدگذاری پیش‌فرض us-ascii است.

منبع XML ممکن است حاوی نویسه‌هایی باشد که در کدگذاری انتخابی شما قابل نمایش نیستند؛ در این حالت، برنامه در طول پردازش با خطا مواجه شده و متوقف می‌شود، و شما باید کدگذاری دیگری را انتخاب کنید. (تضمین می‌شود که این اتفاق در هیچ‌یک از کدگذاری‌های یونیکد مانند UTF-8 رخ ندهد، اما متأسفانه همه قادر به پردازش متن‌های یونیکد نیستند.)

اگر از نسخهٔ گنو iconv(1) استفاده می‌کنید، می‌توانید //TRANSLIT را به انتهای نام کدگذاری اضافه کنید تا برای نویسه‌های غیرقابل‌تبدیل در خروجی، تلاش برای نویسه‌گردانی (transliteration) صورت گیرد. با این حال، آگاه باشید که نویسه‌هایی که واقعاً غیرقابل‌تبدیل هستند به یکی دیگر از آن علامت سؤال‌های کلافه‌کننده تبدیل خواهند شد. (از این موضوع خسته نشده‌اید؟)

افزودن پسوند //TRANSLIT به یک کدگذاری یونیکد — به‌ویژه utf-8//TRANSLIT — بدین معناست که فایل‌های خروجی در قالب یونیکد باقی می‌مانند، اما تبدیل نویسه‌ها در سطح نشانه‌گذاری با استفاده از utf8trans همچنان انجام خواهد شد. بنابراین در بیشتر موارد، یک سند انگلیسی‌زبان که با --encoding=utf-8//TRANSLIT تبدیل می‌شود در واقع به عنوان یک سند US-ASCII به پایان می‌رسد، اما هر نویسهٔ غیرقابل‌ترجمه بدون هیچ‌گونه هشداری به صورت UTF-8 باقی خواهد ماند. (توجه: از نظر دقیق فنی، این یک “نویسه‌گردانی” نیست.) این روش تبدیل، مصالحه‌ای در برابر پردازش سخت‌گیرانهٔ --encoding=us-ascii است که در صورت برخورد با هر نویسهٔ غیرقابل‌ترجمه متوقف می‌شود.

توجه داشته باشید که صفحات راهنما (man pages) و اسناد Texinfo در کدگذاری‌های غیر ASCII (شامل UTF-8) ممکن است در سیستم‌های قدیمی‌تر (غیر بین‌المللی‌سازی‌شده) قابل حمل نباشند، و به همین دلیل است که مقدار پیش‌فرض این گزینه us-ascii است.

برای جلوگیری از هرگونه نگاشت خودکار نویسه یا تبدیل کدگذاری، گزینهٔ --encoding=utf-8 را ارسال کنید.

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

اگر قرار باشد خروجی در خروجی استاندارد نوشته شود (که با گزینهٔ --to-stdout فعال می‌شود)، این گزینه نادیده گرفته می‌شود.

خروجی را به جای فایل‌های جداگانه در خروجی استاندارد می‌نویسد.

اگر از این گزینه استفاده شود، حتی زمانی که قرار است چندین سند خروجی وجود داشته باشد، همه چیز به‌صورت متوالی در خروجی استاندارد ادغام می‌شود. اما توجه داشته باشید که بیشتر برنامه‌های دیگر این خروجی ادغام‌شده را قبول نخواهند کرد.

بدیهی است که این گزینه با --list-files ناسازگار است.

خروجی Texinfo را به makeinfo(1) هدایت (pipe) می‌کند و به‌جای فایل‌های Texinfo، مستقیماً فایل‌های Info ایجاد می‌کند.
خروجی Texinfo را به makeinfo --no-headers هدایت می‌کند، و در نتیجه فایل‌های متنی ساده ایجاد می‌کند.
نمایش اطلاعات مختصر کاربرد و خروج.
نمایش نسخه و خروج.

این برنامه برای انجام عملیات خود از برنامه‌های خاص دیگری استفاده می‌کند. اگر آن‌ها در مکان‌های پیش‌فرض نصب خود نیستند، از گزینه‌های زیر برای تعیین مکان آن‌ها استفاده کنید:

از جدول نگاشت نویسهٔ charmap همراه با برنامهٔ utf8trans(1) (همراه با docbook2X ارائه شده است) که در مسیر path یافت می‌شود، استفاده می‌کند.
مکان برنامهٔ iconv(1) که برای تبدیل‌های کدگذاری استفاده می‌شود.

سازگاری با زبان Texinfo. فایل‌های Texinfo تولیدشده توسط db2x_texixml گاهی اوقات برای کارکرد درست به Texinfo نسخهٔ 4.7 (جدیدترین نسخه) نیاز دارند. به‌ویژه:

•
دستور db2x_texixml به makeinfo متکی است تا علائم نگارشی را پس از یک @ref در صورتی که از قبل وجود نداشته باشد به‌طور خودکار اضافه کند. در غیر این صورت پیوند در نرم‌افزار خوانندهٔ Info کار نخواهد کرد (اگرچه makeinfo هیچ خطایی صادر نمی‌کند).
•
دستور جدید @comma{} برای ویرگول‌هایی (,) که درون فهرست آرگومان‌های دستورهای Texinfo می‌آیند استفاده می‌شود تا از ویرگولی که برای جداسازی آرگومان‌های مختلف به کار می‌رود متمایز شود. در غیر این صورت تنها جایگزین ممکن، تبدیل , به . می‌بود که مسلماً نامطلوب است (اما نسخه‌های پیشین docbook2X این کار را انجام می‌دادند).

اگر نمی‌توانید از نسخهٔ 4.7 برنامهٔ makeinfo استفاده کنید، همچنان می‌توانید از یک اسکریپت sed برای انجام دستی مراحل توضیح‌داده‌شده استفاده کنید.

ارتباط Texi-XML با قالب خروجی XML در makeinfo. قالب Texi-XML استفاده‌شده توسط docbook2X، با قالب XML تولیدشده توسط makeinfo(1) با گزینهٔ --xml، متفاوت و ناسازگار است. این وضعیت تا حدی به این دلیل پیش آمد که قالب Texi-XML در docbook2X پیش از ظهور قالب XML برنامهٔ makeinfo به‌طور مستقل طراحی و پیاده‌سازی شده بود. همچنین Texi-XML بسیار متمرکز بر این است که به‌طور ماشینی از سایر قالب‌های XML تولید شود، در حالی که به نظر می‌رسد کاربرد غیربدیهی خاصی برای قالب XML برنامهٔ makeinfo وجود ندارد. بنابراین در حال حاضر هیچ دلیلی وجود ندارد که docbook2X به جای Texi-XML از قالب XML برنامهٔ makeinfo استفاده کند.

•
شکستن خطوط متن در منوها برای متون غیر ASCII کاملاً خراب است. احتمالاً در همه‌جای دیگر خروجی نیز خراب است، اما این تقصیر makeinfo خواهد بود.
•
گزینهٔ --list-files ممکن است در کنار --info به درستی کار نکند. به‌ویژه، زمانی که فایل Info خروجی بیش از حد بزرگ شود، makeinfo تصمیم می‌گیرد آن را به بخش‌هایی با نام‌های abc.info-1، abc.info-2، abc.info-3 و غیره تقسیم کند. برنامهٔ db2x_texixml دقیقاً نمی‌داند چه تعداد از این فایل‌ها وجود دارد، هرچند می‌توانید برای بررسی آن از دستور ls استفاده کنید.

Steve Cheng <stevecheng@users.sourceforge.net>.

راهنمای docbook2X (در قالب Texinfo یا HTML) چگونگی تبدیل DocBook به صفحات راهنما (man pages) و Texinfo را به‌طور کامل شرح می‌دهد.

اطلاعات به‌روز دربارهٔ این برنامه را می‌توان در وب‌سایت docbook2X ⟨http://docbook2x.sourceforge.net⟩ یافت.

ورودی db2x_texixml توسط XML DTD موجود در مسیر dtd/Texi-XML در توزیع docbook2X تعریف شده است.

3 March 2007 docbook2X 0.8.8