.\" 
.\" mdoc assemble manual page.
.\" (C) 2008 Novell, Inc.
.\" Author:
.\"   Jonathan Pryor (jpryor@novell.com)
.\"
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.TH "mdoc-assemble" 1
.SH "نام (NAME)"
mdoc assemble \- کامپایل مستندات برای استفاده در \fBmonodoc\fR(1)
.SH "خلاصه دستور (SYNOPSIS)"
.B mdoc assemble
[OPTIONS]+
PATHS+
.SH "توضیحات (DESCRIPTION)"
دستور \fBmdoc assemble\fR فایل‌های \fI.tree\fR و \fI.zip\fR را از \fIPATHS\fR
برای استفاده در مرورگر مستندات \fBmonodoc\fR(1) ایجاد می‌کند.
.PP
فایل‌های ورودی باید دارای یک \fIformat\fR (قالب) پشتیبانی‌شده باشند که با گزینهٔ
\fI--format\fR مشخص می‌شود.
.PP
فایل‌های \fI.tree\fR و \fI.zip\fR درون دایرکتوری \fIsources\fR متعلق به \fBmonodoc\fR کپی می‌شوند،
در کنار یک فایل \fI.source\fR که توسط \fBmonodoc\fR(1) برای تعیین محل نمایش مستندات استفاده می‌شود.
.PP
فایل \fI.source\fR ساختار زیر را دارد:
.nf

  <?xml version="1.0"?>
  <monodoc>
    <node label="LABEL" name="PATH" parent="PARENT">
      <node label="LABEL2" name="PATH2" />
      <!-- ... -->
    </node>
    <source provider="PROVIDER" basefile="BASEFILE" path="PATH" />
    <!-- other <source/> elements -->
  </monodoc>

.fi
گره \fI/monodoc/node\fR یک گره اختیاری است که مشخص می‌کند مستندات باید در کجای درخت monodoc نمایش داده شوند،
و عناصر \fI//node\fR می‌توانند تا هر عمقی برای ساخت درخت‌ها تو در تو شوند. \fI//node/@label\fR برچسبی است
که در داخل درخت monodoc نمایش داده خواهد شد.
.PP
صفت \fI//node/@name\fR نام گره در درخت monodoc است و می‌تواند به عنوان مقدار
\fI/monodoc/source/@path\fR استفاده شود.
.PP
صفت \fI//node/@parent\fR نام گره‌ای است که باید به عنوان گره والد استفاده شود.
فایل \fI$MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml\fR حاوی فهرستی از چنین
نام‌هایی است و این مقدار می‌تواند هر مقداری از \fI//node/@name\fR باشد. اگر
مقدار \fI//node/@parent\fR یافت نشود، زیر گره درختی "Various" درج می‌شود.
.PP
صفت \fI/monodoc/source/@provider\fR مشخص می‌کند که هنگام خواندن فایل‌های \fI.tree\fR و \fI.zip\fR
باید از کدام ارائه‌دهنده قالب استفاده شود؛ این مقدار \fIباید\fR با یکی از مقادیر
\fI--format\fR مطابقت داشته باشد.
.PP
صفت \fI/monodoc/source/@basefile\fR پیشوند نام فایل را برای فایل‌های مستندات مشخص می‌کند.
این مقدار باید با پیشوند استفاده‌شده در پارامتر \fI\-\-out\fR یکسان باشد. این مقدار
\fIنباید\fR هیچ پسوند نام فایلی داشته باشد.
.PP
صفت \fI/monodoc/source/@path\fR گره والد را در نمای درختی \fBmonodoc\fR(1) که مستندات
در آن درج می‌شوند مشخص می‌کند.
برای مشاهدهٔ فهرستی از مقادیر \fIPATH\fR (مقادیر \fI//node/@name\fR)، فایل
\fI$MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml\fR را ببینید، یا می‌تواند یک مقدار
\fI//node/@name\fR در همان فایل \fI.source\fR باشد.
.PP
پس از نوشته شدن \fIBASEFILE.source\fR، مستندات را می‌توان به گونه‌ای نصب کرد که
\fBmonodoc\fR(1) مستندات را با این دستور نمایش دهد:
.nf

  cp BASEFILE.source BASEFILE.tree BASEFILE.zip \\
    `pkg-config monodoc --variable=sourcesdir`

.fi
.SH "گزینه‌ها (OPTIONS)"
.TP
\fB\-f\fR, \fB\-\-format\fR=\fIFORMAT\fR
قالب مستندات استفاده‌شده در \fIPATHS\fR را مشخص می‌کند. مقادیر معتبر
\fIFORMAT\fR عبارتند از:
\fIecma\fR،
\fIecmaspec\fR،
\fIerror\fR،
\fIhb\fR،
\fIman\fR،
\fIsimple\fR و
\fIxhtml\fR.
.Sp
برای اطلاعات بیشتر درباره این قالب‌ها، بخش \fIFORMATS\fR را در زیر ببینید.
.Sp
قالب پیش‌فرض (در صورت مشخص نشدن) \fIecma\fR است.
.Sp
گزینهٔ \fI\-\-format\fR می‌تواند همراه با \fIPATHS\fR به صورت متناوب به کار رود
تا قالب استفاده‌شده برای پارامترهای باقی‌مانده را (تا زمان مشاهده گزینهٔ \fI\-\-format\fR بعدی)
تغییر دهد، به عنوان مثال:
.nf

  mdoc assemble -o PREFIX A B --format=man C D --format=xhtml E

.fi
دایرکتوری‌های \fIA\fR و \fIB\fR را با قالب \fIecma\fR، فایل‌های \fIC\fR و \fID\fR را با
قالب \fIman\fR، و دایرکتوری \fIE\fR را با قالب \fIxhtml\fR سرهم‌بندی خواهد کرد.
.TP
\fB\-o\fR, \fB\-\-out\fR=\fIPREFIX\fR
پیشوند فایل خروجی را مشخص می‌کند. \fBmdoc assemble\fR فایل‌های
\fIPREFIX.zip\fR و \fIPREFIX.tree\fR را ایجاد می‌کند.
.TP
\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR
یک پیام راهنما را نمایش می‌دهد و خارج می‌شود.
.SH "قالب‌ها (FORMATS)"
قالب‌های مستندات زیر پشتیبانی می‌شوند:
.SS ecma
\fIقالب مستندات Mono ECMA\fR، یک قالب مستندات XML با یک فایل برای هر نوع داده (type).
.PP
برای اطلاعات بیشتر صفحه راهنمای \fBmdoc\fR(5) را ببینید.
.SS ecmaspec
\fIقالب مستندات مشخصات Mono ECMA\fR.
این قالبی نیست که به دنبال آن هستید؛ این قالبی است که برای نمایش استاندارد ECMA-334 (C#) در \fBmonodoc\fR(1) استفاده می‌شود. برای نمایش مستندات کتابخانه کلاس‌ها استفاده نمی‌شود؛ برای مستندات کتابخانه کلاس‌ها، از قالب
.B ecma
استفاده کنید.
.SS error
\fIقالب مستندات خطا\fR برای ارائه پیام‌های خطای دقیق استفاده می‌شود، و در درخت "C# Compiler Error Reference" در \fBmonodoc\fR(1) به کار می‌رود.
.PP
در این قالب، \fIPATHS\fR یک فایل پیکربندی شامل این XML است:
.nf

    <ErrorProviderConfig>
        <FilesPath>../../mcs/errors</FilesPath>
        <Match>cs????*.cs</Match>
        <ErrorNumSubstringStart>2</ErrorNumSubstringStart>
        <ErrorNumSubstringLength>4</ErrorNumSubstringLength>
        <FriendlyFormatString>CS{0:0###}</FriendlyFormatString>
    </ErrorProviderConfig>

.fi
عناصر به این معنا هستند:
.TP
.I /ErrorProviderConfig/FilesPath
مشخص می‌کند که کجا باید به دنبال فایل‌ها گشت.
.TP
.I /ErrorProviderConfig/Match
الگوی نام فایلی که باید در دایرکتوری \fI/ErrorProviderConfig/FilesPath\fR به دنبال آن گشت را مشخص می‌کند.
.TP
.I /ErrorProviderConfig/ErrorNumSubstringStart
مشخص می‌کند که شماره خطا در کجای نام فایل آغاز می‌شود.
.TP
.I /ErrorProviderConfig/ErrorNumSubstringLength
مشخص می‌کند چه تعداد نویسه بعد از \fI/ErrorProviderConfig/ErrorNumSubstringStart\fR برای شماره خطا استفاده شود.
.TP
.I /ErrorProviderConfig/FriendlyFormatString
قالب‌بندی/نمایش گره را در درخت \fBmonodoc\fR(1) مشخص می‌کند.
.PP
به ازای هر فایل پیدا شده، با اعمال رنگ‌آمیزی نحوی C# به HTML تبدیل می‌شود.
.SS simple
قالب فایل \fIقالب مستندات ساده\fR تمامی فایل‌ها و دایرکتوری‌های زیرمجموعهٔ \fIPATHS\fR را به صورت بازگشتی اضافه می‌کند. هنگام نمایش، فایل‌های HTML همان‌گونه که هستند نمایش داده می‌شوند. فایل‌های متنی با تبدیل هر خط جدید به عنصر HTML \fI<br>\fR به HTML تبدیل می‌شوند. هیچ نوع فایل دیگری پشتیبانی نمی‌شود.
.SS man
\fIقالب مستندات Man Page\fR صفحات راهنمای groff را نمایش می‌دهد. (این یک تجزیه‌کننده کامل groff \fIنیست\fR و تنها ساختارهای صفحه راهنما را که در صفحات راهنمای mono استفاده شده مدیریت می‌کند.)
.PP
\fIPATHS\fR مجموعه‌ای از فایل‌های XML شامل موارد زیر است:
.nf

  <?xml version="1.0"?>
  <manpages>
    <manpage name="NAME" page="FILE" />
  </manpages>

.fi
ممکن است چندین عنصر \fI//manpage\fR درون عنصر ریشه \fI/manpage\fR وجود داشته باشد.
.PP
صفت \fI/manpages/manpage/@name\fR حاوی نام نمایشی گره درخت است، که همچنین نشانی اینترنتی (URL) صفحه راهنما هنگام استفاده از دستور \fILookup URL\fR در \fBmonodoc\fR(1) است (پیش از قرار گرفتن پیشوند \fIman:\fR). بنابراین، اگر \fI/manpages/manpage/@name\fR حاوی \fImono(1)\fR باشد، می‌توان از \fIman:mono(1)\fR در دستور \fILookup URL\fR برای مشاهده صفحه راهنمای \fImono(1)\fR استفاده کرد.
.PP
صفت \fI/manpages/manpage/@page\fR نام فایلی است که حاوی صفحه راهنما است. اگر این فایل وجود نداشته باشد، \fI/manpages/manpage/@name\fR در نمای درختی نمایش داده نخواهد شد.
.SS xhtml
ارائه‌دهنده XHTML مقدار \fIPATHS\fR را به عنوان یک فایل فهرست مطالب (TOC) مربوط به Windows Help file XHTML تفسیر می‌کند و به دنبال اسناد ارجاع‌شده برای ایجاد منبع راهنما می‌گردد.
.SH "همچنین ببینید (SEE ALSO)"
\fBmdoc\fR(1), 
\fBmdoc\fR(5), 
\fBmonodoc\fR(1)
.SH "فهرست‌های پستی (MAILING LISTS)"
.TP
برای جزئیات بیشتر به http://lists.ximian.com/mailman/listinfo/mono-docs-list مراجعه کنید.
.SH "وبگاه (WEB SITE)"
همچنین ببینید: http://www.mono-project.com/docs/tools+libraries/tools/mdoc