.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "BTOOL_FAQ 1"
.TH BTOOL_FAQ 1 2025-07-14 "btparse, version 0.91" btparse
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "نام (NAME)"
btool_faq \- پرسش‌های متداول درباره btparse و Text::BibTeX
.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
این سند تلاش می‌کند به پرسش‌هایی پاسخ دهد که بارها از من پرسیده شده‌اند و پاسخ به آن‌ها آسان است \-\- اما نه صرفاً با مرور مستندات. به دلایل مختلف، پاسخ‌ها به طور پراکنده در چندین صفحه راهنما توزیع شده‌اند و همین امر درک جریان کار را دشوار می‌سازد. از این رو، این صفحه راهنما سعی دارد رشته‌های مختلف فکری را به یکدیگر پیوند زند و به جای ارائه توضیحات طولانی درباره قابلیت‌ها و قواعد کتابخانه‌های btOOL، پاسخ‌هایی سریع و متمرکز به شکل «چگونه فلان کار را انجام دهم؟» ارائه دهد.
.SH "کتابخانه PERL (PERL LIBRARY)"
.IX Header "PERL LIBRARY"
این بخش به پرسش‌هایی می‌پردازد که کاربران \f(CW\*(C`Text::BibTeX\*(C'\fR، مؤلفه پرلِ \fBbtOOL\fR، مطرح کرده‌اند.
.SS "چرا ماکروهای ""month"" در BibTeX تعریف نشده‌اند؟"
.IX Subsection "Why aren't the BibTeX ""month"" macros defined?"
زیرا آن‌ها مختص به کتاب‌شناسی هستند و \f(CW\*(C`Text::BibTeX\*(C'\fR به‌طور پیش‌فرض هیچ فرضی در مورد نوع خاصی از پایگاه‌داده یا حوزه پردازش داده بر ورودی‌های شما تحمیل نمی‌کند. مشکل زمانی رخ می‌دهد که ورودی‌ها را از فایلی مانند \fIfoo.bib\fR تجزیه (parse) می‌کنید که کاملاً معقولانه از ماکروهای ماه (\f(CW\*(C`jan\*(C'\fR، \f(CW\*(C`feb\*(C'\fR و غیره) ارائه‌شده توسط فایل‌های شیوه (style) استاندارد BibTeX استفاده می‌کند:
.PP
.Vb 3
\&   $bibfile = Text::BibTeX::File\->new(\*(Aqfoo.bib\*(Aq)    # open file
\&      or die "foo.bib: $!\en";
\&   $entry = Text::BibTeX::Entry\->new($bibfile);     # parse first entry
.Ve
.PP
با استفاده از این کد، ممکن است برای هر ورودیِ تجزیه‌شده از \fIfoo.bib\fR یک هشدار «ماکروی تعریف‌نشده» (undefined macro) دریافت کنید. گذشته از آزاردهنده بودن ظاهری این پیام‌های هشدار، ماکروهای تعریف‌نشده به عنوان رشته‌های خالی بسط داده می‌شوند؛ یعنی شما هرگونه اطلاعات مربوط به آن‌ها را از دست می‌دهید \-\-\- که اصلاً خوب نیست.
.PP
شما همواره می‌توانید با سرهم‌بندی، ماکروهای ماه را خودتان به اجبار تعریف کنید. قبل از نسخه 0.30، این کار باید با تجزیه مجموعه‌ای از ورودی‌های ساختگی انجام می‌شد، اما اکنون \f(CW\*(C`Text::BibTeX\*(C'\fR یک رابط مستقیم با جدول ماکروهای زیربنایی فراهم می‌کند. شما \fIمی‌توانید\fR قبل از تجزیه هر ورودی، صرفاً این کار را انجام دهید:
.PP
.Vb 5
\&   use Text::BibTeX qw(:macrosubs);
\&   # ...
\&   my %month = (jan => \*(AqJanuary\*(Aq, feb => \*(AqFebruary\*(Aq, ... );
\&   add_macro_text ($macro, $value) 
\&      while (($macro, $value) = each %month);
.Ve
.PP
اما راه بهتری نیز وجود دارد که با نحوه کارها در BibTeX (جایی که ماکروهای پیش‌فرض در فایل شیوه تعریف می‌شوند) هم‌خوانی بیشتری دارد: استفاده از معادل شیءگرای فایل‌های شیوه در \f(CW\*(C`Text::BibTeX\*(C'\fR که ماژول‌های ساختار (structure modules) نامیده می‌شوند. \f(CW\*(C`Text::BibTeX\*(C'\fR یک ماژول ساختار به نام \f(CW\*(C`Text::BibTeX::Bib\*(C'\fR ارائه می‌دهد که فایل‌های شیوه استاندارد BibTeX 0.99 را (تا حدی) شبیه‌سازی می‌کند، از جمله تعریف ماکروهای ماه. ماژول‌های ساختار برای هر فایل به صورت مجزا با استفاده از متد \f(CW\*(C`set_structure\*(C'\fR بر روی شیء \f(CW\*(C`Text::BibTeX::File\*(C'\fR مشخص می‌شوند. بسیار ساده است که به \f(CW\*(C`Text::BibTeX\*(C'\fR اعلام کنید ورودی‌های حاصل از \f(CW$bibfile\fR باید با ساختار \f(CW\*(C`Bib\*(C'\fR مطابقت داشته باشند (که توسط ماژول \f(CW\*(C`Text::BibTeX::Bib\*(C'\fR پیاده‌سازی شده است، هرچند واقعاً نیازی به دانستن آن ندارید):
.PP
.Vb 3
\&   $bibfile = Text::BibTeX::File\->new(\*(Aqfoo.bib\*(Aq)
\&      or die "foo.bib: $!\en";
\&   $bibfile\->set_structure (\*(AqBib\*(Aq);
.Ve
.PP
با این حال، احتمالاً نباید نام یک ساختار خاص را در برنامه‌های خود به صورت ثابت (hardcode) قرار دهید، زیرا در نهایت ماژول‌های ساختار متعددی برای انتخاب وجود خواهند داشت (همان‌طور که فایل‌های شیوه BibTeX متعددی برای انتخاب وجود دارند). رویکرد ترجیحی من این است که ساختار را به یک گزینه خط فرمان تبدیل کنید که مقدار پیش‌فرض آن \f(CW\*(C`Bib\*(C'\fR باشد (زیرا تا زمان نگارش این متن، این تنها ساختاری است که در عمل پیاده‌سازی شده است).
.SS "چگونه داده‌ها را به انتهای یک فایل BibTeX الحاق (append) کنم؟"
.IX Subsection "How do I append to a BibTeX file?"
فقط آن را در حالت الحاق باز کنید و ورودی‌ها را طبق معمول در آن بنویسید. به یاد داشته باشید که یک شیء \f(CW\*(C`Text::BibTeX::File\*(C'\fR اساساً یک پوشش (wrapper) بر روی یک شیء \f(CW\*(C`IO::File\*(C'\fR است، و متد \f(CW\*(C`Text::BibTeX::File::open\*(C'\fR (و در نتیجه \f(CW\*(C`new\*(C'\fR نیز) صرفاً یک پیشانه برای \f(CW\*(C`IO::File::open\*(C'\fR است. \f(CW\*(C`IO::File::open\*(C'\fR نیز به نوبه خود یک پیشانه برای تابع توکار \f(CW\*(C`open\*(C'\fR در پرل (در صورت فراخوانی با یک آرگومان) یا \f(CW\*(C`sysopen\*(C'\fR (دو یا سه آرگومان) است. برای اینکه از زحمت مطالعه تمام آن صفحات راهنما رها شوید، ترفند کار این است: اگر فقط نام فایل را به متد \f(CW\*(C`new\*(C'\fR در \f(CW\*(C`Text::BibTeX::File\*(C'\fR ارسال کنید، با آن درست مانند نام فایلی که به دستور توکار \f(CW\*(C`open\*(C'\fR پرل ارسال شده رفتار می‌شود:
.PP
.Vb 2
\&   my $append_file = Text::BibTeX::File\->new(">>$filename")
\&      or die "couldn\*(Aqt open $filename for appending: $!\en";
.Ve
.PP
فایل \f(CW$filename\fR را برای الحاق به انتها باز می‌کند. اگر بعداً ورودی دیگری از یک فایل دیگر (مثلاً \f(CW$entry\fR) داشتید، می‌توانید آن را با نوشتن عادی، به انتهای \f(CW$append_file\fR اضافه کنید:
.PP
.Vb 1
\&   $entry\->write ($append_file);
.Ve
.PP
برای یک مثال کامل، به \f(CW\*(C`append_entries\*(C'\fR در زیرشاخه \fIexamples/\fR از توزیع \f(CW\*(C`Text::BibTeX\*(C'\fR مراجعه کنید.
.SH "کتابخانه C (C LIBRARY)"
.IX Header "C LIBRARY"
این بخش به پرسش‌های متداول درباره \fBbtparse\fR، مؤلفه C از \fBbtOOL\fR، می‌پردازد.
.SS "آیا برای \fBbtparse\fP بایندینگ پایتون وجود دارد؟"
.IX Subsection "Is there a Python binding for btparse yet?"
تا جایی که من می‌دانم، خیر. من چیزی ننوشته‌ام. اگر شما این کار را انجام دادید، لطفاً به من اطلاع دهید.
.SH "همچنین ببینید (SEE ALSO)"
.IX Header "SEE ALSO"
btparse, Text::BibTeX
.SH "نویسندگان (AUTHORS)"
.IX Header "AUTHOR"
Greg Ward <gward@python.net>
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
.IX Header "COPYRIGHT"
حق نشر \(c) 1997\-2000 متعلق به Gregory P. Ward است. کلیه حقوق محفوظ است. این فایل بخشی از کتابخانه Text::BibTeX است. این کتابخانه نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت همان شرایط خود Perl بازتوزیع نموده و/یا تغییر دهید.