نام (NAME)

hxmkbib - ایجاد کتاب‌شناسی از روی یک الگو

خلاصه دستور (SYNOPSIS)

hxmkbib [ -s separator ] [ -a auxfile ] [ -n maxauthors ] [ -r moreauthors ] bibfile [ templatefile ]

توضیحات (DESCRIPTION)

دستور hxmkbib فهرستی از کلیدهای کتاب‌شناسی (برچسب‌ها) را از auxfile می‌خواند، مدخل‌های متناظر با آن‌ها را در bibfile می‌یابد و با استفاده از templatefile به عنوان الگو، یک کتاب‌شناسی ایجاد می‌کند. auxfile ممکن است، برای نمونه، توسط hxcite(1) ایجاد شده باشد. این فایل شامل برچسب‌ها، در هر خط یکی، است. bibfile یک پایگاه‌داده به سبک refer(1) است. hxmkbib به دنبال مدخل‌هایی می‌گردد که دارای فیلد %L برابر با کلیدی در auxfile باشند.

فایل templatefile از سه بخش تشکیل شده است:

preamble: دیباچه (preamble) بخشی است که تا نخستین وقوع %{ امتداد دارد. دیباچه، به‌جز در موارد وقوع %، بدون تغییر به خروجی کپی می‌شود. برای ایجاد یک % منفرد در خروجی، باید دو % در دیباچه وجود داشته باشد (%%). تمام موارد دیگر % که بلافاصله پس از آن‌ها حرف دیگری بیاید کپی نمی‌شوند، بلکه در رشته‌ای تحت عنوان «ترتیب مرتب‌سازی» جمع‌آوری شده و همان‌طور که در ادامه توضیح داده شده، برای مرتب‌سازی مدخل‌ها به کار می‌روند.
template: الگو (template) با %{L: آغاز شده و با یک %} متناظر پایان می‌یابد. متن بین این دو، به تعداد مدخل‌های کتاب‌شناسی موجود در bibfile که متناظر با کلیدهای auxfile هستند، به خروجی کپی می‌شود. متغیرها در الگو با فیلد متناظر در مدخل کتاب‌شناسی جایگزین می‌شوند: تمام موارد وقوع %x با فیلد %x آن مدخل جایگزین خواهد شد. بخش‌هایی از متن می‌توانند بین %{x: و %} محصور شوند. این بدان معناست که متن بین آن‌ها تنها زمانی باید در خروجی چاپ شود که مدخل جاری دارای فیلد x باشد. متنی که بین %{!x: و %} قرار می‌گیرد، تنها زمانی در خروجی ظاهر خواهد شد که مدخل فیلد x را نداشته باشد. هر دو نوع بخش‌های شرطی را می‌توان به صورت تو در تو نیز استفاده کرد.
postamble: متنِ پس از %} پس از پردازش تمامی مدخل‌های کتاب‌شناسی، بدون تغییر به خروجی کپی می‌شود.

به‌طور پیش‌فرض، مدخل‌های کتاب‌شناسی به ترتیب کلیدهای موجود در auxfile به خروجی کپی می‌شوند، با این استثنا که کلیدهایی که بیش از یک بار تکرار شده‌اند تنها یک بار به کار می‌روند. اگر دیباچه شامل مواردی از %x باشد (که در آن x نه «%» است و نه «{»)، این موارد در کنار یکدیگر ترتیب مرتب‌سازی را تعیین می‌کنند. برای مثال، اگر دیباچه حاوی %A%D باشد، مدخل‌ها ابتدا بر اساس فیلد A (نویسنده) و سپس بر اساس فیلد D (تاریخ) مرتب خواهند شد.

در ادامه نمونه‌ای از یک فایل الگو آورده شده است که کتاب‌شناسی را در قالب HTML ایجاد می‌کند:

<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>

این الگو با چهار خط دیباچه آغاز می‌شود که شامل رشتهٔ مرتب‌سازی %A%D در خط ۳ است. خودِ رشتهٔ مرتب‌سازی در خروجی آورده نمی‌شود، اما باقی‌ماندهٔ کامنت چاپ خواهد شد.

از خط %{L: تا خط %} بخش الگو قرار دارد. به عنوان مثال، خطی که با <dt id=... آغاز می‌شود، شامل یک متن شرطی پیچیده است که در صورت وجود نویسندگان (%A) آن‌ها را چاپ می‌کند، در غیر این صورت اگر ویراستارانی (%E) وجود داشته باشند آن‌ها را چاپ می‌کند، در غیر این صورت مؤسسه‌ای که پدیدآورنده است (%Q) را در صورت وجود چاپ می‌کند، و در غیر این صورت یک خط تیره (-) چاپ می‌نماید. توجه کنید که بخش‌ها چگونه تو در تو قرار گرفته‌اند؛ بخش عمدهٔ متن درون %{!A:...%} است، به این معنی که آن بخش تنها زمانی مؤثر خواهد بود که فیلد نویسنده‌ای (%A) وجود نداشته باشد.

دو خط پایانی بخش مؤخره (postamble) هستند و صرفاً بدون تغییر کپی خواهند شد.

یک مدخل کتاب‌شناسی که در bibfile به شکل زیر باشد:

%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

توسط الگوی بالا به صورت زیر چاپ خواهد شد:

<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>
گزینه‌های زیر پشتیبانی می‌شوند:

-a auxfile

فایلی که شامل فهرست کلیدها (برچسب‌ها) است که مدخل‌های کتاب‌شناختی باید برای آن‌ها چاپ شوند. اگر این گزینه ارائه نشود، نام این فایل از آرگومان
templatefile
با حذف آخرین پسوند و افزودن
.aux
ساخته می‌شود. اگر هیچ
templatefile
مشخص نشده باشد،
auxfile
پیش‌فرض
aux.aux
خواهد بود.

-s separator

اگر چندین نویسنده یا ویراستار در یک مدخل وجود داشته باشند، نام‌های آن‌ها با یک جداکننده در میانشان فهرست خواهد شد. جداکننده به‌طور پیش‌فرض "; " (یعنی یک نقطه‌ویرگول و یک فاصله) است. با این گزینه می‌توان جداکننده را تغییر داد.

-n maxauthors

اگر بیش از
maxauthors
نویسنده در یک مدخل وجود داشته باشد، تنها نام نویسنده نخست چاپ خواهد شد و سایر نویسندگان با رشتهٔ
moreauthors
جایگزین می‌شوند. مقدار پیش‌فرض 3 است.

-r moreauthors

رشته‌ای که در صورت وجود بیش از
maxauthors
نویسنده چاپ می‌شود. مقدار پیش‌فرض "et al." است.

عملوندها (OPERANDS)

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

bibfile: نام یک پایگاه‌دادهٔ کتاب‌شناختی باید مشخص شود. این باید فایلی با قالب refer(1) باشد و هر مدخل باید دست‌کم یک فیلد %L داشته باشد که به‌عنوان کلید استفاده می‌شود. (مدخل‌های فاقد چنین فیلدی نادیده گرفته خواهند شد.)
templatefile: نام فایل ورودی اختیاری است. در صورت نبود آن، hxmkbib قالب را از stdin می‌خواند.

خطاها (DIAGNOSTICS)

مقدارهای خروج زیر بازگردانده می‌شوند:

0: پایان موفقیت‌آمیز.
> 0: خطایی رخ داده است. این وضعیت معمولاً به این دلیل است که یک فایل باز نشد یا جفت‌های %{ و %} به‌درستی تودرتو نشده‌اند. به‌ندرت ممکن است ناشی از خطای کمبود حافظه نیز باشد. برخی از پیام‌های خطای احتمالی:
missing ':' in pattern: دستور hxmkbib یک %{ یافت، اما نویسهٔ دوم یا سوم پس از آن دونقطه نبود.
no '%{' in template file: فایل قالب غیرقابل استفاده است، زیرا هیچ قالبی در آن وجود ندارد.
unbalanced %{..%} in pattern: تعداد %{ بیشتر از %} است.

همچنین ببینید (SEE ALSO)

asc2xml(1), hxcite(1), hxnormalize(1), hxnum(1), hxprune(1), hxtoc(1), hxunent(1), xml2asc(1), UTF-8 (RFC 2279).SHگزارش باگ‌ها (BUGS) مرتب‌سازی بسیار ابتدایی است: این برنامه تاریخ‌ها یا نام‌ها را تجزیه نمی‌کند و صرفاً «Jan 2000» را زیر حرف «J» و «Albert Camus» را زیر حرف «A» مرتب می‌کند. در حال حاضر تنها راهکار جایگزین این است که نام‌ها در bibfile به‌صورت «Camus, Albert» وارد شوند.

این برنامه صرفاً تمام نویسندگان یا ویراستاران را فهرست می‌کند. هیچ راهی برای ایجاد «et. al.» پس از سومین مورد وجود ندارد. راهکار جایگزین، درج «et. al.» در bibfile است. همچنین قرار دادن کاما بین نویسندگان نخست و واژهٔ «and» پیش از آخرین نویسنده امکان‌پذیر نیست.

این برنامه تلاشی برای تفسیر نام نویسندگان یا ویراستاران نمی‌کند و امکان قالب‌بندی مجدد آن‌ها وجود ندارد. نوشتن نامی که در bibfile به‌صورت «Sartre, Jean-Paul» مشخص شده است، به‌صورت «J. Sartre» یا «Jean-Paul Sartre» در خروجی غیرممکن است.

اگر فیلدی از قبل با یک نقطه خاتمه یافته باشد، هیچ راهی برای جلوگیری از درج نقطه پس از آن فیلد وجود ندارد. برای نمونه، اگر نویسنده «A. Person Jr.» باشد، الگوی «%{A:A.%}» ممکن است «A. Person Jr..» را در خروجی تولید کند. تنها گزینه این است که یا در bibfile نقطه نگذارید یا در الگو نقطه قرار ندهید.

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

hxmkbib با این فرض که الگو از نوع HTML/XML است، هر علامت امپرسند (&)، کوچکتری (<) و بزرگتری (>) موجود در bibfile را با موجودیت‌های XML متناظر آن‌ها یعنی &، < و > جایگزین می‌کند. این رفتار ممکن است برای سایر قالب‌ها مناسب نباشد.