.de d \" begin display
.sp
.in +4
.nf
..
.de e \" end display
.in -4
.fi
.sp
..
.TH "HXCITE" "1" "10 Jul 2011" "7.x" "HTML-XML-utils"
.SH "نام (NAME)"
hxcite \- جایگزینی ارجاعات کتاب‌شناختی با پیوندها
.SH "خلاصه دستور (SYNOPSIS)"
.B hxcite
.RB "[\| " \-b
.IR base " \|]"
.RB "[\| " \-p
.IR pattern " \|]"
.RB "[\| " \-a
.IR auxfile " \|]"
.RB "[\| " \-m
.IR marker " \|]"
.RB "[\| " -c " \|]"
.IR bibfile " [\| " file " \|]"
.SH "توضیحات (DESCRIPTION)"
.LP
دستور
.B hxcite
پرونده‌ی
.I file
را در خروجی استاندارد کپی کرده و به‌دنبال رشته‌هایی به شکل [[\fIlabel\fP]] می‌گردد.
برچسب (label) نباید شامل فاصله‌ی خالی باشد و جفت‌کروشه‌های باز و بسته باید بدون
هیچ فاصله‌ای در میان، برچسب را در بر بگیرند. اگر
.B hxcite
برچسب را در
.I bibfile
پیدا کند، رشته با
.I pattern
جایگزین می‌شود. الگو می‌تواند شامل متغیرهای مشخصی باشد. اگر برچسب در
.I bibfile
یافت نشود، دست‌نخورده باقی می‌ماند.
.PP
الگوی پیش‌فرض، رشته را با یک پیوند جایگزین می‌کند، اما اگر گزینه‌ی
.B \-p
استفاده شود، جایگزین می‌تواند هر الگویی باشد. ورودی حتی نیازی نیست که HTML باشد.
.LP
اگر برچسب به‌جای [[...]] در {{...}} قرار گرفته باشد، بدون تغییر به خروجی کپی شده و
با الگو جایگزین نمی‌شود، ولی برچسب همچنان در
.I bibfile
جستجو می‌شود.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر پشتیبانی می‌شوند:
.TP 10
.BI \-p " pattern"
الگویی را تعیین می‌کند که رشته‌ی [[\fIlabel\fP]] با آن جایگزین می‌شود.
الگو می‌تواند شامل متغیرهای
.B %b
(که با مقدار گزینه‌ی
.B \-b
جایگزین می‌شود)،
.B %m
(که با مقدار گزینه‌ی
.B \-m
جایگزین می‌شود) و
.B %L
(که با
.I label
جایگزین می‌شود) باشد. الگوی پیش‌فرض بدین صورت است:
.d
<a href="%b#%L" rel="biblioentry">[%L]<!--{{%m%L}}--></a>
.e
.TP
.BI \-b " base"
مقدار متغیر
.B %b
را در الگو تنظیم می‌کند. معمولاً این مقدار بر روی یک URL نسبی یا
مطلق تنظیم می‌شود. به‌طور پیش‌فرض این مقدار یک رشته‌ی خالی است.
.TP
.BI \-a " auxfile"
تمام برچسب‌هایی که پیدا و جایگزین شده‌اند نیز در یک فایل نوشته می‌شوند. این کار
به این منظور است که
.BR hxmkbib (1)
بتواند آن‌ها را پیدا کرده و یک کتاب‌شناسی ایجاد کند. پرونده‌ی
.I auxfile
پیش‌فرض از نام
.I file
با حذف آخرین پسوند آن (در صورت وجود) و جایگزینی آن با «.aux» ساخته می‌شود.
اگر هیچ
.I file
مشخص نشده باشد، نام پیش‌فرض «aux.aux» خواهد بود.
.TP
.BI \-m " marker"
به‌طور پیش‌فرض، برنامه به‌دنبال «[[name]]» می‌گردد، اما می‌توان آن را
طوری تنظیم کرد که به‌دنبال «[[#name]]» بگردد که در آن # یک رشته است، معمولاً
نمادی مانند «!» یا «=». این قابلیت اجازه می‌دهد ارجاعات دسته‌بندی شوند؛ برای مثال،
«[[!name]]» برای ارجاعات هنجاری (normative) و «[[name]]» برای ارجاعات غیرهنجاری (non-normative).
.TP
.B \-c
باعث نادیده‌گرفته‌شدن «[[name]]» در زمان وقوع آن در درون کامنت‌های XML
(«<!--...-->») می‌شود. این گزینه برای فایل‌هایی مفید است که در آن‌ها چنین برچسب‌هایی درون
کامنت‌ها قرار دارند، تا از باز شدن آن‌ها و احتمالاً ایجاد خروجی نامعتبر جلوگیری شود؛ همچنین زمانی
کاربرد دارد که
.B hxcite
برای فایل‌های غیر HTML استفاده شود که ممکن است حاوی «<!--» باشند بدون آن‌که کامنت باشند.
موارد وقوع «{{name}}» تحت تأثیر
.B \-c
قرار نمی‌گیرند. (اما هشدار بخش باگ‌ها در زیر را ببینید.)
.SH "عملوندها (OPERANDS)"
عملوندهای زیر پشتیبانی می‌شوند:
.TP 10
.I bibfile
نام یک پایگاه‌داده‌ی کتاب‌شناختی باید مشخص شود. این باید فایلی با قالب
.BR refer (1)
باشد و هر مدخل باید حداقل یک فیلد
.B %L
داشته باشد که به‌عنوان برچسب استفاده می‌شود. (مدخل‌های بدون چنین فیلدی نادیده گرفته خواهند شد.)
مدخل‌ها به‌صورت اختیاری می‌توانند یک خط
.B %K
داشته باشند که باید حاوی کلیدواژه‌هایی باشد که با فاصله از هم جدا شده‌اند. این کلیدواژه‌ها می‌توانند
به‌جای برچسب برای ارجاع به مدخل استفاده شوند. بنابراین
.I foo
در [[\fIfoo\fP]] می‌تواند یا برچسب یک مدخل (خط %L) یا یکی از کلیدواژه‌های خط %K مدخل باشد.
.TP
.I file
نام فایل ورودی اختیاری است. در صورت نبود آن،
.B hxcite
از ورودی استاندارد (stdin) می‌خواند. فایل نیازی نیست حتماً یک فایل HTML باشد،
اما الگوی پیش‌فرض (گزینه‌ی
.B \-p
را ببینید) ساختار HTML را فرض می‌کند.
.SH "وضعیت خروج (EXIT STATUS)"
مقادیر خروج زیر بازگردانده می‌شوند:
.TP 10
.B 0
اتمام موفقیت‌آمیز.
.TP
.B > 0
خطایی رخ داده است. معمولاً به این دلیل است که یک فایل باز نشد. به‌ندرت ممکن است به دلیل خطای کمبود حافظه نیز باشد.
.SH "نسخه‌ها (VERSIONS)"
.PP
مارس ۲۰۰۰: توسط Bert Bos <bert@w3.org> با نام «cite» ایجاد شد.
.PP
اوت ۲۰۰۸: به «hxcite» تغییر نام یافت.
.PP
در حال حاضر توسط Bert Bos نگهداری می‌شود.
.SH "گزارش باگ‌ها (BUGS)"
.PP
دستور
.B hxcite
در واقع ورودی HTML یا XML را تجزیه نمی‌کند و گزینه‌ی
.B \-c
صرفاً با هر وقوع «<!--» به‌عنوان آغاز یک کامنت XML رفتار می‌کند، حتی اگر درون مقدار یک صفت
یا یک بخش CDATA رخ دهد. به همین ترتیب برای «-->» جهت پایان کامنت.
.PP
در حال حاضر هیچ روشی برای استفاده از اعداد در ارجاعات (مانند «[1]»، «[2]»)
به‌جای برچسب‌ها («[Lie1996]»، «[UTN22]») وجود ندارد.
.PP
برنامه‌ی
.B hxcite
نیازمند وجود فیلد
.B %L
(برچسب) در هر مدخل در
.I bibfile
است، در حالی که در
.BR refer (1)
چنین الزامی وجود ندارد. همچنین
.B hxcite
قابلیت جستجوی کلیدواژه‌ی
.BR refer
را پیاده‌سازی نکرده است.
.SH "مثال‌ها (EXAMPLES)"
.PP
دستور زیر به‌دنبال ارجاعاتی به فرم «[[!label]]» در «myfile.html» می‌گردد،
ارجاعات درون کامنت‌های HTML را نادیده می‌گیرد، و برچسب‌ها را در «biblio.ref» جستجو می‌کند.
خروجی در «new.html» و فهرست برچسب‌های شناسایی‌شده در «myfile.aux» نوشته می‌شود.
.d
hxcite -c -m '!' biblio.ref myfile.html > new.html
.e
.SH "همچنین ببینید (SEE ALSO)"
.BR asc2xml (1),
.BR refer (1),
.BR hxmkbib (1),
.BR hxnormalize (1),
.BR hxnum (1),
.BR hxprune (1),
.BR hxtoc (1),
.BR hxunent (1),
.BR xml2asc (1),
.BR UTF-8 " (RFC 2279)"