نام (NAME)

hxcite-mkbib - بسط دادن ارجاعات و ساخت کتاب‌نامه

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

hxcite-mkbib [ -b base ] [ -p pattern ] [ -s separator ] bibfile [ file ]

توضیحات (DESCRIPTION)

دستور hxcite-mkbib فایل file را در خروجی استاندارد کپی می‌کند و به دنبال رشته‌هایی به فرم «[[label]]» و قالبی برای کتاب‌نامه می‌گردد. برچسب نباید شامل فاصله خالی (whitespace) باشد و جفت کروشه‌های دوتایی باید بدون هیچ فاصله‌ای در میان، برچسب را احاطه کرده باشند. اگر hxcite-mkbib برچسب را در bibfile بیابد، رشته با pattern جایگزین می‌شود. الگو می‌تواند شامل متغیرهای خاصی باشد. اگر برچسب در bibfile یافت نشود، بدون تغییر رها می‌شود.

الگوی پیش‌فرض، رشته را با یک ابرپیوند جایگزین می‌کند؛ اما اگر از گزینهٔ -p استفاده شود، جایگزین می‌تواند هر الگویی باشد. ورودی حتی نیازی نیست حتماً HTML باشد.

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

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

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

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

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

این قالب با چهار خط مقدمه آغاز می‌شود، از جمله رشتهٔ مرتب‌سازی %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>
گزینه‌های زیر پشتیبانی می‌شوند:

-p pattern

الگویی را مشخص می‌کند که رشتهٔ [[label]] بر اساس آن جایگزین می‌شود.
الگو ممکن است شامل متغیرهای
%b
(که با مقدار گزینهٔ
-b
جایگزین می‌شود) و
%L
(که با
label
جایگزین خواهد شد) باشد.
الگوی پیش‌فرض به این صورت است:
<a href="%b#%L" rel="biblioentry">[%L]</a>

-b base

مقدار متغیر %b را در الگو تعیین می‌کند. معمولاً این مقدار روی یک URL نسبی یا مطلق تنظیم می‌شود. به‌طور پیش‌فرض این مقدار یک رشتهٔ خالی است.

-s separator

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

عملوندها (OPERANDS)

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

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

خطاها (DIAGNOSTICS)

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

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

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

asc2xml(1), hxcite(1), hxmkbib(1), hxnormalize(1), hxnum(1), hxprune(1), hxtoc(1), hxunent(1), xml2asc(1), UTF-8 (RFC 2279)

گزارش باگ‌ها (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 آن‌ها یعنی & < > جایگزین خواهد کرد. این ممکن است برای سایر قالب‌ها مناسب نباشد.

دستور hxcite-mkbib یک اسکریپت شل (bash) است که hxcite(1) و hxmkbib(1) را فراخوانی می‌کند، و بنابراین روی همهٔ پلتفرم‌ها قابل حمل نیست.