). این گزینه عنوان خروجی HTML را روی string مشخص‌شده تنظیم می‌کند. -topm lines آرگومان lines تعداد خطوط نشان‌دهنده حاشیه بالای ورودی قالب‌بندی‌شده nroff را مشخص می‌کند. شمارش خطوط شامل هرگونه سربرگ جاری نیز می‌شود. مقدار پیش‌فرض 7 است. -uelem name از name به عنوان نام عنصری استفاده می‌کند که کاراکترهای دارای خط زیرین را در بر می‌گیرد. مقدار پیش‌فرض I است. فایل نگاشت عنوان بخش (SECTION HEAD MAP FILE) گزینه -headmap می‌تواند برای سفارشی‌سازی اینکه کدام برچسب‌های سربرگ HTML، <H1> ... <H6>، در عناوین بخش‌های صفحه راهنما استفاده شوند به کار رود. به‌طور معمول، man2html خطوطی را که هم‌تراز با حاشیه چپ هستند (-leftm) و دارای چاپ مجدد هستند (بررسی چاپ مجدد با گزینه -sun لغو می‌شود) به عنوان سربرگ بخش‌ها در نظر می‌گیرد. با این حال، می‌توانید برچسب‌های سربرگ HTML مورد استفاده برای هر عنوان بخش دلخواه را اضافه یا بازنویسی کنید. برای نوشتن یک فایل نگاشت عنوان بخش، باید با آرایه‌های انجمنی (associative arrays) در perl(1) آشنا باشید. برای نوشتن فایل نگاشت نیازی نیست که در perl متخصص باشید، با این حال داشتن دانش در مورد perl به شما امکان می‌دهد هوشمندانه‌تر عمل کنید. افزودن به نگاشت پیش‌فرض (Augmenting the Default Map) برای افزودن به نگاشت پیش‌فرض تعریف‌شده توسط man2html، فایل نگاشت شما شامل خطوطی با ساختار زیر خواهد بود: $SectionHead{'<section head text>'} = '<html header tag>'; که در آن <section head text> متن عنوان بخش صفحه راهنما است. برای نمونه: SYNOPSIS یا DESCRIPTION. <html header tag> برچسب سربرگ HTML است که عنوان بخش در آن قرار می‌گیرد. مقادیر مجاز عبارتند از: <H1>، <H2>، <H3>، <H4>، <H5>، <H6>. بازنویسی نگاشت پیش‌فرض (Overriding the Default Map) برای بازنویسی نگاشت پیش‌فرض با مقادیر دلخواه خود، فایل نگاشت شما دارای ساختار زیر خواهد بود: %SectionHead = ( '<section head text>', '<html header tag>', '<section head text>', '<html header tag>', # ... More section head/tag pairs '<section head text>', '<html header tag>', ); نگاشت پیش‌فرض (The Default Map) در زمان نگارش این مستند، این نگاشت پیش‌فرضی است که توسط man2html استفاده می‌شود: %SectionHead = ( '\S.*OPTIONS.*' => '<H2>', 'AUTHORS?' => '<H2>', 'BUGS' => '<H2>', 'COMPATIBILITY' => '<H2>', 'DEPENDENCIES' => '<H2>', 'DESCRIPTION' => '<H2>', 'DIAGNOSTICS' => '<H2>', 'ENVIRONMENT' => '<H2>', 'ERRORS' => '<H2>', 'EXAMPLES' => '<H2>', 'EXTERNAL INFLUENCES' => '<H2>', 'FILES' => '<H2>', 'LIMITATIONS' => '<H2>', 'NAME' => '<H2>', 'NOTES?' => '<H2>', 'OPTIONS' => '<H2>', 'REFERENCES' => '<H2>', 'RETURN VALUE' => '<H2>', 'SECTION.*:' => '<H2>', 'SEE ALSO' => '<H2>', 'STANDARDS CONFORMANCE' => '<H2>', 'STYLE CONVENTION' => '<H2>', 'SYNOPSIS' => '<H2>', 'SYNTAX' => '<H2>', 'WARNINGS' => '<H2>', '\s+Section.*:' => '<H3>', ); $HeadFallback = '<H2>'; # Fallback tag if above is not found. کد منبع perl برنامه man2html را برای آخرین نگاشت پیش‌فرض بررسی کنید. در صورت تمایل می‌توانید متغیر $HeadFallback را به مقدار دیگری تغییر دهید. این مقدار به عنوان برچسب سربرگ یک بخش استفاده می‌شود اگر هیچ تطابقی در نگاشت %SectionHead پیدا نشود. استفاده از عبارات منظم در فایل نگاشت (Using Regular Expressions in the Map File) شاید متوجه کاراکترهای نامتعارف در فایل نگاشت پیش‌فرض، مانند "\s" یا "*" شده باشید. ابزار man2html در واقع <section head text> را به عنوان یک عبارت منظم (regular expression) در perl در نظر می‌گیرد. اگر با عبارات منظم perl آشنایی دارید، می‌توانید از تمام قابلیت‌های آن‌ها در فایل نگاشت خود استفاده کنید. هشدار: ابزار man2html از قبل عبارت منظم را با فاصله‌گذاری حاشیه سمت چپ که توسط گزینه -leftm مشخص شده به ابتدای خط متصل (anchor) می‌کند. بنابراین، از کاراکتر `^' برای متصل کردن عبارت منظم خود به ابتدا استفاده نکنید. با این حال، می‌توانید عبارت خود را با `$' پایان دهید تا به انتهای خط متصل شود. از آنجا که <section head text> در واقع یک عبارت منظم است، اگر می‌خواهید کاراکترها به صورت لغوی (literal) تفسیر شوند، باید مراقب کاراکترهای خاص باشید. هر یک از کاراکترهای `[ ] ( ) . ^ { } $ * ? + |' اگر می‌خواهید perl با آن‌ها «همان‌گونه که هستند» رفتار کند، باید با قرار دادن پیشوند کاراکتر `\' اسکیپ شوند. هشدار: برای مشخص کردن محدوده <section head text> باید به جای نقل‌قول دوتایی (double quotes) از نقل‌قول تکی (single quotes) استفاده شود. این کار هر کاراکتر `\' را برای اسکیپ کاراکترها یا زمانی که `\' برای دنباله‌های تطبیق کاراکتر خاص perl (مانند \s، \w، \S) استفاده می‌شود حفظ می‌کند. نکات دیگر درباره فایل نگاشت (Other Tid-bits on the Map File) توضیحات (کامنت‌ها) را می‌توان با استفاده از کاراکتر '#' در فایل نگاشت درج کرد. هر چیزی پس از کاراکتر '#' و شامل خود آن، تا انتهای خط نادیده گرفته می‌شود. شاید فکر کنید موارد فوق صرفاً برای مشخص کردن عناوین بخش‌های صفحات راهنما حجم زیادی از مطالب است. با این حال، شگفت‌زده خواهید شد که خروجی HTML با برچسب‌های سربرگ چقدر بهتر به نظر می‌رسد، حتی با اینکه سایر موارد درون برچسب <PRE> قرار دارند. پیوند به دیگر صفحات راهنما (LINKING TO OTHER MANPAGES) ابزار man2html امکان پیوند دادن به سایر مراجع صفحات راهنما را فراهم می‌کند. اگر گزینه -cgiurl مشخص شده باشد، man2html لنگرهایی (anchors) ایجاد می‌کند که به سایر صفحات راهنما پیوند دارند. نشانی URL وارد شده با گزینه -cgiurl در واقع یک الگو است که URL واقعی مورد استفاده برای پیوند به سایر صفحات راهنما را تعیین می‌کند. متغیرهای زیر در زمان اجرا تعریف می‌شوند که می‌توان از آن‌ها در رشته الگو استفاده کرد: $title عنوان صفحه راهنمای ارجاع داده شده. $section شماره بخش صفحه راهنمای ارجاع داده شده. $subsection زیربخش صفحه راهنمای ارجاع داده شده. هر متن دیگری در الگو «همان‌طور که هست» حفظ می‌شود. هشدار: ابزار man2html رشته الگو را به عنوان یک عبارت رشته‌ای perl ارزیابی می‌کند. بنابراین ممکن است لازم باشد نام متغیرها را با '{}' (مانند ${title}) احاطه کنید تا man2html متغیر را به درستی تشخیص دهد. نکته: اگر برنامه CGI فراخواننده man2html در واقع یک اسکریپت شل یا یک برنامه perl است، مطمئن شوید که کاراکتر '$' را در الگوی URL به درستی اسکیپ کرده‌اید تا از جایگزینی متغیر توسط برنامه CGI جلوگیری شود. به‌طور معمول، URL یک برنامه CGI را فراخوانی می‌کند (از این رو نام گزینه cgiurl است)، اما این URL می‌تواند به راحتی به اسنادی که به صورت ایستا تبدیل شده‌اند نیز پیوند دهد. مثال ۱ (Example1): رشته الگوی زیر برای فراخوانی یک برنامه CGI جهت بازیابی صفحه راهنمای مربوطه مشخص شده است: /cgi-bin/man.cgi?section=${section}${subsection}&topic=${title} اگر به صفحه راهنمای ls(1) در بخش همچنین ببینید (SEE ALSO) ارجاع داده شود، الگوی بالا به URL زیر ترجمه می‌شود: /cgi-bin/man.cgi?section=1&topic=ls نشانه‌گذاری واقعی HTML شبیه به زیر خواهد بود: <A HREF="/cgi-bin/man.cgi?section=1&topic=ls">ls(1)</A> مثال ۲ (Example2): رشته الگوی زیر برای بازیابی صفحات راهنمای از پیش تبدیل‌شده مشخص شده است: http://foo.org/man$section/$title.$section$subsection.html اگر به صفحه راهنمای mount(1M) ارجاع داده شود، الگوی بالا به URL زیر ترجمه می‌شود: http://foo.org/man1/mount.1M.html نشانه‌گذاری واقعی HTML شبیه به زیر خواهد بود: <A HREF="http://foo.org/man1/mount.1M.html">mount(1M)</A> -cgiurlexp گزینه -cgiurlexp شکل عمومی‌تری از گزینه -cgiurl است. -cgiurlexp امکان مشخص کردن یک عبارت عمومی پرل را فراهم می‌کند. برای مثال: $title=~/^db_/i?"$title.html":"/cgi-bin/man?$title+$section" یک string در -cgiurl را می‌توان با -cgiurlexp به صورت زیر بیان کرد: return "string" جستجوی کلیدواژه (KEYWORD SEARCH) ابزار man2html از طریق استفاده از گزینه -k این قابلیت را دارد که خروجی جستجوی کلیدواژه تولید شده توسط دستورهای man -k یا apropos را پردازش کند. ابزار man2html یک سند HTML از ورودی جستجوی کلیدواژه با قالب زیر تولید خواهد کرد: • تمام مراجع صفحات راهنما بر اساس بخش فهرست می‌شوند. • درون فهرست هر بخش، مراجع صفحات راهنما به ترتیب الفبایی (حساس به حروف بزرگ و کوچک) درون برچسب <DL> مرتب می‌شوند. مراجع صفحات راهنما در بخش <DT> و متن خلاصه در بخش <DD> فهرست می‌شوند. • هر مرجع صفحه راهنمای فهرست‌شده، یک ابرپیوند به صفحه راهنمای اصلی است که توسط گزینه -cgiurl مشخص شده است. این قابلیت پردازش جستجوی کلیدواژه، یک کارکرد افزوده بسیار خوب به رابط فرم‌های WWW برای man(1) می‌بخشد. حتی اگر صفحات راهنما را از طریق برنامه دیگری به صورت ایستا به HTML تبدیل کرده باشید، می‌توانید از man2html و "man -k" برای فراهم آوردن آسان قابلیت جستجوی کلیدواژه برای صفحات راهنمای HTML خود استفاده کنید. پردازش نتایج جستجوی کلیدواژه (Processing Keyword Search Results) متأسفانه استانداردی برای کنترل قالب نتایج جستجوی کلیدواژه وجود ندارد. ابزار man2html تمام تلاش خود را برای مدیریت همه گونه‌های مختلف انجام می‌دهد. با این حال، نتایج جستجوی کلیدواژه تولید شده توسط سیستم‌عامل Solaris به اندازه‌ای با سیستم‌های دیگر متفاوت است که یک گزینه خط فرمان ویژه (-solaris) باید برای مدیریت خروجی آن مشخص شود. نمونه‌ای از نتایج خام جستجوی کلیدواژه در سولاریس: strcpy strcpy (9f) - copy a string from one location to another. strcpy string (3c) - string operations strncpy strcpy (9f) - copy a string from one location to another. strncpy string (3c) - string operations اگر نتایج جستجوی کلیدواژه در سیستم شما به قالب زیر نمایش داده می‌شود: <topic> <actual_manpage> (#) - Description در این صورت لازم است علاوه بر گزینه -k گزینه -solaris را نیز مشخص کنید. نکات تکمیلی (ADDITIONAL NOTES) سیستم‌های مختلف صفحات راهنما را به روش‌های گوناگونی قالب‌بندی می‌کنند. در اینجا فهرستی از گزینه‌های خط فرمان توصیه‌شده برای برخی سیستم‌ها آورده شده است: Convex: <تنظیمات پیش‌فرض باید مناسب باشند> HP: -leftm 1 -topm 8 Sun: -sun (و -solaris هنگام استفاده از -k) برخی از فواصل خطوط در خروجی قالب‌بندی‌شده nroff از بین می‌روند زیرا این فاصله‌گذاری در وسط شکستگی صفحه رخ می‌دهد. این امر هنگامی که man2html متن را صفحه‌زدایی می‌کند، می‌تواند باعث ادغام متونی شود که نباید ادغام می‌شدند. برای جلوگیری از این مشکل، man2html میزان تورفتگی حاشیه را دقیقاً قبل و بعد از شکستگی صفحه پیگیری می‌کند. اگر عرض حاشیه خط بعد از شکستگی صفحه کمتر از خط قبل از شکستگی باشد، آنگاه man2html یک خط خالی در خروجی HTML درج می‌کند. یک ارجاع متقابل در صفحه راهنما توسط شبه‌عبارت زیر شناسایی می‌شود: [A- z.-+_]+([0-9][A-z]?) ابزار man2html در هنگام قرار داشتن در حالت جستجوی کلیدواژه، فقط خطوط دارای " - " (جداکننده عادی بین مراجع صفحات راهنما و متن خلاصه) را تشخیص می‌دهد. ابزار man2html می‌تواند در یک اسکریپت/برنامه CGI برای تبدیل صفحات راهنما در لحظه (on the fly) ادغام شود. این دلیل وجود گزینه -cgiurl است. محدودیت‌ها (LIMITATIONS) ترتیبی که نگاشت عنوان بخش در آن جستجو می‌شود تعریف نشده است. بنابراین اگر دو یا چند <section head text> بتوانند با یک بخش صفحه راهنما تطابق پیدا کنند، هیچ راهی برای تعیین اینکه کدام برچسب نگاشت انتخاب می‌شود وجود ندارد. اگر -seealso مشخص شده باشد، همه ارجاعات متقابل پس از عنوان همچنین ببینید (SEE ALSO) شناسایی می‌شوند. به عبارت دیگر، بخش‌های پس از SEE ALSO ممکن است شامل ارجاعات متقابل دارای ابرپیوند باشند. اشکالات (BUGS) متنی که هم‌تراز با حاشیه سمت چپ است، اما در واقع عنوان بخش نیست، ممکن است به اشتباه عنوان بخش تشخیص داده شود. این اشتباه زمانی که گزینه -sun فعال باشد محتمل‌تر است. نسخه (VERSION) این مستندات man2html نسخه 3.0.1 را توصیف می‌کند. همچنین ببینید (SEE ALSO) man(1), nroff(1), perl(1) http://www.oac.uci.edu/indiv/ehood/man2html.html نویسنده (AUTHOR) Earl Hood ehood@medusa.acs.uci.edu خطاها و از قلم‌افتادگی‌ها (ERRORS AND OMISSIONS) نسخه Troff این سند ابتدا برای نسخه 2.1.0 توسط C. Jeffery Small (jeff@cjsa.com) از طریق رونوشت، قالب‌بندی مجدد، بازآرایی و بازنویسی جزئی محتوای فایل متنی اسکی doc/man2html.txt ایجاد شد. 97/08/12 MAN2HTML(1)

MAN2HTML(1) General Commands Manual MAN2HTML(1) نام (NAME) man2html - تبدیل صفحات راهنمای nroff(1) یونیکس به قالب HTML خلاصه دستور (SYNOPSIS) man2html[-bare] [-belem name] [-botm lines] [-cgiurl string] [-cgiurlexp expr] [-compress] [-headmap mapfile] [-help] [-k] [-leftm chars] [-nodepage] [-noheads] [-pgsize lines] [-seealso] [-solaris] [-sun] [-title string] [-topm lines] [-uelem name] کاربرد متداول: man2html[-options] < infile > outfile man topic | man2html [-options] > outfile توضیحات (DESCRIPTION) فیلتر man2html متن قالب‌بندی‌شده‌ی nroff را از ورودی استاندارد (stdin) می‌خواند و یک سند HTML در خروجی استاندارد (stdout) می‌نویسد. خروجی قالب‌بندی‌شده‌ی nroff درون برچسب‌های

 قرار می‌گیرد، به استثنای
       موارد یا افزوده‌های زیر:

         • عناوین بخش‌ها در برچسب‌های سربرگ header HTML قرار می‌گیرند.  برای
           اطلاعات بیشتر به بخش فایل نگاشت عنوان بخش (SECTION HEAD MAP FILE)
           در زیر مراجعه کنید.  گزینه -noheads می‌تواند برای غیرفعال کردن این
           قابلیت استفاده شود.

         • کلمات پررنگ (Bold) که با دنباله‌های "" مشخص شده‌اند،
           در برچسب‌های  (یا عنصری که از طریق گزینه -belem مشخص شده است)
           قرار می‌گیرند.

         • کلمات زیرخط‌دار که با دنباله‌های "_" مشخص شده‌اند، در
           برچسب‌های  (یا عنصری که از طریق گزینه -uelem مشخص شده است) قرار
           می‌گیرند.

گزینه‌ها (OPTIONS)
       -bare
            این گزینه برچسب‌های  و  HTML را از خروجی حذف می‌کند.
            این قابلیت زمانی مفید است که بخواهید خروجی را در یک سند HTML دیگر
            ادغام کنید.

       -belem name
            از name به عنوان نام عنصری استفاده می‌کند که کاراکترهای با چاپ مجدد
            (overstrike) را در بر می‌گیرد.  مقدار پیش‌فرض B است.

       -botm lines
            آرگومان lines تعداد خطوط نشان‌دهنده حاشیه پایین ورودی قالب‌بندی‌شده
            nroff را مشخص می‌کند.  شمارش خطوط شامل هرگونه پاورقی جاری نیز
            می‌شود.  مقدار پیش‌فرض 7 است.

       -cgiurl string
            آرگومان string یک URL الگو برای ایجاد پیوند به سایر صفحات راهنما
            مشخص می‌کند.  برای اطلاعات بیشتر به بخش پیوند به دیگر صفحات راهنما
            (LINKING TO OTHER MANPAGES) در زیر مراجعه کنید.

       -cgiurlexp expr
            آرگومان expr یک عبارت پرل (Perl) را مشخص می‌کند که برای ایجاد پیوند
            به سایر صفحات راهنما، به یک URL ارزیابی می‌شود.  برای اطلاعات بیشتر
            به بخش پیوند به دیگر صفحات راهنما (LINKING TO OTHER MANPAGES) در
            زیر مراجعه کنید.

       -compress
            خطوط خالی متوالی را در یک خط فشرده و ادغام می‌کند.

       -headmap mapfile
            آرگومان mapfile خوانده می‌شود تا مشخص شود کدام برچسب‌های سربرگ HTML
            باید برای عناوین بخش‌های مختلف در صفحه راهنما استفاده شوند.  برای
            اطلاعات درباره قالب فایل نگاشت به بخش فایل نگاشت عنوان بخش
            (SECTION HEAD MAP FILE) در زیر مراجعه کنید.

       -help
            یک پیام راهنمای خلاصه چاپ کرده و فوراً خارج می‌شود.

       -k   ورودی حاصل از جستجوی کلیدواژه صفحه راهنما را پردازش می‌کند
            (man -k).  برای اطلاعات بیشتر به بخش جستجوی کلیدواژه (KEYWORD
            SEARCH) در زیر مراجعه کنید.

       -leftm chars
            آرگومان chars عرض تعداد کاراکترهای تشکیل‌دهنده حاشیه سمت چپ ورودی
            قالب‌بندی‌شده nroff را مشخص می‌کند.  مقدار پیش‌فرض 0 است.

       -nodepage
            به‌طور پیش‌فرض، man2html ورودی‌های چندصفحه‌ای قالب‌بندی‌شده nroff را در
            یک صفحه ادغام می‌کند.  این گزینه می‌تواند برای غیرفعال کردن
            صفحه‌زدایی استفاده شود که باعث می‌شود سربرگ‌ها و پاورقی‌های جاری ورودی
            قالب‌بندی‌شده nroff به خروجی HTML منتقل شوند.

       -noheads
            به‌طور پیش‌فرض، man2html عناوین بخش‌ها را در برچسب‌های سربرگ HTML قرار
            می‌دهد.  برای اطلاعات بیشتر به بخش فایل نگاشت عنوان بخش (SECTION
            HEAD MAP FILE) در زیر مراجعه کنید.  این گزینه می‌تواند برای غیرفعال
            کردن این قابلیت مشخص شود.

       -pgsize lines
            آرگومان lines تعداد خطوط تشکیل‌دهنده اندازه (طول) صفحه ورودی
            قالب‌بندی‌شده nroff را مشخص می‌کند.  مقدار پیش‌فرض 66 است.

       -seealso
            اگر گزینه -cgiurl مشخص شده باشد، این گزینه ایجاد پیوندها به دیگر
            صفحات راهنما را تنها به بخش همچنین ببینید (SEE ALSO) محدود می‌کند.

       -solaris
            اگر گزینه -k مشخص شده باشد، این گزینه عملکرد آن را تغییر می‌دهد تا
            قالب متناوب نتایج جستجوی کلیدواژه صفحه راهنما را که توسط ابزار
            man(1) در سیستم‌های تحت اجرای Solaris تولید می‌شود پردازش کند.  برای
            اطلاعات بیشتر به بخش جستجوی کلیدواژه (KEYWORD SEARCH) در زیر
            مراجعه کنید.

       -sun الزام وجود چاپ مجدد ضخیم (bold overstriking) برای عنوان بخش در
            ورودی قالب‌بندی‌شده nroff را لغو می‌کند.  نام این گزینه sun گذاشته
            شده است زیرا روی یک ایستگاه کاری Sun مشخص شد که عناوین بخش‌ها در
            صفحات راهنما دارای چاپ مجدد نیستند.

       -title string
            به‌طور پیش‌فرض، man2html عنوان HTML تولید نمی‌کند ().  این
            گزینه عنوان خروجی HTML را روی string مشخص‌شده تنظیم می‌کند.

       -topm lines
            آرگومان lines تعداد خطوط نشان‌دهنده حاشیه بالای ورودی قالب‌بندی‌شده
            nroff را مشخص می‌کند.  شمارش خطوط شامل هرگونه سربرگ جاری نیز می‌شود.
            مقدار پیش‌فرض 7 است.

       -uelem name
            از name به عنوان نام عنصری استفاده می‌کند که کاراکترهای دارای خط
            زیرین را در بر می‌گیرد.  مقدار پیش‌فرض I است.

فایل نگاشت عنوان بخش (SECTION HEAD MAP FILE)
       گزینه -headmap می‌تواند برای سفارشی‌سازی اینکه کدام برچسب‌های سربرگ HTML،
       <H1> ... <H6>، در عناوین بخش‌های صفحه راهنما استفاده شوند به کار رود.
       به‌طور معمول، man2html خطوطی را که هم‌تراز با حاشیه چپ هستند (-leftm) و
       دارای چاپ مجدد هستند (بررسی چاپ مجدد با گزینه -sun لغو می‌شود) به عنوان
       سربرگ بخش‌ها در نظر می‌گیرد.  با این حال، می‌توانید برچسب‌های سربرگ HTML
       مورد استفاده برای هر عنوان بخش دلخواه را اضافه یا بازنویسی کنید.

       برای نوشتن یک فایل نگاشت عنوان بخش، باید با آرایه‌های انجمنی
       (associative arrays) در perl(1) آشنا باشید.  برای نوشتن فایل نگاشت
       نیازی نیست که در perl متخصص باشید، با این حال داشتن دانش در مورد perl
       به شما امکان می‌دهد هوشمندانه‌تر عمل کنید.

   افزودن به نگاشت پیش‌فرض (Augmenting the Default Map)
       برای افزودن به نگاشت پیش‌فرض تعریف‌شده توسط man2html، فایل نگاشت شما شامل
       خطوطی با ساختار زیر خواهد بود:

       $SectionHead{'<section head text>'} = '<html header tag>';

       که در آن

       <section head text>
              متن عنوان بخش صفحه راهنما است.  برای نمونه: SYNOPSIS یا
              DESCRIPTION.

       <html header tag>
              برچسب سربرگ HTML است که عنوان بخش در آن قرار می‌گیرد.  مقادیر
              مجاز عبارتند از: <H1>، <H2>، <H3>، <H4>، <H5>، <H6>.

   بازنویسی نگاشت پیش‌فرض (Overriding the Default Map)
       برای بازنویسی نگاشت پیش‌فرض با مقادیر دلخواه خود، فایل نگاشت شما دارای
       ساختار زیر خواهد بود:

           %SectionHead = (
                    '<section head text>', '<html header tag>',
                    '<section head text>', '<html header tag>',
                    # ... More section head/tag pairs
                    '<section head text>', '<html header tag>',
           );

   نگاشت پیش‌فرض (The Default Map)
       در زمان نگارش این مستند، این نگاشت پیش‌فرضی است که توسط man2html استفاده
       می‌شود:

           %SectionHead = (
               '\S.*OPTIONS.*'             => '<H2>',
               'AUTHORS?'                  => '<H2>',
               'BUGS'                      => '<H2>',
               'COMPATIBILITY'             => '<H2>',
               'DEPENDENCIES'              => '<H2>',
               'DESCRIPTION'               => '<H2>',
               'DIAGNOSTICS'               => '<H2>',
               'ENVIRONMENT'               => '<H2>',
               'ERRORS'                    => '<H2>',
               'EXAMPLES'                  => '<H2>',
               'EXTERNAL INFLUENCES'       => '<H2>',
               'FILES'                     => '<H2>',
               'LIMITATIONS'               => '<H2>',
               'NAME'                      => '<H2>',
               'NOTES?'                    => '<H2>',
               'OPTIONS'                   => '<H2>',
               'REFERENCES'                => '<H2>',
               'RETURN VALUE'              => '<H2>',
               'SECTION.*:'                => '<H2>',
               'SEE ALSO'                  => '<H2>',
               'STANDARDS CONFORMANCE'     => '<H2>',
               'STYLE CONVENTION'          => '<H2>',
               'SYNOPSIS'                  => '<H2>',
               'SYNTAX'                    => '<H2>',
               'WARNINGS'                  => '<H2>',
               '\s+Section.*:'             => '<H3>',
           );
           $HeadFallback = '<H2>';  # Fallback tag if above is not found.

       کد منبع perl برنامه man2html را برای آخرین نگاشت پیش‌فرض بررسی کنید.

       در صورت تمایل می‌توانید متغیر $HeadFallback را به مقدار دیگری تغییر
       دهید.  این مقدار به عنوان برچسب سربرگ یک بخش استفاده می‌شود اگر هیچ
       تطابقی در نگاشت %SectionHead پیدا نشود.

   استفاده از عبارات منظم در فایل نگاشت (Using Regular Expressions in the Map
       File)
       شاید متوجه کاراکترهای نامتعارف در فایل نگاشت پیش‌فرض، مانند "\s" یا "*"
       شده باشید.  ابزار man2html در واقع <section head text> را به عنوان یک
       عبارت منظم (regular expression) در perl در نظر می‌گیرد.  اگر با عبارات
       منظم perl آشنایی دارید، می‌توانید از تمام قابلیت‌های آن‌ها در فایل نگاشت
       خود استفاده کنید.

       هشدار: ابزار man2html از قبل عبارت منظم را با فاصله‌گذاری حاشیه سمت چپ
       که توسط گزینه -leftm مشخص شده به ابتدای خط متصل (anchor) می‌کند.
       بنابراین، از کاراکتر `^' برای متصل کردن عبارت منظم خود به ابتدا استفاده
       نکنید.  با این حال، می‌توانید عبارت خود را با `$' پایان دهید تا به
       انتهای خط متصل شود.

       از آنجا که <section head text> در واقع یک عبارت منظم است، اگر می‌خواهید
       کاراکترها به صورت لغوی (literal) تفسیر شوند، باید مراقب کاراکترهای خاص
       باشید.  هر یک از کاراکترهای `[ ] ( ) . ^ { } $ * ? +  |' اگر می‌خواهید
       perl با آن‌ها «همان‌گونه که هستند» رفتار کند، باید با قرار دادن پیشوند
       کاراکتر `\' اسکیپ شوند.

       هشدار: برای مشخص کردن محدوده <section head text> باید به جای نقل‌قول
       دوتایی (double quotes) از نقل‌قول تکی (single quotes) استفاده شود.  این
       کار هر کاراکتر `\' را برای اسکیپ کاراکترها یا زمانی که `\' برای
       دنباله‌های تطبیق کاراکتر خاص perl (مانند \s، \w، \S) استفاده می‌شود حفظ
       می‌کند.

   نکات دیگر درباره فایل نگاشت (Other Tid-bits on the Map File)
       توضیحات (کامنت‌ها) را می‌توان با استفاده از کاراکتر '#' در فایل نگاشت درج
       کرد.  هر چیزی پس از کاراکتر '#' و شامل خود آن، تا انتهای خط نادیده
       گرفته می‌شود.

       شاید فکر کنید موارد فوق صرفاً برای مشخص کردن عناوین بخش‌های صفحات راهنما
       حجم زیادی از مطالب است.  با این حال، شگفت‌زده خواهید شد که خروجی HTML با
       برچسب‌های سربرگ چقدر بهتر به نظر می‌رسد، حتی با اینکه سایر موارد درون
       برچسب <PRE> قرار دارند.

پیوند به دیگر صفحات راهنما (LINKING TO OTHER MANPAGES)
       ابزار man2html امکان پیوند دادن به سایر مراجع صفحات راهنما را فراهم
       می‌کند.  اگر گزینه -cgiurl مشخص شده باشد، man2html لنگرهایی (anchors)
       ایجاد می‌کند که به سایر صفحات راهنما پیوند دارند.

       نشانی URL وارد شده با گزینه -cgiurl در واقع یک الگو است که URL واقعی
       مورد استفاده برای پیوند به سایر صفحات راهنما را تعیین می‌کند.  متغیرهای
       زیر در زمان اجرا تعریف می‌شوند که می‌توان از آن‌ها در رشته الگو استفاده
       کرد:


           $title عنوان صفحه راهنمای ارجاع داده شده.

           $section
                  شماره بخش صفحه راهنمای ارجاع داده شده.

           $subsection
                  زیربخش صفحه راهنمای ارجاع داده شده.

       هر متن دیگری در الگو «همان‌طور که هست» حفظ می‌شود.

       هشدار: ابزار man2html رشته الگو را به عنوان یک عبارت رشته‌ای perl
       ارزیابی می‌کند.  بنابراین ممکن است لازم باشد نام متغیرها را با '{}'
       (مانند ${title}) احاطه کنید تا man2html متغیر را به درستی تشخیص دهد.

       نکته: اگر برنامه CGI فراخواننده man2html در واقع یک اسکریپت شل یا یک
       برنامه perl است، مطمئن شوید که کاراکتر '$' را در الگوی URL به درستی
       اسکیپ کرده‌اید تا از جایگزینی متغیر توسط برنامه CGI جلوگیری شود.

       به‌طور معمول، URL یک برنامه CGI را فراخوانی می‌کند (از این رو نام گزینه
       cgiurl است)، اما این URL می‌تواند به راحتی به اسنادی که به صورت ایستا
       تبدیل شده‌اند نیز پیوند دهد.

   مثال ۱ (Example1):
       رشته الگوی زیر برای فراخوانی یک برنامه CGI جهت بازیابی صفحه راهنمای
       مربوطه مشخص شده است:

       /cgi-bin/man.cgi?section=${section}${subsection}&topic=${title}

       اگر به صفحه راهنمای ls(1) در بخش همچنین ببینید (SEE ALSO) ارجاع داده
       شود، الگوی بالا به URL زیر ترجمه می‌شود:

       /cgi-bin/man.cgi?section=1&topic=ls

       نشانه‌گذاری واقعی HTML شبیه به زیر خواهد بود:

       <A HREF="/cgi-bin/man.cgi?section=1&topic=ls">ls(1)</A>

   مثال ۲ (Example2):
       رشته الگوی زیر برای بازیابی صفحات راهنمای از پیش تبدیل‌شده مشخص شده است:

       http://foo.org/man$section/$title.$section$subsection.html

       اگر به صفحه راهنمای mount(1M) ارجاع داده شود، الگوی بالا به URL زیر
       ترجمه می‌شود:

       http://foo.org/man1/mount.1M.html

       نشانه‌گذاری واقعی HTML شبیه به زیر خواهد بود:

       <A HREF="http://foo.org/man1/mount.1M.html">mount(1M)</A>

   -cgiurlexp
       گزینه -cgiurlexp شکل عمومی‌تری از گزینه -cgiurl است.  -cgiurlexp امکان
       مشخص کردن یک عبارت عمومی پرل را فراهم می‌کند. برای مثال:

       $title=~/^db_/i?"$title.html":"/cgi-bin/man?$title+$section"

       یک string در -cgiurl را می‌توان با -cgiurlexp به صورت زیر بیان کرد:

       return "string"

جستجوی کلیدواژه (KEYWORD SEARCH)
       ابزار man2html از طریق استفاده از گزینه -k این قابلیت را دارد که خروجی
       جستجوی کلیدواژه تولید شده توسط دستورهای man -k یا apropos را پردازش
       کند.  ابزار man2html یک سند HTML از ورودی جستجوی کلیدواژه با قالب زیر
       تولید خواهد کرد:

         • تمام مراجع صفحات راهنما بر اساس بخش فهرست می‌شوند.

         • درون فهرست هر بخش، مراجع صفحات راهنما به ترتیب الفبایی (حساس به
           حروف بزرگ و کوچک) درون برچسب <DL> مرتب می‌شوند.  مراجع صفحات راهنما
           در بخش <DT> و متن خلاصه در بخش <DD> فهرست می‌شوند.

         • هر مرجع صفحه راهنمای فهرست‌شده، یک ابرپیوند به صفحه راهنمای اصلی است
           که توسط گزینه -cgiurl مشخص شده است.

       این قابلیت پردازش جستجوی کلیدواژه، یک کارکرد افزوده بسیار خوب به رابط
       فرم‌های WWW برای man(1) می‌بخشد.  حتی اگر صفحات راهنما را از طریق برنامه
       دیگری به صورت ایستا به HTML تبدیل کرده باشید، می‌توانید از man2html و
       "man -k" برای فراهم آوردن آسان قابلیت جستجوی کلیدواژه برای صفحات
       راهنمای HTML خود استفاده کنید.

   پردازش نتایج جستجوی کلیدواژه (Processing Keyword Search Results)
       متأسفانه استانداردی برای کنترل قالب نتایج جستجوی کلیدواژه وجود ندارد.
       ابزار man2html تمام تلاش خود را برای مدیریت همه گونه‌های مختلف انجام
       می‌دهد.  با این حال، نتایج جستجوی کلیدواژه تولید شده توسط سیستم‌عامل
       Solaris به اندازه‌ای با سیستم‌های دیگر متفاوت است که یک گزینه خط فرمان
       ویژه (-solaris) باید برای مدیریت خروجی آن مشخص شود.

   نمونه‌ای از نتایج خام جستجوی کلیدواژه در سولاریس:
       strcpy        strcpy (9f)  - copy a string from one location to another.
       strcpy        string (3c)  - string operations
       strncpy       strcpy (9f)  - copy a string from one location to another.
       strncpy       string (3c)  - string operations

       اگر نتایج جستجوی کلیدواژه در سیستم شما به قالب زیر نمایش داده می‌شود:

           <topic>  <actual_manpage> (#) - Description

       در این صورت لازم است علاوه بر گزینه -k گزینه -solaris را نیز مشخص کنید.

نکات تکمیلی (ADDITIONAL NOTES)
       سیستم‌های مختلف صفحات راهنما را به روش‌های گوناگونی قالب‌بندی می‌کنند.  در
       اینجا فهرستی از گزینه‌های خط فرمان توصیه‌شده برای برخی سیستم‌ها آورده شده
       است:

           Convex:   <تنظیمات پیش‌فرض باید مناسب باشند>
           HP:       -leftm 1 -topm 8
           Sun:      -sun (و -solaris هنگام استفاده از -k)

       برخی از فواصل خطوط در خروجی قالب‌بندی‌شده nroff از بین می‌روند زیرا این
       فاصله‌گذاری در وسط شکستگی صفحه رخ می‌دهد.  این امر هنگامی که man2html متن
       را صفحه‌زدایی می‌کند، می‌تواند باعث ادغام متونی شود که نباید ادغام می‌شدند.
       برای جلوگیری از این مشکل، man2html میزان تورفتگی حاشیه را دقیقاً قبل و
       بعد از شکستگی صفحه پیگیری می‌کند.  اگر عرض حاشیه خط بعد از شکستگی صفحه
       کمتر از خط قبل از شکستگی باشد، آنگاه man2html یک خط خالی در خروجی HTML
       درج می‌کند.

       یک ارجاع متقابل در صفحه راهنما توسط شبه‌عبارت زیر شناسایی می‌شود: [A-
       z.-+_]+([0-9][A-z]?)

       ابزار man2html در هنگام قرار داشتن در حالت جستجوی کلیدواژه، فقط خطوط
       دارای " - " (جداکننده عادی بین مراجع صفحات راهنما و متن خلاصه) را تشخیص
       می‌دهد.

       ابزار man2html می‌تواند در یک اسکریپت/برنامه CGI برای تبدیل صفحات راهنما
       در لحظه (on the fly) ادغام شود.  این دلیل وجود گزینه -cgiurl است.

محدودیت‌ها (LIMITATIONS)
       ترتیبی که نگاشت عنوان بخش در آن جستجو می‌شود تعریف نشده است.  بنابراین
       اگر دو یا چند <section head text> بتوانند با یک بخش صفحه راهنما تطابق
       پیدا کنند، هیچ راهی برای تعیین اینکه کدام برچسب نگاشت انتخاب می‌شود وجود
       ندارد.

       اگر -seealso مشخص شده باشد، همه ارجاعات متقابل پس از عنوان همچنین
       ببینید (SEE ALSO) شناسایی می‌شوند.  به عبارت دیگر، بخش‌های پس از SEE ALSO
       ممکن است شامل ارجاعات متقابل دارای ابرپیوند باشند.

اشکالات (BUGS)
       متنی که هم‌تراز با حاشیه سمت چپ است، اما در واقع عنوان بخش نیست، ممکن
       است به اشتباه عنوان بخش تشخیص داده شود.  این اشتباه زمانی که گزینه -sun
       فعال باشد محتمل‌تر است.

نسخه (VERSION)
       این مستندات man2html نسخه 3.0.1 را توصیف می‌کند.

همچنین ببینید (SEE ALSO)
       man(1), nroff(1), perl(1)

       http://www.oac.uci.edu/indiv/ehood/man2html.html

نویسنده (AUTHOR)
       Earl Hood
       ehood@medusa.acs.uci.edu

خطاها و از قلم‌افتادگی‌ها (ERRORS AND OMISSIONS)
       نسخه Troff این سند ابتدا برای نسخه 2.1.0 توسط C. Jeffery Small
       (jeff@cjsa.com) از طریق رونوشت، قالب‌بندی مجدد، بازآرایی و بازنویسی جزئی
       محتوای فایل متنی اسکی doc/man2html.txt ایجاد شد.

                                   97/08/12                        MAN2HTML(1)