refer(1) General Commands Manual refer(1)

refer - پردازش ارجاعات کتابشناسی برای groff

refer [-bCenPRS] [-a n] [-B field.macro] [-c fields] [-f n] [-i fields] [-k field] [-l range-expression] [-p database-file] [-s fields] [-t n] [file ...]
refer --help
refer -v
refer --version

پیاده‌سازی گنو از refer بخشی از سامانه قالب‌بندی اسناد groff(1) است. refer یک پیش‌پردازنده troff(1) است که استنادها و ارجاعات کتاب‌شناختی را با جستجوی کلیدواژه‌های مشخص‌شده در یک سند ورودی roff(7) آماده می‌سازد؛ این امر نیاز به تایپ دستی چنین یادداشت‌هایی را برطرف کرده و اجازه می‌دهد شیوه استناد در خروجی قالب‌بندی‌شده، به طور مستقل و سامان‌مند تغییر یابد. این برنامه محتوای هر file را در جریان خروجی استاندارد کپی می‌کند، هر استناد بین خطوطی که با .[ و .] آغاز می‌شوند را جستجو کرده و آن را با یک مرجع کتاب‌شناختی جایگزین می‌نماید. علاوه بر این، نسخه گنو refer خطوط بین موارد آغازشونده با .R1 و .R2 را به عنوان دستورالعمل‌هایی تفسیر می‌کند که نحوه پردازش استنادها را هدایت می‌نمایند. refer درخواست‌های lf مربوط به roff را تفسیر و تولید می‌کند تا نام فایل‌ها و شماره خطوط در پیام‌های تولیدشده توسط دستوراتی که خروجی آن را می‌خوانند، به درستی سند منبع را توصیف کنند. به طور معمول، refer مستقیماً توسط کاربر اجرا نمی‌شود، بلکه با مشخص کردن گزینه -R در groff(1) فراخوانی می‌گردد. اگر هیچ عملوند fileی داده نشود، یا اگر file برابر با “-” باشد، refer جریان ورودی استاندارد را می‌خواند.

یک استناد، اثری را از طریق ارجاع به یک رکورد کتاب‌شناختی حاوی جزئیات آن مشخص می‌کند. با فهرست کردن کلیدواژه‌هایی که مدخل اثر را به طور یکتا شناسایی می‌کنند، اثر مورد نظر را از یک پایگاه‌داده رکوردها انتخاب کنید. در روش دیگر، یک سند می‌تواند در همان نقطه‌ای که استناد در آن رخ می‌دهد، رکوردی برای اثر مشخص نماید. یک سند می‌تواند بنا به تمایل، از هر یک از این دو راهبرد یا هر دوی آن‌ها استفاده کند.

برای هر استناد، refer یک نشان در متن تولید می‌کند، مانند یک شماره بالانویس پاورقی یا “[Lesk1978a]”. یک نشان شامل یک برچسب در بین قلاب‌ها است. این نشان می‌تواند به روش‌های گوناگون از متن اطراف و از برچسب‌های دیگر جدا شود. refer درخواست‌های زبان roff تولید می‌کند که توسط یک سند یا یک بسته ماکرو مانند me، mm، mom یا ms قابل استفاده است تا برای هر استناد یک ارجاع قالب‌بندی‌شده تولید شود. مرجع یک استناد می‌تواند بلافاصله پس از وقوع آن در خروجی ظاهر شود (مانند پاورقی‌ها)، یا مراجع ممکن است انباشته شوند و خروجی متناظر بعداً در سند ظاهر گردد (مانند پی‌نوشت‌ها). هنگامی که مراجع انباشته می‌شوند، استنادهای متعدد به یک مرجع یکسان، یک مدخل قالب‌بندی‌شده واحد را تولید می‌کنند.

تفسیر خطوط بین نشانه‌های .R1 و .R2 به عنوان دستورات پیش‌پردازنده، یک قابلیت گسترش‌یافته در refer گنو است. اسنادی که از این ویژگی استفاده می‌کنند همچنان می‌توانند توسط refer نسخه AT&T پردازش شوند؛ این کار با افزودن خطوط زیر:

.de R1
.ig R2
..
به ابتدای سند انجام می‌پذیرد. ورودی فوق باعث می‌شود troff همه چیز بین .R1 و .R2 را نادیده بگیرد. اثرات برخی از دستورات refer از طریق گزینه‌های خط فرمان نیز قابل دستیابی است؛ این گزینه‌ها برای سازگاری با refer نسخه AT&T پشتیبانی می‌شوند. معمولاً استفاده از دستورات راحت‌تر است.

یک رکورد کتاب‌شناختی، اثر مورد ارجاع را با جزئیات کافی توصیف می‌کند تا بتوان آن را طبق استانداردهای پذیرفته‌شده شفافیت علمی و حرفه‌ای استناد داد. قالب رکورد امکان یادداشت‌نویسی و گسترش را فراهم می‌سازد که یک سند می‌تواند از آن استفاده کرده یا آن را نادیده بگیرد. یک رکورد توالی متنی ساده‌ای از فیلدها است (یک فیلد در هر خط)، که هر کدام شامل یک علامت درصد %، یک نویسه حرفی‌عددی برای رده‌بندی آن، یک فاصله، و محتوای آن فیلد است. اگر محتوای یک فیلد خالی باشد، فیلد نادیده گرفته می‌شود.

معمولاً چنین رکوردهایی در یک پایگاه‌داده کتاب‌شناختی سازمان‌دهی می‌شوند که در آن هر مدخل با خطوط خالی یا مرزهای فایل از یکدیگر جدا می‌گردد. این شیوه اسناد را از نیاز به نگهداری داده‌های کتاب‌شناختی در خود معاف می‌کند. برنامه‌های lookbib(1) و lkbib(1) یک پایگاه‌داده کتاب‌شناختی را بررسی می‌کنند، و indxbib(1) آن را نمایه‌سازی می‌کند تا بازیابی از آن سرعت گیرد و زمان پردازش سند کاهش یابد. استفاده از این ابزارها اختیاری است.

کاربردهای متداول مدخل‌های فیلدهای کتاب‌شناختی به شرح زیر است. درون یک رکورد، فیلدهایی غیر از %A و %E جایگزین رخدادهای قبلی خود می‌شوند. ترتیب فیلدهای چندگانه %A و %E حائز اهمیت است.

%A
نام یک نویسنده را مشخص می‌کند. اگر نام شامل پسوندی مانند “Jr.” یا “III” باشد، باید با یک کاما از نام خانوادگی جدا شود. توصیه می‌کنیم همیشه یک فیلد %A یا یک فیلد %Q ارائه دهید.
%B
عنوان کتابی را که مقاله مورد استناد در آن گردآوری شده است ثبت می‌کند. فیلدهای %J و %T را ببینید.
%C
نام شهر یا سایر مکان‌های انتشار را مشخص می‌کند.
%D
تاریخ انتشار را نشان می‌دهد. سال را به طور کامل مشخص کنید. اگر ماه مشخص شده است، به جای شماره آن از نام ماه استفاده کنید؛ تنها سه حرف اول نیاز است. توصیه می‌کنیم همیشه یک فیلد %D ارائه دهید؛ اگر تاریخ نامشخص است، از “in press” یا “unknown” به عنوان محتوای آن استفاده کنید.
%E
نام یک ویراستار کتابی را که مقاله مورد استناد در آن گردآوری شده است مشخص می‌کند. در مواردی که یک اثر ویراستار دارد اما نویسنده‌ای ندارد، ویراستاران را در فیلدهای %A نام ببرید و “, (ed.)” یا “, (eds.)” را به آخرین مورد از آن‌ها پیوست نمایید.
%G
شماره سفارش دولتی ایالات متحده، شابک (ISBN)، شناسه برخط شیء (DOI)، یا سایر شناسه‌های یکتا را ثبت می‌کند.
%I
نام ناشر (منتشرکننده) را مشخص می‌کند.
%J
نام مجله‌ای را که مقاله مورد استناد در آن گردآوری شده است ثبت می‌کند. فیلدهای %B و %T را ببینید.
%K
کلیدواژه‌هایی را که برای کمک به جستجو در نظر گرفته شده‌اند فهرست می‌کند.
%L
یک برچسب است؛ معمولاً در مدخل‌های پایگاه‌داده استفاده نمی‌شود، اما می‌تواند قالب برچسبی را که در غیر این صورت تعیین می‌شد بازنویسی کند.
%N
شماره دوره یا انتشار مجله‌ای را که مقاله مورد استناد در آن گردآوری شده است ثبت می‌کند.
%O
اطلاعات اضافی (“سایر”) را ارائه می‌دهد، که معمولاً در انتهای مرجع قرار می‌گیرد.
%P
شماره صفحات اثری را که بخشی از یک مجموعه بزرگ‌تر است فهرست می‌کند. یک بازه را با m-n مشخص کنید.
%Q
در صورتی که هیچ فیلد %A وجود نداشته باشد، نام یک نویسنده سازمانی را مشخص می‌کند. تنها یک فیلد %Q مجاز است.
%R
شناسه‌ای برای یک گزارش، پایان‌نامه، یادداشت اداری، یا سایر آثار منتشرنشده است.
%S
عنوان مجموعه‌ای (series) را که اثر مورد استناد به آن تعلق دارد ثبت می‌کند.
%T
عنوان اثر است. فیلدهای %B و %J را ببینید.
%V
شماره جلد مجله یا کتاب حاوی اثر مورد استناد است.
%X
یک یادداشت توضیحی (annotation) است. طبق عرف، در سند استنادکننده قالب‌بندی نمی‌شود.

اگر از ویژگی قدیمی و رو به زوال “رشته‌های نشانه‌گذاری اعراب” در بسته‌های ماکروی ms یا me استفاده می‌شود، چنین رشته‌هایی باید پس از نویسه‌ای که قرار است علامت‌گذاری شود قرار گیرند؛ یک سند ms باید پیش از استفاده از آن‌ها ماکروی AM را فراخوانی کند. رشته‌های اعراب را در گیومه قرار ندهید: به جای دو علامت از یک \ استفاده کنید. برای یک رویکرد امروزی به مسئله نشانه‌های تفکیک‌کننده، groff_char(7) را ببینید.

استنادها قالب مشخصی دارند.

.[opening-text
flags keyword ...
field
...
.]closing-text

موارد opening-text، closing-text و flags اختیاری هستند، و تنها لازم است یک keyword یا field مشخص شود. اگر کلیدواژه‌ها حضور داشته باشند، refer پایگاه(های) داده کتاب‌شناختی را برای یافتن یک مرجع یکتا که با آن‌ها مطابقت دارد جستجو می‌کند. تطابق‌های چندگانه خطا هستند؛ کلیدواژه‌های بیشتری اضافه کنید تا ابهام مرجع برطرف شود. در صورت عدم وجود کلیدواژه‌ها، فیلدها رکورد کتاب‌شناختی را تشکیل می‌دهند. در غیر این صورت، فیلدها داده‌های اضافی را برای جایگزینی یا تکمیل داده‌های موجود در مرجع مشخص می‌کنند. هنگامی که مراجع در حال انباشته شدن هستند و کلیدواژه‌ها وجود دارند، فیلدهای اضافی را حداکثر در اولین استناد به یک مرجع خاص مشخص کنید؛ آن‌ها برای تمامی استنادهای بعدی به آن اعمال می‌شوند.

موارد opening-text و closing-text ورودی‌های roff هستند که برای قرار دادن برچسب در قلاب استفاده می‌شوند، و دستور bracket-label را بازنویسی می‌کنند. فاصله‌های ابتدا و انتها حائز اهمیت هستند. اگر هر یک از این موارد غیرخالی باشد، آرگومان متناظر دستور bracket-label استفاده نمی‌شود؛ این رفتار را با پرچم‌های [ و ] تغییر دهید.

مورد flags فهرستی از نویسه‌های غیرحرفی‌عددی است که هر یک از آن‌ها نحوه رفتار با استناد مشخص را تغییر می‌دهد. نسخه AT&T برنامه refer آن‌ها را نادیده می‌گیرد زیرا غیرحرفی‌عددی هستند. آن‌ها نسخه گنو refer را به شرح زیر هدایت می‌کنند.

#
از برچسب مشخص‌شده توسط دستور short-label (در صورت وجود) استفاده می‌کند. در غیر این صورت refer از برچسب عادی استفاده می‌نماید. به طور معمول، یک برچسب کوتاه سبک‌های استناد نویسنده-تاریخ متشکل از یک نام، یک سال، و در صورت لزوم یک حرف ابهام‌زدا را پیاده‌سازی می‌کند. “#” برای القای چنین برچسب (شبه) عددی در نظر گرفته شده است.
[
قبل از opening-text ، اولین آرگومان داده‌شده به دستور bracket-label را قرار می‌دهد.
]
بعد از closing-text ، دومین آرگومان داده‌شده به دستور bracket-label را قرار می‌دهد.

یک مزیت پرچم‌های [ و ] نسبت به استفاده از opening-text و closing-text این است که می‌توانید شیوه قلاب‌بندی سند را در یک مکان با استفاده از دستور bracket-label به‌روزرسانی کنید. مزیت دیگر این است که در صورت استفاده از پرچم‌ها، مرتب‌سازی و ادغام استنادها لزوماً مهار نمی‌شود.

برنامه refer هر برچسب حاصل از یک استناد را به خط ورودی roff پیش از نشانه .[ پیوست می‌کند. اگر چنین خطی وجود نداشته باشد، refer یک پیام هشدار تشخیصی صادر می‌کند.

هیچ نمادگذاری خاصی برای استناد به چندین مرجع به صورت متوالی وجود ندارد. از توالی استنادها، یکی برای هر مرجع، بدون هیچ فاصله‌ای بین آن‌ها استفاده کنید. refer تمام برچسب‌های آن‌ها را به خط پیش از اولین مورد متصل می‌کند. این برچسب‌ها ممکن است مرتب یا ادغام شوند. توضیحات مربوط به عبارت برچسب <>، و دستورات sort-adjacent-labels و abbreviate-label-ranges را ببینید. اگر استناد یک برچسب دارای opening-text یا closing-text غیرخالی باشد، آن برچسب ادغام نمی‌شود. با این حال، برچسب‌های دو استناد مجاور، که اولی از پرچم ] و بدون هیچ closing-text استفاده می‌کند، و دومی از پرچم [ و بدون هیچ opening-text استفاده می‌کند، ممکن است مرتب و ادغام شوند حتی اگر opening-text اولی یا closing-text دومی غیرخالی باشد. (برای جلوگیری از این عملیات، از توالی گریز نویسه ساختگی \& به عنوان closing-text اولی استفاده کنید.)

دستورها بین خطوطی قرار دارند که با .R1 و .R2 آغاز می‌شوند. گزینه -R مانع از شناسایی این خطوط می‌گردد. هنگامی که refer با یک خط .R1 مواجه می‌شود، هرگونه مراجع انباشته‌شده را تخلیه می‌کند. نه خطوط .R1 و نه .R2، و نه هیچ‌چیز بین آن‌ها، در خروجی نوشته نمی‌شوند.

دستورها با خطوط جدید یا نقطه-ویرگول از هم جدا می‌شوند. علامت هش (#) معرف یک یادداشت است که تا انتهای خط ادامه می‌یابد، اما خط جدید را پنهان نمی‌کند. هر دستور به کلماتی تفکیک می‌شود. کلمات با فاصله یا جهش (tab) از هم جدا می‌شوند. کلمه‌ای که با یک گیومه دوگانه (خنثی) (") آغاز می‌شود، تا گیومه دوگانه بعدی که پس از آن گیومه دوگانه دیگری نیامده باشد امتداد می‌یابد. اگر چنین گیومه دوگانه‌ای وجود نداشته باشد، کلمه تا انتهای خط ادامه می‌یابد. جفت‌های گیومه دوگانه درون کلمه‌ای که با گیومه دوگانه آغاز شده است، به یک گیومه دوگانه تقلیل می‌یابند. نه علامت هش و نه نقطه-ویرگول در داخل گیومه دوگانه شناسایی نمی‌شوند. یک خط را می‌توان با خاتمه دادن آن با یک ممیز وارونه “\” ادامه داد؛ این کار در همه‌جا به جز پس از علامت هش کار می‌کند.

هر نام دستور که با * علامت‌گذاری شده است، دارای یک دستور منفی مرتبط به صورت no-name است که اثر name را خنثی می‌کند. به عنوان مثال، دستور no-sort مشخص می‌کند که مراجع نباید مرتب شوند. دستورات منفی هیچ آرگومانی نمی‌پذیرند.

در توضیحات زیر هر آرگومان باید یک کلمه واحد باشد؛ field برای یک حرف تکی بزرگ یا کوچک نام‌گذاری فیلد به کار می‌رود؛ fields برای توالی‌ای از چنین حروفی به کار می‌رود؛ m و n برای اعداد غیرمنفی به کار می‌روند؛ string برای یک رشته دلخواه به کار می‌رود؛ file برای نام یک فایل به کار می‌رود.

نام‌های کوچک fields را مخفف می‌کند. حرف آغازین با string1 از حرف آغازین دیگر، با string2 از نام خانوادگی، و با string3 از هر چیز دیگری (مانند “von” یا “de”) جدا خواهد شد. پیش‌فرض این‌ها یک نقطه به همراه یک فاصله است. در یک نام کوچک خط‌تیره‌دار، حرف آغازین بخش اول نام با string4 از خط‌تیره جدا می‌شود؛ پیش‌فرض این مورد یک نقطه است. هیچ تلاشی برای مدیریت ابهاماتی که ممکن است از اختصار ناشی شوند صورت نمی‌گیرد. نام‌ها پیش از مرتب‌سازی و پیش از ساخت برچسب مخفف می‌شوند.
سه یا تعداد بیشتری برچسب مجاور که به مراجع متوالی اشاره دارند، به برچسبی متشکل از برچسب اول، به دنبال آن string، و به دنبال آن برچسب آخر مخفف می‌شوند. این قابلیت عمدتاً برای برچسب‌های عددی مفید است. اگر string حذف شود، مقدار پیش‌فرض آن “-” خواهد بود.
مراجع را به جای نوشتن هر یک از آن‌ها در زمان مواجهه، انباشته می‌کند. مراجع انباشته‌شده هر زمان که مرجعی به شکل:
.[
$LIST$
.]
دیده شود، پس از پردازش تمام فایل‌های ورودی، و هر زمان که یک خط .R1 شناسایی گردد، نوشته خواهند شد.
مورد field یک یادداشت توضیحی است؛ آن را در انتهای مرجع به صورت پاراگرافی که پیش از آن خط:
.string

آمده است چاپ می‌کند. اگر string حذف شود، پیش‌فرض آن AP خواهد بود؛ اگر field نیز حذف شود، پیش‌فرض آن X خواهد بود. تنها یک فیلد می‌تواند یادداشت توضیحی باشد.

هر string یک حرف تعریف معین یا نامعین است، و هنگام مرتب‌سازی باید در ابتدای فیلدهای T نادیده گرفته شود. در ابتدا، “a”، “an” و “the” به عنوان حروف تعریف شناخته می‌شوند.
تمام مراجع موجود در هر file پایگاه‌داده کتاب‌شناختی را می‌نویسد. این دستور باید آخرین مورد در یک بلوک .R1/.R2 باشد.
در متن، هر برچسب را درون string1 و string2 قرار می‌دهد. وقوع string2 که بلافاصله پس از آن string1 بیاید، به string3 تبدیل خواهد شد. رفتار پیش‌فرض به شرح زیر است.
bracket-label \*([. \*(.] ", "
فیلدهای fields را به حروف بزرگ و حروف بزرگ کوچک تبدیل می‌کند.
خطوط .R1 و .R2 را حتی اگر با نویسه‌ای غیر از فاصله یا خط جدید دنبال شوند، شناسایی می‌کند.
هر file پایگاه‌داده کتاب‌شناختی را جستجو می‌کند. برای هر file، اگر نمایه‌ای به نام file.i که توسط indxbib(1) ایجاد شده باشد موجود باشد، آنگاه به جای آن جستجو خواهد شد؛ هر نمایه می‌تواند چندین پایگاه‌داده را پوشش دهد.
رشته string یک عبارت برچسب است که رشته‌ای را مشخص می‌کند تا پس از ساخت برچسب، جایگزین فیلد D شود. برای شرح عبارت‌های برچسب، زیربخش “عبارت‌های برچسب” در ادامه را ببینید. این دستور زمانی مفید است که شما برچسب‌های صریح در فهرست مراجع نمی‌خواهید، بلکه می‌خواهید هرگونه رفع ابهام لازم را با مقید کردن تاریخ به نحوی مدیریت کنید. برچسب مورد استفاده در متن معمولاً ترکیبی از نویسنده و تاریخ خواهد بود. در بیشتر موارد باید از دستور no-label-in-reference نیز استفاده نمایید. برای مثال،
date-as-label D.+yD.y%a*D.-y
یک حرف رفع ابهام را به بخش سال فیلد D در مرجع پیوست خواهد کرد.
پایگاه‌داده پیش‌فرض باید جستجو شود. این رفتار پیش‌فرض است، بنابراین نسخه منفی این دستور مفیدتر است. برنامه refer در اولین باری که نیاز به انجام جستجو دارد، مشخص می‌کند که آیا پایگاه‌داده پیش‌فرض باید جستجو شود یا خیر. بنابراین دستور no-default-database باید پیش از آن زمان صادر شود تا موثر واقع گردد.
هنگامی که مرجع خوانده می‌شود، fields باید دور ریخته شوند؛ هیچ تعریف رشته‌ای برای fields در خروجی نوشته نخواهد شد. در ابتدا، fields برابر با XYZ هستند.
استفاده از “et al” (و دیگران) را در ارزیابی عبارت‌های @ درون عبارت‌های برچسب پیکربندی می‌کند. اگر u تعداد نویسندگان لازم برای بدون ابهام ساختن توالی نویسندگان باشد و کل تعداد نویسندگان t باشد، آنگاه t-u نویسنده آخر با string جایگزین خواهند شد، به شرط آن که t-u کمتر از m نباشد و t کمتر از n نباشد. رفتار پیش‌فرض به شرح زیر است.
et-al " et al" 2 3
به نبود نقطه در انتهای این مخفف توجه داشته باشید، که مسلماً درست نیست. (Et al[.] مخفف et alli است، همان‌طور که etc. مخفف et ceteraاست.)
فایل file را درج کرده و محتویات آن را به عنوان دستور تفسیر می‌کند.
چندین نویسنده را با stringها به هم متصل می‌کند. هنگامی که دقیقاً دو نویسنده وجود داشته باشد، آن‌ها با string1 به هم متصل می‌شوند. هنگامی که بیش از دو نویسنده وجود داشته باشد، همه به جز دو نویسنده آخر با string2، و دو نویسنده آخر با string3 به هم متصل خواهند شد. اگر string3 حذف شود، پیش‌فرض آن string1 خواهد بود؛ اگر string2 نیز حذف شود، آن نیز به طور پیش‌فرض string1 خواهد شد. برای مثال،
join-authors " and " ", " ", and "
روش پیش‌فرض برای پیوند دادن نویسندگان را بازیابی می‌کند.
هنگام نوشتن مرجع در خروجی، رشته [F را به عنوان برچسب مرجع تعریف می‌کند. این رفتار پیش‌فرض است، بنابراین نسخه منفی این دستور کاربردی‌تر است.
برای هر مرجع یک برچسب در متن خروجی می‌دهد. برچسب طبق توضیحات دستور bracket-label از متن اطراف جدا خواهد شد. این رفتار پیش‌فرض است، بنابراین نسخه منفی این دستور کاربردی‌تر است.
رشته string یک عبارت برچسب است که نحوه برچسب‌گذاری هر مرجع را توصیف می‌کند.
هنگام ادغام برچسب‌های دو بخشی، بخش دوم از برچسب دوم را با string از برچسب اول جدا می‌کند. توضیحات مربوط به عبارت برچسب <> را ببینید.
در متن، هرگونه علائم نگارشی در انتهای خط را به بعد از برچسب منتقل می‌کند. توصیه می‌کنیم از این دستور استفاده کنید مگر آن که از اعداد بالانویس به عنوان برچسب بهره می‌برید.
فیلدهایی را که نام آن‌ها در string آمده است معکوس می‌کند. یک عدد صحیح اختیاری پس از نام فیلد، تعداد چنین فیلدهایی را به مقدار ارائه‌شده محدود می‌سازد؛ عدم ذکر عدد صحیح به معنای عدم وجود محدودیت است.
هنگام جستجوی کلیدها در پایگاه‌های داده‌ای که نمایه‌ای برای آن‌ها وجود ندارد، محتویات fields را نادیده می‌گیرد. در ابتدا، فیلدهای XYZ نادیده گرفته می‌شوند.
تنها ایجاب می‌کند که n نویسه اول کلیدها ارائه شوند. در عمل هنگام جستجوی یک کلید، کلمات موجود در پایگاه‌داده به حداکثر n و طول کلید کوتاه می‌شوند. در ابتدا، n برابر با 6 است.
رشته string یک عبارت برچسب است که سبکی جایگزین (معمولاً کوتاه‌تر) از برچسب را مشخص می‌سازد. این مورد زمانی استفاده می‌شود که پرچم # در استناد داده شده باشد. هنگام استفاده از برچسب‌های سبک نویسنده-تاریخ، هویت نویسنده یا نویسندگان گاهی از بافت متن مشخص است، و بنابراین ممکن است مطلوب باشد که نویسنده یا نویسندگان از برچسب حذف شوند. دستور short-label معمولاً برای مشخص کردن برچسبی حاوی صرفاً یک تاریخ و احیاناً یک حرف رفع ابهام استفاده خواهد شد.
مراجع را بر اساس string مرتب می‌کند. مراجع به طور خودکار انباشته خواهند شد. رشته string باید فهرستی از نام‌های فیلد باشد که هر کدام با یک عدد دنبال می‌شوند، و نشان می‌دهند که چه تعداد فیلد با آن نام باید برای مرتب‌سازی استفاده شود. “+” می‌تواند برای نشان دادن این که همه فیلدهای دارای آن نام باید استفاده شوند، به کار رود. همچنین . می‌تواند برای نشان دادن این که مراجع باید با استفاده از برچسب (آزمایشی) مرتب شوند، به کار رود. (زیربخش “عبارت‌های برچسب” در ادامه، مفهوم برچسب آزمایشی را توصیف می‌کند.)
برچسب‌هایی را که در متن مجاور هستند، بر اساس موقعیت آن‌ها در فهرست مراجع مرتب می‌کند. این دستور معمولاً باید در صورتی که دستور abbreviate-label-ranges صادر شده باشد، یا اگر عبارت برچسب شامل عبارت <> باشد، استفاده شود. این دستور هیچ اثری ندارد مگر آن که مراجع در حال انباشته شدن باشند.

عبارت‌های برچسب می‌توانند هم به صورت عادی و هم به صورت آزمایشی ارزیابی شوند. نتیجه ارزیابی عادی برای خروجی استفاده می‌شود. نتیجه ارزیابی آزمایشی، که برچسب آزمایشی نامیده می‌شود، برای جمع‌آوری اطلاعاتی استفاده می‌شود که ارزیابی عادی برای رفع ابهام برچسب به آن نیاز دارد. عبارت‌های برچسب مشخص‌شده توسط دستورات date-as-label و short-label به صورت آزمایشی ارزیابی نمی‌شوند. ارزیابی عادی و آزمایشی برای همه انواع عبارت‌ها به جز عبارت‌های @، * و % یکسان هستند. توضیحات زیر برای ارزیابی عادی به کار می‌روند، مگر آن که خلاف آن مشخص شده باشد.

بخش nم از field است. اگر n حذف شود، پیش‌فرض آن 1 است.
'string'
نویسه‌های درون string به صورت تحت‌اللفظی.
@
تمام نویسندگان متصل‌شده به گونه‌ای که توسط دستور join-authors مشخص شده است. کل نام هر نویسنده استفاده می‌شود. با این حال، اگر مراجع بر اساس نویسنده مرتب شده باشند (یعنی مشخصه مرتب‌سازی با “A+” آغاز شود)، آنگاه نام خانوادگی نویسندگان به جای آن استفاده خواهد شد، به شرط آن که این کار ابهام ایجاد نکند، و همچنین ممکن است یک زیرتوالی اولیه از نویسندگان به جای همه نویسندگان استفاده شود، باز هم به شرط آن که این کار ابهامی به وجود نیاورد. به ازای هر دو اثر مرجع با n نویسنده، استفاده از تنها نام خانوادگی برای نویسنده nم یک مرجع، مبهم تلقی می‌شود اگر مرجع دیگر در n-1 نویسنده اول مشترک باشد، نویسندگان nم هر مرجع یکسان نباشند، اما نام خانوادگی نویسندگان nم آن‌ها یکسان باشد. یک زیرتوالی اولیه سره از توالی نویسندگان برای یک مرجع، مبهم تلقی می‌شود اگر مرجعی با توالی دیگری از نویسندگان وجود داشته باشد که آن زیرتوالی را نیز به عنوان یک زیرتوالی اولیه سره داشته باشد. هنگامی که یک زیرتوالی اولیه از نویسندگان استفاده می‌شود، نویسندگان باقی‌مانده با رشته مشخص‌شده توسط دستور et-al جایگزین می‌شوند؛ این دستور ممکن است شرایط اضافی دیگری را نیز که پیش از استفاده از زیرتوالی اولیه باید برآورده شوند مشخص کند. علامت @ به صورت آزمایشی به یک نمایش رسمی و معیار (canonical) از نویسندگان ارزیابی می‌شود، به گونه‌ای که نویسندگانی که برای اهداف مرتب‌سازی برابر ارزیابی می‌شوند، نمایش یکسانی داشته باشند.
%n
%a
%A
%i
%I
شماره سریالی مرجع که بر اساس نویسه پس از % قالب‌بندی شده است. شماره سریالی یک مرجع برابر است با 1 به علاوه تعداد مراجع پیشین با برچسب آزمایشی یکسان با این مرجع. این عبارت‌ها به صورت آزمایشی به یک رشته خالی ارزیابی می‌شوند.
اگر مرجع دیگری با برچسب آزمایشی یکسان با این مرجع وجود داشته باشد، آنگاه expr، در غیر این صورت یک رشته خالی. این عبارت به صورت آزمایشی به یک رشته خالی ارزیابی می‌شود.
تعداد n حرف بزرگ یا کوچک یا رقم اول (+) یا آخر (-) از expr. نویسه‌های ویژه roff (مانند \('a) به عنوان یک حرف تکی شمرده می‌شوند. رشته‌های اعراب حفظ می‌شوند اما در شمارش کل به حساب نمی‌آیند.
مورد expr تبدیل‌شده به حروف کوچک.
مورد expr تبدیل‌شده به حروف بزرگ.
مورد expr تبدیل‌شده به حروف بزرگ و حروف بزرگ کوچک.
مورد expr معکوس‌شده به طوری که نام خانوادگی در ابتدا باشد.
مورد expr همراه با نام‌های کوچک مخفف‌شده. فیلدهای مشخص‌شده در دستور abbreviate پیش از ارزیابی هرگونه برچسب مخفف می‌شوند. بنابراین .a تنها زمانی مفید است که می‌خواهید یک فیلد در برچسب مخفف شود اما در مرجع مخفف نگردد.
بخش سال از expr.
بخش قبل از سال از expr، یا کل expr اگر شامل سال نباشد.
بخش بعد از سال از expr، یا یک رشته خالی اگر expr شامل سال نباشد.
بخش نام خانوادگی از expr.
مورد expr1 به جز اینکه اگر آخرین نویسه expr1 برابر با - باشد، با expr2 جایگزین خواهد شد.
expr1 expr2
الحاق expr1 و expr2.
اگر expr1 غیرخالی باشد آنگاه expr1 وگرنه expr2.
اگر expr1 غیرخالی باشد آنگاه expr2 وگرنه یک رشته خالی.
اگر expr1 غیرخالی باشد آنگاه expr2 وگرنه expr3.
<expr>
برچسب در دو بخش است، که با expr از هم جدا می‌شوند. دو برچسب دو بخشی مجاور که بخش اول یکسانی دارند با پیوست کردن بخش دوم برچسب دوم به برچسب اول با فاصله‌گذاری رشته مشخص‌شده در دستور separate-label-second-parts (در ابتدا، یک کاما به همراه یک فاصله) ادغام می‌شوند؛ برچسب حاصل نیز یک برچسب دو بخشی با همان بخش اول قبل از ادغام خواهد بود، و بنابراین برچسب‌های بیشتری نیز می‌توانند با آن ادغام شوند. مجاز است که بخش اول خالی باشد؛ این حالت ممکن است برای عبارت‌های مورد استفاده در دستور short-label مطلوب باشد.
(expr)
مشابه expr. برای گروه‌بندی استفاده می‌شود.

عبارت‌های بالا به ترتیب اولویت (بیشترین اولویت در ابتدا) فهرست شده‌اند؛ & و | اولویت یکسانی دارند.

هر مرجع با یک فراخوانی از ماکروی ]- آغاز می‌شود. رشته [F به عنوان برچسب این مرجع تعریف خواهد شد، مگر آن که دستور no-label-in-reference داده شده باشد. سپس مجموعه‌ای از تعاریف رشته‌ای، یکی برای هر فیلد، می‌آید: رشته [X متناظر با فیلد X است. ثبات [P در صورتی که فیلد P حاوی بازه‌ای از صفحات باشد، برابر با 1 تنظیم می‌شود. ثبات‌های [T، [A و [O بسته به این که آیا فیلدهای T، A و O با هر یک از نویسه‌های .?! (نویسه پایان جمله) خاتمه می‌یابند یا خیر، برابر با 1 تنظیم می‌شوند. ثبات [E در صورتی که رشته [E شامل بیش از یک نام باشد، برابر با 1 تنظیم خواهد شد. به دنبال مرجع، فراخوانی ماکروی ][ می‌آید. اولین آرگومان این ماکرو عددی را مشخص می‌کند که نوع مرجع را نشان می‌دهد. اگر یک مرجع شامل فیلد J باشد، به عنوان نوع 1 دسته‌بندی می‌شود، در غیر این صورت اگر شامل فیلد B باشد، نوع 3 خواهد بود، در غیر این صورت اگر شامل فیلد G یا R باشد، نوع 4 خواهد بود، در غیر این صورت اگر شامل فیلد I باشد، نوع 2 خواهد بود، وگرنه نوع 0 خواهد بود. آرگومان دوم یک نام نمادین برای این نوع است: other، journal-article، book، article-in-book یا tech-report. گروه‌هایی از مراجع که انباشته شده‌اند یا توسط دستور bibliography تولید شده‌اند، با فراخوانی ماکروی ]< شروع شده و با فراخوانی ماکروی ]> خاتمه می‌یابند.

گزینه --help پیام راهنمای نحوه استفاده را نمایش می‌دهد، در حالی که -v و --version اطلاعات نگارش را نمایش می‌دهند؛ همگی پس از آن خارج می‌شوند.

خطوط آغازشونده با .R1/.R2 را شناسایی نمی‌کند.

سایر گزینه‌ها معادل دستورات refer هستند.

reverse An
no-label-in-text; no-label-in-reference
در ادامه ببینید.
capitalize fields
compatible
accumulate
label %n
search-ignore fields
label L~%a
-k field
label field~%a
label A.nD.y%a
-l m
label A.n+mD.y%a
-l ,n
label A.nD.y-n%a
-l m,n
label A.n+mD.y-n%a
no-default-database
database db-file
move-punctuation
sort spec
label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "
search-truncate n

گزینه B دارای معادل‌های دستوری است با این تمایز که نام‌های فایل مشخص‌شده در خط فرمان به جای شیوه معمول، به گونه‌ای پردازش می‌شوند که گویی آرگومان‌های دستور bibliography هستند.

annotate X AP; no-label-in-reference
-B field.macro
annotate field macro; no-label-in-reference

برنامه refer در صورت عملکرد موفقیت‌آمیز با وضعیت 0، اگر نتواند آرگومان‌های خط فرمان خود را تفسیر کند با وضعیت 2، و در صورت مواجهه با خطا در حین اجرا با وضعیت 1 خارج می‌شود.

نام فایلی را به این متغیر اختصاص دهید تا پایگاه‌داده پیش‌فرض را بازنویسی کند.

/usr/dict/papers/Ind
پایگاه‌داده پیش‌فرض.
file.i
فایل‌های نمایه.
/usr/share/groff/1.24.1/tmac/refer.tmac
ماکروها و رشته‌هایی را تعریف می‌کند که ادغام با بسته‌های ماکرویی را که مایل به پشتیبانی از refer هستند تسهیل می‌نماید.

refer از فایل‌های موقت استفاده می‌کند. صفحه راهنمای groff(1) را برای جزئیات محل ایجاد چنین فایل‌هایی ببینید.

در عبارت‌های برچسب، عبارت‌های <> در داخل عبارت‌های .char نادیده گرفته می‌شوند.

ما می‌توانیم عملکرد refer را با یک پایگاه‌داده کتاب‌شناختی نمونه شامل یک مدخل و یک سند ساده roff برای استناد به آن مدخل نشان دهیم.

$ 
cat > my-db-file
%A Daniel P.\& Friedman
%A Matthias Felleisen
%C Cambridge, Massachusetts
%D 1996
%I The MIT Press
%T The Little Schemer, Fourth Edition
$ 
refer -p my-db-file
Read the book
.[
friedman
.]
on your summer vacation.
<Control+D>
.lf 1 -
Read the book\*([.1\*(.]
.ds [F 1
.]-
.ds [A Daniel P. Friedman and Matthias Felleisen
.ds [C Cambridge, Massachusetts
.ds [D 1996
.ds [I The MIT Press
.ds [T The Little Schemer, Fourth Edition
.nr [T 0
.nr [A 0
.][ 2 book
.lf 5 -
on your summer vacation.

مثال بالا به ما نشان می‌دهد که refer الف) یک برچسب “1” تولید می‌کند؛ ب) آن برچسب را درون درون‌یابی‌های رشته‌های “[.” و “.]” قرار می‌دهد؛ ج) ماکروی “]-” را فراخوانی می‌کند؛ د) رشته‌ها و ثبات‌های حاوی برچسب و داده‌های کتاب‌شناختی را برای مرجع تعریف می‌کند؛ هـ) ماکروی “][” را فراخوانی می‌نماید؛ و و) از درخواست lf برای بازیابی شماره خطوط ورودی استفاده می‌کند. همان‌طور که در زیربخش “رابط ماکرو” در بالا ذکر شد، این مسئولیت سند است که اطلاعات را به شکل مفیدی به کار گرفته و قالب‌بندی نماید. بیایید ببینیم چگونه می‌توانیم groff_ms(7) را برای این کار به خدمت بگیریم.

$ 
REFER=my-db-file groff -R -ms
.LP
Read the book
.[
friedman
.]
on your summer vacation.
Commentary is available.\*{*\*}
.FS \*{*\*}
Space reserved for penetrating insight.
.FE

سازوکار شماره‌گذاری خودکار پاورقی در ms از شماره‌گذاری برچسب‌های refer آگاه نیست، بنابراین ما به صورت دستی یک پاورقی نمادین (بالانویس‌شده) را برای حاشیه غیرکتاب‌شناختی خود مشخص کرده‌ایم.

“Refer — A Bibliography System”, توسط Bill Tuthill، 1983، Computing Services, University of California, Berkeley.

“Some Applications of Inverted Indexes on the Unix System”, توسط M. E. Lesk، 1978، AT&T Bell Laboratories Computing Science Technical Report No. 69.

indxbib(1), lookbib(1), lkbib(1)

2026-03-15 groff 1.24.1