نام (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 درون برچسب‌های <PRE> قرار می‌گیرد، به استثنای موارد یا افزوده‌های زیر:

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

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

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

گزینه‌ها (OPTIONS)

-bare: این گزینه برچسب‌های <HEAD> و <BODY> 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 تولید نمی‌کند (<TITLE>). این گزینه عنوان خروجی 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 ایجاد شد.