.\" .\" mdoc manual page. .\" (C) 2008 Jonathan Pryor .\" 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" 1 .SH "نام (NAME)" mdoc \- ابزار مدیریت مستندات Mono .SH "خلاصه دستور (SYNOPSIS)" .B mdoc .I command [\fIoptions\fR] [\fIargs\fR] .SH "نمای کلی (OVERVIEW)" \fImdoc\fR یک سامانهٔ مدیریت مستندات مبتنی بر اسمبلی است. .PP \fImdoc\fR امکان ایجاد و به‌روزرسانی قالب‌های اولیهٔ مستندات (\fIstubs\fR) را بر اساس محتوای یک اسمبلی فراهم می‌کند. این ابزار به مستندات موجود در کد منبع وابسته نیست. .PP مزایای آن عبارتند از: .TP .B * .B خوانایی کد. مستندات خوب معمولاً (الف) مفصل بوده و (ب) پر از مثال است. (برای مقایسه، مستندات Microsoft .NET Framework را که اغلب شامل یک صفحه یا بیشتر مستند برای هر عضو است، با مستندات JavaDoc که غالباً می‌تواند یک جمله برای هر عضو باشد، مقایسه کنید.) .Sp قرار دادن مستندات مفصل در کد منبع می‌تواند بارها باعث حجیم شدن فایل منبع شود، چرا که حجم مستندات می‌تواند از متد واقعی که مستند می‌شود طولانی‌تر باشد. .TP .B * .B بومی‌سازی. قالب‌های مستندسازی درون کد منبع (مانند \fIcsc /doc\fR) هیچ پشتیبانی‌ای از چندین زبان انسانی ندارند. اگر برای اهداف مستندسازی نیاز به پشتیبانی از بیش از یک زبان انسانی دارید، \fImdoc\fR کارآمد است؛ زیرا اجازه می‌دهد خروجی هر زبان در دایرکتوری مختص خود قرار گیرد، و \fImdoc\fR می‌تواند انواع و اعضا را برای هر دایرکتوری مستندات جداگانه اضافه کند. .TP .B * .B مدیریت. داشتن تیم‌های مستندسازی و توسعهٔ مجزا امر غیرمعمولی نیست. همچنین این احتمال وجود دارد که تیم مستندسازی تجربهٔ بسیار کمی در زبان برنامه‌نویسی مورد استفاده داشته باشد. در چنین شرایطی، مستندسازی درون‌خطی مطلوب نیست؛ چرا که تیم مستندسازی ممکن است هنگام به‌روزرسانی مستندات، سهواً خطایی را وارد کد منبع کند. همچنین، ممکن است به دلایل امنیتی مایل نباشید تیم مستندسازی به کد منبع دسترسی داشته باشد. \fImdoc\fR اجازه می‌دهد مستندات \fIکاملاً\fR مجزا و مستقل از کد منبع مورد استفاده برای ایجاد اسمبلی نگهداری شوند. .PP مستندات را می‌توان با استفاده از دستور \fBmdoc update\fR تولید کرد: .nf mdoc update -o docs/en ProjectName.dll .fi پس از اینکه قالب‌های اولیهٔ مستندات تولید شدند (و در حالت ایده‌آل بعداً با مستندات واقعی تکمیل شدند)، سه روش برای مشاهدهٔ مستندات وجود دارد: .TP .B * برای تولید یک دایرکتوری ساده از صفحات HTML (یک فایل HTML به ازای هر نوع)، از \fBmdoc export-html\fR استفاده کنید: .nf mdoc export-html -o /srv/www/htdocs/ProjectName docs/en .fi .TP .B * برای استفاده از یک برنامهٔ وب ASP.NET جهت نمایش منابع، ببینید: \fIhttp://anonsvn.mono-project.com/source/trunk/monodoc/engine/web\fR. .Sp از نسخهٔ دریافت‌شده از سورس‌کد \fImonodoc\fR، می‌توانید این کار را انجام دهید: .nf cd engine make web .fi این دستور از \fBxsp\fR(1) برای سرو کردن برنامهٔ وب ASP.NET استفاده خواهد کرد؛ برای مشاهدهٔ مستندات، \fIhttp://localhost:8080\fR را باز کنید. .TP .B * برای استفاده از مرورگر مستندات \fBmonodoc\fR(1)، ابتدا باید مستندات را \fIسرهم‌بندی\fR (\fIassemble\fR) کنید: .nf mdoc assemble -o ProjectName docs/en .fi دستور بالا فایل‌های \fIProjectName.tree\fR و \fIProjectName.zip\fR را ایجاد می‌کند. یک فایل اضافی \fIProjectName.sources\fR نیز باید ارائه شود که مشخص می‌کند مستندات در کجای سیستم راهنما باید متصل شوند؛ این یک فایل بسیار سادهٔ XML است، مانند این: .nf .fi فایل پیکربندی بالا مشخص می‌کند که مستندات در قالب ECMA هستند، نام فایل پایه \fIProjectName\fR است و باید در بخش \fI"various"\fR از درخت مستندات متصل شود. اگر می‌خواهید گره‌های مختلف تعریف‌شده در مستندات را مشاهده کنید، می‌توانید به فایل \fImonodoc.xml\fR که معمولاً در \fI/usr/lib/monodoc/monodoc.xml\fR نصب می‌شود نگاهی بیندازید. .Sp پس از اینکه تمام فایل‌های مورد نیاز (.zip، .tree و .sources) را در اختیار داشتید، می‌توانید آن‌ها را با دستور زیر در سیستم نصب کنید: .nf cp ProjectName.tree ProjectName.zip ProjectName.source \\ `pkg-config monodoc --variable sourcesdir` .fi دستور بالا فایل‌ها را در دایرکتوری ثبت‌شده توسط Monodoc کپی می‌کند؛ برای انجام این کار ممکن است به دسترسی ریشه نیاز داشته باشید. دایرکتوری واقعی توسط فراخوانی \fIpkg-config\fR بازگردانده می‌شود. .SH "دستورهای MDOC (MDOC COMMANDS)" .PP \fBmdoc assemble\fR .RS 4 مستندات را برای استفاده در مرورگر \fBmonodoc\fR(1) کامپایل می‌کند. .PP برای جزئیات بیشتر صفحهٔ راهنمای \fBmdoc-assemble\fR(1) را ببینید. .RE .PP \fBmdoc export-html\fR .RS 4 مستندات را به ساختاری دایرکتوری از فایل‌های HTML صادر می‌کند. .PP برای جزئیات بیشتر صفحهٔ راهنمای \fBmdoc-export-html\fR(1) را ببینید. .RE .PP \fBmdoc export-msxdoc\fR .RS 4 مستندات را در قالب تک‌فایلی \fIMicrosoft XML Documentation\fR صادر می‌کند. .PP برای جزئیات بیشتر صفحهٔ راهنمای \fBmdoc-export-msxdoc\fR(1) را ببینید. .RE .PP \fBmdoc help\fR .RS 4 راهنمای داخلی یک دستور مشخص را نمایش می‌دهد. .nf mdoc help assemble .fi معادل است با: .nf mdoc assemble --help .fi می‌توان چندین زیردستور را به‌طور هم‌زمان مشخص کرد: .nf mdoc help assemble export-html update validate .fi .RE .PP \fBmdoc update\fR .RS 4 مستندات را به‌روزرسانی کرده و بر اساس یک اسمبلی مرجع، اعضا را اضافه یا حذف می‌کند. .PP برای جزئیات بیشتر صفحهٔ راهنمای \fBmdoc-update\fR(1) را ببینید. .RE .PP \fBmdoc validate\fR .RS 4 مستندات را بر اساس شِمای مستندات Mono اعتبارسنجی می‌کند. .PP برای جزئیات بیشتر صفحهٔ راهنمای \fBmdoc-validate\fR(1) را ببینید. .RE .SH "همچنین ببینید (SEE ALSO)" mdoc(5), mdoc-assemble(1), mdoc-export-html(1), mdoc-update(1), mdoc-validate(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 مراجعه کنید.