Ова датотека документује ГНУ „‘help2man’“ наредбу која производи
једноставне странице упутства из „‘--help’“ и „‘--version’“ излаза
других наредби.

   Ауторска права © 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009,
2010, 2011, 2012, 2013, 2014, 2015, 2020, 2021 Free Software Foundation,
Inc.

   Можете да умножавате и расподељујете вербатим (цд) примерке овог
упутства под условом да су обавештења о ауторским правима и ово
обавештење о дозволи сачуване на свим примерцима.

   Можете да умножавате и да расподељујете измењена издања овог упутства
под условима за вербатим (цд) примерке, под условом да се целокупно
проистекло дело расподељује под условима обавештења о овлашћењу
идентичном овом.

   Можете да умножавате и да расподељујете преводе овог приручника на
други језик, под горе наведеним условима за измењена издања, с тим што
ово обавештење о овлашћењу може бити наведено у преводу који одобри
Фондација.

‘help2man’
**********

„‘help2man’“ производи једноставне странице упутства из „‘--help’“ и
„‘--version’“ излаза других наредби.

1 Преглед за „‘help2man’“
*************************

„‘help2man’“ је алат за самостално стварање једноставних страница
упутства из излаза програма.

   Иако су странице приручника изборне за ГНУ програме других пројеката,
тако их Дебијан захтева (see Странице упутства (стандарди))

   Циљ овог програма је да ауторима софтвера омогући једноставан начин
да у своју дистрибуцију укључе страницу упутства без потребе да тај
документ одржавају.

   С обзиром на програм који даје разумне „‘--help’“ и „‘--version’“
излазе, „‘help2man’“ може преуредити тај излаз у нешто што подсећа на
страницу упутства.

2 Како покренути „‘help2man’“
*****************************

Формат за покретање „‘help2man’“ програма је:

     help2man [ОПЦИЈА]... ИЗВРШНА

   „‘help2man’“ подржава следеће опције:

‘-n НИСКА’
‘--name=НИСКА’
     Користите „НИСКУ“ као опис за „‘НАЗИВ’“ пасус странице упутства.

     Подразумевано (у недостатку нечега бољег) овај пасус садржи
     ‘страницу упутства за ПРОГРАМ ИЗДАЊЕ’.

     Ова опција преписује одељак датотеке укључења „‘[назив]’“ (see
     Укључујући текст).

‘-s ОДЕЉАК’
‘--section ОДЕЉАК’
     Користи „ОДЕЉАК“ као одељак за страницу упутства.  Основни одељак
     је 1.

‘-m УПУТСТВО’
‘--manual=УПУТСТВО’
     Поставља назив одељка упутства на „ОДЕЉАК“, који се користи као
     средишњи наслов за страницу упутства.  Подразумевано ‘Наредбе
     корисника’ се користи за странице у одељку 1, ‘Игре’ за одељак 6 и
     ‘Помагала администрације система’ за одељке 8 и 1M.

‘-S ИЗВОР’
‘--source=ИЗВОР’
     Извор програма користи се као подножје странице, и често садржи
     назив организације или скупа чији је програм део.  Подразумевано
     вредност је назив и издање пакета.

‘-L ЈЕЗИК’
‘--locale=ЈЕЗИК’
     Изаберите излазни језик (основно је ‘C’).  И програм и „‘help2man’“
     морају подржавати дати ЈЕЗИК (see Преведене странице упутства).

‘-i ДАТОТЕКА’
‘--include=ДАТОТЕКА’
     Укључује материјал из ДАТОТЕКЕ (see Укључујући текст).

‘-I ДАТОТЕКА’
‘--opt-include=ДАТОТЕКА’
     Варијанта „‘--include’“ за коришћење у правилима „Makefile“ шаблона
     која не захтева да ДАТОТЕКА постоји.

‘-o ДАТОТЕКА’
‘--output=ДАТОТЕКА’
     Шаље излаз у ДАТОТЕКУ уместо на ‘стд_излаз’.

‘-p ТЕКСТ’
‘--info-page=ТЕКСТ’
     Назив упутства „Texinfo“.

‘-N’
‘--no-info’
     Сузбија укључење параграфа ‘ВИДЕТИ ТАКОЂЕ’ који упућује читаоца на
     „Texinfo“ документацију.

‘-l’
‘--libtool’
     Одбацује „‘lt-’“ префикс из примерка назива програма у сажетку
     („‘libtool’“ ствара скрипте омотача у директоријуму изградње које
     призивају „‘foo’“ као „‘.libs/lt-foo’“).

‘--help’
‘--version’
     Прикажите податке о помоћи или издању.

   По основи „‘help2man’“ прослеђује стандардне опције „‘--help’“ и
„‘--version’“ извршној мада се алтернативе могу навести коришћењем:

‘-h ОПЦИЈА’
‘--help-option=ОПЦИЈА’
     Ниска опције помоћи.

‘-v ОПЦИЈА’
‘--version-option=ОПЦИЈА’
     Ниска опције издања.

‘--version-string=НИСКА’
     Ниска издања.

‘--no-discard-stderr’
     Укључите стандардну грешку приликом обраде излаза опције.

3 ‘--help’ Препоруке
********************

Ево неколико препорука о томе шта да укључите у „‘--help’“ излаз.
Укључивањем овога даје „‘help2man’“-у најбољу прилику да створи
примерену страницу упутства, као и да корисницима буде од користи.

   Видите „See Сучеља линије наредби (стандарде)“ и „See
Странице упутства (стандарде)“, за званичне ГНУ стандарде који се
односе на „‘--help’“ и странице упутства.

   • Сажетак о томе како позвати програм.  Ако се различита коришћења
     програма различито позивају, наведите их све.  На пример (уређено
     за краткоћу):

          Коришћење: cp [ОПЦИЈА]... ОДРЕДИШТЕ ИЗВОРА
            или:     cp [ОПЦИЈА]... ИЗВОР... ДИРЕКТОРИЈУМ
          ...

     Користите „‘argv[0]’“ за назив програма у овим сажецима, баш тако
     какав јесте, без уклањања директоријума.  Ово је за разлику од
     канонског (сталног) назива програма који се користи у
     „‘--version’“.

   • Врло кратко објашњење шта програм ради, укључујући подразумевано
     и/или типично понашање.  На пример, ево за „‘cp’“:

          Умножите ИЗВОР у ОДРЕДИШТЕ, или више ИЗВОР(а) у ДИРЕКТОРИЈУМ.

   • Списак опција, увучен на стубац 2.  Ако програм подржава опције са
     једним знаком, прво њих ставите, а затим еквивалентну дугу опцију
     (ако постоји).  Ако опција захтева аргумент, укључите и њега
     такође, дајући му значећи назив.  Поравнајте описе у прикладни
     стубац, по жељи.  Имајте на уму да да би га „‘help2man’“ исправно
     препознао, опис мора бити одвојен од опција са најмање два размака,
     а описи који се настављају у наредним редовима морају започети у
     истом ступцу.

     Ево опет (уређеног) одломка из „‘cp’“, који приказује кратку опцију
     са еквивалентном дугом опцијом, само дугу опцију, и само кратку
     опцију:

            -a, --archive                исто као „-dpR“
                --backup[=КОНТРОЛА]      прави резерву сваке ...
            -b                           као „--backup“ али ...

     За програме који имају много опција, може бити пожељно поделити
     списак опција на одељке као што су „‘Опште’“, „‘Управљање
     излазом’“, или било шта друго што има смисла у датом случају.
     Обично је најбоље поређати по азбучном речу (прво назив кратке
     опције, а затим дуге) унутар сваког одељка, или читав списак ако
     нема одељака.

   • Све корисне додатне информације о понашању програма, као што су
     утицајне променљиве окружења, даље објашњење опција итд.  На
     пример, „‘cp’“ расправља о „‘УПРАВЉАЊУ_ИЗДАЊЕМ’“ и ретким
     датотекама.

   • Неколико примера уобичајене употребе, по вашем нахођењу.  Један
     добар пример обично вреди хиљаду речи описа, стога се ово врло
     препоручује.

   • На крају, ред који наводи како послати извештаје о грешкама
     е-поштом.  Обично ће „АДРЕСА-ДОПИСИВАЊА“ бити
     „‘bug-PROGRAM@gnu.org’“; користите овај образац за ГНУ програме кад
     год је то могуће.  Такође је добро споменути почетну страницу
     програма, друге дописне листе, итд.

   Програмска сучеља „‘argp’“ и „‘popt’“ вам омогућавају да наведете
описе опција за „‘--help’“ у истој структури као и остатак дефиниције
опције; можете пожелели да размислите о коришћењу ових рутина за
рашчлањивање опција уместо „‘getopt’“.

   Подразумевано „‘help2man’“ има проналазачки приступ за одређивање
одељака странице упутства: ред који се састоји од „‘Опције:’“ на пример
довешће до тога да се следећи текст појави у одељку „‘ОПЦИЈЕ’“, а ред
која почиње са „‘Ауторска права’“ појавиће се у одељку
„‘АУТОРСКА_ПРАВА’“.  Изван овог истраживачког приступа, ред који се
састоји од „‘*Речи*’“ започеће нови одељак, а „‘Речи:’“ нови пододељак.

4 Укључивање додатног текста у излаз
************************************

Додатни статички текст може бити укључен у створену страницу упутства
коришћењем опција „‘--include’“ и „‘--opt-include’“ (see Призивам „help2man“).
Пошто ове датотеке могу бити назване било како, за
доследност предлажемо да користите проширење „‘.h2m’“ за укључене
датотеке „‘help2man’“-а.

   Формат за датотеке укључене са овом опцијом је узорак:

     [одељак]
     текст

     /шаблон/
     текст

   Блокови вербатим „*roff“ текста су уметнути у излаз било на почетак
датог „‘[одељка]’“ (не разликује величину слова), или након пасуса који
одговара „‘/шаблону/’“.

   Шаблони користе синтаксу регуларног израза Перла и могу га пратити
„‘i’“, „‘s’“ или „‘m’“ измењивачи (see perlre(1) (*manpages*))

   Редови пре првог одељка или шаблона који почињу са „‘-’“ се обрађују
као опције.  Све друго се неприметно занемарује и може се користити за
напомене, „RCS“ кључне речи и слично.

   Поредак излаза одељка (за оне укључене) је:

     НАЗИВ
     САЖЕТАК
     ОПИС
     ОПЦИЈЕ
     _друго_
     ОКРУЖЕЊЕ
     ДАТОТЕКЕ
     ПРИМЕРИ
     АУТОР
     ИЗВЕШТАВАЊЕ О ГРЕШКАМА
     АУТОРСКА ПРАВА
     ВИДИТЕ ТАКОЂЕ

   Било који одељци ‘[назива]’ или ‘[сажетка]’ који се појављују у
датотеци укључивања ће заменити оно што ће бити самостално произведено
(иако још увек можете да препишете претходно са „‘--name’“ ако је
потребно).

   Остали одељци се додају аутоматски произведеном излазу за стандардне
одељке дате горе, или се укључују у „_друге_“ (изнад) редом како су
нађени у датотеци за укључивање.

   Стављање текста у одељак може бити изричито затражено коришћењем
синтаксе „‘[<одељак]’“, „‘[=одељак]’“ или „‘[>одељак]’“, за стављање
додатног текста пре, уместо, или после подразумеваног излаза.

5 Коришћење „‘help2man’“ са „‘make’“
************************************

Предложена употреба „‘help2man’“ у „Makefiles“-у је да бисмо имали
страницу упутства која не зависи од извршне, већ од датотеке извора у
којој су „‘--help’“ и „‘--version’“ излази дефинисани.

   Ова употреба омогућава да одржавалац може да створи страницу упутства
и да је укључи у дистрибуцију а да да крајњи корисник не мора да има
инсталиран програм „‘help2man’“.

   Правило примера за програм „‘прог’“ може бити:

     prog.1: $(srcdir)/main.c
             -$(HELP2MAN) --output=$@ --name='програм примера' ./prog

   Вредност за „‘HELP2MAN’“ се може подесити у „‘configure.in’“
користећи нешто од:

     АМ_НЕДОСТАЈУЋИ_ПРОГ(HELP2MAN, help2man)

   за „‘automake’“, или нешто као:

     АЦ_ПУТАЊА_ПРОГ(HELP2MAN, help2man, false // No help2man //)

   за саму „‘autoconf’“.

6 Стварање странице упутства на матерњем језику
***********************************************

Странице упутства се могу произвести за сваки језик кога подржава и
програм и „‘help2man’“ са „‘--locale’“ (‘-L’) опцијом.

     help2man -L fr_FR@euro -o cp.fr.1 cp

   Видите „<http://translationproject.org/domain/help2man.html>“ за
језике које „‘help2man’“ тренутно подржава, и „See Извештаји“ о томе
како да пошаљете друге преводе.

6.1 Промена места каталога порука
=================================

Приликом стварања преведених страница упутства из директоријума за
изградњу програма, највероватније да преводи инсталирани на уобичајеном
месту неће бити (ако су уопште инсталирани) одговарајући за издање
програма који се гради.

   Предучитљиву библиотеку обезбеђује „‘help2man’“ који ће пресрести
„‘bindtextdomain’“ позиве подешавајући место каталога порука за домен
дат „‘$TEXTDOMAIN’“-ом и преписати место до путање дате
„‘$LOCALEDIR’“-ом.

   Тако на пример:

     mkdir -p tmp/sr/LC_MESSAGES
     cp po/sr.gmo tmp/sr/LC_MESSAGES/ПРОГ.mo
     LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
       LOCALEDIR=tmp \
       TEXTDOMAIN=ПРОГ \
       help2man -L sr_SR@euro -i ПРОГ.sr.h2m -o ПРОГ.sr.1 ПРОГ
     rm -rf tmp

   довешће до тога да „ПРОГ“ учита каталог поруке из „‘tmp’“ уместо
„‘/usr/share/locale’“.

   Белешке:
   • Уопштавање „‘sr_SR@euro’“ у „‘sr’“ у горњем примеру је постигнуто
     „‘gettext’“-ом, ако су специфичнија поклапања доступна и она ће
     такође бити поново мапирана.

   • Ово предучитавање је тестирано само за „‘eglibc’ 2.11.2“ и
     „‘gettext’ 0.18.1.1“ на ГНУ/Линукс систему; обавестите ме о томе да
     ли (или не) ради код вас (see Извештаји).

7 Пример „‘help2man’“ излаза
****************************

Дат је хипотетички програм „‘foo’“ који даје следећи излаз:

     $ foo --version
     GNU foo 1.1

     Ауторска права © 2011 Free Software Foundation, Inc.
     Ово је слободан софтвер; видите извор за услове умножавања.  Нема НИКАКВЕ
     гаранције; чак ни о ТРЖИШНОЈ ВРЕДНОСТИ или ПРИЛАГОЂЕНОСТИ ОДРЕЂЕНОЈ НАМЕНИ.

     Написао је А. Програмер.
     $ foo --help
     ГНУ „foo“ не ради ништа занимљиво осим што служи као пример за
     „help2man“.

     Коришћење: foo [ОПЦИЈА]...

     Опције:
       -a, --option      опција
       -b, --another-option[=ВРЕДНОСТ]
                         још једна опција

           --help        приказује ову помоћ и излази
           --version     исписује податке о издању и излази

     Примери:
       foo               не ради ништа
       foo --option      иста ствар, дајући „--option“

     Грешке пријавите на <bug-gnu-utils@gnu.org>.

   „‘help2man’“ ће произвести „‘nroff’“ улаз за страницу упутства која
ће бити форматирана овако некако:

     FOO(1)                         Корисник Наредбе                        FOO(1)

     НАЗИВ
            foo – страница упутства за „foo 1.1“

     САЖЕТАК
            foo [ОПЦИЈА]...

     ОПИС
            ГНУ  „foo“  не ради ништа занимљиво осим што служи као пример за
            „help2man“.

     ОПЦИЈЕ
            -a, --option
                   опција

            -b, --another-option[=ВРЕДНОСТ]
                   друга опција

            --help приказује ову помоћ и излази

            --version
                   исписује податке о издању и излази

     ПРИМЕРИ
            foo    не ради ништа

            foo --option
                   иста ствар, дајући „--option“

     АУТОР
            Написао је А. Програмер.

     ИЗВЕШТАВАЊЕ ГРЕШАКА
            Грешке пријавите на <bug-gnu-utils@gnu.org>.

     АУТОРСКА ПРАВА
            Ауторска права © 2011 Free Software Foundation, Inc.
            Ово је слободан програм;  видите  извор  за  услове  умножавања.
            Нема НИКАКВЕ гаранције; чак ни о ТРЖИШНОЈ ВРЕДНОСТИ или ПРИЛАГОЂЕНОСТИ
            ОДРЕЂЕНОЈ НАМЕНИ.

     ВИДИТЕ ТАКОЂЕ
            Пуна документација за „foo“ се одржава као  „Texinfo“  приручник.
            Ако  су  „info“ и „foo“ програми исправно инсталирани на вашем сајту,
            наредба

                   info foo

            би требало да вам да приступ читавом упутству.

     foo 1.1                          Мај 2011                           FOO(1)

8 Извештавање о грешкама или предлозима
***************************************

Ако наиђете на неприлике или имате предлоге о овом програму или
приручнику, пошаљите извештај на „<bug-help2man@gnu.org>“.

   Напомена за преводиоце: Преводи се налазе на „Пројекту превођења
(http://translationproject.org/)“ видите
„<http://translationproject.org/html/translators.html>“ за појединости.

9 Добијање „‘help2man’“
***********************

Најновије издање ове дистрибуције је доступно на мрежи са ГНУ изворишта:

     <http://ftpmirror.gnu.org/help2man/>

   Ако аутоматско преусмерење не успе, списак изворишта је на:

     <http://www.gnu.org/order/ftp.html>

   Или ако је потребно можете да користите главни ГНУ фтп сервер:
     <http://ftp.gnu.org/gnu/help2man/>