.\" $Id: mandoc.db.5,v 1.5 2016/08/01 12:27:15 schwarze Exp $ .\" .\" Copyright (c) 2014, 2016 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate: August 1 2016 $ .Dt MANDOC.DB 5 .Os .Sh "نام (NAME)" .Nm mandoc.db .Nd پایگاه‌داده کلیدواژه‌های صفحات راهنما در mandoc .Sh "توضیحات (DESCRIPTION)" قالب فایل .Nm برای ذخیره اطلاعات درباره صفحات راهنمای نصب‌شده جهت تسهیل جستجوی معنایی در راهنماها استفاده می‌شود. هر درخت از صفحات راهنما شامل فایل .Nm مختص به خود است؛ برای مشاهده مثال‌ها بخش .Sx "فایل‌ها (FILES)" را ببینید. .Pp چنین فایل‌های پایگاه‌داده‌ای توسط .Xr makewhatis 8 تولید شده و توسط .Xr man 1 , .Xr apropos 1 و .Xr whatis 1 استفاده می‌شوند. .Pp قالب این فایل از سه نوع داده استفاده می‌کند: .Pp .Bl -dash -compact -offset 2n -width 1n .It اعداد صحیح علامت‌دار ۳۲ بیتی با ترتیب بایت بزرگ‌پایان (شبکه‌ای / big endian) .It رشته‌های پایان‌یافته با NUL .It فهرست‌هایی از رشته‌های پایان‌یافته با NUL که با یک نویسه دوم NUL خاتمه می‌یابند .El .Pp اعداد در مرزهای چهار بایتی تراز می‌شوند؛ در جاهایی که پس از رشته‌ها یا فهرست‌هایی از رشته‌ها قرار می‌گیرند، فاصله‌گذاری (padding) با نویسه‌های اضافی NUL انجام می‌شود. برخی از اعداد، اما نه همه آن‌ها، به موقعیت‌هایی درون فایل اشاره می‌کنند. این اشاره‌گرها بر حسب بایت اندازه‌گیری می‌شوند و نخستین بایت فایل به عنوان بایت ۰ در نظر گرفته می‌شود. .Pp هر فایل شامل موارد زیر است: .Pp .Bl -dash -compact -offset 2n -width 1n .It یک عدد جادویی (magic number)، 0x3a7d0cdb. .It یک شماره نسخه، در حال حاضر ۱. .It یک اشاره‌گر به جدول ماکروها. .It یک اشاره‌گر به عدد جادویی پایانی. .It جدول صفحات (طول متغیر). .It جدول ماکروها (طول متغیر). .It مجدداً عدد جادویی، 0x3a7d0cdb. .El .Pp جدول صفحات شامل یک مدخل برای هر فایل فیزیکی صفحه راهنما است، صرف‌نظر از این که چه تعداد پیوند سخت یا نرم در سیستم‌فایل داشته باشد. جدول صفحات شامل موارد زیر است: .Pp .Bl -dash -compact -offset 2n -width 1n .It تعداد صفحات موجود در پایگاه‌داده. .It برای هر صفحه: .Bl -dash -compact -offset 2n -width 1n .It یک اشاره‌گر به فهرست نام‌ها. .It یک اشاره‌گر به فهرست بخش‌ها. .It یک اشاره‌گر به فهرست معماری‌ها، یا ۰ در صورتی که صفحه مستقل از ماشین (معماری) باشد. .It یک اشاره‌گر به رشته توصیف یک‌خطی. .It یک اشاره‌گر به فهرست نام‌فایل‌ها. .El .It برای هر صفحه، فهرست نام‌ها. پیش از هر نام یک تک‌بایت قرار دارد که نشان‌دهنده منابع آن نام است. مفهوم بیت‌ها به شرح زیر است: .Bl -dash -compact -offset 2n -width 1n .It 0x10: نام در یک نام‌فایل ظاهر شده است. .It 0x08: نام در یک خط هدر آمده است، یعنی در ماکروی \&.Dt یا \&.TH. .It 0x04: نام، نخستین مورد در خط عنوان است، یعنی در نخستین ماکروی \&.Nm در بخش NAME ظاهر شده است. .It 0x02: نام در هر ماکروی \&.Nm در بخش NAME ظاهر شده است. .It 0x01: نام در یک بلوک \&.Nm در بخش SYNOPSIS ظاهر شده است. .El .It برای هر صفحه، فهرست بخش‌ها. هر بخش به صورت یک رشته داده می‌شود، نه یک عدد. .It برای هر صفحه وابسته به معماری، فهرست معماری‌ها. .It برای هر صفحه، رشته توصیف یک‌خطی برگرفته از ماکروی \&.Nd. .It برای هر صفحه، فهرست نام‌فایل‌ها به صورت نسبی نسبت به ریشه مسیر manpath مربوطه. این فهرست شامل پیوندهای سخت، پیوندهای نرم و پیوندهای شبیه‌سازی‌شده با درخواست‌های \&.so در .Xr roff 7 است. پیش از نخستین نام‌فایل، یک تک‌بایت با مفهوم زیر قرار دارد: .Bl -dash -compact -offset 2n -width 1n .It .Dv FORM_SRC No = 0x01 : فرمت فایل .Xr mdoc 7 یا .Xr man 7 است. .It .Dv FORM_CAT No = 0x02 : صفحه راهنما از پیش فرمت‌بندی شده است. .El .It صفر تا سه بایت NUL برای فاصله‌گذاری (padding). .El .Pp جدول ماکروها شامل موارد زیر است: .Pp .Bl -dash -compact -offset 2n -width 1n .It تعداد کلیدهای ماکروی متفاوت، در حال حاضر ۳۶ عدد. ترتیب ماکروها در .In mansearch.h تعریف شده و مفهوم کلیدهای ماکرو در .Xr apropos 1 مستند شده است. .It برای هر کلید ماکرو، یک اشاره‌گر به جدول ماکروی مربوطه. .It برای هر کلید ماکرو، جدول ماکرو (طول متغیر). .El .Pp هر جدول ماکرو شامل موارد زیر است: .Pp .Bl -dash -compact -offset 2n -width 1n .It تعداد مدخل‌ها در جدول. .It برای هر مدخل: .Bl -dash -compact -offset 2n -width 1n .It یک اشاره‌گر به مقدار کلید ماکرو. هر مقدار، رشته‌ای از متن است که از فراخوانی یک ماکرو برگرفته شده است. .It یک اشاره‌گر به فهرست صفحات. .El .It برای هر مدخل، مقدار کلید ماکرو. .It صفر تا سه بایت NUL برای فاصله‌گذاری (padding). .It برای هر مدخل، یک یا چند اشاره‌گر به صفحات در جدول صفحات، که به اشاره‌گر فهرست نام‌ها اشاره دارند و پس از آن‌ها عدد ۰ قرار می‌گیرد. .El .Sh "فایل‌ها (FILES)" .Bl -tag -width /usr/share/man/mandoc.db -compact .It Pa /usr/share/man/mandoc.db پایگاه‌داده صفحات راهنما برای سیستم پایه. .It Pa /usr/X11R6/man/mandoc.db همان مورد برای سامانه پنجره .Xr X 7 . .It Pa /usr/local/man/mandoc.db همان مورد برای .Xr packages 7 . .El .Pp برنامه‌ای برای استخراج اطلاعات فایل‌های .Nm در قالبی خوانا برای انسان که برای .Xr diff 1 مناسب باشد، در دایرکتوری .Pa /usr/src/regress/usr.bin/mandoc/db/dbm_dump/ فراهم شده است. .Sh "همچنین ببینید (SEE ALSO)" .Xr apropos 1 , .Xr man 1 , .Xr whatis 1 , .Xr makewhatis 8 .Sh "تاریخچه (HISTORY)" پایگاه‌داده صفحات راهنما .Pa /usr/lib/whatis نخستین بار در .Bx 2 پدیدار شد. قالب کنونی نخستین بار در .Ox 6.1 ظاهر شد. .Sh "نویسندگان (AUTHORS)" .An -nosplit نسخه اولیه .Xr makewhatis 8 در سال ۱۹۷۹ توسط .An Bill Joy نوشته شد. قالب کنونی پایگاه‌داده در سال ۲۰۱۶ توسط .An Ingo Schwarze Aq Mt schwarze@openbsd.org طراحی شد.