وادار كردن خود به كامنت نوشتن

قابليت جالبي در ويژوال استوديو وجود دارد كه شايد كمتر در مورد آن مطلب نوشته شده است و آن هم تنظيم پروژه به نحوي است كه اگر براي كليه موارد public كامنتي نوشته نشود، برنامه كامپايل نخواهد شد. همچنين اگر نام پارامتري را تغيير داديد، اما كامنت مرتبط با آن را به روز نكرديد، باز هم خطاي كامپايل را دريافت خواهيد كرد كه از اين لحاظ هم بسيار عالي است و به نوعي «وادار كردن خود به كامنت نوشتن» است.

براي اين تنظيم، ابتدا به برگه خواص پروژه مراجعه كنيد. سپس در قسمت Build تنظيمات زير را اعمال نمائيد:
Treat warnings as errors را بر روي All قرار دهيد.
در ذيل آن، در قسمت Output‌، گزينه‌ي XML Documentation file را تيك بزنيد.

البته اين تغيير بهتر است در يك پروژه جديد مد نظر باشد، چون اگر الان اقدام به اين تنظيم كنيد، به طور قطع از خير آن خواهيد گذشت! كامنت نويسي به مرور و در حين توسعه يك برنامه يا كتابخانه قابل تحمل است وگرنه اگر براي روز آخر قرار داده شود، به احتمال زياد انجام نخواهد شد.

مطالب مرتبط:

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

اضافه كردن كامنت جهت فضاهاي نام

در مورد «درست كردن فايل راهنماي CHM از توضيحات XML يك پروژه» پيشتر مطلبي در اين سايت منتشر شده است. تمام اين‌ها هم خوب! اما فايل راهنماي نهايي توليدي يك ايراد مهم دارد. Sandcastle Help File Builder نياز دارد كه به ازاي هر فضاي نامي كه در پروژه‌ي شما وجود دارد، يك summary و توضيح هم ارائه شود؛ در غير اينصورت خطاي قرمز رنگ زير را در ابتداي صفحه معرفي كلاس‌هاي يك فضاي نام، نمايش خواهند داد:

[Missing <summary> documentation for "N:Some.Test"]

از آنطرف كامپايلرهاي مورد استفاده چنين توضيحاتي را قبول ندارند و نمي‌توان براي فضاهاي نام، توضيحاتي را همانند كلاس‌ها يا متدها، ارائه داد. براي حل اين مشكل، يك راه حل ساده وجود دارد: به ازاي هر فضاي نامي كه در پروژه وجود دارد، يك كلاس خالي را به نام "NamespaceDoc" به پروژه اضافه كنيد. مثلا:

namespace Some.Test
{
    /// <summary>
    /// The <see cref="Some.Test"/> namespace contains classes for ....
    /// </summary>

    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }
}

به اين ترتيب توضيحاتي كه ملاحظه مي‌كنيد توسط Sandcastle Help File Builder مورد استفاده قرار خواهد گرفت و آن اخطارهاي قرمز رنگ عدم وجود توضيحات مرتبط با فضاهاي نام، از فايل توليدي نهايي حذف خواهند شد.

روش دوم:
در خود برنامه Sandcastle Help File Builder، در قسمت Project Properties > Comments > NameSpaceSummaries، امكان وارد كردن توضيحات فضاهاي نام نيز وجود دارد. (كه آنچنان جالب نيست؛ بهتر است همه چيز يكپارچه باشد.)

فايل‌هاي chm و مشكل فارسي - قسمت دوم

بر اساس جستجوهايي كه انجام داده‌ام، CHM پشتيباني كاملي را از يونيكد انجام نمي‌دهد (مشكل جستجو و همچنين ايندكس كردن).
اما با ترفندي مي‌توان اين مساله را حل كرد و آن هم تبديل encoding فايل‌ها به عربي است (windows-1256). در اين حالت هم جستجو كار مي‌كند و هم عنوان صفحات هنگام جستجو در ليست موارد ياد شده درست نمايش داده مي‌شود و صفحه add to favorites نيز مشكلي در نمايش عنوان‌هاي صفحه‌ها نخواهد داشت. روش كار به شرح زير است:

الف) encoding تمام فايل‌هاي html خود را به صورت زير تغيير دهيد (از utf-8 به windows-1256):

<meta content="text/html; charset=Windows-1256" http-equiv="Content-Type">

ب) محتواي تمام فايل‌هاي html خود را يكبار با فرمت ويندوز 1256 ذخيره كنيد. براي اين منظور در دات نت به سادگي زير مي‌توان عمل كرد:

using System.IO;
using System.Text;

public static void SaveAs1256(string fileName)
{
 string content = File.ReadAllText(fileName);
 File.WriteAllText(fileName, content, Encoding.GetEncoding("windows-1256"));
}

شايد بعضي از ويرايشگرهاي متني هم اين مورد را پشتيباني كنند.(مانند ويرايشگر ويژوال استوديو)

ج) اصلاح فايل hhp پروژه خود
فايل hhp مربوط به html help work shop را باز كنيد. (همان فايل پروژه ساخت راهنما)
اگر مثال قبل را دنبال كرده باشيد، محتواي فايل آن چيزي شبيه به خطوط زير خواهد بود:

[OPTIONS]
Compatibility=1.1 or later
Compiled file=test.chm
Contents file=Table of Contents.hhc
Default Window=win1
Default topic=page1.html
Display compile progress=No
Full-text search=Yes
Index file=Index.hhk
Language=0x429 Farsi
Title=راهنماي يك

[WINDOWS]
win1=,"Table of Contents.hhc","Index.hhk","page1.html","page1.html",,,,,0x3420,,0x304e,,,,,,2,,0


[FILES]
page1.html
page2.html

[INFOTYPES]

نياز است تا آن‌را به صورت زير ويرايش كرد تا فرمت 1256 به آن اعمال شود:
به قسمت options چند سطر زير را اضافه كنيد: (زبان فارسي و فونت تاهوماي عربي)

Default Font=Tahoma,8,178
Language=0x429 Farsi

اكنون پس از كامپايل مجدد مجموعه، مشكلي در مورد جستجو يا به هم ريختگي عنوان‌ها ديگر وجود نخواهد داشت.

محض نمونه، كل وبلاگ جاري را به يك فايل chm تبديل كرده‌ام كه ‌آن‌را از آدرس زير مي‌توانيد دريافت نمائيد:
دريافت فايل

براي آزمايش، يك عبارت فارسي را در آن جستجو نمائيد.


پ.ن.
اين راه حلي است كه به نظر من رسيده و جواب داده. اگر شما با encoding هاي ديگر هم جواب گرفته‌ايد (مشكل جستجوي فارسي حل شده) لطفا پيغام بگذاريد. با تشكر.

فايل‌هاي chm و مشكل فارسي - قسمت اول

همانطور كه مطلع هستيد از ويندوز ويستا به بعد، فرمت قديمي فايل‌هاي راهنماي ويندوز (فايل‌هاي hlp) منسوخ شده تلقي مي‌شود و فرمت پيشنهادي، chm است. نرم افزارهاي زيادي براي تهيه فايل‌هاي compiled html help يا همان chm هاي معروف وجود دارند كه معروفترين آن‌ها برنامه‌ي Help & Manual است.
اما تمام اين برنامه‌ها در حقيقت پوسته‌اي هستند براي برنامه‌ي رايگان html help work shop مايكروسافت و در نهايت از كامپايلر آن استفاده مي‌كنند. بنابراين چرا از برنامه‌ي رايگان اصلي استفاده نشود؟

اگر تا به حال با html help work shop كار نكرده‌ايد، در ادامه مروري سريع بر آن خواهيم داشت:

الف) درست كردن فايل‌هاي صفحات راهنما
برنامه‌ي Help & Manual ايي كه معرفي شد و تمام نمونه‌هاي مشابه آن، تنها كار مهمي را كه انجام مي‌دهند اين است كه شما را از يك html editor بي‌نياز مي‌كنند. بنابراين زمانيكه مي‌خواهيم از برنامه‌ي اصلي html help work shop استفاده كنيم نياز به يك html editor خارجي براي تهيه فايل‌هاي راهنما خواهيم داشت. مثلا مرحوم front page يا نگارش جديد آن به نام Microsoft expression web يا Dreamweaver يا Aptana يا حتي notepad !
در اينجا تنها مشخص كردن نوع encoding نمايش صفحه براي صحيح نمايش داده شدن متون فارسي كافي است. اما اين تمام ماجرا نيست.

ب) كامپايل كردن فايل‌هاي راهنماي ايجاد شده
براي اين منظور بجاي آپلود بيش از 30 تصوير جهت توضيحات قدم به قدم نحوه‌ي انجام اين‌كار، يك فايل ويديويي درست كرده‌ام كه آن‌‌را از آدرس زير مي‌توانيد دريافت كنيد.
دريافت فايل

همانطور كه در اين فايل آموزشي مقدماتي هم تاكيد شده، به صورت پيش فرض جستجوي فارسي كار نمي‌كند. همچنين اگر يك متن انگليسي را جستجو كنيد، صفحات ياد شده با عنواني به هم ريخته نمايش داده مي‌شوند. در صفحه افزودن به علاقمندي‌ها نيز يك چنين مشكلي با عنوان‌ها وجود دارد.

در قسمت دوم، نحوه‌ي رفع اين دو مشكل (مشكل جستجوي عبارات فارسي و مشكل عنوان‌هاي به هم ريخته) را بررسي خواهيم كرد.

ادامه دارد ...