نحوه یافتن مستندات توسط Manweb (How Manweb Finds Documentation)

برنامه manweb یک نشانی اینترنتی (URL) را به یک مرورگر وب ارسال می‌کند. این بخش توضیح می‌دهد که پارامترهای فراخوانی manweb چگونه به آن URL تبدیل می‌شوند.

جستجوی manweb در "دایرکتوری وب" (web directory) آغاز می‌شود. این دایرکتوری یا مقدار کلیدواژه webdir در فایل پیکربندی manweb شما است، یا دایرکتوری پیش‌فرض /usr/man/web خواهد بود.

پارامترهای فراخوانی شما یک "زنجیره موضوعی" را تشکیل می‌دهند. با حرکت از چپ به راست، اولین پارامتر موضوع اصلی است، دومین پارامتر زیرموضوعی از موضوع اصلی است، و به همین ترتیب ادامه می‌یابد.

بیایید حالت ساده‌ای را بررسی کنیم که در آن دقیقاً یک پارامتر را مشخص می‌کنید -- یک موضوع اصلی. ما آن را maintopic می‌نامیم و به ۴ روشی که ممکن است manweb آن را پیدا کند نگاهی می‌اندازیم:

• اگر manweb فایلی با نام maintopic.html در دایرکتوری وب پیدا کند، نشانی URL که manweb به مرورگر ارسال می‌کند صرفاً یک نشانی با پیشوند file: است که آن فایل .html را مشخص می‌سازد.

• اگر فایل .html وجود نداشته باشد، اما فایلی با نام maintopic.url موجود باشد، محتوای خط اول آن فایل .url همان چیزی است که manweb به مرورگر ارسال می‌کند. برنامه اصلاً این محتوا را تفسیر نمی‌کند؛ اگر داده‌های نامعتبری باشد، مرورگر در باز کردن آن به مشکل می‌خورد.

• اگر نه فایل .html و نه فایل .url وجود داشته باشد، اما دایرکتوری با نام maintopic موجود باشد، manweb در آن دایرکتوری به دنبال فایلی به نام index.html می‌گردد. اگر چنین فایلی وجود داشته باشد، manweb یک نشانی با پیشوند file: که به فایل index.html اشاره دارد را به مرورگر می‌فرستد. اگر index.html وجود نداشته باشد، manweb از یک نشانی با پیشوند file: استفاده می‌کند که به خود دایرکتوری اشاره دارد.

• اگر manweb با هیچ‌یک از روش‌های بالا مستندات را پیدا نکند، مسیر جستجوی فایل‌های اجرایی شما (همان‌طور که توسط متغیر محیطی PATH تعریف شده است) را برای یافتن برنامه‌ای با نام maintopic جستجو می‌کند. اگر برنامه‌ای پیدا کند، در دایرکتوری حاوی آن برنامه به دنبال فایلی با نام doc.url می‌گردد. در صورت یافتن، مقدار maintopic.html را به انتهای خط اول آن فایل اضافه کرده و آن را به مرورگر می‌فرستد؛ مگر اینکه خط اول به اسلش ختم نشده باشد -- در این صورت، manweb خط اول فایل را بدون هیچ تغییری به مرورگر ارسال می‌کند.

هنگامی که زیرموضوعات وجود داشته باشند، ماجرا جذاب‌تر می‌شود. با بررسی هر یک از ۴ حالت بالا:

• در جایی که maintopic.html وجود دارد، تعیین زیرموضوع نامعتبر است. یک پیام هشدار دریافت خواهید کرد و زیرموضوعات نادیده گرفته می‌شوند.

• در جایی که فایل .html وجود ندارد اما maintopic.url موجود است، manweb زنجیره زیرموضوعات را به انتهای URL دریافتی از فایل .url متصل می‌کند؛ همانند این مثال: فایل .url حاوی http://acme.com/productxyz/ است و زیرموضوعات شامل create و database هستند. نشانی که manweb به مرورگر می‌فرستد http://acme.com/productxyz/create/database.html خواهد بود.

  برنامه manweb بررسی نمی‌کند که آیا این نوع الحاق برای نشانی مورد نظر معنادار است یا خیر، به جز اینکه اگر نشانی داخل فایل .url به اسلش (/) ختم نشده باشد، manweb یک پیام هشدار صادر می‌کند و چیزی به انتها الحاق نمی‌کند (زیرموضوعات را نادیده می‌گیرد).

• در جایی که نه فایل .html و نه فایل .url وجود دارد، اما یک دایرکتوری maintopic موجود است، manweb به صورت بازگشتی وارد آن دایرکتوری می‌شود و جستجوی کاملاً جدیدی را با استفاده از نخستین زیرموضوع به عنوان موضوع اصلی و بقیه زیرموضوعات به عنوان زیرموضوع‌های آن آغاز می‌کند.

• هنگامی که زیرموضوعات مشخص شده باشند، جستجوی PATH منطقی نخواهد بود، بنابراین manweb آن را انجام نمی‌دهد.

  اگر زیرموضوعاتی را مشخص کنید، سازوکار PATH که در بالا برای یک موضوع تشریح شد اعمال نمی‌شود.

اگر هیچ پارامتری ارائه ندهید، manweb همان‌طور که در بالا برای زیرپوشه‌ها شرح داده شد، یک URL برای خود دایرکتوری وب ایجاد می‌کند.

توضیحات بالا با فرض وجود تنها یک دایرکتوری وب ساده‌سازی شده است. در واقعیت، کلیدواژه webdir در فایل پیکربندی می‌تواند زنجیره‌ای از دایرکتوری‌های وب را تعیین کند. manweb هر یک از آن‌ها را به نوبت جستجو کرده و قبل از رفتن به دایرکتوری بعدی، تمام انواع جستجوها را در هر دایرکتوری وب به انجام می‌رساند.

فایل پیکربندی (The Configuration File)

مکان پیش‌فرض فایل پیکربندی manweb در مسیر /etc/manweb.conf است. اما می‌توانید آن را با متغیر محیطی MANWEB_CONF_FILE لغو کرده و با گزینه فراخوانی -config نیز مقدار آن را بازنویسی نمایید.

خطوطی که با "#" آغاز می‌شوند دیدگاه (کامنت) بوده و نادیده گرفته می‌شوند؛ خطوط خالی نیز نادیده گرفته خواهند شد.

سایر خطوط دارای قالب keyword=value هستند. کلیدواژه‌های تعریف‌شده عبارتند از:

webdir

دنباله‌ای از دایرکتوری‌ها که با دونقطه (:) از هم جدا شده‌اند تا همان‌طور که در بالا توضیح داده شد برای یافتن مستندات جستجو شوند. اگر این مقدار را مشخص نکنید، پیش‌فرض تنها /usr/man/web است.

browser

مشخصات فایل مرورگر وبی که manweb باید برای نمایش مستندات فراخوانی کند (به جز زمانی که از man برای نمایش صفحه راهنمای سنتی استفاده می‌کند). اگر مشخصات فایل شامل اسلش نباشد، manweb فایل را در مسیر جستجوی PATH جستجو می‌کند.

اگر این گزینه را مشخص نکنید، پیش‌فرض مقدار متغیر محیطی BROWSER خواهد بود و اگر آن متغیر نیز تنظیم نشده باشد، مرورگر lynx به کار می‌رود.

مثال:

# Configuration file for Manweb
webdir=/usr/share/manweb
browser=netscape

نحوه ایجاد مستندات HTML (How To Make HTML Documentation)

صفحات نمایش‌داده‌شده توسط manweb نیازی به قالب خاصی ندارند. می‌توانید با استفاده از هر ابزار تولید صفحه وب یا حتی با تایپ مستقیم کدهای HTML در یک ویرایشگر متنی، هر آنچه می‌خواهید بنویسید.

خوانندگان ممکن است از ساختاری تقریباً مشابه صفحات راهنمای کلاسیک یونیکس (نام، خلاصه دستور و غیره) استقبال کنند.

شما می‌توانید صفحات راهنمای قدیمی nroff/troff را با استفاده از برنامه mandoc به HTML قابل قبولی تبدیل کنید. نیازی نیست صرفاً برای دسترسی به اطلاعات با manweb این کار را انجام دهید، چرا که اگر manweb صفحات HTML را نیابد به عنوان پشتیبان به فراخوانی man روی می‌آورد؛ اما اگر در حال نگهداری مستندات هستید، می‌توانید از این روش به عنوان نقطه شروعی برای نگهداری آن‌ها در قالب HTML در آینده استفاده کنید.

مثال:

    
      $ mandoc -T html foo.1 >foo.html
    

در صورت وجود تعداد زیادی صفحه، می‌توانید از find برای انجام هم‌زمان همه آن‌ها و از parallel برای تسریع فرآیند استفاده کنید.

اگر مجموعه بزرگی از صفحات راهنما را تبدیل می‌کنید، باید با فایل‌های سرایند پیوندخورده و راهنماهای پیونددار (که در آن‌ها صفحه راهنمای troff به صفحات دیگر ارجاع می‌دهد) با دستوری شبیه به این برخورد کنید:

  
      $ mandoc -T html -O includes='./%N.html'; -O man='%N.%S.html' ...
  

این دستور پیوندهای مشابه HTML به نام‌های فایل‌های HTML ایجاد می‌کند، و سپس شما پیوندهای نمادین (symbolic links) را برای آن نام‌ها می‌سازید.