نام (NAME)

docbook2man-spec.pl - تبدیل RefEntryهای DocBook به صفحات man

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

sgmlspl docbook2man-spec.pl

nsgmls [ sgml document ]| sgmlspl docbook2man-spec.pl

توضیحات (DESCRIPTION)

برنامه docbook2man یک فایل مشخصات sgmlspl است که صفحات man را (با استفاده از ماکروهای -man) از نشانه‌گذاری‌های RefEntry در DocBook تولید می‌کند.

این برنامه خروجی ESIS تولیدشده توسط nsgmls (یا سایر تجزیه‌کننده‌های SGML) را از ورودی استاندارد می‌خواند. نشانه‌گذاری‌هایی که درون RefEntry نباشند نادیده گرفته می‌شوند.

خروجی آن، یعنی صفحات man تبدیل‌شده، در دایرکتوری جاری نوشته می‌شوند. اگر اطلاعات RefMeta در یک RefEntry مشخص نشده باشد، صفحه man در خروجی استاندارد نوشته خواهد شد.

فایل manpage.links نیز ایجاد خواهد شد که شامل هرگونه نام مستعار (alias) برای صفحات man تولیدشده است. این فایل ساختار زیر را دارد:

<man page> <alias
manpage>

فایل manpage.refs ارجاعات XRef را ردیابی می‌کند. توجه داشته باشید که اگر سند ورودی دارای ارجاع به جلو (forward reference) باشد، ممکن است نیاز باشد docbook2man دو بار فراخوانی شود (بار اول برای به‌روزرسانی manpage.refs) تا ارجاعات حل‌وفصل شوند.

پیش‌نیازها (REQUIREMENTS)

بسته SGMLSpm از CPAN. این بسته شامل اسکریپت sgmlspl نیز هست که استفاده از آن الزامی است.

محدودیت‌ها (LIMITATIONS)

اجرای docbook2man روی اسناد غیر DocBook یا SGML ناسازگار، رفتار پیش‌بینی‌نشده‌ای خواهد داشت. :-)

این برنامه یک اسکریپت Perl کند و ناپایدار است.

این برنامه حتی به پشتیبانی از تمام نشانه‌گذاری‌های ممکن در DocBook نزدیک هم نیست و در برخی موارد ممکن است حتی با نشانه‌گذاری‌های پشتیبانی‌شده نیز خروجی اشتباه تولید کند.

کارهای باقی‌مانده (TO DO)

موارد بدیهی:

•

رفع اشکالات docbook2man که در اسناد آزمایشی یافت شده‌اند، به‌ویژه در weird.sgml.

•

افزودن قابلیت مدیریت المان‌های جدید و اصلاح مدیریت المان‌های موجود. پایدارتر و مقاوم‌تر شدن.

•

تولید تمیزترین و خواناترین خروجی man ممکن (برخلاف برخی مبدل‌های دیگر). پیروی از شیوه‌نامه‌های man(7) در لینوکس. از آنجا که تبدیل به صفحات man معمولاً به‌ندرت انجام می‌شود، کندتر یا پیچیده‌تر بودن بهتر از تولید خروجی اشتباه است. همچنین اگر شخصی بنا به هر دلیلی بخواهد از DocBook دست بکشد، آخرین صفحات man تبدیل‌شده می‌توانند به‌صورت دستی نگهداری شوند.

•

افزایش سرعت. به نظر می‌رسد بیشتر مشکلات کارایی تاکنون مربوط به تجزیه ESIS باشد. بازنویسی SGMLS.pm با C و/یا دریافت مستقیم ورودی از SP.

•

پشتیبانی از سایر زبان‌های (انسانی). اما با نویسه‌های غیر ASCII چه باید کرد؟ SGMLSpm آن‌ها را گزارش نمی‌دهد و roff هم آن‌ها را درک نمی‌کند. [توضیح: متن پس از فهرست‌های درون‌بسته (و بلوک‌های SS) باعث از کار افتادن docbook2man خواهد شد] اگر این کار انجام شود، افراد بیشتری می‌توانند از DocBook استفاده کنند.

کپی‌رایت و تکثیر (COPYRIGHT)

حق نشر (C) 1998-1999 متعلق به Steve Cheng <steve@ggi-project.org> است.

این برنامه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط پروانه عمومی همگانی گنو (GNU General Public License) همان‌طور که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، چه نسخه ۲ یا (به انتخاب خودتان) هر نسخه بعدی، بازتوزیع کرده یا تغییر دهید.

شما باید به همراه این برنامه یک نسخه از پروانه عمومی همگانی گنو را دریافت کرده باشید؛ فایل COPYING را بررسی کنید. در غیر این صورت، لطفاً به آدرس زیر بنویسید: Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.