.\" $OpenBSD: mandoc.1,v 1.166 2020/02/15 15:28:01 schwarze Exp $ .\" .\" Copyright (c) 2012, 2014-2021 Ingo Schwarze .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" .\" 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 14 2021 $ .Dt MANDOC 1 .Os .Sh "نام (NAME)" .Nm mandoc .Nd قالب‌بندی صفحه‌های راهنما .Sh "خلاصه دستور (SYNOPSIS)" .Nm mandoc .Op Fl ac .Op Fl I Cm os Ns = Ns Ar name .Op Fl K Ar encoding .Op Fl mdoc | man .Op Fl O Ar options .Op Fl T Ar output .Op Fl W Ar level .Op Ar .Sh "توضیحات (DESCRIPTION)" ابزار .Nm صفحه‌های راهنما را برای نمایش قالب‌بندی می‌کند. .Pp به‌طور پیش‌فرض، .Nm متن‌های .Xr mdoc 7 یا .Xr man 7 را از ورودی استاندارد (stdin) خوانده و خروجی .Fl T Cm locale تولید می‌کند. .Pp گزینه‌ها به شرح زیر هستند: .Bl -tag -width Ds .It Fl a اگر خروجی استاندارد یک ترمینال باشد و .Fl c مشخص نشده باشد، مانند .Xr man 1 از .Xr less 1 برای صفحه‌بندی خروجی استفاده می‌کند. .It Fl c صفحه‌های راهنمای قالب‌بندی‌شده را بدون استفاده از .Xr less 1 برای صفحه‌بندی آن‌ها، در خروجی استاندارد رونوشت می‌کند. این رفتار پیش‌فرض است. می‌توان آن را برای لغو اثر .Fl a مشخص کرد. .It Fl I Cm os Ns = Ns Ar name نام پیش‌فرض سیستم‌عامل .Pq Ar name را برای ماکروی .Ic \&Os در .Xr mdoc 7 و ماکروی .Ic \&TH در .Xr man 7 بازنویسی می‌کند. .It Fl K Ar encoding کدگذاری ورودی را مشخص می‌کند. آرگومان‌های .Ar encoding پشتیبانی‌شده عبارتند از .Cm us-ascii ، .Cm iso-8859-1 و .Cm utf-8 . در صورت مشخص نشدن، تشخیص خودکار از نخستین مورد منطبق در فهرست زیر استفاده می‌کند: .Bl -enum .It اگر سه بایت اول فایل ورودی، نشان ترتیب بایت (BOM، 0xefbbbf) مربوط به UTF-8 باشد، ورودی به عنوان .Cm utf-8 تفسیر می‌شود. .It اگر خط اول یا دوم فایل ورودی با قالب خط حالت .Sy emacs مطابقت داشته باشد: .Pp .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*- .Pp آنگاه ورودی مطابق با .Ar encoding تفسیر می‌شود. .It اگر نخستین بایت غیر ASCII در فایل، آغازگر یک توالی معتبر UTF-8 باشد، ورودی به عنوان .Cm utf-8 تفسیر می‌شود. .It در غیر این صورت، ورودی به عنوان .Cm iso-8859-1 تفسیر می‌شود. .El .It Fl mdoc | man با گزینهٔ .Fl mdoc ، تمام فایل‌های ورودی به عنوان .Xr mdoc 7 تفسیر می‌شوند. با .Fl man ، تمام فایل‌های ورودی به عنوان .Xr man 7 تفسیر می‌شوند. به‌طور پیش‌فرض، زبان ورودی به‌صورت خودکار برای هر فایل تشخیص داده می‌شود: اگر اولین ماکرو .Ic \&Dd یا .Ic \&Dt باشد، تجزیه‌کنندهٔ .Xr mdoc 7 به کار می‌رود؛ در غیر این صورت، تجزیه‌کنندهٔ .Xr man 7 استفاده می‌شود. همراه با سایر آرگومان‌ها، .Fl m بدون هیچ پیامی نادیده گرفته می‌شود. .It Fl O Ar options گزینه‌های خروجی جدا شده با کاما. برای مشاهدهٔ .Ar options پشتیبانی‌شده، به توضیحات قالب‌های خروجی اختصاصی مراجعه کنید. .It Fl T Ar output قالب خروجی را انتخاب می‌کند. مقدارهای پشتیبانی‌شده برای آرگومان .Ar output عبارتند از .Cm ascii ، .Cm html ، مقدار پیش‌فرض .Cm locale ، .Cm man ، .Cm markdown ، .Cm pdf ، .Cm ps ، .Cm tree و .Cm utf8 . .Pp حالت ویژهٔ .Fl T Cm lint فقط ورودی را تجزیه کرده و هیچ خروجی تولید نمی‌کند. این حالت به منزلهٔ .Fl W Cm all است و پیام‌های تجزیه‌کننده را که معمولاً در خروجی خطای استاندارد ظاهر می‌شوند، به خروجی استاندارد هدایت می‌کند. .It Fl W Ar level حداقل سطح پیام .Pq Ar level را برای گزارش در خروجی خطای استاندارد و تأثیرگذاری بر وضعیت خروج تعیین می‌کند. سطح .Ar level می‌تواند .Cm base ، .Cm style ، .Cm warning ، .Cm error یا .Cm unsupp باشد. سطح .Cm base سیستم‌عامل را به‌طور خودکار از محتوای ماکروی .Ic \&Os ، از گزینهٔ خط فرمان .Fl Ios ، یا از مقدار بازگشتی .Xr uname 3 استخراج می‌کند. سطوح .Cm openbsd و .Cm netbsd گونه‌هایی از .Cm base هستند که تشخیص خودکار را کنار گذاشته و اعتبارسنجی قراردادهای سیستم پایه را برای یک سیستم‌عامل خاص درخواست می‌کنند. سطح .Cm all نام مستعاری برای .Cm base است. به‌طور پیش‌فرض، .Nm پیامی نمایش نمی‌دهد. برای جزئیات به .Sx "وضعیت خروج (EXIT STATUS)" و .Sx "خطاها (DIAGNOSTICS)" مراجعه کنید. .Pp گزینهٔ ویژهٔ .Fl W Cm stop به .Nm دستور می‌دهد پس از تجزیهٔ فایلی که هشدارهایی یا خطاهایی حداقل در سطح درخواستی ایجاد می‌کند، خارج شود. هیچ خروجی قالب‌بندی‌شده‌ای از آن فایل تولید نخواهد شد. اگر هم یک .Ar level و هم .Cm stop درخواست شوند، می‌توان آن‌ها را با کاما به هم متصل کرد؛ به عنوان مثال .Fl W Cm error , Ns Cm stop . .It Ar file از فایل ورودی داده‌شده می‌خواند. اگر چندین فایل مشخص شده باشند، به ترتیب داده‌شده پردازش می‌شوند. در صورت مشخص نشدن، .Nm از ورودی استاندارد می‌خواند. .El .Pp گزینه‌های .Fl fhklw نیز پشتیبانی می‌شوند و در .Xr man 1 مستند شده‌اند. در حالت‌های .Fl f و .Fl k ، ابزار .Nm همچنین از گزینه‌های .Fl CMmOSs که در راهنمای .Xr apropos 1 توضیح داده شده‌اند پشتیبانی می‌کند. گزینه‌های .Fl fkl مانعة‌الجمع هستند و یکدیگر را لغو می‌کنند. .Ss "خروجی ASCII" از .Fl T Cm ascii برای اجبار به خروجی متن با کدگذاری نویسه‌های ۷-بیتی ASCII مستندشده در صفحهٔ راهنمای .Xr ascii 7 ، صرف‌نظر از .Xr locale 1 تنظیم‌شده در محیط استفاده کنید. .Pp سبک قلم‌ها با استفاده از نویسه‌های پس‌بر (back-spaced) اعمال می‌شود، به‌طوری که نویسهٔ زیرخط‌دار .Sq c به‌صورت .Sq _ Ns \e[bs] Ns c نمایش داده می‌شود، که در آن .Sq \e[bs] نویسهٔ پس‌بر با شماره ۸ است. نویسه‌های پررنگ به‌صورت .Sq c Ns \e[bs] Ns c نمایش داده می‌شوند. این نشانه‌گذاری معمولاً توسط صفحه‌بند یا .Xr ul 1 به دنباله‌های ترمینال مناسب تبدیل می‌شود. برای حذف نشانه‌گذاری، خروجی را به .Xr col 1 .Fl b هدایت کنید. .Pp نویسه‌های ویژه‌ای که در .Xr mandoc_char 7 مستند شده‌اند، با بهترین تقریب ممکن به معادل ASCII نمایش داده می‌شوند. به‌ویژه، گیومه‌های تکی باز و بسته .Pq Sq single quotes به ترتیب با نویسه‌های شماره 0x60 و 0x27 نمایش داده می‌شوند که با تمام استانداردهای ASCII از ۱۹۶۵ تا آخرین بازنگری (۲۰۱۲) مطابقت دارد و با روش سنتی قالب‌بندهای .Xr roff 7 در نمایش گیومه‌های تکی در خروجی ASCII همخوانی دارد. این نمایش صحیح ASCII ممکن است با قلم‌های مدرن سازگار با یونیکد عجیب به نظر برسد؛ زیرا برخلاف ASCII، یونیکد از نقطهٔ کد U+0060 فقط برای اکسان گراو استفاده می‌کند و هرگز برای گیومهٔ باز به‌کار نمی‌رود. .Pp آرگومان‌های .Fl O زیر پذیرفته می‌شوند: .Bl -tag -width Ds .It Cm indent Ns = Ns Ar indent حاشیهٔ چپ برای متن عادی به‌جای پنج فاصلهٔ پیش‌فرض در .Xr mdoc 7 و هفت فاصله در .Xr man 7 ، روی .Ar indent نویسهٔ خالی تنظیم می‌شود. افزایش این مقدار توصیه نمی‌شود؛ ممکن است منجر به افت کیفیت قالب‌بندی شود، برای نمونه سرریز خطوط یا شکستگی‌های نامناسب در خط. هنگامی که خروجی به صفحه‌بندی در یک ترمینال با پهنای کمتر از ۶۶ ستون هدایت می‌شود، مقدار پیش‌فرض به سه ستون کاهش می‌یابد. .It Cm mdoc فایل‌های ورودی .Xr man 7 را به سبک خروجی .Xr mdoc 7 قالب‌بندی می‌کند. این کار نام سیستم‌عامل را به‌جای عنوان صفحه در سمت راست خط پاورقی چاپ می‌کند، و متضمن .Fl O Cm indent Ns =5 است. یک کاربرد مفید آن بررسی این است که آیا خروجی .Fl T Cm man مشابه منبع .Xr mdoc 7 که از آن تولید شده قالب‌بندی می‌شود یا خیر. .It Cm tag Ns Op = Ns Ar term اگر صفحهٔ راهنمای قالب‌بندی‌شده در یک صفحه‌بند باز شود، به‌جای نمایش صفحهٔ راهنما از ابتدا، به تعریف .Ar term پرش می‌کند. اگر هیچ .Ar term مشخص نشده باشد، از اولین آرگومان خط فرمان که شمارهٔ .Ar section نیست مجدداً استفاده می‌شود. اگر آن آرگومان در قالب .Ar key Ns = Ns Ar val مربوط به .Xr apropos 1 باشد، به‌جای کل آرگومان فقط .Ar val استفاده می‌شود. این ویژگی برای دستورهایی مانند .Ql man -akO tag Ic=ulimit برای جستجوی یک کلیدواژه و پرش مستقیم به تعریف آن در صفحات راهنمای منطبق مفید است. .It Cm width Ns = Ns Ar width پهنای خروجی به‌جای مقدار پیش‌فرض ۷۸ روی .Ar width تنظیم می‌شود. هنگامی که خروجی به صفحه‌بندی در ترمینالی با پهنای کمتر از ۷۹ ستون ارسال می‌شود، مقدار پیش‌فرض به یکی کمتر از پهنای ترمینال کاهش می‌یابد. در هر حال، خطوطی که در حالت پیش‌فرض (literal) خارج می‌شوند هرگز شکسته نمی‌شوند و ممکن است از پهنای خروجی فراتر روند. .El .Ss "خروجی HTML" خروجی تولیدشده توسط .Fl T Cm html با استفاده از تگ‌های خودبسته اختیاری با HTML5 مطابقت دارد. سبک‌های پیش‌فرض فقط از CSS1 استفاده می‌کنند. معادلاتی که از بلوک‌های .Xr eqn 7 تولید می‌شوند از MathML استفاده می‌کنند. .Pp فایل .Pa /usr/share/misc/mandoc.css کلاس‌های شیوه‌نامه موجود برای سفارشی‌سازی خروجی را مستند می‌کند. اگر شیوه‌نامه‌ای با .Fl O Cm style مشخص نشود، .Fl T Cm html به‌طور پیش‌فرض خروجی ساده‌ای (از طریق یک شیوه‌نامهٔ تعبیه‌شده) تولید می‌کند که در هر مرورگر وب گرافیکی یا متنی قابل خواندن است. .Pp نویسه‌های غیر ASCII به‌صورت ارجاعات نویسهٔ شانزده‌شانزدهی یونیکد نمایش داده می‌شوند. .Pp آرگومان‌های .Fl O زیر پذیرفته می‌شوند: .Bl -tag -width Ds .It Cm fragment اعلامیهٔ و عنصرهای ، و را حذف کرده و فقط زیردرخت درون عنصر را تولید می‌کند. آرگومان .Cm style نادیده گرفته خواهد شد. این ویژگی هنگام گنجاندن محتوای راهنما در اسناد موجود مفید است. .It Cm includes Ns = Ns Ar fmt رشتهٔ .Ar fmt ، برای مثال .Ar ../src/%I.html ، به عنوان الگویی برای فایل‌های سرایند پیوند داده‌شده (معمولاً از طریق ماکروی .Ic \&In ) استفاده می‌شود. نمونه‌های .Sq \&%I با نام فایل include جایگزین می‌شوند. حالت پیش‌فرض، عدم ارائهٔ پیوند است. .It Cm man Ns = Ns Ar fmt Ns Op ; Ns Ar fmt رشتهٔ .Ar fmt ، برای مثال .Ar ../html%S/%N.%S.html ، به عنوان الگویی برای راهنماهای پیوند داده‌شده (معمولاً از طریق ماکروی .Ic \&Xr ) استفاده می‌شود. نمونه‌های .Sq \&%N و .Sq %S به ترتیب با نام و بخش راهنمای پیوند داده‌شده جایگزین می‌شوند. اگر بخشی گنجانده نشده باشد، بخش ۱ فرض می‌شود. حالت پیش‌فرض عدم ارائهٔ پیوند است. اگر دو الگو ارائه شود و فایل .Ar %N.%S در دایرکتوری جاری موجود باشد، الگوی اول استفاده می‌شود؛ در غیر این صورت، الگوی دوم به کار می‌رود. .It Cm style Ns = Ns Ar style.css فایل .Ar style.css برای شیوه‌نامهٔ خارجی استفاده می‌شود. این باید یک URI معتبر مطلق یا نسبی باشد. .It Cm tag Ns Op = Ns Ar term نحو و معناشناسی مشابه با .Sx "خروجی ASCII" . این مورد با ارسال یک URI با طرح .Ic file:// که به یک شناسهٔ بخش ختم می‌شود به صفحه‌بند پیاده‌سازی شده است، نه ارسال صرفاً یک نام فایل. هنگام استفاده از این آرگومان، از صفحه‌بندی استفاده کنید که از چنین URIهایی پشتیبانی می‌کند، به عنوان مثال: .Bd -literal -offset 3n MANPAGER='lynx -force_html' man -T html -O tag=MANPAGER man MANPAGER='w3m -T text/html' man -T html -O tag=toc mandoc .Ed .Pp در نتیجه، برای خروجی HTML، این آرگومان با .Xr more 1 یا .Xr less 1 کار نمی‌کند. برای نمونه، .Ql MANPAGER=less man -T html -O tag=toc mandoc کار نمی‌کند زیرا .Xr less 1 از URIهای .Ic file:// پشتیبانی نمی‌کند. .It Cm toc اگر یک فایل ورودی حداقل شامل دو بخش غیر استاندارد باشد، فهرست مطالبی را نزدیک ابتدای خروجی چاپ می‌کند. .El .Ss "خروجی Locale" به‌طور پیش‌فرض، .Nm به‌صورت خودکار خروجی UTF-8 یا ASCII را بر اساس .Xr locale 1 جاری انتخاب می‌کند. اگر هر یک از متغیرهای محیطی .Ev LC_ALL ، .Ev LC_CTYPE یا .Ev LANG تنظیم شده باشند و اولین متغیری که تنظیم شده، کدگذاری نویسهٔ UTF-8 را انتخاب کند، .Sx "خروجی UTF-8" تولید می‌شود؛ در غیر این صورت، به .Sx "خروجی ASCII" بازمی‌گردد. این حالت خروجی را می‌توان صراحتاً با .Fl T Cm locale نیز انتخاب کرد. .Ss "خروجی Man" از .Fl T Cm man برای ترجمهٔ ورودی .Xr mdoc 7 به قالب خروجی .Xr man 7 استفاده کنید. این برای توزیع منابع صفحات راهنما به سیستم‌های قدیمی که فاقد قالب‌بندهای .Xr mdoc 7 هستند مفید است. کدهای تعبیه‌شدهٔ .Xr eqn 7 و .Xr tbl 7 پشتیبانی نمی‌شوند. .Pp اگر قالب ورودی یک فایل .Xr man 7 باشد، ورودی در خروجی رونوشت می‌شود. تجزیه‌کننده نیز اجرا می‌شود، و مثل همیشه، سطح .Fl W مشخص می‌کند که کدام .Sx "خطاها (DIAGNOSTICS)" پیش از رونوشت ورودی به خروجی نمایش داده شوند. .Ss "خروجی Markdown" از .Fl T Cm markdown برای ترجمهٔ ورودی .Xr mdoc 7 به قالب markdown مطابق با .Lk http://daringfireball.net/projects/markdown/syntax.text "مشخصات سال ۲۰۰۴ جان گروبر" استفاده کنید. خروجی همچنین تقریباً با مشخصات .Lk http://commonmark.org CommonMark مطابقت دارد. .Pp مجموعه نویسه‌های مورد استفاده برای خروجی markdown برابر با ASCII است. نویسه‌های غیر ASCII به‌صورت موجودیت‌های HTML کدگذاری می‌شوند. از آنجا که این کار در زمینه‌های قلم لفظی (literal) ممکن نیست، زیرا آن‌ها به‌صورت کد درون‌خطی و بلوک‌های کد در خروجی markdown نمایش داده می‌شوند، نویسه‌های غیر ASCII در این زمینه‌ها به تقریب‌های ASCII نویسه‌گردانی می‌شوند. .Pp مارک‌داون یک زبان نشانه‌گذاری بسیار ضعیف است، بنابراین تمام نشانه‌گذاری‌های معنایی از بین می‌روند و حتی بخشی از نشانه‌گذاری‌های نمایشی نیز ممکن است از دست بروند. از این گزینه به عنوان یک مرحلهٔ میانی برای تبدیل به HTML استفاده نکنید؛ به‌جای آن، مستقیماً از .Fl T Cm html استفاده کنید. .Pp زبان‌های ورودی .Xr man 7 ، .Xr tbl 7 و .Xr eqn 7 توسط حالت خروجی .Fl T Cm markdown پشتیبانی نمی‌شوند. .Ss "خروجی PDF" خروجی PDF-1.1 را می‌توان با .Fl T Cm pdf تولید کرد. برای آرگومان‌های .Fl O و پیش‌فرض‌ها، به .Sx "خروجی PostScript" مراجعه کنید. .Ss "خروجی PostScript" صفحات PostScript .Qq Adobe-3.0 سطح ۲ را می‌توان با .Fl T Cm ps تولید کرد. صفحات خروجی به‌طور پیش‌فرض در اندازهٔ letter هستند و با خانوادهٔ قلم Times با اندازهٔ ۱۱ پوینت رندر می‌شوند. حاشیه‌ها به‌صورت ۱/۹ طول و عرض صفحه محاسبه می‌شوند. ارتفاع خط 1.4m است. .Pp نویسه‌های ویژه مانند .Sx "خروجی ASCII" نمایش داده می‌شوند. .Pp آرگومان‌های .Fl O زیر پذیرفته می‌شوند: .Bl -tag -width Ds .It Cm paper Ns = Ns Ar name نام اندازهٔ کاغذ .Pq Ar name می‌تواند یکی از موارد .Ar a3 ، .Ar a4 ، .Ar a5 ، .Ar legal یا .Ar letter باشد. همچنین می‌توانید ابعاد را به‌صورت دستی به شکل .Ar NNxNN ، عرض در ارتفاع بر حسب میلی‌متر مشخص کنید. در صورت مواجهه با یک مقدار ناشناخته، از .Ar letter استفاده می‌شود. .El .Ss "خروجی UTF-8" از .Fl T Cm utf8 برای اجبار به خروجی متنی با کدگذاری نویسهٔ چندبایتی UTF-8، صرف‌نظر از تنظیمات .Xr locale 1 در محیط، استفاده کنید. برای اطلاعات مربوط به سبک قلم‌ها و آرگومان‌های .Fl O به .Sx "خروجی ASCII" مراجعه کنید. .Pp در سیستم‌های عاملی که فاقد پشتیبانی از locale یا نویسه‌های پهن هستند، و سیستم‌هایی که در آن‌ها نمایش داخلی نویسه‌ها UCS-4 نیست، .Nm همواره به .Sx "خروجی ASCII" بازمی‌گردد. .Ss "خروجی درخت نحو (Syntax tree)" از .Fl T Cm tree برای نمایش یک بازنمایی قابل خواندن برای انسان از درخت نحو استفاده کنید. این گزینه برای اشکال‌زدایی کد منبع صفحات راهنما مفید است. قالب دقیق ممکن است تغییر کند، بنابراین برای آن تجزیه‌کننده ننویسید. .Pp پاراگراف اول داده‌های فرادادهٔ یافت‌شده در پیش‌درآمد .Xr mdoc 7 ، خط .Ic \&TH در .Xr man 7 ، یا مقادیر جایگزین استفاده‌شده را نمایش می‌دهد. .Pp در تخلیهٔ درخت (tree dump)، هر خط خروجی یک گره درخت نحو را نشان می‌دهد. گره‌های فرزند نسبت به گره والد خود دارای تورفتگی هستند. ستون‌ها عبارتند از: .Pp .Bl -enum -compact .It برای گره‌های ماکرو، نام ماکرو؛ برای گره‌های متنی و .Xr tbl 7 ، محتوا. قالب ویژه‌ای برای گره‌های .Xr eqn 7 وجود دارد. .It نوع گره (text، elem، block، head، body، body-end، tail، tbl، eqn). .It پرچم‌ها: .Bl -dash -compact .It یک پرانتز باز اگر گره یک جداکنندهٔ بازکننده باشد. .It یک ستاره اگر گره خط ورودی جدیدی را آغاز کند. .It شمارهٔ خط ورودی (شروع از یک). .It یک دو نقطه. .It شمارهٔ ستون ورودی (شروع از یک). .It یک پرانتز بسته اگر گره یک جداکنندهٔ پایان‌بخش باشد. .It یک نقطه اگر گره به یک جمله پایان دهد. .It عبارت BROKEN اگر گره، بلوکی باشد که توسط بلوک دیگری شکسته شده است. .It عبارت NOSRC اگر گره در فایل ورودی نباشد، بلکه به‌طور خودکار از ماکروها تولید شده باشد. .It عبارت NOPRT اگر قرار نباشد گره برای هیچ قالب خروجی‌ای، خروجی تولید کند. .El .El .Pp آرگومان .Fl O زیر پذیرفته می‌شود: .Bl -tag -width Ds .It Cm noval اعتبارسنجی را نادیده گرفته و درخت نحو اعتبارسنجی‌نشده را نمایش می‌دهد. این می‌تواند به تشخیص اینکه آیا یک رفتار مشخص ناشی از تجزیه‌کننده است یا اعتبارسنج کمک کند. در این حالت فراداده در دسترس نیست. .El .Sh "محیط (ENVIRONMENT)" .Bl -tag -width MANPAGER .It Ev LC_CTYPE کدگذاری نویسهٔ .Xr locale 1 . هنگامی که .Sx "خروجی Locale" انتخاب شده باشد، تصمیم می‌گیرد که از قالب خروجی ASCII استفاده شود یا UTF-8. این متغیر هرگز بر تفسیر فایل‌های ورودی تأثیری ندارد. .It Ev MANPAGER هر مقدار غیرخالی متغیر محیطی .Ev MANPAGER به‌جای برنامهٔ استاندارد صفحه‌بندی، یعنی .Xr less 1 استفاده می‌شود؛ برای جزئیات به .Xr man 1 مراجعه کنید. تنها در صورتی استفاده می‌شود که .Fl a یا .Fl l مشخص شده باشد. .It Ev PAGER برنامهٔ صفحه‌بندی را در زمانی که .Ev MANPAGER تعریف نشده باشد مشخص می‌کند. اگر نه PAGER و نه MANPAGER تعریف نشده باشند، از .Xr less 1 استفاده می‌شود. تنها در صورتی استفاده می‌شود که .Fl a یا .Fl l مشخص شده باشد. .El .Sh "وضعیت خروج (EXIT STATUS)" ابزار .Nm با یکی از مقادیر زیر خارج می‌شود که توسط سطح پیام .Pq Ar level مرتبط با گزینهٔ .Fl W کنترل می‌شود: .Pp .Bl -tag -width Ds -compact .It 0 هیچ نقض قراردادی در سیستم پایه، پیشنهادهای نگارشی، هشدار یا خطایی رخ نداده است، یا موارد رخ‌داده نادیده گرفته شدند زیرا پایین‌تر از .Ar level درخواستی بودند. .It 1 حداقل یک مورد نقض قرارداد سیستم پایه یا پیشنهاد نگارشی رخ داده است، اما بدون هشدار یا خطا، و .Fl W Cm base یا .Fl W Cm style مشخص شده بود. .It 2 حداقل یک هشدار رخ داده است، اما خطایی رخ نداده، و .Fl W Cm warning یا یک .Ar level پایین‌تر درخواست شده بود. .It 3 حداقل یک خطای تجزیه رخ داده است، اما با هیچ ویژگی پشتیبانی‌نشده‌ای مواجه نشد، و .Fl W Cm error یا یک .Ar level پایین‌تر درخواست شده بود. .It 4 حداقل با یک ویژگی پشتیبانی‌نشده مواجه شد، و .Fl W Cm unsupp یا یک .Ar level پایین‌تر درخواست شده بود. .It 5 آرگومان‌های نامعتبر خط فرمان مشخص شده‌اند. هیچ فایل ورودی خوانده نشده است. .It 6 یک خطای سیستم‌عامل رخ داده است، به عنوان مثال اتمام حافظه، توصیف‌گرهای فایل یا مدخل‌های جدول فرآیندها. چنین خطاهایی ممکن است باعث خروج فوری .Nm شوند، احتمالاً در میانهٔ تجزیه یا قالب‌بندی یک فایل. .El .Pp توجه داشته باشید که انتخاب حالت خروجی .Fl T Cm lint متضمن .Fl W Cm all است. .Sh "مثال‌ها (EXAMPLES)" برای صفحه‌بندی صفحات راهنما در ترمینال: .Pp .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 .Pp برای تولید صفحات راهنمای HTML با .Pa /usr/share/misc/mandoc.css به عنوان شیوه‌نامه: .Pp .Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html .Pp برای بررسی یک مجموعهٔ بزرگ از صفحات راهنما: .Pp .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga .Pp برای تولید یک سری از صفحات راهنمای PostScript برای کاغذ A4: .Pp .Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 > manuals.ps .Pp تبدیل یک راهنمای مدرن .Xr mdoc 7 به قالب قدیمی‌تر .Xr man 7 ، جهت استفاده در سیستم‌هایی که فاقد تجزیه‌کنندهٔ .Xr mdoc 7 هستند: .Pp .Dl $ mandoc \-T man foo.mdoc > foo.man .Sh "خطاها (DIAGNOSTICS)" پیام‌های نمایش‌داده‌شده توسط .Nm از این قالب پیروی می‌کنند: .Bd -ragged -offset indent .Nm : .Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments .Pq Ar os .Ed .Pp سه بخش اول، نام .Ar file ، شمارهٔ .Ar line و شمارهٔ .Ar column فایل ورودی را که پیام در آن فعال شده است مشخص می‌کنند. شماره‌های خط و ستون از ۱ شروع می‌شوند. هر دو برای پیام‌هایی که به یک فایل ورودی به‌طور کلی اشاره دارند حذف می‌شوند. همهٔ رشته‌های .Ar level و .Ar message در ادامه توضیح داده شده‌اند. نام .Ar macro ایجادکنندهٔ پیام و .Ar arguments آن در جایی که بی‌معنی باشند حذف می‌شوند. مشخص‌کنندهٔ سیستم‌عامل .Pq Ar os برای پیام‌هایی که مربوط به همهٔ سیستم‌های عامل هستند حذف می‌شود. پیام‌های مهلک دربارهٔ آرگومان‌های نامعتبر خط فرمان یا خطاهای سیستم‌عامل، برای نمونه زمانی که حافظه تمام شده است، ممکن است بخش‌های .Ar file و .Ar level را نیز حذف کنند. .Pp سطوح پیام دارای معانی زیر هستند: .Bl -tag -width "warning" .It Cm syserr یک خطای سیستم‌عامل رخ داده است. الزاماً مشکلی در فایل‌های ورودی وجود ندارد. با این وجود ممکن است خروجی ناقص یا از دست رفته باشد. .It Cm badarg آرگومان‌های نامعتبر خط فرمان مشخص شده‌اند. هیچ فایل ورودی خوانده نشده و خروجی تولید نمی‌شود. .It Cm unsupp یک فایل ورودی از ویژگی‌های سطح پایین و پشتیبانی‌نشدهٔ .Xr roff 7 استفاده می‌کند. خروجی ممکن است ناقص و/یا بدقالب‌بندی‌شده باشد، بنابراین استفاده از GNU troff به‌جای .Nm برای پردازش فایل ترجیح داده می‌شود. .It Cm error نشان‌دهندهٔ خطر از دست رفتن اطلاعات یا قالب‌بندی به شدت ناقص است که در بیشتر موارد به دلیل خطاهای نحوی جدی ایجاد می‌شود. .It Cm warning نشان‌دهندهٔ این احتمال است که اطلاعات نمایش‌داده‌شده یا قالب‌بندی آن ممکن است به شکل جزئی با قصد نویسنده مغایرت داشته باشد. علاوه بر این، خطاهای نحوی حداقل به عنوان هشدار دسته‌بندی می‌شوند، حتی اگر معمولاً باعث خرابی قالب‌بندی نشوند. .It Cm style یک فایل ورودی از سبک مشکوک یا نامناسب استفاده می‌کند. این یک ایراد نحوی نیست، و احتمالاً نه قالب‌بندی و نه قابلیت انتقال به خطر نمی‌افتند. در حالی که دقت زیادی به خرج داده می‌شود تا در سطوح پیام بالاتر از موارد مثبت کاذب جلوگیری شود، سطح .Cm style تلاش می‌کند احتمال نادیده ماندن مسائل را کاهش دهد، بنابراین ممکن است گاهی پیشنهادهای نادرست ارائه دهد. لطفاً از قضاوت درست خود برای تصمیم‌گیری در مورد اینکه آیا یک پیشنهاد خاص .Cm style واقعاً تغییر در فایل ورودی را توجیه می‌کند یا خیر، استفاده کنید. .It Cm base قراردادی که در سیستم پایهٔ یک سیستم‌عامل خاص استفاده می‌شود، رعایت نشده است. این‌ها اشتباهات نشانه‌گذاری نیستند، و نه کیفیت قالب‌بندی و نه قابلیت حمل در خطر نیستند. پیام‌های سطح .Cm base با برچسب شهودی‌ترِ سطحِ .Cm style چاپ می‌شوند. .El .Pp پیام‌های سطوح .Cm base ، .Cm style ، .Cm warning ، .Cm error و .Cm unsupp پنهان هستند مگر اینکه سطح آن‌ها، یا سطحی پایین‌تر، با استفاده از گزینهٔ .Fl W یا حالت خروجی .Fl T Cm lint درخواست شده باشد. .Pp همان‌طور که در ادامه اشاره شده است، تمام بررسی‌های .Cm base و برخی از بررسی‌های .Cm style تنها در صورتی انجام می‌شوند که یک نام سیستم‌عامل خاص در آرگومان‌های گزینهٔ خط فرمان .Fl W ، ماکروی .Ic \&Os ، گزینهٔ خط فرمان .Fl Ios یا در صورت عدم وجود هیچ‌یک، در مقدار بازگشتی تابع .Xr uname 3 وجود داشته باشد. .Ss "قواعد برای صفحه‌های راهنمای سیستم پایه" .Bl -ohang .It Sy "Mdocdate found" .Pq mdoc , Nx ماکروی .Ic \&Dd از جایگزینی کلیدواژهٔ CVS .Ic Mdocdate استفاده می‌کند که توسط سیستم پایهٔ .Nx پشتیبانی نمی‌شود. در عوض استفاده از قالب مرسوم .Dq "Month dd, yyyy" را در نظر بگیرید. .It Sy "Mdocdate missing" .Pq mdoc , Ox ماکروی .Ic \&Dd از جایگزینی کلیدواژهٔ CVS .Ic Mdocdate استفاده نمی‌کند، اما استفاده از آن در سیستم پایهٔ .Ox به‌طور سنتی مورد انتظار است. .It Sy "unknown architecture" .Pq mdoc , Ox , Nx آرگومان سوم ماکروی .Ic \&Dt با هیچ‌یک از معماری‌هایی که این سیستم‌عامل روی آن‌ها اجرا می‌شود مطابقت ندارد. .It Sy "operating system explicitly specified" .Pq mdoc , Ox , Nx ماکروی .Ic \&Os دارای آرگومان است. در سیستم پایه، این ماکرو طبق سنت خالی رها می‌شود. .It Sy "RCS id missing" .Pq Ox , Nx صفحهٔ راهنما فاقد خط توضیحی با شناسهٔ RCS تولیدشده توسط جایگزینی کلیدواژهٔ CVS .Ic OpenBSD یا .Ic NetBSD است که طبق سنت در این سیستم‌های عامل استفاده می‌شود. .El .Ss "پیشنهادهای نگارشی (Style suggestions)" .Bl -ohang .It Sy "legacy man(7) date format" .Pq mdoc ماکروی .Ic \&Dd از قالب تاریخ قدیمی .Xr man 7 به شکل .Dq yyyy-dd-mm استفاده می‌کند. در عوض استفاده از قالب تاریخ مرسوم .Xr mdoc 7 به شکل .Dq "Month dd, yyyy" را در نظر بگیرید. .It Sy "normalizing date format to" : No ... .Pq mdoc , man ماکروی .Ic \&Dd یا .Ic \&TH یک نام اختصاری ماه یا شمارهٔ روز با صفر اولیه ارائه می‌دهد. در خروجی قالب‌بندی‌شده، نام ماه به‌طور کامل نوشته شده و صفر اولیه حذف می‌شود. .It Sy "lower case character in document title" .Pq mdoc , man عنوان همچنان همان‌طور که در ماکروی .Ic \&Dt یا .Ic \&TH داده شده استفاده می‌شود. .It Sy "duplicate RCS id" یک صفحهٔ راهنما شامل دو رونوشت از شناسهٔ RCS برای یک سیستم‌عامل است. حذف نمونهٔ بعدی و انتقال اولین مورد به بالای صفحه را در نظر بگیرید. .It Sy "possible typo in section name" .Pq mdoc تطبیق فازی رشته نشان داد که آرگومان یک ماکروی .Ic \&Sh مشابه، اما نه کاملاً یکسان با نام یک بخش استاندارد است. .It Sy "unterminated quoted argument" .Pq roff آرگومان‌های ماکرو را می‌توان در نویسه‌های نقل‌قول دوگانه محصور کرد تا نیازی به گریز دادن نویسه‌های فاصله و نام‌های ماکرو در آرگومان نباشد. گیومهٔ پایانی آخرین آرگومان یک ماکرو را می‌توان حذف کرد. با این حال، حذف آن توصیه نمی‌شود زیرا خوانایی کد را دشوارتر می‌کند. .It Sy "useless macro" .Pq mdoc یک ماکروی .Ic \&Bt ، .Ic \&Tn یا .Ic \&Ud یافت شد. به‌سادگی آن را حذف کنید؛ هیچ کاربرد مفیدی ندارد. .It Sy "consider using OS macro" .Pq mdoc رشته‌ای در متن ساده یا در یک ماکروی .Ic \&Bx یافت شد که می‌تواند با استفاده از .Ic \&Ox ، .Ic \&Nx ، .Ic \&Fx یا .Ic \&Dx نمایش داده شود. .It Sy "errnos out of order" .Pq mdoc, Nx موارد .Ic \&Er در فهرست .Ic \&Bl ترتیب الفبایی ندارند. .It Sy "duplicate errno" .Pq mdoc, Nx یک فهرست .Ic \&Bl شامل دو مدخل متوالی .Ic \&It است که یک شمارهٔ .Ic \&Er یکسان را توصیف می‌کنند. .It Sy "referenced manual not found" .Pq mdoc یک ماکروی .Ic \&Xr به صفحهٔ راهنمایی ارجاع می‌دهد که پیدا نشد. هنگام اجرا با .Fl W Cm base ، جستجو به سیستم پایه محدود می‌شود، به‌طور پیش‌فرض به .Pa /usr/share/man : Ns Pa /usr/X11R6/man . این مسیر را می‌توان در زمان کامپایل با استفاده از ماکروی پیش‌پردازندهٔ .Dv MANPATH_BASE پیکربندی کرد. هنگام اجرا با .Fl W Cm style ، جستجو در امتداد کل مسیر جستجو طبق توضیحات صفحهٔ راهنمای .Xr man 1 انجام می‌شود، با رعایت گزینه‌های خط فرمان .Fl m و .Fl M ، متغیر محیطی .Ev MANPATH و فایل .Xr man.conf 5 و بازگشت به مسیر پیش‌فرض .Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man ، که در زمان کامپایل با استفاده از ماکروی پیش‌پردازندهٔ .Dv MANPATH_DEFAULT نیز قابل پیکربندی است. .It Sy "trailing delimiter" .Pq mdoc آخرین آرگومان یک ماکروی .Ic \&Ex ، \&Fo ، \&Nd ، \&Nm ، \&Os ، \&Sh ، \&Ss ، \&St یا .Ic \&Sx به یک جداکنندهٔ پایانی ختم می‌شود. این معمولاً نگارش بدی است و اغلب نشان‌دهندهٔ غلط املایی است. به احتمال زیاد می‌توان جداکننده را حذف کرد. .It Sy "no blank before trailing delimiter" .Pq mdoc آخرین آرگومان ماکرویی که از آرگومان‌های جداکنندهٔ پایانی پشتیبانی می‌کند، طولانی‌تر از یک بایت است و به یک جداکنندهٔ پایانی ختم می‌شود. درج یک فاصله را در نظر بگیرید تا جداکننده به یک آرگومان جداگانه تبدیل شود، و بدین ترتیب از دامنهٔ ماکرو خارج شود. .It Sy "fill mode already enabled, skipping" .Pq man درخواست .Ic \&fi رخ داده در حالی که سند هنوز در حالت پر کردن است، یا پیش‌تر به حالت پر کردن بازگشته است. این هیچ اثری ندارد. .It Sy "fill mode already disabled, skipping" .Pq man درخواست .Ic \&nf رخ داده در حالی که سند پیش‌تر به حالت بدون پر کردن تغییر کرده و هنوز به حالت پر کردن بازنگشته است. این هیچ اثری ندارد. .It Sy "input text line longer than 80 bytes" شکستن خط متن ورودی را در یکی از نویسه‌های فاصله قبل از ستون ۸۰ در نظر بگیرید. .It Sy "verbatim \(dq--\(dq, maybe consider using \e(em" .Pq mdoc اگرچه دستگاه خروجی ASCII خط تیرهٔ پیوسته (em-dash) را به‌صورت .Qq \-\- نمایش می‌دهد، اما این روش مناسبی برای نوشتن آن در فایل ورودی نیست زیرا در تمام دستگاه‌های خروجی دیگر ظاهر نامناسبی پیدا می‌کند. .It Sy "function name without markup" .Pq mdoc کلمه‌ای که به دنبال آن یک جفت پرانتز خالی قرار دارد در یک خط متن دیده شده است. استفاده از ماکروی .Ic \&Fn یا .Ic \&Xr را در نظر بگیرید. .It Sy "whitespace at end of input line" .Pq mdoc , man , roff فاصله‌های خالی در پایان خطوط ورودی تقریباً هرگز اهمیت معنایی ندارند \(em اما در موارد نادری که اهمیت داشته باشند، هنگام بازبینی و نگهداری اسناد بسیار گیج‌کننده خواهند بود. .It Sy "bad comment style" .Pq roff خطوط توضیحات با یک نقطه، یک ممیز وارونه و یک نویسهٔ نقل‌قول دوگانه شروع می‌شوند. ابزار .Nm خط را حتی بدون ممیز وارونه به عنوان خط توضیحات در نظر می‌گیرد، اما حذف ممیز وارونه ممکن است با سایر ابزارها سازگار نباشد. .El .Ss "هشدارهای مربوط به مقدمه سند (Prologue)" .Bl -ohang .It Sy "missing manual title, using UNTITLED" .Pq mdoc یک ماکروی .Ic \&Dt هیچ آرگومانی ندارد، یا هیچ ماکروی .Ic \&Dt پیش از اولین ماکروی غیر مقدماتی وجود ندارد. .It Sy "missing manual title, using \(dq\(dq" .Pq man هیچ ماکروی .Ic \&TH وجود ندارد، یا آرگومانی ندارد. .It Sy "missing manual section, using \(dq\(dq" .Pq mdoc , man یک ماکروی .Ic \&Dt یا .Ic \&TH فاقد آرگومان اجباری بخش است. .It Sy "unknown manual section" .Pq mdoc شمارهٔ بخش در یک خط .Ic \&Dt نامعتبر است، اما همچنان استفاده می‌شود. .It Sy "filename/section mismatch" .Pq mdoc , man نام فایل ورودیِ در حال پردازش مشخص است و پسوند نام فایل آن با یک رقم غیر صفر شروع می‌شود، اما ماکروی .Ic \&Dt یا .Ic \&TH شامل آرگومان .Ar section است که با رقم غیر صفر متفاوتی شروع می‌شود. آرگومان .Ar section به همان صورتی که داده شده استفاده می‌شود. بررسی اینکه آیا نام فایل یا آرگومان نیاز به اصلاح دارند را در نظر بگیرید. .It Sy "missing date, using \(dq\(dq" .Pq mdoc, man سند به عنوان .Xr mdoc 7 تجزیه شده و فاقد ماکروی .Ic \&Dd است، یا ماکروی .Ic \&Dd هیچ آرگومانی ندارد یا فقط آرگومان‌های خالی دارد؛ یا سند به عنوان .Xr man 7 تجزیه شده و فاقد ماکروی .Ic \&TH است، یا ماکروی .Ic \&TH کمتر از سه آرگومان دارد یا آرگومان سوم آن خالی است. .It Sy "cannot parse date, using it verbatim" .Pq mdoc , man تاریخ ارائه‌شده در ماکروی .Ic \&Dd یا .Ic \&TH از قالب مرسوم پیروی نمی‌کند. .It Sy "date in the future, using it anyway" .Pq mdoc , man تاریخ داده‌شده در ماکروی .Ic \&Dd یا .Ic \&TH بیش از یک روز جلوتر از زمان فعلی سیستم .Xr time 3 است. .It Sy "missing Os macro, using \(dq\(dq" .Pq mdoc سیستم پیش‌فرض یا فعلی در این مورد نشان داده نمی‌شود. .It Sy "late prologue macro" .Pq mdoc یک ماکروی .Ic \&Dd یا .Ic \&Os پس از ماکرویی غیر از ماکروهای مقدمه رخ می‌دهد، اما همچنان اعمال می‌شود. .It Sy "prologue macros out of order" .Pq mdoc ماکروهای مقدمه با ترتیب سنتی .Ic \&Dd ، .Ic \&Dt ، .Ic \&Os ارائه نشده‌اند. هر سه ماکرو حتی زمانی که با ترتیب متفاوتی ارائه شوند اعمال می‌گردند. .El .Ss "هشدارهای مربوط به ساختار سند" .Bl -ohang .It Sy ".so is fragile, better use ln(1)" .Pq roff گنجاندن فایل‌ها تنها زمانی کار می‌کند که برنامهٔ تجزیه‌کننده با دایرکتوری کاری جاریِ صحیح اجرا شود. .It Sy "no document body" .Pq mdoc , man بدنهٔ سند شامل هیچ متن یا ماکرویی نیست. یک سند خالی متشکل از تنها یک خط سرایند و یک خط پاورقی نمایش داده می‌شود. .It Sy "content before first section header" .Pq mdoc , man برخی ماکروها یا متن‌ها پیش از اولین سرآیند بخش .Ic \&Sh یا .Ic \&SH قرار گرفته‌اند. ماکروها و متن‌های خطاکار تجزیه شده و در بالاترین سطح درخت نحو، خارج از هر بلوک بخشی اضافه می‌شوند. .It Sy "first section is not NAME" .Pq mdoc آرگومان اولین ماکروی .Ic \&Sh برابر با .Sq NAME نیست. این ممکن است .Xr makewhatis 8 و .Xr apropos 1 را دچار سردرگمی کند. .It Sy "NAME section without Nm before Nd" .Pq mdoc بخش NAME شامل هیچ ماکروی فرزند .Ic \&Nm پیش از اولین ماکروی .Ic \&Nd نیست. .It Sy "NAME section without description" .Pq mdoc بخش NAME فاقد ماکروی اجباری فرزند .Ic \&Nd است. .It Sy "description not at the end of NAME" .Pq mdoc بخش NAME شامل یک ماکروی فرزند .Ic \&Nd است، اما محتوای دیگری پس از آن آمده است. .It Sy "bad NAME section content" .Pq mdoc بخش NAME شامل متن ساده یا ماکروهایی به غیر از .Ic \&Nm و .Ic \&Nd است. .It Sy "missing comma before name" .Pq mdoc بخش NAME شامل یک ماکروی .Ic \&Nm است که نه اولین مورد است و نه کاما پیش از آن آمده است. .It Sy "missing description line, using \(dq\(dq" .Pq mdoc ماکروی .Ic \&Nd فاقد آرگومان لازم است. خط عنوان صفحهٔ راهنما پس از خط تیره به پایان می‌رسد. .It Sy "description line outside NAME section" .Pq mdoc یک ماکروی .Ic \&Nd خارج از بخش NAME ظاهر شده است. آرگومان‌ها به هر حال چاپ می‌شوند و متن بعدی برای .Xr apropos 1 استفاده می‌شود، اما هیچ‌یک از این رفتارها قابل انتقال نیستند. .It Sy "sections out of conventional order" .Pq mdoc یک بخش استاندارد بعد از بخش دیگری که معمولاً پیش از آن قرار می‌گیرد، واقع شده است. همهٔ عناوین بخش‌ها همان‌طور که داده شده‌اند استفاده می‌شوند، و ترتیب بخش‌ها تغییر نمی‌کند. .It Sy "duplicate section title" .Pq mdoc یک عنوان بخش استاندارد بیش از یک بار ظاهر شده است. .It Sy "unexpected section" .Pq mdoc یک سرآیند بخش استاندارد در بخشی از راهنما ظاهر شده که معمولاً در آنجا کاربردی ندارد. .It Sy "cross reference to self" .Pq mdoc یک ماکروی .Ic \&Xr به نام و بخشی اشاره دارد که با بخش صفحهٔ راهنمای فعلی و نام ذکرشده در ماکروی .Ic \&Nm در بخش NAME یا SYNOPSIS، یا در ماکروی .Ic \&Fn یا .Ic \&Fo در SYNOPSIS مطابقت دارد. استفاده از .Ic \&Nm یا .Ic \&Fn به‌جای .Ic \&Xr را در نظر بگیرید. .It Sy "unusual Xr order" .Pq mdoc در بخش SEE ALSO، یک ماکروی .Ic \&Xr با شمارهٔ بخش پایین‌تر پس از ماکرویی با شمارهٔ بالاتر آمده است، یا دو ماکروی .Ic \&Xr که به یک بخش اشاره دارند ترتیب الفبایی ندارند. .It Sy "unusual Xr punctuation" .Pq mdoc در بخش SEE ALSO، نشانه‌گذاری بین دو ماکروی .Ic \&Xr چیزی به جز یک کامای تنها است، یا بعد از آخرین ماکروی .Ic \&Xr نشانه‌گذاری اضافی وجود دارد. .It Sy "AUTHORS section without An macro" .Pq mdoc یک بخش AUTHORS فاقد ماکروهای .Ic \&An ، یا شامل ماکروهای خالی است. احتمالاً نام‌های نویسندگانی وجود دارد که فاقد نشانه‌گذاری هستند. .El .Ss "هشدارهای مربوط به ماکروها و تو در تویی" .Bl -ohang .It Sy "obsolete macro" .Pq mdoc برای جایگزین‌ها به راهنمای .Xr mdoc 7 مراجعه کنید. .It Sy "macro neither callable nor escaped" .Pq mdoc نام ماکرویی که قابل فراخوانی نیست در یک خط ماکرو ظاهر شده است. به‌صورت کلمه‌به‌کلمه چاپ می‌شود. اگر هدف فراخوانی آن است، آن را به خط ورودی خودش منتقل کنید؛ در غیر این صورت با قرار دادن .Sq \e& در ابتدای آن، آن را بگریزانید. .It Sy "skipping paragraph macro" در اسناد .Xr mdoc 7 ، این وضعیت در این موارد رخ می‌دهد: .Bl -dash -compact .It در ابتدا و انتهای بخش‌ها و زیربخش‌ها .It دقیقاً پیش از فهرست‌ها و نماهای غیر فشرده .It در انتهای موارد در فهرست‌های غیر ستونی و غیر فشرده .It و برای چندین ماکروی پاراگراف متوالی. .El در اسناد .Xr man 7 ، این وضعیت در این موارد رخ می‌دهد: .Bl -dash -compact .It برای ماکروهای خالیِ .Ic \&P ، .Ic \&PP و .Ic \&LP .It برای ماکروهای .Ic \&IP که نه آرگومان سرآیند دارند و نه بدنه .It برای .Ic \&br یا .Ic \&sp دقیقاً پس از .Ic \&SH یا .Ic \&SS .El .It Sy "moving paragraph macro out of list" .Pq mdoc یک مورد در یک فهرست .Ic \&Bl شامل یک ماکروی پاراگراف پایانی است. ماکروی پاراگراف به بعد از انتهای فهرست منتقل می‌شود. .It Sy "skipping no-space macro" .Pq mdoc یک خط ورودی با یک ماکروی .Ic \&Ns شروع می‌شود، یا آرگومان بعدی بعد از ماکروی .Ic \&Ns یک جداکنندهٔ پایانی تنها است. ماکرو نادیده گرفته می‌شود. .It Sy "blocks badly nested" .Pq mdoc اگر دو بلوک با یکدیگر همپوشانی دارند، یکی باید کاملاً دیگری را در بر بگیرد. در غیر این صورت، خروجی تولیدشده در هر قالب خروجی احتمالاً عجیب به نظر خواهد رسید، و رندر در قالب‌های خروجی مبتنی بر SGML احتمالاً کاملاً نادرست خواهد بود زیرا چنین زبان‌هایی به هیچ وجه از بلوک‌های بد تو در تو پشتیبانی نمی‌کنند. نمونه‌های معمول از بلوک‌های بد تو در تو عبارتند از .Qq Ic \&Ao \&Bo \&Ac \&Bc و .Qq Ic \&Ao \&Bq \&Ac . در این مثال‌ها، .Ic \&Ac به ترتیب باعث شکستن .Ic \&Bo و .Ic \&Bq می‌شود. .It Sy "nested displays are not portable" .Pq mdoc یک نمای .Ic \&Bd ، .Ic \&D1 یا .Ic \&Dl به‌صورت تو در تو درون نمای .Ic \&Bd دیگری قرار گرفته است. این کار در .Nm کار می‌کند، اما در اکثر پیاده‌سازی‌های دیگر با شکست مواجه می‌شود. .It Sy "moving content out of list" .Pq mdoc یک بلوک فهرست .Ic \&Bl پیش از اولین ماکروی .Ic \&It شامل متن یا ماکرو است. فرزندان خطاکار به پیش از آغاز فهرست منتقل می‌شوند. .It Sy "first macro on line" درون یک فهرست .Ic \&Bl Fl column ، ماکروی .Ic \&Ta به عنوان اولین ماکرو در یک خط ظاهر شده است که رفتاری غیر قابل حمل است. .It Sy "line scope broken" .Pq man هنگام تجزیهٔ دامنهٔ خط بعدی ماکروی قبلی، ماکروی دیگری پیدا می‌شود که ماکروی قبلی را پیش از موعد خاتمه می‌دهد. ماکروی قطع‌شدهٔ قبلی از درخت تجزیه حذف می‌شود. .El .Ss "هشدارهای مربوط به آرگومان‌های گمشده" .Bl -ohang .It Sy "skipping empty request" .Pq roff , eqn نام ماکرو از درخواست تعریف ماکرو جا افتاده است، یا یک عبارت کنترلی یا کلیدواژهٔ عملیاتی در .Xr eqn 7 فاقد آرگومان لازم است. .It Sy "conditional request controls empty scope" .Pq roff یک درخواست شرطی تنها زمانی مفید است که یکی از موارد زیر در همان خط ورودی منطقی به دنبال آن بیاید: .Bl -dash -compact .It کلیدواژهٔ .Sq \e{ برای باز کردن یک دامنهٔ چندخطی. .It یک درخواست یا ماکرو یا مقداری متن، که منجر به یک دامنهٔ تک‌خطی می‌شود. .It پایان فوری خط منطقی بدون هرگونه فاصلهٔ خالی، که منجر به دامنهٔ خط بعدی می‌شود. .El در اینجا، یک درخواست شرطی فقط با فاصله‌های انتهایی همراه شده است و محتوای دیگری در خط ورودی منطقی آن وجود ندارد. توجه داشته باشید که فرقی نمی‌کند خط ورودی منطقی با نویسهٔ ادامهٔ خط .Sq \e به چندین خط ورودی فیزیکی تقسیم شده باشد یا خیر. این یکی از موارد نادری است که در آن فاصلهٔ خالی انتهایی از نظر نحوی اهمیت دارد. درخواست شرطی دامنه‌ای را کنترل می‌کند که تنها شامل فاصله‌های خالی است، بنابراین بعید است که تأثیر قابل توجهی داشته باشد، مگر اینکه یک بندِ بعدیِ .Ic \&el را کنترل کند. .It Sy "skipping empty macro" .Pq mdoc ماکروی مشخص‌شده هیچ آرگومانی ندارد و بنابراین اثری نخواهد داشت. .It Sy "empty block" .Pq mdoc , man یک بلوک .Ic \&Bd ، .Ic \&Bk ، .Ic \&Bl ، .Ic \&D1 ، .Ic \&Dl ، .Ic \&MT ، .Ic \&RS یا .Ic \&UR در بدنهٔ خود شامل هیچ چیزی نیست و خروجی تولید نخواهد کرد. .It Sy "empty argument, using 0n" .Pq mdoc پهنای مورد نیاز بعد از .Fl offset یا .Fl width در .Ic \&Bd یا .Ic \&Bl جا افتاده است. .It Sy "missing display type, using -ragged" .Pq mdoc ماکروی .Ic \&Bd بدون نوع نمای مورد نیاز فراخوانی شده است. .It Sy "list type is not the first argument" .Pq mdoc در یک ماکروی .Ic \&Bl ، حداقل یک آرگومان دیگر قبل از آرگومان نوع آمده است. ابزار .Nm با هر ترتیبی از آرگومان‌ها کار می‌کند، اما برخی از پیاده‌سازی‌های دیگر .Xr mdoc 7 چنین قابلیتی ندارند. .It Sy "missing -width in -tag list, using 8n" .Pq mdoc هر ماکروی .Ic \&Bl که آرگومان .Fl tag دارد، به .Fl width نیز نیاز دارد. .It Sy "missing utility name, using \(dq\(dq" .Pq mdoc ماکروی .Ic \&Ex Fl std بدون آرگومان فراخوانی شده در حالی که پیش از آن .Ic \&Nm با یک آرگومان فراخوانی نشده است. .It Sy "missing function name, using \(dq\(dq" .Pq mdoc ماکروی .Ic \&Fo بدون آرگومان فراخوانی شده است. هیچ نام تابعی چاپ نمی‌شود. .It Sy "empty head in list item" .Pq mdoc در یک فهرست .Fl diag ، .Fl hang ، .Fl inset ، .Fl ohang یا .Fl tag از نوع .Ic \&Bl ، یک ماکروی .Ic \&It فاقد آرگومان لازم است. سرآیند مورد خالی گذاشته می‌شود. .It Sy "empty list item" .Pq mdoc در یک فهرست .Fl bullet ، .Fl dash ، .Fl enum یا .Fl hyphen از نوع .Ic \&Bl ، یک بلوک .Ic \&It خالی است. یک مورد فهرست خالی نشان داده می‌شود. .It Sy "missing argument, using next line" .Pq mdoc یک ماکروی .Ic \&It در یک فهرست .Ic \&Bd Fl column هیچ آرگومانی ندارد. در حالی که .Nm از متن یا ماکروهای خط بعدی (در صورت وجود) برای سلول استفاده می‌کند، قالب‌بندهای دیگر ممکن است فهرست را نادرست قالب‌بندی کنند. .It Sy "missing font type, using \efR" .Pq mdoc یک ماکروی .Ic \&Bf هیچ آرگومانی ندارد. به قلم پیش‌فرض تغییر وضعیت می‌دهد. .It Sy "unknown font type, using \efR" .Pq mdoc آرگومان .Ic \&Bf نامعتبر است. به‌جای آن از قلم پیش‌فرض استفاده می‌شود. .It Sy "nothing follows prefix" .Pq mdoc یک ماکروی .Ic \&Pf بدون آرگومان است، یا فقط یک آرگومان دارد و هیچ ماکرویی در همان خط ورودی به دنبال آن نمی‌آید. این کار هدف آن را خنثی می‌کند؛ به‌ویژه، ایجاد فاصله قبل از متن یا ماکروهای موجود در خط ورودی بعدی سرکوب نمی‌شود. .It Sy "empty reference block" .Pq mdoc یک ماکروی .Ic \&Rs بلافاصله با یک ماکروی .Ic \&Re در خط ورودی بعدی دنبال شده است. چنین بلوک خالی هیچ خروجی تولید نمی‌کند. .It Sy "missing section argument" .Pq mdoc یک ماکروی .Ic \&Xr فاقد آرگومان دوم خود، یعنی شمارهٔ بخش است. آرگومان اول، یعنی نام، چاپ می‌شود اما بدون پرانتزهای متعاقب آن. .It Sy "missing -std argument, adding it" .Pq mdoc یک ماکروی .Ic \&Ex یا .Ic \&Rv فاقد آرگومان الزامی .Fl std است. ابزار .Nm حتی زمانی که مشخص نشده باشد، .Fl std را فرض می‌کند، اما ممکن است پیاده‌سازی‌های دیگر چنین نکنند. .It Sy "missing option string, using \(dq\(dq" .Pq man ماکروی .Ic \&OP بدون هیچ آرگومانی فراخوانی شده است. یک جفت قلاب خالی نمایش داده می‌شود. .It Sy "missing resource identifier, using \(dq\(dq" .Pq man ماکروی .Ic \&MT یا .Ic \&UR بدون هیچ آرگومانی فراخوانی شده است. یک جفت علامت کوچکتر/بزرگترِ خالی نمایش داده می‌شود. .It Sy "missing eqn box, using \(dq\(dq" .Pq eqn یک علامت زیروبم یا یک عملگر دوتایی پیدا شده است، اما چیزی در سمت چپ آن وجود ندارد. یک جعبهٔ خالی درج می‌شود. .El .Ss "هشدارهای مربوط به آرگومان‌های نادرست ماکرو" .Bl -ohang .It Sy "duplicate argument" .Pq mdoc یک ماکروی .Ic \&Bd یا .Ic \&Bl دارای بیش از یک آرگومان .Fl compact ، بیش از یک .Fl offset یا بیش از یک .Fl width است. تمام نمونه‌های این آرگومان‌ها به جز آخرین مورد نادیده گرفته می‌شوند. .It Sy "skipping duplicate argument" .Pq mdoc یک ماکروی .Ic \&An دارای بیش از یک آرگومان .Fl split یا .Fl nosplit است. تمام موارد این آرگومان‌ها به جز اولین مورد نادیده گرفته می‌شوند. .It Sy "skipping duplicate display type" .Pq mdoc یک ماکروی .Ic \&Bd بیش از یک آرگومان نوع دارد؛ اولین مورد استفاده می‌شود. .It Sy "skipping duplicate list type" .Pq mdoc یک ماکروی .Ic \&Bl بیش از یک آرگومان نوع دارد؛ اولین مورد استفاده می‌شود. .It Sy "skipping -width argument" .Pq mdoc یک فهرست .Fl column ، .Fl diag ، .Fl ohang ، .Fl inset یا .Fl item از نوع .Ic \&Bl دارای آرگومان .Fl width است. این هیچ اثری ندارد. .It Sy "wrong number of cells" در یک خط از یک فهرست .Ic \&Bl Fl column ، تعداد نویسه‌های تب یا ماکروهای .Ic \&Ta کمتر از تعداد مورد انتظار از خط سرآیند فهرست است یا بیش از یک واحد از تعداد مورد انتظار فراتر رفته است. سلول‌های ناموجود خالی می‌مانند، و تمام سلول‌های فراتر از تعداد ستون‌ها در یک تک سلول ترکیب می‌شوند. .It Sy "unknown AT&T UNIX version" .Pq mdoc یک ماکروی .Ic \&At آرگومان نامعتبر دارد. به‌صورت کلمه‌به‌کلمه با پیشوند .Qq "AT&T UNIX " استفاده می‌شود. .It Sy "comma in function argument" .Pq mdoc یک آرگومان از ماکروی .Ic \&Fa یا .Ic \&Fn شامل یک کاما است؛ احتمالاً باید به دو آرگومان تقسیم شود. .It Sy "parenthesis in function name" .Pq mdoc اولین آرگومان یک ماکروی .Ic \&Fc یا .Ic \&Fn شامل پرانتز باز یا بسته است؛ احتمالاً این اشتباه است زیرا پرانتزها به‌طور خودکار اضافه می‌شوند. .It Sy "unknown library name" .Pq mdoc, not on Ox یک ماکروی .Ic \&Lb دارای آرگومان نام ناشناخته است و به‌صورت .Qq library Dq Ar name نمایش داده می‌شود. .It Sy "invalid content in Rs block" .Pq mdoc یک بلوک .Ic \&Rs شامل متن ساده یا ماکروهای غیر % است. محتوای نامعتبر در درخت نحو باقی می‌ماند. قالب‌بندی ممکن است ناقص باشد. .It Sy "invalid Boolean argument" .Pq mdoc یک ماکروی .Ic \&Sm آرگومانی به غیر از .Cm on یا .Cm off دارد. آرگومان نامعتبر از ماکرو خارج می‌شود که باعث می‌شود ماکرو خالی مانده و حالت فاصله‌گذاری را تغییر دهد. .It Sy "argument contains two font escapes" .Pq roff آرگومان دوم یک درخواست .Ic char شامل بیش از یک توالی گریز قلم است. قلم اشتباه ممکن است پس از استفاده از نویسه فعال بماند. .It Sy "unknown font, skipping request" .Pq man , tbl یک درخواست .Ic \&ft در .Xr roff 7 یا یک اصلاح‌کنندهٔ طرح‌بندی .Ic \&f در .Xr tbl 7 دارای آرگومان .Ar font ناشناخته است. .It Sy "odd number of characters in request" .Pq roff یک درخواست .Ic \&tr شامل تعداد فردی از نویسه‌ها است. آخرین نویسه به نویسهٔ فاصله نگاشت می‌شود. .El .Ss "هشدارهای مربوط به متن خام" .Bl -ohang .It Sy "blank line in fill mode, using .sp" .Pq mdoc معنای خطوط ورودی خالی تنها در حالت بدون پر کردن به‌خوبی تعریف شده است: در حالت پر کردن، شکستگی خطوطِ متن ورودی نباید معنایی داشته باشد. با این حال، برای سازگاری با groff، خطوط خالی در حالت پر کردن مانند درخواست‌های .Ic \&sp قالب‌بندی می‌شوند. برای ایجاد شکستگی پاراگراف، به‌جای خط خالی از .Ic \&Pp استفاده کنید. .It Sy "tab in filled text" .Pq mdoc , man معنای نویسه‌های تب تنها در حالت بدون پر کردن به‌خوبی تعریف شده است: در حالت پر کردن، فاصله‌ها نباید در خطوط ورودی متن معنایی داشته باشند. به عنوان یک انتخاب وابسته به پیاده‌سازی، نویسه‌های تب در خطوط متنی در هر صورت به قالب‌بندها منتقل می‌شوند. با توجه به اینکه متنِ قبل از نویسهٔ تب پر خواهد شد، پیش‌بینی اینکه تب به کدام موقعیت پرشِ تب پیشروی خواهد کرد دشوار است. .It Sy "new sentence, new line" .Pq mdoc یک جملهٔ جدید در میانهٔ یک خط متنی شروع می‌شود. آن را در یک خط ورودی جدید شروع کنید تا به قالب‌بندها کمک کند فاصلهٔ مناسبی ایجاد کنند. .It Sy "invalid escape sequence" .Pq roff یک توالی گریز دارای جداکنندهٔ آغازین نامعتبر برای آرگومان است، فاقد جداکنندهٔ پایانی آرگومان است، آرگومان قالب نامعتبر دارد، یا یک توالی گریز نویسه با نام نامعتبر است. اگر آرگومان ناقص باشد، .Ic \e* و .Ic \en به یک رشتهٔ خالی منبسط می‌شوند، .Ic \eB به رقم .Sq 0 و .Ic \ew به طول آرگومان ناقص بسط می‌یابد. همهٔ توالی‌های گریز نامعتبر دیگر نادیده گرفته می‌شوند. .It Sy "undefined escape, printing literally" .Pq roff در یک توالی گریز، اولین نویسه دقیقاً پس از ممیز وارونهٔ ابتدایی نامعتبر است. آن نویسه به‌صورت لفظی چاپ می‌شود که معادل نادیده گرفتن ممیز وارونه است. .It Sy "undefined string, using \(dq\(dq" .Pq roff اگر رشته‌ای بدون تعریف قبلی استفاده شود، مقدار آن به‌طور ضمنی روی رشتهٔ خالی تنظیم می‌شود. با این حال، تعریف صریح رشته‌ها قبل از استفاده، کد را خواناتر نگه می‌دارد. .El .Ss "هشدارهای مربوط به جدول‌ها" .Bl -ohang .It Sy "tbl line starts with span" .Pq tbl اولین سلول در یک خط طرح‌بندی جدول یک گسترش افقی است .Pq Sq Cm s . داده‌های ارائه‌شده برای این سلول نادیده گرفته شده و چیزی در سلول چاپ نمی‌شود. .It Sy "tbl column starts with span" .Pq tbl اولین خط از مشخصات طرح‌بندی جدول یک گسترش عمودی را درخواست می‌کند .Pq Sq Cm ^ . داده‌های ارائه‌شده برای این سلول نادیده گرفته شده و چیزی در سلول چاپ نمی‌شود. .It Sy "skipping vertical bar in tbl layout" .Pq tbl مشخصات طرح‌بندی جدول شامل بیش از دو خط عمودی متوالی است. یک خط عمودی دوگانه چاپ می‌شود و خطوط اضافی دور ریخته می‌شوند. .El .Ss "خطاهای مربوط به جدول‌ها" .Bl -ohang .It Sy "non-alphabetic character in tbl options" .Pq tbl خط گزینه‌های جدول حاوی نویسه‌ای به غیر از حرف، فاصله یا کاما در جایی است که انتظار می‌رود نام گزینه شروع شود. نویسه نادیده گرفته می‌شود. .It Sy "skipping unknown tbl option" .Pq tbl خط گزینه‌های جدول شامل رشته‌ای از حروف است که با هیچ نام گزینهٔ شناخته‌شده‌ای مطابقت ندارد. کلمه نادیده گرفته می‌شود. .It Sy "missing tbl option argument" .Pq tbl یک گزینهٔ جدول که نیاز به آرگومان دارد با پرانتز باز دنبال نشده است، یا پرانتز باز بلافاصله با پرانتز بسته دنبال شده است. گزینه نادیده گرفته می‌شود. .It Sy "wrong tbl option argument size" .Pq tbl آرگومان گزینهٔ جدول شامل تعداد نویسه‌های نامعتبر است. هم گزینه و هم آرگومان نادیده گرفته می‌شوند. .It Sy "empty tbl layout" .Pq tbl مشخصات طرح‌بندی جدول کاملاً خالی است و صفر خط و صفر ستون را مشخص می‌کند. به عنوان پیش‌فرض جایگزین، یک تک ستون تراز چپ استفاده می‌شود. .It Sy "invalid character in tbl layout" .Pq tbl مشخصات طرح‌بندی جدول شامل نویسه‌ای است که نه می‌تواند به عنوان کلید طرح‌بندی و نه به عنوان اصلاح‌کنندهٔ طرح‌بندی تفسیر شود، یا یک اصلاح‌کننده قبل از اولین کلید آمده است. نویسهٔ نامعتبر دور ریخته می‌شود. .It Sy "unmatched parenthesis in tbl layout" .Pq tbl مشخصات طرح‌بندی جدول شامل پرانتز باز است، اما پرانتز بستهٔ منطبق ندارد. بقیهٔ خط ورودی، شروع از پرانتز، اثری ندارد. .It Sy "ignoring excessive spacing in tbl layout" .Pq tbl یک اصلاح‌کنندهٔ فاصله‌گذاری در طرح‌بندی جدول به‌طور نامعقولی بزرگ است. به‌جای آن از فاصله‌گذاری پیش‌فرض 3n استفاده می‌شود. .It Sy "tbl without any data cells" .Pq tbl یک جدول شامل هیچ سلول داده‌ای نیست. احتمالاً خروجی تولید نخواهد کرد. .It Sy "ignoring data in spanned tbl cell" .Pq tbl یک سلول جدول به عنوان گسترش افقی .Pq Sq Cm s یا گسترش عمودی .Pq Sq Cm ^ در طرح‌بندی جدول علامت‌گذاری شده است، اما حاوی داده است. داده نادیده گرفته می‌شود. .It Sy "ignoring extra tbl data cells" .Pq tbl یک خط داده شامل سلول‌های بیشتری نسبت به خط طرح‌بندی متناظر است. داده‌های موجود در سلول‌های اضافی نادیده گرفته می‌شوند. .It Sy "data block open at end of tbl" .Pq tbl یک بلوک داده با .Cm T{ باز شده، اما هرگز با .Cm T} منطبق بسته نشده است. خطوط دادهٔ باقی‌مانده از جدول همگی در یک سلول قرار می‌گیرند و هر سلول باقی‌مانده خالی می‌ماند. .El .Ss "خطاهای مربوط به کدهای roff، mdoc و man" .Bl -ohang .It Sy "duplicate prologue macro" .Pq mdoc یکی از ماکروهای مقدمه بیش از یک بار رخ داده است. آخرین مورد، همهٔ موارد قبلی را بازنویسی می‌کند. .It Sy "skipping late title macro" .Pq mdoc ماکروی .Ic \&Dt بعد از اولین ماکروی غیر مقدماتی ظاهر شده است. قالب‌بندهای سنتی نمی‌توانند این مورد را مدیریت کنند زیرا سرآیند صفحه را قبل از تجزیهٔ بدنهٔ سند می‌نویسند. اگرچه این محدودیت فنی در مورد .Nm صدق نمی‌کند، معناشناسی سنتی حفظ می‌شود. ماکروی دیرهنگام به همراه آرگومان‌هایش دور ریخته می‌شود. .It Sy "input stack limit exceeded, infinite loop?" .Pq roff محدودیت‌های صریح بازگشتی برای قابلیت‌های زیر پیاده‌سازی شده‌اند تا از حلقه‌های نامتناهی جلوگیری شود: .Bl -dash -compact .It بسط توالی‌های گریز تو در تو از جمله بسط رشته‌ها و ثبات‌های عددی، .It بسط ماکروهای تعریف‌شده توسط کاربر تو در تو، .It و گنجاندن فایل با .Ic \&so . .El هنگامی که به این محدودیت برخورد می‌شود، خروجی نادرست خواهد بود و معمولاً بخشی از محتوا از دست می‌رود، اما تجزیه‌کننده می‌تواند ادامه دهد. .It Sy "skipping bad character" .Pq mdoc , man , roff فایل ورودی شامل بایتی است که نویسهٔ قابل چاپ .Xr ascii 7 نیست. پیام به شمارهٔ نویسه اشاره می‌کند. بایت خطاکار با یک علامت سوال .Pq Sq \&? جایگزین می‌شود. ویرایش فایل ورودی برای جایگزینی بایت با برگردان ASCII نویسهٔ مورد نظر را در نظر بگیرید. .It Sy "skipping unknown macro" .Pq mdoc , man , roff اولین شناسه در خط درخواست یا ماکرو نه به عنوان درخواست .Xr roff 7 ، نه به عنوان ماکروی تعریف‌شده توسط کاربر، و نه به عنوان ماکروی .Xr mdoc 7 یا .Xr man 7 شناخته نشده است. ممکن است اشتباه تایپ شده باشد یا پشتیبانی نشود. درخواست یا ماکرو به همراه آرگومان‌هایش دور ریخته می‌شود. .It Sy "skipping request outside macro" .Pq roff یک درخواست .Ic shift یا .Ic return خارج از هرگونه تعریف ماکرو رخ داده است و اثری ندارد. .It Sy "skipping insecure request" .Pq roff یک فایل ورودی تلاش کرده دستوری در شل اجرا کند یا فایلی خارجی را بخواند یا بنویسد. چنین تلاش‌هایی به دلایل امنیتی رد می‌شوند. .It Sy "skipping item outside list" .Pq mdoc , eqn یک ماکروی .Ic \&It خارج از هرگونه فهرست .Ic \&Bl رخ داده است، یا یک جداکنندهٔ .Ic above در .Xr eqn 7 خارج از یک توده رخ داده است. آن ماکرو یا جداکننده به همراه آرگومان‌هایش دور ریخته می‌شود. .It Sy "skipping column outside column list" .Pq mdoc یک ماکروی .Ic \&Ta خارج از هرگونه بلوک .Ic \&Bl Fl column رخ داده است. به همراه آرگومان‌هایش دور ریخته می‌شود. .It Sy "skipping end of block that is not open" .Pq mdoc , man , eqn , tbl , roff عناصر نحوی مختلف فقط می‌توانند برای بستن صریح بلوک‌هایی استفاده شوند که پیش‌تر باز شده‌اند. یک ماکروی بستن بلوک در .Xr mdoc 7 ، یک ماکروی .Ic \&ME ، \&RE یا .Ic \&UE در .Xr man 7 ، یک جداکنندهٔ راست یا آکوالاد بسته در .Xr eqn 7 ، یا پایان یک معادله، جدول، یا درخواست شرطی .Xr roff 7 مشاهده شده در حالی که هیچ بلوک منطبقی باز نیست. درخواست یا ماکروی خطاکار دور ریخته می‌شود. .It Sy "fewer RS blocks open, skipping" .Pq man ماکروی .Ic \&RE با یک آرگومان فراخوانی شده است، اما کمتر از تعداد مشخص‌شده بلوک .Ic \&RS باز است. ماکروی .Ic \&RE دور ریخته می‌شود. .It Sy "inserting missing end of block" .Pq mdoc , tbl ماکروهای مختلف .Xr mdoc 7 و همچنین جدول‌ها نیاز به بستن صریح توسط ماکروهای اختصاصی دارند. بلوکی که از تو در تویی نامعتبر پشتیبانی نمی‌کند، پیش از بسته شدن کامل همهٔ فرزندانش به پایان می‌رسد. گره‌های فرزندِ باز به‌طور ضمنی بسته می‌شوند. .It Sy "appending missing end of block" .Pq mdoc , man , eqn , tbl , roff در پایان سند، یک بلوک صریح .Xr mdoc 7 ، یک دامنهٔ خط بعدی در .Xr man 7 یا بلوک .Ic \&MT ، \&RS یا .Ic \&UR ، یک معادله، جدول، یا یک بلوک شرطی یا نادیده‌گیری .Xr roff 7 همچنان باز است. بلوک باز به‌طور ضمنی بسته می‌شود. .It Sy "escaped character not allowed in a name" .Pq roff شناسه‌های ماکرو، رشته و ثبات از نویسه‌های ASCII قابل چاپ و غیر فاصله تشکیل شده‌اند. توالی‌های گریز و نویسه‌ها و رشته‌هایی که با آن‌ها بیان می‌شوند نمی‌توانند بخشی از یک نام را تشکیل دهند. اولین آرگومان یک درخواست .Ic \&am ، .Ic \&as ، .Ic \&de ، .Ic \&ds ، .Ic \&nr یا .Ic \&rr ، یا هر آرگومان یک درخواست .Ic \&rm ، یا نام یک درخواست یا ماکروی تعریف‌شده توسط کاربر که فراخوانی می‌شود، با یک توالی گریز خاتمه می‌یابد. در موارد .Ic \&as ، .Ic \&ds و .Ic \&nr ، درخواست هیچ اثری ندارد. در موارد .Ic \&am ، .Ic \&de ، .Ic \&rr و .Ic \&rm ، آنچه تا این نقطه تجزیه شده به عنوان آرگومان‌های درخواست استفاده می‌شود و بقیهٔ خط ورودی از جمله توالی گریز دور ریخته می‌شود. هنگام تجزیه برای نام یک درخواست یا ماکروی تعریف‌شده توسط کاربر برای فراخوانی، فقط توالی گریز دور ریخته می‌شود. نویسه‌های پیش از آن به عنوان نام درخواست یا ماکرو استفاده می‌شوند و نویسه‌های پس از آن به عنوان آرگومان‌های درخواست یا ماکرو به کار می‌روند. .It Sy "using macro argument outside macro" .Pq roff توالی گریز \e$ خارج از هرگونه تعریف ماکرو رخ داده و به یک رشتهٔ خالی بسط می‌یابد. .It Sy "argument number is not numeric" .Pq roff آرگومان توالی گریز \e$ یک رقم نیست؛ توالی گریز به رشتهٔ خالی بسط می‌یابد. .It Sy "NOT IMPLEMENTED: Bd -file" .Pq mdoc به دلایل امنیتی، ماکروی .Ic \&Bd از آرگومان .Fl file پشتیبانی نمی‌کند. با درخواست درج یک فایل حساس، یک سند مخرب ممکن است کاربر دارای امتیازات بالا را فریب دهد تا ناخواسته فایل را روی صفحه نمایش دهد و محتوای آن را برای اطرافیان آشکار کند. این آرگومان و نام فایل به دنبال آن نادیده گرفته می‌شوند. .It Sy "skipping display without arguments" .Pq mdoc یک ماکروی بلوک .Ic \&Bd هیچ آرگومانی ندارد. بلوک دور ریخته می‌شود و محتوای بلوک در هر حالتی که قبل از بلوک فعال بوده نمایش داده می‌شود. .It Sy "missing list type, using -item" .Pq mdoc یک ماکروی .Ic \&Bl نوع فهرست را مشخص نکرده است. .It Sy "argument is not numeric, using 1" .Pq roff آرگومان یک درخواست .Ic \&ce یک عدد نیست. .It Sy "argument is not a character" .Pq roff اولین آرگومان یک درخواست .Ic char نه یک نویسهٔ ASCII منفرد است و نه یک توالی گریز تک‌نویسه‌ای. درخواست به همراه تمام آرگومان‌هایش نادیده گرفته می‌شود. .It Sy "missing manual name, using \(dq\(dq" .Pq mdoc اولین فراخوانی .Ic \&Nm ، یا هر فراخوانی در بخش NAME، فاقد آرگومان لازم است. .It Sy "uname(3) system call failed, using UNKNOWN" .Pq mdoc ماکروی .Ic \&Os بدون آرگومان فراخوانی شده و فراخوانی سیستمی .Xr uname 3 شکست خورده است. به عنوان راه حل، .Nm می‌تواند با .Sm off .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .Sm on کامپایل شود. .It Sy "unknown standard specifier" .Pq mdoc یک ماکروی .Ic \&St دارای آرگومان ناشناخته است و دور ریخته می‌شود. .It Sy "skipping request without numeric argument" .Pq roff , eqn یک درخواست .Ic \&it یا عبارت .Ic \&size یا .Ic \&gsize در .Xr eqn 7 دارای آرگومان غیر عددی یا منفی است یا اصلاً آرگومانی ندارد. درخواست یا عبارت نامعتبر نادیده گرفته می‌شود. .It Sy "excessive shift" .Pq roff آرگومان یک درخواست .Ic shift بزرگتر از تعداد آرگومان‌های ماکرویی است که در حال حاضر اجرا می‌شود. همهٔ آرگومان‌های ماکرو حذف شده و \en(.$ روی صفر تنظیم می‌شود. .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" .Pq roff به دلایل امنیتی، .Nm درخواست‌های گنجاندن فایل با .Ic \&so را تنها با مسیرهای نسبی و فقط بدون صعود به دایرکتوری والد مجاز می‌داند. با درخواست درج یک فایل حساس، یک سند مخرب ممکن است کاربر دارای امتیازات بالا را فریب دهد تا ناخواسته فایل را روی صفحه نمایش دهد و محتوای آن را برای اطرافیان فاش کند. .Nm تنها مسیری را نشان می‌دهد که پس از .Ic \&so ظاهر می‌شود. .It Sy ".so request failed" .Pq roff پاسخ به یک درخواست .Ic \&so نیازمند خواندن یک فایل خارجی است، اما فایل باز نشد. .Nm تنها مسیری را نشان می‌دهد که پس از .Ic \&so ظاهر می‌شود. .It Sy "skipping all arguments" .Pq mdoc , man , eqn , roff ماکروی .Ic \&Bt ، .Ic \&Ed ، .Ic \&Ef ، .Ic \&Ek ، .Ic \&El ، .Ic \&Lp ، .Ic \&Pp ، .Ic \&Re ، .Ic \&Rs یا .Ic \&Ud در .Xr mdoc 7 ، یک ماکروی .Ic \&It در فهرستی که از سرآیند برای موارد پشتیبانی نمی‌کند، ماکروی .Ic \&LP ، .Ic \&P یا .Ic \&PP در .Xr man 7 ، ماکروی .Ic \&EQ یا .Ic \&EN در .Xr eqn 7 ، یا یک درخواست .Ic \&br ، .Ic \&fi یا .Ic \&nf در .Xr roff 7 یا درخواست بستن بلوک .Sq \&.. با حداقل یک آرگومان فراخوانی شده است. همهٔ آرگومان‌ها نادیده گرفته می‌شوند. .It Sy "skipping excess arguments" .Pq mdoc , man , roff یک ماکرو یا درخواست با آرگومان‌های بیش از حد فراخوانی شده است: .Bl -dash -offset 2n -width 2n -compact .It .Ic \&Fo ، .Ic \&MT ، .Ic \&PD ، .Ic \&RS ، .Ic \&UR ، .Ic \&ft یا .Ic \&sp با بیش از یک آرگومان .It .Ic \&An با یک آرگومان دیگر بعد از .Fl split یا .Fl nosplit .It .Ic \&RE با بیش از یک آرگومان یا با یک آرگومان غیر عدد صحیح .It .Ic \&OP یا درخواستی از خانوادهٔ .Ic \&de با بیش از دو آرگومان .It .Ic \&Dt با بیش از سه آرگومان .It .Ic \&TH با بیش از پنج آرگومان .It .Ic \&Bd ، .Ic \&Bk یا .Ic \&Bl با آرگومان‌های نامعتبر .El آرگومان‌های اضافی نادیده گرفته می‌شوند. .El .Ss "ویژگی‌های پشتیبانی‌نشده" .Bl -ohang .It Sy "input too large" .Pq mdoc , man در حال حاضر، .Nm نمی‌تواند فایل‌های ورودی بزرگتر از محدودیت دلخواه خود یعنی 2^31 بایت (۲ گیگابایت) را پردازش کند. از آنجا که صفحات راهنمای مفید همواره کوچک هستند، این امر در عمل مشکلی ایجاد نمی‌کند. تجزیه به محض تشخیص این وضعیت متوقف می‌شود. .It Sy "unsupported control character" .Pq roff یک نویسهٔ کنترلی ASCII که توسط سایر پیاده‌سازی‌های .Xr roff 7 پشتیبانی می‌شود اما توسط .Nm پشتیبانی نمی‌شود در یک فایل ورودی پیدا شد. با یک علامت سوال جایگزین می‌شود. .It Sy "unsupported escape sequence" .Pq roff یک فایل ورودی شامل یک توالی گریز است که توسط GNU troff یا Heirloom troff پشتیبانی می‌شود اما در .Nm پشتیبانی نمی‌شود، و احتمال دارد که این امر باعث از دست رفتن اطلاعات یا قالب‌بندی بسیار ناقص شود. .It Sy "unsupported roff request" .Pq roff یک فایل ورودی شامل یک درخواست .Xr roff 7 است که توسط GNU troff یا Heirloom troff پشتیبانی می‌شود اما در .Nm پشتیبانی نمی‌شود، و احتمال دارد که این امر باعث از دست رفتن اطلاعات یا قالب‌بندی بسیار ناقص شود. .It Sy "eqn delim option in tbl" .Pq eqn , tbl خط گزینه‌های یک جدول جداکننده‌های معادله را تعریف می‌کند. هر کد منبع معادله که درون جدول قرار دارد به‌صورت قالب‌بندی‌نشده چاپ خواهد شد. .It Sy "unsupported table layout modifier" .Pq tbl مشخصات طرح‌بندی جدول شامل یک اصلاح‌کنندهٔ .Sq Cm m است. اصلاح‌کننده دور ریخته می‌شود. .It Sy "ignoring macro in table" .Pq tbl , mdoc , man یک جدول حاوی فراخوانی یک ماکروی .Xr mdoc 7 یا .Xr man 7 یا یک ماکروی تعریف‌نشده است. ماکرو نادیده گرفته می‌شود، و آرگومان‌های آن مانند یک خط متن در نظر گرفته می‌شوند. .It Sy "skipping tbl in -Tman mode" .Pq mdoc , tbl یک فایل ورودی شامل ماکروی .Ic \&TS است. این پیام تنها در حالت خروجی .Fl T Cm man تولید می‌شود که در آن ورودی‌های .Xr tbl 7 پشتیبانی نمی‌شوند. .It Sy "skipping eqn in -Tman mode" .Pq mdoc , eqn یک فایل ورودی شامل ماکروی .Ic \&EQ است. این پیام تنها در حالت خروجی .Fl T Cm man تولید می‌شود که در آن ورودی‌های .Xr eqn 7 پشتیبانی نمی‌شوند. .El .Ss "آرگومان‌های نادرست خط فرمان" .Bl -ohang .It Sy "bad command line argument" آرگومان به دنبال یکی از گزینه‌های خط فرمان .Fl IKMmOTW نامعتبر است، یا یک .Ar file داده‌شده به عنوان آرگومان خط فرمان باز نمی‌شود. .It Sy "duplicate command line argument" گزینهٔ خط فرمان .Fl I دو بار مشخص شده است. .It Sy "option has a superfluous value" یک آرگومان برای گزینهٔ .Fl O دارای مقدار است اما مقداری نمی‌پذیرد. .It Sy "missing option value" یک آرگومان برای گزینهٔ .Fl O مقداری ندارد اما نیازمند آن است. .It Sy "bad option value" یک آرگومان برای گزینهٔ .Cm indent یا .Cm width از .Fl O دارای مقدار نامعتبر است. .It Sy "duplicate option value" یک گزینهٔ .Fl O یکسان بیش از یک بار مشخص شده است. .It Sy "no such tag" گزینهٔ .Fl O Cm tag مشخص شده است اما برچسب در هیچ‌یک از صفحات راهنمای نمایش‌داده‌شده پیدا نشد. .It Sy "\-Tmarkdown unsupported for man(7) input" .Pq man گزینهٔ .Fl T Cm markdown مشخص شده است اما یک فایل ورودی از زبان .Xr man 7 استفاده می‌کند. هیچ خروجی برای آن فایل ورودی تولید نمی‌شود. .El .Sh "همچنین ببینید (SEE ALSO)" .Xr apropos 1 , .Xr man 1 , .Xr eqn 7 , .Xr man 7 , .Xr mandoc_char 7 , .Xr mdoc 7 , .Xr roff 7 , .Xr tbl 7 .Sh "تاریخچه (HISTORY)" ابزار .Nm نخستین بار در .Ox 4.8 ظاهر شد. گزینهٔ .Fl I در .Ox 5.2 و گزینه‌های .Fl aCcfhKklMSsw در .Ox 5.7 پدیدار شدند. .Sh "نویسندگان (AUTHORS)" .An -nosplit ابزار .Nm توسط .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv نوشته شده است و توسط .An Ingo Schwarze Aq Mt schwarze@openbsd.org نگهداری می‌شود.