.de d \" begin display
.sp
.in +4
.nf
..
.de e \" end display
.in -4
.fi
.sp
..
.TH "HXCITE\-MKBIB" "1" "10 Jul 2011" "7.x" "HTML-XML-utils"
.SH "نام (NAME)"
hxcite-mkbib \- بسط دادن ارجاعات و ساخت کتاب‌نامه
.SH "خلاصه دستور (SYNOPSIS)"
.B hxcite\-mkbib
.RB "[\| " \-b
.IR base " \|]"
.RB "[\| " \-p
.IR pattern " \|]"
.RB "[\| " \-s
.IR separator " \|]"
.IR bibfile " [\| " file " \|]"
.SH "توضیحات (DESCRIPTION)"
.LP
دستور
.B hxcite\-mkbib
فایل
.I file
را در خروجی استاندارد کپی می‌کند و به دنبال رشته‌هایی به فرم «[[\fIlabel\fP]]» و قالبی برای کتاب‌نامه می‌گردد. برچسب نباید شامل فاصله خالی (whitespace) باشد و جفت کروشه‌های دوتایی باید بدون هیچ فاصله‌ای در میان، برچسب را احاطه کرده باشند. اگر
.B hxcite\-mkbib
برچسب را در
.IR bibfile
بیابد، رشته با
.IR pattern
جایگزین می‌شود. الگو می‌تواند شامل متغیرهای خاصی باشد. اگر برچسب در
.IR bibfile
یافت نشود، بدون تغییر رها می‌شود.
.PP
الگوی پیش‌فرض، رشته را با یک ابرپیوند جایگزین می‌کند؛ اما اگر از گزینهٔ
.B \-p
استفاده شود، جایگزین می‌تواند هر الگویی باشد. ورودی حتی نیازی نیست حتماً HTML باشد.
.PP
فایل
.I file
از سه بخش تشکیل شده است:
.TP 10
.B preamble
مقدمه (preamble) بخشی است که تا نخستین وقوع
.BR %{
ادامه دارد. مقدمه یک بار به خروجی کپی می‌شود (همراه با بسط داده شدن برچسب‌های محصور در کروشه
(«[[\fIlabel\fP]]»)). نویسهٔ
.B %
به‌طور ویژه‌ای پردازش می‌شود. برای ایجاد یک % تکی در خروجی، باید دو نویسه از آن در مقدمه وجود داشته باشد (%%). تمام دفعات دیگر وقوع % که پس از آن حرف دیگری آمده باشد کپی نمی‌شوند، بلکه در رشته‌ای به نام «ترتیب مرتب‌سازی» (sort order) جمع‌آوری شده و همان‌طور که در ادامه توضیح داده شده، برای مرتب‌سازی ورودی‌ها به کار می‌روند.
.TP
.B template
قالب (template) با
.B %{L:
آغاز شده و با یک
.BR %}
متناظر پایان می‌یابد. متن میان آن‌ها به تعداد مدخل‌های کتاب‌شناختی موجود در
.I bibfile
که با برچسب‌های درون کروشه در
.IR file
همخوانی دارند، کپی می‌شود. متغیرها در قالب با فیلد متناظر در مدخل کتاب‌شناختی جایگزین می‌شوند: تمامی رخدادهای
.BI % x
با فیلد
.BI % x
مدخل جایگزین خواهند شد. بخش‌هایی از متن ممکن است بین
.BI %{ x :
و
.BR %}
قرار گیرند. این بدان معناست که متن میان آن‌ها تنها زمانی باید در خروجی چاپ شود که مدخل جاری دارای فیلد
.IR x
باشد. متنی که بین
.BI %{! x :
و
.B %}
محصور شده باشد، تنها در صورتی چاپ خواهد شد که مدخل فاقد فیلد
.IR x
.B باشد
(آن را نداشته باشد). هر دو نوع بخش‌های شرطی می‌توانند به‌صورت تو در تو نیز قرار گیرند.
.TP
.B postamble
متن پس از
.B %}
بدون تغییر به خروجی کپی می‌شود، پس از آن‌که همهٔ مدخل‌های کتاب‌شناختی پردازش شدند.
.PP
به‌طور پیش‌فرض، مدخل‌های کتاب‌شناختی به ترتیبی که برچسب‌ها در
.IR file
آمده‌اند به خروجی کپی می‌شوند، جز اینکه برچسب‌هایی که بیش از یک‌بار تکرار شده‌اند تنها یک‌بار استفاده می‌شوند. اگر مقدمه شامل مواردی از
.BI % x
باشد (که در آن
.I x
نه «%» است و نه «{»)، آنگاه این موارد با یکدیگر ترتیب مرتب‌سازی را تعیین می‌کنند. برای نمونه، اگر مقدمه شامل %A%D باشد، مدخل‌ها ابتدا بر اساس فیلد A (نویسنده) و سپس بر اساس فیلد D (تاریخ) مرتب خواهند شد.
.PP
در اینجا نمونه‌ای از فایلی آمده است که یک کتاب‌نامه را در قالب HTML ایجاد می‌کند:
.d
<html>
<title>Bibliography</title>
\&... text with [[references]] here...
<!--%A%D sorted on author, then date -->
<dl>
%{L:
<dt id="%L">%{A:A%}%{!A:%{E:E%}%{!E:%{Q:Q%}%{!Q:-%}%}%}</dt>
<dd>%{B:"%T"
  in: %{E:%E (eds)
  %}<cite>%B.</cite>%{V: %V.%}
  %}%{J:"%T"
  in: %{E:%E (eds)
  %}<cite>%J.</cite>%{V: %V.%}%{N: %N.%}%{P: pp. %P.%}
  %}%{!B:%{!J:<cite>%T.</cite>
  %}%}%{I:%I.
  %}%{D:%D.
  %}%{C:%C.
  %}%{R:%R.
  %}%{S:%S.
  %}%{O:%O
  %}%{U:<a href="%U">%U</a>
  %}</dd>
%}
</dl>
</html>
.e
این قالب با چهار خط مقدمه آغاز می‌شود، از جمله رشتهٔ مرتب‌سازی %A%D در خط ۳. خود رشتهٔ مرتب‌سازی در خروجی چاپ نخواهد شد، اما بقیه توضیحات (کامنت) چاپ می‌شود.
.PP
از خط
.B %{L:
تا خط
.B %}
قالب اصلی است. برای نمونه، خطی که با
.B <dt id=...
شروع می‌شود، شامل متنی شرطی و پیچیده است که در صورت وجود نویسندگان (%A) آن‌ها را چاپ می‌کند، در غیر این صورت اگر ویراستارانی (%E) وجود داشته باشند آن‌ها را چاپ می‌کند، در غیر این صورت نهادی که نویسنده است (%Q) در صورت وجود، و در غیر این صورت یک خط تیره (-) چاپ می‌کند. توجه داشته باشید که این بخش‌ها چگونه تو در تو شده‌اند؛ بیشتر متن درون
.BR %{!A:...%}
قرار دارد، به این معنی که این بخش تنها در صورتی عمل خواهد کرد که فیلد نویسنده (%A) وجود نداشته باشد.
.PP
دو خط پایانی مؤخره (postamble) هستند و صرفاً بدون تغییر کپی خواهند شد.
.PP
یک مدخل کتاب‌شناختی که در
.IR bibfile
به این صورت باشد:
.d
%L Java
%A Gosling, James
%A Joy, Bill
%A Steele, Guy
%T The Java language specification
%D 1998
%I Addison-Wesley
%U http://java.sun.com/docs/books/jls/index.html
.e
توسط قالب بالا به صورت زیر چاپ خواهد شد:
.d
<dt id="Java">Gosling, James; Joy, Bill; Steele, Guy</dt>
<dd><cite>The Java language specification.</cite>
  Addison-Wesley.
  1998.
  <a href="http://java.sun.com/docs/books/jls/index.html">http://java.sun.com/docs/books/jls/index.html</a>
  </dd>
.e.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر پشتیبانی می‌شوند:
.TP 10
.BI \-p " pattern"
الگویی را مشخص می‌کند که رشتهٔ [[\fIlabel\fP]] بر اساس آن جایگزین می‌شود.
الگو ممکن است شامل متغیرهای
.B %b
(که با مقدار گزینهٔ
.B \-b
جایگزین می‌شود) و
.B %L
(که با
.I label
جایگزین خواهد شد) باشد.
الگوی پیش‌فرض به این صورت است:
.d
<a href="%b#%L" rel="biblioentry">[%L]</a>
.e
.TP
.BI \-b " base"
مقدار متغیر
.B %b
را در الگو تعیین می‌کند. معمولاً این مقدار روی یک URL نسبی یا مطلق تنظیم می‌شود. به‌طور پیش‌فرض این مقدار یک رشتهٔ خالی است.
.TP
.BI \-s " separator"
اگر چندین نویسنده یا ویراستار در یک مدخل وجود داشته باشند، نام‌های آن‌ها با یک جداکننده میانشان فهرست خواهد شد. به‌طور پیش‌فرض این جداکننده "; " (یعنی یک نقطه‌ویرگول و یک فاصله) است. با این گزینه می‌توان جداکننده را تغییر داد.
.SH "عملوندها (OPERANDS)"
عملوندهای زیر پشتیبانی می‌شوند:
.TP 10
.I bibfile
نام یک پایگاه‌دادهٔ کتاب‌شناختی باید مشخص شود. این باید فایلی در قالب
.BR refer (1)
بوده و هر مدخل باید دست‌کم دارای یک فیلد
.B %L
باشد، که با برچسب‌های درون قلاب مقایسه می‌شود. (مدخل‌های فاقد چنین فیلدی نادیده گرفته خواهند شد.)
.TP
.I file
نام فایل ورودی اختیاری است. در صورت مشخص نشدن،
.BR hxmkbib (1)
الگو را از stdin خواهد خواند.
.SH "خطاها (DIAGNOSTICS)"
مقدارهای خروج زیر بازگردانده می‌شوند:
.TP 10
.B 0
پایان موفقیت‌آمیز.
.TP
.B > 0
خطایی رخ داد. معمولاً این به این دلیل است که فایلی باز نشد یا جفت‌های %{ و %} به‌درستی تودرتو نشده‌اند. در مواردی بسیار نادر ممکن است ناشی از خطای کمبود حافظه نیز باشد. برخی از پیام‌های خطای احتمالی:
.TP
.I missing ':' in pattern
دستور
.B hxmkbib
یک %{ یافت اما نویسهٔ دوم یا سوم پس از آن دونقطه (:) نبود.
.TP
.I no '%{' in template file
فایل الگو غیرقابل استفاده است، زیرا هیچ الگویی در آن وجود ندارد.
.TP
.I unbalanced %{..%} in pattern
تعداد %{ بیشتر از %} است.
.SH "همچنین ببینید (SEE ALSO)"
.BR asc2xml (1),
.BR hxcite (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)"
.SH "گزارش باگ‌ها (BUGS)"
مرتب‌سازی ابتدایی است: برنامه تاریخ‌ها یا نام‌ها را تجزیه نمی‌کند و صرفاً "Jan 2000" را زیر حرف "J" و "Albert Camus" را زیر حرف "A" مرتب می‌کند. در حال حاضر تنها راهکار این است که نام‌ها در
.I bibfile
به‌صورت "Camus, Albert" قرار داده شوند.
.PP
برنامه صرفاً همهٔ نویسندگان یا ویراستاران را فهرست می‌کند. هیچ راهی برای ایجاد یک ".et al" پس از سومی وجود ندارد. راهکار این است که ".et al" را در
.I bibfile
قرار دهید. همچنین گذاشتن ویرگول میان نویسندگان ابتدایی و واژهٔ "and" پیش از نویسندهٔ پایانی امکان‌پذیر نیست.
.PP
برنامه تلاشی برای تفسیر نام‌های نویسندگان یا ویراستاران نمی‌کند و آن‌ها را نمی‌توان بازقالب‌بندی کرد. نوشتن نامی که در
.I bibfile
به‌صورت "Sartre, Jean-Paul" مشخص شده است، به‌شکل "J. Sartre" یا "Jean-Paul Sartre" در خروجی غیرممکن است.
.PP
اگر یک فیلد از قبل با یک نقطه پایان یابد، هیچ راهی برای جلوگیری از آمدن نقطه پس از آن وجود ندارد. برای نمونه، اگر نویسنده "A. Person Jr." باشد، الگوی "%{A:A.%}" ممکن است "A. Person Jr.." را تولید کند. تنها گزینه این است که یا در
.I bibfile
نقطه نگذارید یا در الگو نقطه‌ای قرار ندهید.
.PP
مدخل‌های موجود در
.I bibfile
تنها در صورتی قابل استفاده هستند که یک فیلد
.B %L
(برچسب) داشته باشند. برنامه بر خلاف
.BR refer (1)
نمی‌تواند مدخل‌ها را با جستجوی کلیدواژه‌ها بیابد.
.PP
دستور
.B hxmkbib
با این فرض که الگو HTML/XML است، هرگونه علامت امپرسند (&) و علامت‌های کوچک‌تر (<) و بزرگ‌تر (>) موجود در
.I bibfile
را با موجودیت‌های XML آن‌ها یعنی &amp; &lt; &gt; جایگزین خواهد کرد. این ممکن است برای سایر قالب‌ها مناسب نباشد.
.PP
دستور
.B hxcite\-mkbib
یک اسکریپت شل (bash) است که
.BR hxcite (1)
و
.BR hxmkbib (1)
را فراخوانی می‌کند، و بنابراین روی همهٔ پلتفرم‌ها قابل حمل نیست.