Sindbad~EG File Manager

This is help2man-uk.info.tmp, produced by makeinfo version 6.8 from
help2man-uk.texi.

У цьому файлі міститься документація до програми GNU ‘help2man’.
Програму призначено для створення простих сторінок довідника (man) на
основі даних, виведених певною програмою, запущеною із параметрами
‘--help’ та ‘--version’.

   © Free Software Foundation, Inc., 1999–2021

   Цей підручник можна копіювати без змін і поширювати, якщо в усіх
копіях збережено запис про авторські права та цей запис про можливість
копіювання.

   Цей підручник можна копіювати, вносити до копії зміни і поширювати
створені копії, якщо виконано умови копіювання без змін, а уся похідна
робота повинна поширюватися за тих самих умов, що і цей підручник.

   Переклади цього підручника іншими мовами можна копіювати і поширювати
відповідно до викладених вище умов щодо змінених версій, окрім того, що
ці умови може бути перекладено, якщо переклад офіційно затверджено
Фундацією вільного програмного забезпечення.
INFO-DIR-SECTION Розробка програмного забезпечення
START-INFO-DIR-ENTRY
* help2man-uk: (help2man-uk).  Програма для автоматичного створення
				 сторінок підручника (man).
END-INFO-DIR-ENTRY


File: help2man-uk.info.tmp,  Node: Top,  Next: Огляд,  Up: (dir)

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

‘help2man’ призначено для створення простих сторінок довідника (man) на
основі даних, виведених певною програмою, запущеною із параметрами
‘--help’ та ‘--version’.

* Menu:

* Огляд::		       Огляд ‘help2man’.
* Як викликати help2man::      Як запустити‘help2man’.
* Рекомендації щодо --help::   Рекомендованеформатуванняданих,
				 виведенихза допомогою‘--help’.
* Включення тексту::	       Включеннядодаткового текстудо
				 виведенихпрограмою даних.
* Використання Makefile::      Використання‘help2man’ упоєднанні з
				 ‘make’.
* Локалізовані сторінки man::  Створеннясторінокпідручникамовами,відмін
				 нимивіданглійської.
* Приклад::		       Приклад роботи ‘help2man’.
* Звіти::		       Як повідомити про вади
				 тазапропонуватиудосконалення.
* Доступність:: 	       Як отримати ‘help2man’.


File: help2man-uk.info.tmp,  Node: Огляд,  Next: Як викликати help2man,  Prev: Top,  Up: Top

1 Огляд ‘help2man’
******************

‘help2man’ призначено для автоматизованого створення простих сторінок
довідника (mna) на основі даних, виведених програмою, для якої
створюється відповідна сторінка.

   Хоча сторінки підручника і не є обов’язковими для програм GNU, у
інших проектах, зокрема Debian, наявність таких сторінок є обов’язковою
(*note (стандарти)Сторінки man::)

   Цю програму призначено для спрощення для авторів програмного
забезпечення створення сторінки підручника для дистрибутива з програмою
без потреби у постійній роботі з підтримання її актуальності.

   Якщо програма здатна виводити достатньо коректні дані у відповідь на
додавання до команди стандартних параметрів ‘--help’ та ‘--version’,
‘help2man’ може упорядкувати виведені програмою дані у щось, що є
достатньо якісною сторінкою підручника.


File: help2man-uk.info.tmp,  Node: Як викликати help2man,  Next: Рекомендації щодо --help,  Prev: Огляд,  Up: Top

2 Як запустити ‘help2man’
*************************

Формат команди запуску ‘help2man’:

     help2man [ПАРАМЕТР]... ВИКОНУВАНИЙ ФАЙЛ

   У ‘help2man’ передбачено підтримку таких параметрів:

‘-n РЯДОК’
‘--name=РЯДОК’
     Використовувати РЯДОК як опис для розділу ‘NAME’ сторінки
     підручника.

     Типово, якщо немає нічого кращого, відповідний абзац буде таким:
     ‘manual page for ПРОГРАМА НОМЕР ВЕРСІЇ’.

     За допомогою цього параметра можна перевизначити розділ ‘[name]’
     файла включення (*note Включення тексту::).

‘-s РОЗДІЛ’
‘--section РОЗДІЛ’
     Використовувати для сторінки man розділ, вказаний аргументом
     РОЗДІЛ.  Типовим розділом є 1.

‘-m ПІДРУЧНИК’
‘--manual=ПІДРУЧНИК’
     Встановити назву для розділу підручника РОЗДІЛ, яка буде
     центральною частиною заголовка сторінки.  Типово для ‘команд
     користувача’ використовується розділ 1, для ‘ігор’ використовується
     розділ 6, а для ‘програм для адміністрування системи’
     використовуються розділи 8 та 1M.

‘-S ДЖЕРЕЛО’
‘--source=ДЖЕРЕЛО’
     Запис джерела програми використовується як нижній колонтитул
     сторінки і містить назву організації або комплекту програм,
     частиною якого є програма.  Типовим значенням запису є назва
     пакунка і номер версії.

‘-L ЛОКАЛЬ’
‘--locale=ЛОКАЛЬ’
     Вибрати локаль для виведення результатів (типовою є локаль ‘C’).
     Підтримку вказаної ЛОКАЛІ має бути передбачено одночасно у самій
     програмі і у ‘help2man’ (*note Локалізовані сторінки man::).

‘-i ФАЙЛ’
‘--include=ФАЙЛ’
     Включити матеріал з файла ФАЙЛ (*note Включення тексту::).

‘-I ФАЙЛ’
‘--opt-include=ФАЙЛ’
     Варіант ‘--include’ для використання у шаблонних правилах Makefile,
     для якого не потрібне існування файла ФАЙЛ.

‘-o ФАЙЛ’
‘--output=ФАЙЛ’
     Вивести результат до файла ФАЙЛ, а не до ‘stdout’.

‘-p ТЕКСТ’
‘--info-page=ТЕКСТ’
     Назва підручника Texinfo.

‘-N’
‘--no-info’
     Придушити включення абзацу розділу ‘SEE ALSO’, який спрямовував би
     читача до документації з 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’
     Включити дані із stderr під час обробки результатів додавання
     параметра.


File: help2man-uk.info.tmp,  Node: Рекомендації щодо --help,  Next: Включення тексту,  Prev: Як викликати help2man,  Up: Top

3 Рекомендації щодо ‘--help’
****************************

У цьому розділі наведено рекомендації щодо того, що слід включати у
дані, які має виводити ваша програма у відповідь на додавання до
команди, якою вона запускається, параметра ‘--help’.  Виконання цих
рекомендацій надасть змогу ‘help2man’ вивести якісну сторінку man, а
також надасть користувачам кориснішу інформацію.

   Див.  *note (стандарти)Інтерфейси командного рядка:: та *note
(стандарти)Сторінки man::, щоб ознайомитися з офіційними стандартами GNU
щодо використання параметра ‘--help’ та сторінок man.

   • Коротке резюме щодо того, як запускати програму.  Якщо різні режими
     роботи програми потребують використання різних способів запуску,
     наведіть повний список варіантів.  Приклад (для зручності
     скорочено):

          Usage: cp [OPTION]... SOURCE DEST
            or:  cp [OPTION]... SOURCE... DIRECTORY
          ...

     У цих коротких описах використовуйте замість назви програми
     ‘argv[0]’, як є, без вилучення частини із записами каталогів.  Це
     не збігається із канонічною (сталою) назвою програми, яка
     використовується у команді з параметром ‘--version’.

   • Дуже короткий опис призначення програми, зокрема типової поведінки.
     Приклад для програми ‘cp’:

          Копіює ДЖЕРЕЛО у ЦІЛЬ, або декілька ДЖЕРЕЛ у КАТАЛОГ.

   • Список параметрів з відступом до позиції 2 у рядку.  Якщо у
     програмі передбачено використання однолітерних параметрів, пункти
     цих параметрів мають бути на початку рядка, а далі вже має бути
     розширений еквівалентний запис (якщо такий передбачено).  Якщо до
     параметра потрібно додавати аргумент, включіть його до опису,
     надавши йому зрозумілої користувачеві назви.  Вирівняйте описи за
     певною позицією у рядку.  Зауважте, що для того, щоб програма
     ‘help2man’ могла належним чином розпізнати опис, його слід
     відокремити від запису параметра принаймні двома пробілами, а у
     багаторядковому описі другий і наступні рядки мають починатися з
     однієї позиції у рядку.

     Нижче наведено (редагований) приклад з опису параметрів програми
     ‘cp’, з коротким і довгим варіантом параметра, лише довгим
     варіантом параметра і лише коротким варіантом параметра:

            -a, --archive                same as -dpR
                --backup[=CONTROL]       make a backup of each ...
            -b                           like --backup but ...

     Якщо програмі можна передавати багато параметрів, варто розділити
     список параметрів на частини, наприклад, ‘Загальні’, ‘Керування
     виведенням’ тощо.  Зазвичай, параметри варто упорядковувати за
     абеткою (спершу за короткими варіантами записів параметрів, потім
     за довгими) у межах кожної з частин або у межах усього списку, якщо
     у ньому нема частин.

   • Будь-які додаткові дані щодо поведінки програми, зокрема важливі
     для роботи змінні середовища, додаткові відомості щодо параметрів
     тощо.  Наприклад, для програми ‘cp’ можна навести дані щодо змінної
     середовища ‘VERSION_CONTROL’ та розріджених файлів.

   • Декілька прикладів типового використання, за вашим вибором.  Один
     хороший приклад, зазвичай, вартий тисячі слів опису, отже варто
     завжди включати до довідки приклади.

   • На завершення, слід навести настанови щодо адреси, на яку слід
     надсилати повідомлення про вади.  Типовою ПОШТОВОЮ АДРЕСОЮ є
     ‘bug-ПРОГРАМА@gnu.org’.  Варто дотримуватися саме цієї форми, якщо
     йдеться про програму GNU. Також варто згадати адресу домашньої
     сторінки програми, пов’язані із її обговоренням списки листування
     тощо.

   Інтерфейси програмування ‘argp’ та ‘popt’ надають вам змогу вказати
описи параметрів для ‘--help’ з тією самою структурою, що решта описів
параметрів; вам варто скористатися цими підпрограмами для обробки
параметрів замість ‘getopt’.

   Типово, у ‘help2man’ для виявлення розділів сторінки підручника
використовується певна евристика: наприклад, рядок із записом
‘Параметри:’ призведе до того, що наступну за ним частину тексту буде
додано до розділу ‘ПАРАМЕТРИ’, а рядок, що починається зі слова
‘Copyright’ стане частиною розділу ‘COPYRIGHT’.  Окрім цього, рядок, що
містить, наприклад, ‘*Слова*’ стане початком нового розділу, а рядок
‘Слова:’ — нового підрозділу.


File: help2man-uk.info.tmp,  Node: Включення тексту,  Next: Використання Makefile,  Prev: Рекомендації щодо --help,  Up: Top

4 Включення додаткового тексту до виведених програмою даних
***********************************************************

До створеної сторінки підручника можна додати статичний текст за
допомогою параметрів ‘--include’ та ‘--opt-include’ (*note Як викликати
help2man::).  Хоча можна використовувати файли з довільними назвами, для
певності ми рекомендуємо використовувати для файлів включень ‘help2man’
суфікс назви ‘.h2m’.

   Формат даних у файлі, який додається за допомогою цього параметра,
має бути простим:

     [розділ]
     текст

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

   Блоки тексту *roff вставляються до виведених даних або на початку
вказаного ‘[розділу]’ (без врахування регістру), або після абзацу, що
відповідає ‘/шаблону/’.

   У шаблонах використовується синтаксис формальних виразів Perl, можна
використовувати модифікатори ‘i’, ‘s’ або ‘m’ (*note perlre(1):
(*manpages*)perlre.)

   Рядки перед першим розділом або шаблоном, які починаються з набору
символів ‘-’, вважаються визначеннями параметрів.  Всі інші такі рядки
буде проігноровано, ними можна скористатися для коментування, ключових
слів RCS тощо.

   Порядок виведення розділів (для включених розділів):

     NAME
     SYNOPSIS
     DESCRIPTION
     OPTIONS
     _інше_
     ENVIRONMENT
     FILES
     EXAMPLES
     AUTHOR
     REPORTING BUGS
     COPYRIGHT
     SEE ALSO

   Будь-які розділи ‘[name]’ or ‘[synopsis]’ вказані у включеному файлі,
замінять собою відповідні розділи, створені у автоматичному режимі.  Ви
можете зберегти перший з цих розділів за допомогою параметра ‘--name’,
якщо захочете.

   Інші розділи буде додано перед автоматично створеними даними
стандартних розділів, вказаних вище, або буде включено до _іншого_
(вище) у порядку, у якому їх вказано у файлі-включенні.

   Можна явним чином вимагати розташовування тексту у розділі за
допомогою синтаксичної конструкції ‘[<розділ]’, ‘[=розділ]’ або
‘[>розділ]’ для розташовування тексту перед, замість або після типових
виведених даних, відповідно.


File: help2man-uk.info.tmp,  Node: Використання Makefile,  Next: Локалізовані сторінки man,  Prev: Включення тексту,  Up: Top

5 Використання ‘help2man’ у поєднанні з ‘make’
**********************************************

Рекомендованим випадком використання ‘help2man’ у файлах Makefile є
випадок, коли сторінка довідника має залежати не від наявності
виконуваного файла, а від файлів початкових даних, у яких визначено
текст, який виводиться у відповідь на додавання параметрів ‘--help’ та
‘--version’ до команди.

   У такий спосіб можна забезпечити створення сторінки довідника
супровідником пакунка із включенням його до дистрибутива програми, без
потреби для користувача пакунка у встановленні програми ‘help2man’.

   Приклад правила для програми ‘prog’:

     prog.1: $(srcdir)/main.c
             -$(HELP2MAN) --output=$@ --name='an example program' ./prog

   Значення змінної ‘HELP2MAN’ можна встановити у ‘configure.in’ у один
з таких способів:

     AM_MISSING_PROG(HELP2MAN, help2man)

   для ‘automake’ або чимось таким:

     AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)

   для ‘autoconf’.


File: help2man-uk.info.tmp,  Node: Локалізовані сторінки man,  Next: Приклад,  Prev: Використання Makefile,  Up: Top

6 Створення сторінок підручника мовами, відмінними від англійської
******************************************************************

Сторінки підручника можна створити для будь-якої локалі, підтримку якої
передбачено у програмі та у ‘help2man’ за допомогою параметра ‘--locale’
(‘-L’).

     help2man -L uk_UA@euro -o cp.uk.1 cp

   Із поточним списком підтримуваних ‘help2man’ мов можна ознайомитися
тут: <http://translationproject.org/domain/help2man.html>.  Довідку щодо
надсилання нових перекладів наведено у розділі *note Звіти::.

6.1 Як змінити розташування каталогів повідомлень
=================================================

Якщо локалізовані сторінки підручника створюються з каталогу збирання
програми, ймовірно, встановлені до стандартного каталогу сторінки не
відповідатимуть (якщо їх взагалі буде встановлено) версії програми, яка
встановлюватиметься.

   Разом з ‘help2man’ постачається попередньо завантажувана бібліотека,
яка перехоплюватиме виклики ‘bindtextdomain’, налаштовуючи адресу для
каталогів перекладів для домену, вказаного змінною ‘$TEXTDOMAIN’, і
перевизначаючи адресу каталогу, вказаного за допомогою змінної
‘$LOCALEDIR’.

   Приклад:

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

   накаже програмі ПРОГРАМА завантажити каталог повідомлень із
перекладами з ‘tmp’, а не з ‘/usr/share/locale’.

   Примітки:
   • Узагальнення локалі ‘uk_UA@euro’ до ‘uk’ у наведеному вище прикладі
     виконується засобами ‘gettext’.  Якщо буде виявлено специфічнішу
     відповідність, її також буде використано.

   • Цей спосіб попереднього завантаження було перевірено лише для
     ‘eglibc’ 2.11.2 та ‘gettext’ 0.18.1.1 у системі GNU/Linux.
     Повідомте авторові, якщо цей спосіб працює або не працює у вашій
     системі (*note Звіти::).


File: help2man-uk.info.tmp,  Node: Приклад,  Next: Звіти,  Prev: Локалізовані сторінки man,  Up: Top

7 Приклад роботи ‘help2man’
***************************

Припустімо, що якась програма з назвою ‘foo’ виводить такі дані:

     $ foo --version
     GNU foo 1.1

     Copyright (C) 2011 Free Software Foundation, Inc.
     This is free software; see the source for copying conditions.  There is NO
     warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

     Written by A. Programmer.
     $ foo --help
     GNU `foo' does nothing interesting except serve as an example for
     `help2man'.

     Usage: foo [OPTION]...

     Options:
       -a, --option      an option
       -b, --another-option[=VALUE]
                         another option

           --help        display this help and exit
           --version     output version information and exit

     Examples:
       foo               do nothing
       foo --option      the same thing, giving `--option'

     Про вади слід повідомляти на адресу <bug-gnu-utils@gnu.org>.

   ‘help2man’ створити вхідні дані для програми ‘nroff’ для показу
сторінки підручника, формат яких буде приблизно таким:

     FOO(1)                         User Commands                        FOO(1)

     NAME
            foo - manual page for foo 1.1

     SYNOPSIS
            foo [OPTION]...

     DESCRIPTION
            GNU  `foo'  does nothing interesting except serve as an example for
            `help2man'.

     OPTIONS
            -a, --option
                   an option

            -b, --another-option[=VALUE]
                   another option

            --help display this help and exit

            --version
                   output version information and exit

     EXAMPLES
            foo    do nothing

            foo --option
                   the same thing, giving `--option'

     AUTHOR
            Written by A. Programmer.

     REPORTING BUGS
            Report bugs to <bug-gnu-utils@gnu.org>.

     COPYRIGHT
            Copyright © 2011 Free Software Foundation, Inc.
            This is free software;  see  the  source  for  copying  conditions.
            There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
            PARTICULAR PURPOSE.

     SEE ALSO
            The full documentation for foo is maintained as a  Texinfo  manual.
            If  the  info and foo programs are properly installed at your site,
            the command

                   info foo

            should give you access to the complete manual.

     foo 1.1                          May 2011                           FOO(1)


File: help2man-uk.info.tmp,  Node: Звіти,  Next: Доступність,  Prev: Приклад,  Up: Top

8 Як повідомити про вади та запропонувати удосконалення
*******************************************************

Якщо вами буде виявлено вади або у вас виникнуть пропозиції щодо
удосконалення цієї програми або підручника до неї, будь ласка, повідомте
про це, надіславши повідомлення на адресу <bug-help2man@gnu.org>.

   Зауваження для перекладачів: переклади здійснюються за допомогою the
Translation Project (http://translationproject.org/), докладніший опис
можна знайти тут: <http://translationproject.org/html/translators.html>.


File: help2man-uk.info.tmp,  Node: Доступність,  Prev: Звіти,  Up: Top

9 Як отримати ‘help2man’
************************

Найсвіжішу версію цього пакунка можна знайти у інтернеті на дзеркалі
пакунків GNU:

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

   Якщо автоматичне переспрямовування не спрацює, список дзеркал можна
знайти тут:

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

   Крім того, якщо це потрібно, ви можете скористатися основним
дзеркалом FTP GNU:
     <http://ftp.gnu.org/gnu/help2man/>


Tag Table:
Node: Top1990
Node: Огляд4204
Node: Як викликати help2man5771
Node: Рекомендації щодо --help10479
Node: Включення тексту17955
Node: Використання Makefile21454
Node: Локалізовані сторінки man23162
Node: Приклад26477
Node: Звіти29347
Node: Доступність30278

End Tag Table


Local Variables:
coding: utf-8
End: