نام (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)