mdoc-assemble(1) General Commands Manual mdoc-assemble(1)

mdoc assemble - کامپایل مستندات برای استفاده در monodoc(1)

mdoc assemble [OPTIONS]+ PATHS+

دستور mdoc assemble فایل‌های .tree و .zip را از PATHS برای استفاده در مرورگر مستندات monodoc(1) ایجاد می‌کند.

فایل‌های ورودی باید دارای یک format (قالب) پشتیبانی‌شده باشند که با گزینهٔ --format مشخص می‌شود.

فایل‌های .tree و .zip درون دایرکتوری sources متعلق به monodoc کپی می‌شوند، در کنار یک فایل .source که توسط monodoc(1) برای تعیین محل نمایش مستندات استفاده می‌شود.

فایل .source ساختار زیر را دارد:

<?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>
گره /monodoc/node یک گره اختیاری است که مشخص می‌کند مستندات باید در کجای درخت monodoc نمایش داده شوند، و عناصر //node می‌توانند تا هر عمقی برای ساخت درخت‌ها تو در تو شوند. //node/@label برچسبی است که در داخل درخت monodoc نمایش داده خواهد شد.

صفت //node/@name نام گره در درخت monodoc است و می‌تواند به عنوان مقدار /monodoc/source/@path استفاده شود.

صفت //node/@parent نام گره‌ای است که باید به عنوان گره والد استفاده شود. فایل $MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml حاوی فهرستی از چنین نام‌هایی است و این مقدار می‌تواند هر مقداری از //node/@name باشد. اگر مقدار //node/@parent یافت نشود، زیر گره درختی "Various" درج می‌شود.

صفت /monodoc/source/@provider مشخص می‌کند که هنگام خواندن فایل‌های .tree و .zip باید از کدام ارائه‌دهنده قالب استفاده شود؛ این مقدار باید با یکی از مقادیر --format مطابقت داشته باشد.

صفت /monodoc/source/@basefile پیشوند نام فایل را برای فایل‌های مستندات مشخص می‌کند. این مقدار باید با پیشوند استفاده‌شده در پارامتر --out یکسان باشد. این مقدار نباید هیچ پسوند نام فایلی داشته باشد.

صفت /monodoc/source/@path گره والد را در نمای درختی monodoc(1) که مستندات در آن درج می‌شوند مشخص می‌کند. برای مشاهدهٔ فهرستی از مقادیر PATH (مقادیر //node/@name)، فایل $MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml را ببینید، یا می‌تواند یک مقدار //node/@name در همان فایل .source باشد.

پس از نوشته شدن BASEFILE.source، مستندات را می‌توان به گونه‌ای نصب کرد که monodoc(1) مستندات را با این دستور نمایش دهد:

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

قالب مستندات استفاده‌شده در PATHS را مشخص می‌کند. مقادیر معتبر FORMAT عبارتند از: ecma، ecmaspec، error، hb، man، simple و xhtml.

برای اطلاعات بیشتر درباره این قالب‌ها، بخش FORMATS را در زیر ببینید.

قالب پیش‌فرض (در صورت مشخص نشدن) ecma است.

گزینهٔ --format می‌تواند همراه با PATHS به صورت متناوب به کار رود تا قالب استفاده‌شده برای پارامترهای باقی‌مانده را (تا زمان مشاهده گزینهٔ --format بعدی) تغییر دهد، به عنوان مثال:

mdoc assemble -o PREFIX A B --format=man C D --format=xhtml E
دایرکتوری‌های A و B را با قالب ecma، فایل‌های C و D را با قالب man، و دایرکتوری E را با قالب xhtml سرهم‌بندی خواهد کرد.
پیشوند فایل خروجی را مشخص می‌کند. mdoc assemble فایل‌های PREFIX.zip و PREFIX.tree را ایجاد می‌کند.
یک پیام راهنما را نمایش می‌دهد و خارج می‌شود.

قالب‌های مستندات زیر پشتیبانی می‌شوند:

قالب مستندات Mono ECMA، یک قالب مستندات XML با یک فایل برای هر نوع داده (type).

برای اطلاعات بیشتر صفحه راهنمای mdoc(5) را ببینید.

قالب مستندات مشخصات Mono ECMA. این قالبی نیست که به دنبال آن هستید؛ این قالبی است که برای نمایش استاندارد ECMA-334 (C#) در monodoc(1) استفاده می‌شود. برای نمایش مستندات کتابخانه کلاس‌ها استفاده نمی‌شود؛ برای مستندات کتابخانه کلاس‌ها، از قالب ecma استفاده کنید.

قالب مستندات خطا برای ارائه پیام‌های خطای دقیق استفاده می‌شود، و در درخت "C# Compiler Error Reference" در monodoc(1) به کار می‌رود.

در این قالب، PATHS یک فایل پیکربندی شامل این XML است:

<ErrorProviderConfig>
    <FilesPath>../../mcs/errors</FilesPath>
    <Match>cs????*.cs</Match>
    <ErrorNumSubstringStart>2</ErrorNumSubstringStart>
    <ErrorNumSubstringLength>4</ErrorNumSubstringLength>
    <FriendlyFormatString>CS{0:0###}</FriendlyFormatString>
</ErrorProviderConfig>
عناصر به این معنا هستند:
/ErrorProviderConfig/FilesPath
مشخص می‌کند که کجا باید به دنبال فایل‌ها گشت.
/ErrorProviderConfig/Match
الگوی نام فایلی که باید در دایرکتوری /ErrorProviderConfig/FilesPath به دنبال آن گشت را مشخص می‌کند.
/ErrorProviderConfig/ErrorNumSubstringStart
مشخص می‌کند که شماره خطا در کجای نام فایل آغاز می‌شود.
/ErrorProviderConfig/ErrorNumSubstringLength
مشخص می‌کند چه تعداد نویسه بعد از /ErrorProviderConfig/ErrorNumSubstringStart برای شماره خطا استفاده شود.
/ErrorProviderConfig/FriendlyFormatString
قالب‌بندی/نمایش گره را در درخت monodoc(1) مشخص می‌کند.

به ازای هر فایل پیدا شده، با اعمال رنگ‌آمیزی نحوی C# به HTML تبدیل می‌شود.

قالب فایل قالب مستندات ساده تمامی فایل‌ها و دایرکتوری‌های زیرمجموعهٔ PATHS را به صورت بازگشتی اضافه می‌کند. هنگام نمایش، فایل‌های HTML همان‌گونه که هستند نمایش داده می‌شوند. فایل‌های متنی با تبدیل هر خط جدید به عنصر HTML <br> به HTML تبدیل می‌شوند. هیچ نوع فایل دیگری پشتیبانی نمی‌شود.

قالب مستندات Man Page صفحات راهنمای groff را نمایش می‌دهد. (این یک تجزیه‌کننده کامل groff نیست و تنها ساختارهای صفحه راهنما را که در صفحات راهنمای mono استفاده شده مدیریت می‌کند.)

PATHS مجموعه‌ای از فایل‌های XML شامل موارد زیر است:

<?xml version="1.0"?>
<manpages>
  <manpage name="NAME" page="FILE" />
</manpages>
ممکن است چندین عنصر //manpage درون عنصر ریشه /manpage وجود داشته باشد.

صفت /manpages/manpage/@name حاوی نام نمایشی گره درخت است، که همچنین نشانی اینترنتی (URL) صفحه راهنما هنگام استفاده از دستور Lookup URL در monodoc(1) است (پیش از قرار گرفتن پیشوند man:). بنابراین، اگر /manpages/manpage/@name حاوی mono(1) باشد، می‌توان از man:mono(1) در دستور Lookup URL برای مشاهده صفحه راهنمای mono(1) استفاده کرد.

صفت /manpages/manpage/@page نام فایلی است که حاوی صفحه راهنما است. اگر این فایل وجود نداشته باشد، /manpages/manpage/@name در نمای درختی نمایش داده نخواهد شد.

ارائه‌دهنده XHTML مقدار PATHS را به عنوان یک فایل فهرست مطالب (TOC) مربوط به Windows Help file XHTML تفسیر می‌کند و به دنبال اسناد ارجاع‌شده برای ایجاد منبع راهنما می‌گردد.

mdoc(1), mdoc(5), monodoc(1)

برای جزئیات بیشتر به http://lists.ximian.com/mailman/listinfo/mono-docs-list مراجعه کنید.

همچنین ببینید: http://www.mono-project.com/docs/tools+libraries/tools/mdoc