.de d \" begin display
.sp
.in +4
.nf
..
.de e \" end display
.in -4
.fi
.sp
..
.TH "HXMKBIB" "1" "10 Jul 2011" "7.x" "HTML-XML-utils"
.SH "نام (NAME)"
hxmkbib \- ایجاد کتاب‌شناسی از روی یک الگو
.SH "خلاصه دستور (SYNOPSIS)"
.B hxmkbib
.RB "[\| " \-s
.IR separator " \|]"
.RB "[\| " \-a
.IR auxfile " \|]"
.RB "[\| " \-n
.IR maxauthors " \|]"
.RB "[\| " \-r
.IR moreauthors " \|]"
.IR bibfile " [\| " templatefile " \|]"
.SH "توضیحات (DESCRIPTION)"
.LP
دستور
.B hxmkbib
فهرستی از کلیدهای کتاب‌شناسی (برچسب‌ها) را از
.I auxfile
می‌خواند، مدخل‌های متناظر با آن‌ها را در
.I bibfile
می‌یابد و با استفاده از
.I templatefile
به عنوان الگو، یک کتاب‌شناسی ایجاد می‌کند.
.I auxfile
ممکن است، برای نمونه، توسط
.BR hxcite (1)
ایجاد شده باشد. این فایل شامل برچسب‌ها، در هر خط یکی، است.
.I bibfile
یک پایگاه‌داده به سبک
.BR refer (1)
است.
.B hxmkbib
به دنبال مدخل‌هایی می‌گردد که دارای فیلد
.B %L
برابر با کلیدی در
.I auxfile
باشند.
.PP
فایل
.I templatefile
از سه بخش تشکیل شده است:
.TP 10
.B preamble
دیباچه (preamble) بخشی است که تا نخستین وقوع
.BR %{
امتداد دارد. دیباچه، به‌جز در موارد وقوع
.BR % \c
، بدون تغییر به خروجی کپی می‌شود.
برای ایجاد یک % منفرد در خروجی، باید دو % در دیباچه وجود داشته باشد (%%). تمام موارد دیگر % که بلافاصله پس از آن‌ها حرف دیگری بیاید کپی نمی‌شوند، بلکه در رشته‌ای تحت عنوان «ترتیب مرتب‌سازی» جمع‌آوری شده و همان‌طور که در ادامه توضیح داده شده، برای مرتب‌سازی مدخل‌ها به کار می‌روند.
.TP
.B template
الگو (template) با
.B %{L:
آغاز شده و با یک
.B %}
متناظر پایان می‌یابد. متن بین این دو، به تعداد مدخل‌های کتاب‌شناسی موجود در
.I bibfile
که متناظر با کلیدهای
.I auxfile
هستند، به خروجی کپی می‌شود.
متغیرها در الگو با فیلد متناظر در مدخل کتاب‌شناسی جایگزین می‌شوند: تمام موارد وقوع
.BI % x
با فیلد
.BI % x
آن مدخل جایگزین خواهد شد. بخش‌هایی از متن می‌توانند بین
.BI %{ x :
و
.B %}
محصور شوند. این بدان معناست که متن بین آن‌ها تنها زمانی باید در خروجی چاپ شود که مدخل جاری دارای فیلد
.I x
باشد. متنی که بین
.BI %{! x :
و
.B %}
قرار می‌گیرد، تنها زمانی در خروجی ظاهر خواهد شد که مدخل فیلد
.I x
را
.B نداشته
باشد. هر دو نوع بخش‌های شرطی را می‌توان به صورت تو در تو نیز استفاده کرد.
.TP
.B postamble
متنِ پس از
.B %}
پس از پردازش تمامی مدخل‌های کتاب‌شناسی، بدون تغییر به خروجی کپی می‌شود.
.PP
به‌طور پیش‌فرض، مدخل‌های کتاب‌شناسی به ترتیب کلیدهای موجود در
.I auxfile
به خروجی کپی می‌شوند، با این استثنا که کلیدهایی که بیش از یک بار تکرار شده‌اند تنها یک بار به کار می‌روند. اگر دیباچه شامل مواردی از
.BI % x
باشد (که در آن
.I x
نه «%» است و نه «{»)، این موارد در کنار یکدیگر ترتیب مرتب‌سازی را تعیین می‌کنند.
برای مثال، اگر دیباچه حاوی %A%D باشد، مدخل‌ها ابتدا بر اساس فیلد A (نویسنده) و سپس بر اساس فیلد D (تاریخ) مرتب خواهند شد.
.PP
در ادامه نمونه‌ای از یک فایل الگو آورده شده است که کتاب‌شناسی را در قالب HTML ایجاد می‌کند:
.d
<html>
<title>Bibliography</title>
<!--%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
یک مدخل کتاب‌شناسی که در
.I 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 \-a " auxfile"
فایلی که شامل فهرست کلیدها (برچسب‌ها) است که مدخل‌های کتاب‌شناختی باید برای آن‌ها چاپ شوند. اگر این گزینه ارائه نشود، نام این فایل از آرگومان
.I templatefile
با حذف آخرین پسوند و افزودن
.BR .aux
ساخته می‌شود. اگر هیچ
.I templatefile
مشخص نشده باشد،
.I auxfile
پیش‌فرض
.BR aux.aux
خواهد بود.
.TP
.BI \-s " separator"
اگر چندین نویسنده یا ویراستار در یک مدخل وجود داشته باشند، نام‌های آن‌ها با یک جداکننده در میانشان فهرست خواهد شد. جداکننده به‌طور پیش‌فرض "; " (یعنی یک نقطه‌ویرگول و یک فاصله) است. با این گزینه می‌توان جداکننده را تغییر داد.
.TP
.BI \-n " maxauthors"
اگر بیش از
.I maxauthors
نویسنده در یک مدخل وجود داشته باشد، تنها نام نویسنده نخست چاپ خواهد شد و سایر نویسندگان با رشتهٔ
.IR moreauthors
جایگزین می‌شوند. مقدار پیش‌فرض 3 است.
.TP
.BI \-r " moreauthors"
رشته‌ای که در صورت وجود بیش از
.I maxauthors
نویسنده چاپ می‌شود. مقدار پیش‌فرض "et al." است.
.SH "عملوندها (OPERANDS)"
عملوندهای زیر پشتیبانی می‌شوند:
.TP 10
.I bibfile
نام یک پایگاه‌دادهٔ کتاب‌شناختی باید مشخص شود. این باید فایلی با قالب
.BR refer (1)
باشد و هر مدخل باید دست‌کم یک فیلد
.B %L
داشته باشد که به‌عنوان کلید استفاده می‌شود. (مدخل‌های فاقد چنین فیلدی نادیده گرفته خواهند شد.)
.TP
.I templatefile
نام فایل ورودی اختیاری است. در صورت نبود آن،
.B hxmkbib
قالب را از 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 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.» در
.IR bibfile
است. همچنین قرار دادن کاما بین نویسندگان نخست و واژهٔ «and» پیش از آخرین نویسنده امکان‌پذیر نیست.
.PP
این برنامه تلاشی برای تفسیر نام نویسندگان یا ویراستاران نمی‌کند و امکان قالب‌بندی مجدد آن‌ها وجود ندارد. نوشتن نامی که در
.I bibfile
به‌صورت «Sartre, Jean-Paul» مشخص شده است، به‌صورت «J. Sartre» یا «Jean-Paul Sartre» در خروجی غیرممکن است.
.PP
اگر فیلدی از قبل با یک نقطه خاتمه یافته باشد، هیچ راهی برای جلوگیری از درج نقطه پس از آن فیلد وجود ندارد. برای نمونه، اگر نویسنده «A. Person Jr.» باشد، الگوی «%{A:A.%}» ممکن است «A. Person Jr..» را در خروجی تولید کند. تنها گزینه این است که یا در
.IR bibfile
نقطه نگذارید یا در الگو نقطه قرار ندهید.
.PP
مدخل‌ها در
.I bibfile
تنها در صورتی قابل استفاده هستند که دارای یک فیلد
.B %L
(برچسب) باشند. این برنامه نمی‌تواند مانند
.BR refer (1)
مدخل‌ها را با جستجوی کلیدواژه‌ها بیابد.
.PP
.B hxmkbib
با این فرض که الگو از نوع HTML/XML است، هر علامت امپرسند (&)، کوچکتری (<) و بزرگتری (>) موجود در
.I bibfile
را با موجودیت‌های XML متناظر آن‌ها یعنی &amp;، &lt; و &gt; جایگزین می‌کند. این رفتار ممکن است برای سایر قالب‌ها مناسب نباشد.