درست كردن فايل راهنماي CHM از توضيحات XML يك پروژه

تا حالا هيچ وقت براي شما اين سؤال پيش اومده كه اين فايل‌هاي CHM راهنماي زيبايي كه براي مثال به‌عنوان مستندات يك كتابخانه در دات نت ارائه مي‌شوند با چه نرم‌افزار يا نرم‌افزارهايي توليد مي‌شوند؟ يا اينكه به نظر يك يا چند نفر ساعت‌ها وقت مي‌گذارند، صفحات HTML مربوطه را توليد مي‌كنند و در آخر با استفاده از ابزارهاي توليد فايل CHM ، فايل راهنما را نهايي مي‌كنند؟
اين فايل‌ها به صورت خودكار بر اساس XML code comments ارائه شده براي يك متد ، كلاس و امثال آن توليد مي‌شوند. براي مثال به توضيحات زير دقت بفرمائيد:

    /// <summary>
    /// استخراج ايميل‌هاي يك فايل متني و ذخيره آن در فايلي جديد
    /// </summary>
    /// <param name="inFilePath">فايل ورودي</param>
    /// <param name="outFilePath">فايل خروجي</param>
    public static void ExtractEmails(string inFilePath, string outFilePath)

هر چند VS.Net‌ در ايجاد خوكار قالب اوليه اين نوع كامنت‌ها بسيار خوب عمل مي‌كند اما نكات پيشرفته‌تري نيز در اين‌باره موجود هستند كه در كيفيت فايل راهنماي توليد شده بر اساس اين توضيحات بسيار مؤثرند. راهنماي كاملي در اين‌باره را از اينجا مي‌توانيد دريافت كنيد.
در ادامه نحوه توليد خودكار اين نوع راهنماها را بررسي خواهيم كرد.

الف) نصب برنامه‌هاي مورد نياز
براي ايجاد فايل chm از توضيحات xml ايي ارائه شده، ابتدا دو برنامه سورس باز زير را دريافت و نصب كنيد:

• Sandcastle
  

• Sandcastle Help File Builder

سپس نياز به HTML Help 2.0 compiler خواهد بود. اين كامپايلر به همراه SDK ويژوال استوديو ارائه مي‌شود. بسته به نگارش VS مورد استفاده، نياز است تا يكي از موارد زير را دريافت و نصب كنيد:

• Visual Studio 2005 SDK Version 4.0
  

• Visual Studio 2008 SDK Version 1.0

برنامه hxcomp.exe ذكر شده، عموما در مسير زير نصب خواهد شد:

%Program Files%\Common Files\Microsoft Shared\Help 2.0 Compiler\

ب) تنظيمات VS.Net
مرحله بعد به تنظيمات VS.Net مربوط مي‌شود. به صفحه خواص پروژه مراجعه كنيد و در برگه Build ، گزينه توليد XML documentation file را انتخاب كنيد. سپس مجددا پروژه خود را كامپايل كنيد.

ج) تنظيمات Sandcastle Help File Builder
يك پروژه جديد را در اين برنامه آغاز كرده و سپس فايل اسمبلي و xml توليد شده آنرا انتخاب كنيد. (بر روي دكمه add كليك كرده و هر دو فايل exe يا dll مورد نظر را به همراه فايل xml آن كه در قسمت ب توليد كرديم، انتخاب كنيد. در صورت عدم انتخاب يكي از موارد فايل راهنما توليد نخواهد شد)
اكنون نوبت به تنظيمات پروژه مي‌رسد.
در قسمت Build:
گزينه Help File Format را انتخاب كرده و سپس html help 2x را نيز تيك بزنيد. (در صورت تمايل به توليد اين نوع فرمت)
در قسمت Dependencies ، تمام اسمبلي‌هايي را كه پروژه شما به آن وابسته است، اضافه كنيد.
توسط گزينه Framework Version ، نگارشي از دات نت فريم ورك كه اسمبلي شما بر اساس آن كامپايل شده است را انتخاب كنيد.
در قسمت Help File:
Presentation Style را بر روي VS2005 قرار دهيد. اين‌كار اجباري نيست اما راهنماي حاصل زيباتر خواهد بود.
در قسمت Paths :
مسيرهاي كامپايلرهاي راهنما را مشخص كنيد. بر روي سيستم من اين مسيرها مطابق شكل زير هستند:

اگر HTML Help Workshop بر روي سيستم شما نصب نبود، آنرا از اين آدرس دريافت نمائيد.

د) ساخت فايل راهنما
بر روي آيكون build در نوار ابزار برنامه كليك كنيد (و يا انتخاب گزينه documentation->build)

تا اينجا اگر هر دو نوع Help1xAndHelp2x را در قسمت build انتخاب كرده باشيد، دو نوع راهنماي مستقل و همچنين قابل يكپارچه شدن با سيستم راهنماي VS.net را توليد كرده‌ايد.

ه) يكپارچه سازي Help2x توليد شده با سيستم راهنماي VS.Net
پروژه جديدي را در VS.Net از نوع Other Project Types > Extensibility > Help Integration Wizard ايجاد كنيد. در مرحله اول، ايجاد setup و نوع VS را انتخاب كرده و در صفحه بعد فايل‌هاي Help2x خود را اضافه كنيد (فايلهايي با پسوند hxs). دو مرحله آخر را مطابق نيازهاي كاري خود تنظيم نموده و پروژه را در آخر build كنيد. نصاب توليد شده فايل‌هاي راهنماي شما را با سيستم راهنماي VS.Net يكپارچه خواهد ساخت.

چند نكته:
1- جهت سفارشي سازي بيشتر راهنماي توليد شده مي‌توان از ابزار سورس باز زير نيز كمك گرفت:
http://www.codeplex.com/DocProject
2- افزونه‌اي رايگان براي VS.Net جهت سهولت توليد توضيحات XML در آدرس زير قابل دريافت است:
http://www.roland-weigelt.de/ghostdoc