HXCITE(1)                       HTML-XML-utils                       HXCITE(1)

نام (NAME)
       hxcite - جایگزینی ارجاعات کتاب‌شناختی با پیوندها

خلاصه دستور (SYNOPSIS)
       hxcite [ -b base ] [ -p pattern ] [ -a auxfile ] [ -m marker ] [ -c ]
       bibfile [ file ]

توضیحات (DESCRIPTION)
       دستور hxcite پرونده‌ی file را در خروجی استاندارد کپی کرده و به‌دنبال
       رشته‌هایی به شکل [[label]] می‌گردد.  برچسب (label) نباید شامل فاصله‌ی خالی
       باشد و جفت‌کروشه‌های باز و بسته باید بدون هیچ فاصله‌ای در میان، برچسب را
       در بر بگیرند. اگر hxcite برچسب را در bibfile پیدا کند، رشته با pattern
       جایگزین می‌شود. الگو می‌تواند شامل متغیرهای مشخصی باشد. اگر برچسب در
       bibfile یافت نشود، دست‌نخورده باقی می‌ماند.

       الگوی پیش‌فرض، رشته را با یک پیوند جایگزین می‌کند، اما اگر گزینه‌ی -p
       استفاده شود، جایگزین می‌تواند هر الگویی باشد. ورودی حتی نیازی نیست که
       HTML باشد.

       اگر برچسب به‌جای [[...]] در {{...}} قرار گرفته باشد، بدون تغییر به خروجی
       کپی شده و با الگو جایگزین نمی‌شود، ولی برچسب همچنان در bibfile جستجو
       می‌شود.

گزینه‌ها (OPTIONS)
       گزینه‌های زیر پشتیبانی می‌شوند:

       -p pattern
                 الگویی را تعیین می‌کند که رشته‌ی [[label]] با آن جایگزین می‌شود.
                 الگو می‌تواند شامل متغیرهای %b (که با مقدار گزینه‌ی -b جایگزین
                 می‌شود)، %m (که با مقدار گزینه‌ی -m جایگزین می‌شود) و %L (که با
                 label جایگزین می‌شود) باشد. الگوی پیش‌فرض بدین صورت است:

                     <a href="%b#%L" rel="biblioentry">[%L]<!--{{%m%L}}--></a>


       -b base   مقدار متغیر %b را در الگو تنظیم می‌کند. معمولاً این مقدار بر
                 روی یک URL نسبی یا مطلق تنظیم می‌شود. به‌طور پیش‌فرض این مقدار
                 یک رشته‌ی خالی است.

       -a auxfile
                 تمام برچسب‌هایی که پیدا و جایگزین شده‌اند نیز در یک فایل نوشته
                 می‌شوند. این کار به این منظور است که hxmkbib(1) بتواند آن‌ها را
                 پیدا کرده و یک کتاب‌شناسی ایجاد کند. پرونده‌ی auxfile پیش‌فرض از
                 نام file با حذف آخرین پسوند آن (در صورت وجود) و جایگزینی آن
                 با «.aux» ساخته می‌شود.  اگر هیچ file مشخص نشده باشد، نام
                 پیش‌فرض «aux.aux» خواهد بود.

       -m marker به‌طور پیش‌فرض، برنامه به‌دنبال «[[name]]» می‌گردد، اما می‌توان آن
                 را طوری تنظیم کرد که به‌دنبال «[[#name]]» بگردد که در آن # یک
                 رشته است، معمولاً نمادی مانند «!» یا «=». این قابلیت اجازه
                 می‌دهد ارجاعات دسته‌بندی شوند؛ برای مثال، «[[!name]]» برای
                 ارجاعات هنجاری (normative) و «[[name]]» برای ارجاعات
                 غیرهنجاری (non-normative).

       -c        باعث نادیده‌گرفته‌شدن «[[name]]» در زمان وقوع آن در درون
                 کامنت‌های XML («<!--...-->») می‌شود. این گزینه برای فایل‌هایی
                 مفید است که در آن‌ها چنین برچسب‌هایی درون کامنت‌ها قرار دارند،
                 تا از باز شدن آن‌ها و احتمالاً ایجاد خروجی نامعتبر جلوگیری شود؛
                 همچنین زمانی کاربرد دارد که hxcite برای فایل‌های غیر HTML
                 استفاده شود که ممکن است حاوی «<!--» باشند بدون آن‌که کامنت
                 باشند.  موارد وقوع «{{name}}» تحت تأثیر -c قرار نمی‌گیرند.
                 (اما هشدار بخش باگ‌ها در زیر را ببینید.)

عملوندها (OPERANDS)
       عملوندهای زیر پشتیبانی می‌شوند:

       bibfile   نام یک پایگاه‌داده‌ی کتاب‌شناختی باید مشخص شود. این باید فایلی
                 با قالب refer(1) باشد و هر مدخل باید حداقل یک فیلد %L داشته
                 باشد که به‌عنوان برچسب استفاده می‌شود. (مدخل‌های بدون چنین فیلدی
                 نادیده گرفته خواهند شد.)  مدخل‌ها به‌صورت اختیاری می‌توانند یک
                 خط %K داشته باشند که باید حاوی کلیدواژه‌هایی باشد که با فاصله
                 از هم جدا شده‌اند. این کلیدواژه‌ها می‌توانند به‌جای برچسب برای
                 ارجاع به مدخل استفاده شوند. بنابراین foo در [[foo]] می‌تواند
                 یا برچسب یک مدخل (خط %L) یا یکی از کلیدواژه‌های خط %K مدخل
                 باشد.

       file      نام فایل ورودی اختیاری است. در صورت نبود آن، hxcite از ورودی
                 استاندارد (stdin) می‌خواند. فایل نیازی نیست حتماً یک فایل HTML
                 باشد، اما الگوی پیش‌فرض (گزینه‌ی -p را ببینید) ساختار HTML را
                 فرض می‌کند.

وضعیت خروج (EXIT STATUS)
       مقادیر خروج زیر بازگردانده می‌شوند:

       0         اتمام موفقیت‌آمیز.

       > 0       خطایی رخ داده است. معمولاً به این دلیل است که یک فایل باز نشد.
                 به‌ندرت ممکن است به دلیل خطای کمبود حافظه نیز باشد.

نسخه‌ها (VERSIONS)
       مارس ۲۰۰۰: توسط Bert Bos <bert@w3.org> با نام «cite» ایجاد شد.

       اوت ۲۰۰۸: به «hxcite» تغییر نام یافت.

       در حال حاضر توسط Bert Bos نگهداری می‌شود.

گزارش باگ‌ها (BUGS)
       دستور hxcite در واقع ورودی HTML یا XML را تجزیه نمی‌کند و گزینه‌ی -c صرفاً
       با هر وقوع «<!--» به‌عنوان آغاز یک کامنت XML رفتار می‌کند، حتی اگر درون
       مقدار یک صفت یا یک بخش CDATA رخ دهد. به همین ترتیب برای «-->» جهت پایان
       کامنت.

       در حال حاضر هیچ روشی برای استفاده از اعداد در ارجاعات (مانند «[1]»،
       «[2]») به‌جای برچسب‌ها («[Lie1996]»، «[UTN22]») وجود ندارد.

       برنامه‌ی hxcite نیازمند وجود فیلد %L (برچسب) در هر مدخل در bibfile است،
       در حالی که در refer(1) چنین الزامی وجود ندارد. همچنین hxcite قابلیت
       جستجوی کلیدواژه‌ی refer را پیاده‌سازی نکرده است.

مثال‌ها (EXAMPLES)
       دستور زیر به‌دنبال ارجاعاتی به فرم «[[!label]]» در «myfile.html» می‌گردد،
       ارجاعات درون کامنت‌های HTML را نادیده می‌گیرد، و برچسب‌ها را در
       «biblio.ref» جستجو می‌کند.  خروجی در «new.html» و فهرست برچسب‌های
       شناسایی‌شده در «myfile.aux» نوشته می‌شود.

           hxcite -c -m '!' biblio.ref myfile.html > new.html


همچنین ببینید (SEE ALSO)
       asc2xml(1), refer(1), hxmkbib(1), hxnormalize(1), hxnum(1), hxprune(1),
       hxtoc(1), hxunent(1), xml2asc(1), UTF-8 (RFC 2279)

7.x                               10 Jul 2011                        HXCITE(1)