\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Manweb Reference Documentation" 0 "" "netpbm documentation"

.SH "نام (NAME)"
manweb \- مرور مستندات Netpbm (و سایر مستندات)

.UN synopsis
.SH "خلاصه دستور (SYNOPSIS)"

\fBmanweb\fP \fB-help\fP
.PP
\fBmanweb\fP
[\fB-config=\fIconfigfile\fP\fP]
[\fItopic\fP [ \fIsubtopic\fP ... ] ]

.UN examples
.SH "مثال‌ها (EXAMPLES)"

.nf
manweb
.fi
این دستور نمایه اصلی (مستر ایندکس) مستندات را دریافت می‌کند.
.nf
manweb netpbm
.fi
این دستور صفحه اصلی مستندات بسته Netpbm را همراه با پیوندها به سایر بخش‌های مستندات باز می‌کند.
.nf
manweb netpbm pngtopam
.fi
این دستور مستقیماً به صفحه مستندات برنامه Pngtopam در بسته Netpbm می‌رود.
.nf
manweb pngtopam
.fi
این دستور نیز در صورتی که اجرای دستور پوسته \fBpngtopam\fP به اجرای همین برنامه منجر شود (متغیر محیطی \fBPATH\fP در این موضوع دخیل است)، مستقیماً به صفحه مستندات برنامه Pngtopam در بسته Netpbm می‌رود.
.nf
manweb 3 fopen
.fi
این دستور صفحه راهنمای سنتی (man page) زیرروال fopen() را با استفاده از \fBman\fP دریافت می‌کند.
.nf
manweb cp
.fi
این دستور راهنمای GNU Info برای برنامه \fBcp\fP را با استفاده از \fBinfo\fP باز می‌کند.


.UN description
.SH "توضیحات (DESCRIPTION)"
.PP
برنامه \fBmanweb\fP مستندات مرجع را از طریق دستورات سریع پوسته نمایش می‌دهد. این برنامه جایگزینی برای دستور نام‌آشنای \fBman\fP است.

.SH "تفاوت‌های میان Man و Manweb (Differences Between Man and Manweb)"
.PP
مزایای \fBmanweb\fP نسبت به \fBman\fP عبارتند از:


.IP \(bu

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

.IP \(bu

مستندات می‌توانند به زبان HTML باشند، که نسبت به قالب nroff/troff مورد استفاده در \fBman\fP، بسیار شناخته‌شده‌تر، کاربردی‌تر و گویاتر است.

.IP \(bu

برنامه \fBmanweb\fP موضوعات شما را در ساختار درختی برای مستندات چندسطحی قرار می‌دهد. برنامه \fBman\fP برای یک سطح از مستندات طراحی شده است؛ به عنوان مثال، شما می‌توانید برای هر دستور پوسته یک صفحه راهنما داشته باشید، اما نمی‌توانید برای زیردستورهای یک دستور پوسته صفحه جداگانه‌ای داشته باشید. همچنین نمی‌توانید به درستی برای اعضای کتابخانه‌های گوناگون زیرروال، صفحات راهنمای مناسب داشته باشید.

.IP \(bu

مستندات می‌توانند دارای ابرپیوند (hyperlink) باشند.

.PP
نیازی نیست که کارسازهای وب حتماً درگیر باشند -- مستندات می‌توانند در فایل‌های محلی قرار داشته باشند. همچنین نیازی به گرافیک نیست -- مرورگر متنی \fBlynx\fP در همان پایانه‌هایی که \fBman\fP در آن‌ها کار می‌کند، به خوبی پاسخگوست.
.PP
برنامه \fBmanweb\fP مستنداتی را که مشخص کرده‌اید پیدا می‌کند و مرورگر وب انتخابی شما را برای نمایش آن فراخوانی می‌نماید. مستنداتی که \fBmanweb\fP می‌یابد می‌تواند یک فایل HTML روی سامانه شما باشد (که در این صورت، \fBmanweb\fP یک نشانی با پیشوند \fBfile:\fP به مرورگر شما می‌دهد) یا یک نشانی اینترنتی (URL) صریح باشد. آن نشانی صریح ممکن است یک URL با پیشوند \fBhttp:\fP باشد که به یک فایل HTML روی یک کارساز وب اشاره دارد، یا هر چیز دیگری که مرورگر شما آن را بشناسد.
.PP
اگر \fBmanweb\fP نه فایل HTML و نه URL پیدا کند، اما پارامترهای ارسالی شما طوری به نظر برسند که ممکن است برای \fBman\fP معنایی داشته باشند، \fBmanweb\fP دستور \fBman\fP را فراخوانی می‌کند. بنابراین، می‌توانید از یک دستور واحد برای دسترسی به مجموعه عظیم صفحات راهنمای سنتی به علاوه هرگونه مستندات جدیدتر \fBmanweb\fP استفاده کنید. شما می‌توانید در پوسته نام مستعار (alias) "man" را برای "manweb" تعریف کنید.
.PP
برنامه \fBmanweb\fP مستندات Info را نیز پیدا می‌کند. این برنامه پس از جستجو برای مستندات HTML و URL و پیش از اجرای \fBman\fP، به دنبال موضوع مشخص‌شده به عنوان یک سرفصل Info می‌گردد. اگر \fBmanweb\fP سرفصل Info متناظری پیدا کند، برنامه \fBinfo\fP را روی آن اجرا می‌کند. سیستم Info همان سامانه مستندسازی است که پروژه گنو از جمله برای جایگزینی صفحات راهنمای سنتی یونیکس ابداع کرد. با این حال، HTML و وب جهانی اندکی پس از آن اختراع شدند و از این رو Info چندان فراگیر نشد، اما هنوز هم نرم‌افزارهای گنوی زیادی وجود دارند که مستندات آن‌ها به صورت سرفصل‌های Info است.

.SS "نحوه یافتن مستندات توسط Manweb (How Manweb Finds Documentation)"
.PP
برنامه \fBmanweb\fP یک نشانی اینترنتی (URL) را به یک مرورگر وب ارسال می‌کند. این بخش توضیح می‌دهد که پارامترهای فراخوانی \fBmanweb\fP چگونه به آن URL تبدیل می‌شوند.
.PP
جستجوی \fBmanweb\fP در "دایرکتوری وب" (web directory) آغاز می‌شود. این دایرکتوری یا مقدار کلیدواژه \fBwebdir\fP در فایل پیکربندی \fBmanweb\fP شما است، یا دایرکتوری پیش‌فرض \fB/usr/man/web\fP خواهد بود.
.PP
پارامترهای فراخوانی شما یک "زنجیره موضوعی" را تشکیل می‌دهند. با حرکت از چپ به راست، اولین پارامتر موضوع اصلی است، دومین پارامتر زیرموضوعی از موضوع اصلی است، و به همین ترتیب ادامه می‌یابد.
.PP
بیایید حالت ساده‌ای را بررسی کنیم که در آن دقیقاً یک پارامتر را مشخص می‌کنید -- یک موضوع اصلی. ما آن را \fImaintopic\fP می‌نامیم و به ۴ روشی که ممکن است \fBmanweb\fP آن را پیدا کند نگاهی می‌اندازیم:


.IP \(bu

.sp
اگر \fBmanweb\fP فایلی با نام \fImaintopic\fP\fB.html\fP در دایرکتوری وب پیدا کند، نشانی URL که \fBmanweb\fP به مرورگر ارسال می‌کند صرفاً یک نشانی با پیشوند \fBfile:\fP است که آن فایل .html را مشخص می‌سازد.

.IP \(bu

.sp
اگر فایل .html وجود نداشته باشد، اما فایلی با نام \fImaintopic\fP\fB.url\fP موجود باشد، محتوای خط اول آن فایل .url همان چیزی است که \fBmanweb\fP به مرورگر ارسال می‌کند. برنامه اصلاً این محتوا را تفسیر نمی‌کند؛ اگر داده‌های نامعتبری باشد، مرورگر در باز کردن آن به مشکل می‌خورد.

.IP \(bu

.sp
اگر نه فایل .html و نه فایل .url وجود داشته باشد، اما دایرکتوری با نام \fImaintopic\fP موجود باشد، \fBmanweb\fP در آن دایرکتوری به دنبال فایلی به نام \fIindex.html\fP می‌گردد. اگر چنین فایلی وجود داشته باشد، \fBmanweb\fP یک نشانی با پیشوند \fBfile:\fP که به فایل index.html اشاره دارد را به مرورگر می‌فرستد. اگر \fIindex.html\fP وجود نداشته باشد، \fBmanweb\fP از یک نشانی با پیشوند \fBfile:\fP استفاده می‌کند که به خود دایرکتوری اشاره دارد.

.IP \(bu

.sp
اگر \fBmanweb\fP با هیچ‌یک از روش‌های بالا مستندات را پیدا نکند، مسیر جستجوی فایل‌های اجرایی شما (همان‌طور که توسط متغیر محیطی \fBPATH\fP تعریف شده است) را برای یافتن برنامه‌ای با نام \fImaintopic\fP جستجو می‌کند. اگر برنامه‌ای پیدا کند، در دایرکتوری حاوی آن برنامه به دنبال فایلی با نام \fBdoc.url\fP می‌گردد. در صورت یافتن، مقدار \fImaintopic\fP\fB.html\fP را به انتهای خط اول آن فایل اضافه کرده و آن را به مرورگر می‌فرستد؛ مگر اینکه خط اول به اسلش ختم \fIنشده\fP باشد -- در این صورت، \fBmanweb\fP خط اول فایل را بدون هیچ تغییری به مرورگر ارسال می‌کند.
       
.PP
هنگامی که زیرموضوعات وجود داشته باشند، ماجرا جذاب‌تر می‌شود. با بررسی هر یک از ۴ حالت بالا:


.IP \(bu

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

.IP \(bu

در جایی که فایل .html وجود ندارد اما \fImaintopic\fP\fB.url\fP موجود است، \fBmanweb\fP زنجیره زیرموضوعات را به انتهای URL دریافتی از فایل .url متصل می‌کند؛ همانند این مثال: فایل .url حاوی \fBhttp://acme.com/productxyz/\fP است و زیرموضوعات شامل \fBcreate\fP و \fBdatabase\fP هستند. نشانی که \fBmanweb\fP به مرورگر می‌فرستد \fBhttp://acme.com/productxyz/create/database.html\fP خواهد بود.
.sp
برنامه \fBmanweb\fP بررسی نمی‌کند که آیا این نوع الحاق برای نشانی مورد نظر معنادار است یا خیر، به جز اینکه اگر نشانی داخل فایل .url به اسلش (\fB/\fP) ختم نشده باشد، \fBmanweb\fP یک پیام هشدار صادر می‌کند و چیزی به انتها الحاق نمی‌کند (زیرموضوعات را نادیده می‌گیرد).
.IP \(bu

در جایی که نه فایل .html و نه فایل .url وجود دارد، اما یک دایرکتوری \fImaintopic\fP موجود است، \fBmanweb\fP به صورت بازگشتی وارد آن دایرکتوری می‌شود و جستجوی کاملاً جدیدی را با استفاده از نخستین زیرموضوع به عنوان موضوع اصلی و بقیه زیرموضوعات به عنوان زیرموضوع‌های آن آغاز می‌کند.
.IP \(bu

هنگامی که زیرموضوعات مشخص شده باشند، جستجوی \fBPATH\fP منطقی نخواهد بود، بنابراین \fBmanweb\fP آن را انجام نمی‌دهد.


اگر زیرموضوعاتی را مشخص کنید، سازوکار \fBPATH\fP که در بالا برای یک موضوع تشریح شد اعمال نمی‌شود.
.PP
اگر هیچ پارامتری ارائه ندهید، \fBmanweb\fP همان‌طور که در بالا برای زیرپوشه‌ها شرح داده شد، یک URL برای خود دایرکتوری وب ایجاد می‌کند.
.PP
توضیحات بالا با فرض وجود تنها یک دایرکتوری وب ساده‌سازی شده است. در واقعیت، کلیدواژه \fBwebdir\fP در فایل پیکربندی می‌تواند زنجیره‌ای از دایرکتوری‌های وب را تعیین کند. \fBmanweb\fP هر یک از آن‌ها را به نوبت جستجو کرده و قبل از رفتن به دایرکتوری بعدی، تمام انواع جستجوها را در هر دایرکتوری وب به انجام می‌رساند.

.SS "فایل پیکربندی (The Configuration File)"
.PP
مکان پیش‌فرض فایل پیکربندی \fBmanweb\fP در مسیر \fB/etc/manweb.conf\fP است. اما می‌توانید آن را با متغیر محیطی \fBMANWEB_CONF_FILE\fP لغو کرده و با گزینه فراخوانی \fB-config\fP نیز مقدار آن را بازنویسی نمایید.
.PP
خطوطی که با "#" آغاز می‌شوند دیدگاه (کامنت) بوده و نادیده گرفته می‌شوند؛ خطوط خالی نیز نادیده گرفته خواهند شد.
.PP
سایر خطوط دارای قالب \fIkeyword\fP=\fIvalue\fP هستند. کلیدواژه‌های تعریف‌شده عبارتند از:

.TP
webdir
  
دنباله‌ای از دایرکتوری‌ها که با دونقطه (:) از هم جدا شده‌اند تا همان‌طور که در بالا توضیح داده شد برای یافتن مستندات جستجو شوند. اگر این مقدار را مشخص نکنید، پیش‌فرض تنها \fB/usr/man/web\fP است.
.TP
browser
  
مشخصات فایل مرورگر وبی که \fBmanweb\fP باید برای نمایش مستندات فراخوانی کند (به جز زمانی که از \fBman\fP برای نمایش صفحه راهنمای سنتی استفاده می‌کند). اگر مشخصات فایل شامل اسلش نباشد، \fBmanweb\fP فایل را در مسیر جستجوی PATH جستجو می‌کند.
.sp
اگر این گزینه را مشخص نکنید، پیش‌فرض مقدار متغیر محیطی \fBBROWSER\fP خواهد بود و اگر آن متغیر نیز تنظیم نشده باشد، مرورگر \fBlynx\fP به کار می‌رود.


مثال:
.nf
# Configuration file for Manweb

webdir=/usr/share/manweb
browser=netscape
.fi

.SS "نحوه ایجاد مستندات HTML (How To Make HTML Documentation)"
.PP
صفحات نمایش‌داده‌شده توسط \fBmanweb\fP نیازی به قالب خاصی ندارند. می‌توانید با استفاده از هر ابزار تولید صفحه وب یا حتی با تایپ مستقیم کدهای HTML در یک ویرایشگر متنی، هر آنچه می‌خواهید بنویسید.
.PP
خوانندگان ممکن است از ساختاری تقریباً مشابه صفحات راهنمای کلاسیک یونیکس (نام، خلاصه دستور و غیره) استقبال کنند.
.PP
شما می‌توانید صفحات راهنمای قدیمی nroff/troff را با استفاده از برنامه \fBmandoc\fP به HTML قابل قبولی تبدیل کنید. نیازی نیست صرفاً برای دسترسی به اطلاعات با \fBmanweb\fP این کار را انجام دهید، چرا که اگر \fBmanweb\fP صفحات HTML را نیابد به عنوان پشتیبان به فراخوانی \fBman\fP روی می‌آورد؛ اما اگر در حال نگهداری مستندات هستید، می‌توانید از این روش به عنوان نقطه شروعی برای نگهداری آن‌ها در قالب HTML در آینده استفاده کنید.
.PP
مثال:

.nf
    \f(CW
      $ mandoc -T html foo.1 >foo.html
    \fP
.fi
.PP
در صورت وجود تعداد زیادی صفحه، می‌توانید از \fBfind\fP برای انجام هم‌زمان همه آن‌ها و از \fBparallel\fP برای تسریع فرآیند استفاده کنید.
.PP
اگر مجموعه بزرگی از صفحات راهنما را تبدیل می‌کنید، باید با فایل‌های سرایند پیوندخورده و راهنماهای پیونددار (که در آن‌ها صفحه راهنمای troff به صفحات دیگر ارجاع می‌دهد) با دستوری شبیه به این برخورد کنید:

.nf
  \f(CW
      $ mandoc -T html -O includes='./%N.html'; -O man='%N.%S.html' ...
  \fP
.fi

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

 
.SH "منبع مستندات (DOCUMENT SOURCE)"
این صفحه راهنما توسط ابزار 'makeman' بسته Netpbm از منبع HTML تولید شده است. مستندات اصلی در آدرس زیر قرار دارد:
.IP
.B http://netpbm.sourceforge.net/doc/manweb.html
.PP