1 This is help2man-uk.info.tmp, produced by makeinfo version 6.8 from
4 У цьому файлі міститься документація до програми GNU ‘help2man’.
5 Програму призначено для створення простих сторінок довідника (man) на
6 основі даних, виведених певною програмою, запущеною із параметрами
7 ‘--help’ та ‘--version’.
9 © Free Software Foundation, Inc., 1999–2021
11 Цей підручник можна копіювати без змін і поширювати, якщо в усіх
12 копіях збережено запис про авторські права та цей запис про можливість
15 Цей підручник можна копіювати, вносити до копії зміни і поширювати
16 створені копії, якщо виконано умови копіювання без змін, а уся похідна
17 робота повинна поширюватися за тих самих умов, що і цей підручник.
19 Переклади цього підручника іншими мовами можна копіювати і поширювати
20 відповідно до викладених вище умов щодо змінених версій, окрім того, що
21 ці умови може бути перекладено, якщо переклад офіційно затверджено
22 Фундацією вільного програмного забезпечення.
23 INFO-DIR-SECTION Розробка програмного забезпечення
25 * help2man-uk: (help2man-uk). Програма для автоматичного створення
26 сторінок підручника (man).
30 File: help2man-uk.info.tmp, Node: Top, Next: Огляд, Up: (dir)
35 ‘help2man’ призначено для створення простих сторінок довідника (man) на
36 основі даних, виведених певною програмою, запущеною із параметрами
37 ‘--help’ та ‘--version’.
41 * Огляд:: Огляд ‘help2man’.
42 * Як викликати help2man:: Як запустити‘help2man’.
43 * Рекомендації щодо --help:: Рекомендованеформатуванняданих,
44 виведенихза допомогою‘--help’.
45 * Включення тексту:: Включеннядодаткового текстудо
46 виведенихпрограмою даних.
47 * Використання Makefile:: Використання‘help2man’ упоєднанні з
49 * Локалізовані сторінки man:: Створеннясторінокпідручникамовами,відмін
51 * Приклад:: Приклад роботи ‘help2man’.
52 * Звіти:: Як повідомити про вади
53 тазапропонуватиудосконалення.
54 * Доступність:: Як отримати ‘help2man’.
57 File: help2man-uk.info.tmp, Node: Огляд, Next: Як викликати help2man, Prev: Top, Up: Top
62 ‘help2man’ призначено для автоматизованого створення простих сторінок
63 довідника (mna) на основі даних, виведених програмою, для якої
64 створюється відповідна сторінка.
66 Хоча сторінки підручника і не є обов’язковими для програм GNU, у
67 інших проектах, зокрема Debian, наявність таких сторінок є обов’язковою
68 (*note (стандарти)Сторінки man::)
70 Цю програму призначено для спрощення для авторів програмного
71 забезпечення створення сторінки підручника для дистрибутива з програмою
72 без потреби у постійній роботі з підтримання її актуальності.
74 Якщо програма здатна виводити достатньо коректні дані у відповідь на
75 додавання до команди стандартних параметрів ‘--help’ та ‘--version’,
76 ‘help2man’ може упорядкувати виведені програмою дані у щось, що є
77 достатньо якісною сторінкою підручника.
80 File: help2man-uk.info.tmp, Node: Як викликати help2man, Next: Рекомендації щодо --help, Prev: Огляд, Up: Top
82 2 Як запустити ‘help2man’
83 *************************
85 Формат команди запуску ‘help2man’:
87 help2man [ПАРАМЕТР]... ВИКОНУВАНИЙ ФАЙЛ
89 У ‘help2man’ передбачено підтримку таких параметрів:
93 Використовувати РЯДОК як опис для розділу ‘NAME’ сторінки
96 Типово, якщо немає нічого кращого, відповідний абзац буде таким:
97 ‘manual page for ПРОГРАМА НОМЕР ВЕРСІЇ’.
99 За допомогою цього параметра можна перевизначити розділ ‘[name]’
100 файла включення (*note Включення тексту::).
104 Використовувати для сторінки man розділ, вказаний аргументом
105 РОЗДІЛ. Типовим розділом є 1.
109 Встановити назву для розділу підручника РОЗДІЛ, яка буде
110 центральною частиною заголовка сторінки. Типово для ‘команд
111 користувача’ використовується розділ 1, для ‘ігор’ використовується
112 розділ 6, а для ‘програм для адміністрування системи’
113 використовуються розділи 8 та 1M.
117 Запис джерела програми використовується як нижній колонтитул
118 сторінки і містить назву організації або комплекту програм,
119 частиною якого є програма. Типовим значенням запису є назва
120 пакунка і номер версії.
124 Вибрати локаль для виведення результатів (типовою є локаль ‘C’).
125 Підтримку вказаної ЛОКАЛІ має бути передбачено одночасно у самій
126 програмі і у ‘help2man’ (*note Локалізовані сторінки man::).
130 Включити матеріал з файла ФАЙЛ (*note Включення тексту::).
134 Варіант ‘--include’ для використання у шаблонних правилах Makefile,
135 для якого не потрібне існування файла ФАЙЛ.
139 Вивести результат до файла ФАЙЛ, а не до ‘stdout’.
143 Назва підручника Texinfo.
147 Придушити включення абзацу розділу ‘SEE ALSO’, який спрямовував би
148 читача до документації з Texinfo.
152 Викинути префікс ‘lt-’ з екземплярів назви програми у короткому
153 описі (‘libtool’ створює скрипти-обгортки у каталозі збирання, які
154 викликають програму ‘foo’ як ‘.libs/lt-foo’).
158 Вивести довідкові дані або дані щодо версії.
160 Типово ‘help2man’ передає виконуваному файлу стандартні параметри
161 ‘--help’ та ‘--version’. Альтернативні параметри можна вказати так:
164 ‘--help-option=ПАРАМЕТР’
165 Рядок параметра довідки.
168 ‘--version-option=ПАРАМЕТР’
169 Рядок параметра версії.
171 ‘--version-string=РЯДОК’
174 ‘--no-discard-stderr’
175 Включити дані із stderr під час обробки результатів додавання
179 File: help2man-uk.info.tmp, Node: Рекомендації щодо --help, Next: Включення тексту, Prev: Як викликати help2man, Up: Top
181 3 Рекомендації щодо ‘--help’
182 ****************************
184 У цьому розділі наведено рекомендації щодо того, що слід включати у
185 дані, які має виводити ваша програма у відповідь на додавання до
186 команди, якою вона запускається, параметра ‘--help’. Виконання цих
187 рекомендацій надасть змогу ‘help2man’ вивести якісну сторінку man, а
188 також надасть користувачам кориснішу інформацію.
190 Див. *note (стандарти)Інтерфейси командного рядка:: та *note
191 (стандарти)Сторінки man::, щоб ознайомитися з офіційними стандартами GNU
192 щодо використання параметра ‘--help’ та сторінок man.
194 • Коротке резюме щодо того, як запускати програму. Якщо різні режими
195 роботи програми потребують використання різних способів запуску,
196 наведіть повний список варіантів. Приклад (для зручності
199 Usage: cp [OPTION]... SOURCE DEST
200 or: cp [OPTION]... SOURCE... DIRECTORY
203 У цих коротких описах використовуйте замість назви програми
204 ‘argv[0]’, як є, без вилучення частини із записами каталогів. Це
205 не збігається із канонічною (сталою) назвою програми, яка
206 використовується у команді з параметром ‘--version’.
208 • Дуже короткий опис призначення програми, зокрема типової поведінки.
209 Приклад для програми ‘cp’:
211 Копіює ДЖЕРЕЛО у ЦІЛЬ, або декілька ДЖЕРЕЛ у КАТАЛОГ.
213 • Список параметрів з відступом до позиції 2 у рядку. Якщо у
214 програмі передбачено використання однолітерних параметрів, пункти
215 цих параметрів мають бути на початку рядка, а далі вже має бути
216 розширений еквівалентний запис (якщо такий передбачено). Якщо до
217 параметра потрібно додавати аргумент, включіть його до опису,
218 надавши йому зрозумілої користувачеві назви. Вирівняйте описи за
219 певною позицією у рядку. Зауважте, що для того, щоб програма
220 ‘help2man’ могла належним чином розпізнати опис, його слід
221 відокремити від запису параметра принаймні двома пробілами, а у
222 багаторядковому описі другий і наступні рядки мають починатися з
223 однієї позиції у рядку.
225 Нижче наведено (редагований) приклад з опису параметрів програми
226 ‘cp’, з коротким і довгим варіантом параметра, лише довгим
227 варіантом параметра і лише коротким варіантом параметра:
229 -a, --archive same as -dpR
230 --backup[=CONTROL] make a backup of each ...
231 -b like --backup but ...
233 Якщо програмі можна передавати багато параметрів, варто розділити
234 список параметрів на частини, наприклад, ‘Загальні’, ‘Керування
235 виведенням’ тощо. Зазвичай, параметри варто упорядковувати за
236 абеткою (спершу за короткими варіантами записів параметрів, потім
237 за довгими) у межах кожної з частин або у межах усього списку, якщо
240 • Будь-які додаткові дані щодо поведінки програми, зокрема важливі
241 для роботи змінні середовища, додаткові відомості щодо параметрів
242 тощо. Наприклад, для програми ‘cp’ можна навести дані щодо змінної
243 середовища ‘VERSION_CONTROL’ та розріджених файлів.
245 • Декілька прикладів типового використання, за вашим вибором. Один
246 хороший приклад, зазвичай, вартий тисячі слів опису, отже варто
247 завжди включати до довідки приклади.
249 • На завершення, слід навести настанови щодо адреси, на яку слід
250 надсилати повідомлення про вади. Типовою ПОШТОВОЮ АДРЕСОЮ є
251 ‘bug-ПРОГРАМА@gnu.org’. Варто дотримуватися саме цієї форми, якщо
252 йдеться про програму GNU. Також варто згадати адресу домашньої
253 сторінки програми, пов’язані із її обговоренням списки листування
256 Інтерфейси програмування ‘argp’ та ‘popt’ надають вам змогу вказати
257 описи параметрів для ‘--help’ з тією самою структурою, що решта описів
258 параметрів; вам варто скористатися цими підпрограмами для обробки
259 параметрів замість ‘getopt’.
261 Типово, у ‘help2man’ для виявлення розділів сторінки підручника
262 використовується певна евристика: наприклад, рядок із записом
263 ‘Параметри:’ призведе до того, що наступну за ним частину тексту буде
264 додано до розділу ‘ПАРАМЕТРИ’, а рядок, що починається зі слова
265 ‘Copyright’ стане частиною розділу ‘COPYRIGHT’. Окрім цього, рядок, що
266 містить, наприклад, ‘*Слова*’ стане початком нового розділу, а рядок
267 ‘Слова:’ — нового підрозділу.
270 File: help2man-uk.info.tmp, Node: Включення тексту, Next: Використання Makefile, Prev: Рекомендації щодо --help, Up: Top
272 4 Включення додаткового тексту до виведених програмою даних
273 ***********************************************************
275 До створеної сторінки підручника можна додати статичний текст за
276 допомогою параметрів ‘--include’ та ‘--opt-include’ (*note Як викликати
277 help2man::). Хоча можна використовувати файли з довільними назвами, для
278 певності ми рекомендуємо використовувати для файлів включень ‘help2man’
281 Формат даних у файлі, який додається за допомогою цього параметра,
290 Блоки тексту *roff вставляються до виведених даних або на початку
291 вказаного ‘[розділу]’ (без врахування регістру), або після абзацу, що
292 відповідає ‘/шаблону/’.
294 У шаблонах використовується синтаксис формальних виразів Perl, можна
295 використовувати модифікатори ‘i’, ‘s’ або ‘m’ (*note perlre(1):
298 Рядки перед першим розділом або шаблоном, які починаються з набору
299 символів ‘-’, вважаються визначеннями параметрів. Всі інші такі рядки
300 буде проігноровано, ними можна скористатися для коментування, ключових
303 Порядок виведення розділів (для включених розділів):
318 Будь-які розділи ‘[name]’ or ‘[synopsis]’ вказані у включеному файлі,
319 замінять собою відповідні розділи, створені у автоматичному режимі. Ви
320 можете зберегти перший з цих розділів за допомогою параметра ‘--name’,
323 Інші розділи буде додано перед автоматично створеними даними
324 стандартних розділів, вказаних вище, або буде включено до _іншого_
325 (вище) у порядку, у якому їх вказано у файлі-включенні.
327 Можна явним чином вимагати розташовування тексту у розділі за
328 допомогою синтаксичної конструкції ‘[<розділ]’, ‘[=розділ]’ або
329 ‘[>розділ]’ для розташовування тексту перед, замість або після типових
330 виведених даних, відповідно.
333 File: help2man-uk.info.tmp, Node: Використання Makefile, Next: Локалізовані сторінки man, Prev: Включення тексту, Up: Top
335 5 Використання ‘help2man’ у поєднанні з ‘make’
336 **********************************************
338 Рекомендованим випадком використання ‘help2man’ у файлах Makefile є
339 випадок, коли сторінка довідника має залежати не від наявності
340 виконуваного файла, а від файлів початкових даних, у яких визначено
341 текст, який виводиться у відповідь на додавання параметрів ‘--help’ та
342 ‘--version’ до команди.
344 У такий спосіб можна забезпечити створення сторінки довідника
345 супровідником пакунка із включенням його до дистрибутива програми, без
346 потреби для користувача пакунка у встановленні програми ‘help2man’.
348 Приклад правила для програми ‘prog’:
350 prog.1: $(srcdir)/main.c
351 -$(HELP2MAN) --output=$@ --name='an example program' ./prog
353 Значення змінної ‘HELP2MAN’ можна встановити у ‘configure.in’ у один
356 AM_MISSING_PROG(HELP2MAN, help2man)
358 для ‘automake’ або чимось таким:
360 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
365 File: help2man-uk.info.tmp, Node: Локалізовані сторінки man, Next: Приклад, Prev: Використання Makefile, Up: Top
367 6 Створення сторінок підручника мовами, відмінними від англійської
368 ******************************************************************
370 Сторінки підручника можна створити для будь-якої локалі, підтримку якої
371 передбачено у програмі та у ‘help2man’ за допомогою параметра ‘--locale’
374 help2man -L uk_UA@euro -o cp.uk.1 cp
376 Із поточним списком підтримуваних ‘help2man’ мов можна ознайомитися
377 тут: <http://translationproject.org/domain/help2man.html>. Довідку щодо
378 надсилання нових перекладів наведено у розділі *note Звіти::.
380 6.1 Як змінити розташування каталогів повідомлень
381 =================================================
383 Якщо локалізовані сторінки підручника створюються з каталогу збирання
384 програми, ймовірно, встановлені до стандартного каталогу сторінки не
385 відповідатимуть (якщо їх взагалі буде встановлено) версії програми, яка
388 Разом з ‘help2man’ постачається попередньо завантажувана бібліотека,
389 яка перехоплюватиме виклики ‘bindtextdomain’, налаштовуючи адресу для
390 каталогів перекладів для домену, вказаного змінною ‘$TEXTDOMAIN’, і
391 перевизначаючи адресу каталогу, вказаного за допомогою змінної
396 mkdir -p tmp/uk/LC_MESSAGES
397 cp po/uk.gmo tmp/uk/LC_MESSAGES/ПРОГРАМА.mo
398 LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
400 TEXTDOMAIN=ПРОГРАМА \
401 help2man -L uk_UA@euro -i ПРОГРАМА.uk.h2m -o ПРОГРАМА.uk.1 ПРОГРАМА
404 накаже програмі ПРОГРАМА завантажити каталог повідомлень із
405 перекладами з ‘tmp’, а не з ‘/usr/share/locale’.
408 • Узагальнення локалі ‘uk_UA@euro’ до ‘uk’ у наведеному вище прикладі
409 виконується засобами ‘gettext’. Якщо буде виявлено специфічнішу
410 відповідність, її також буде використано.
412 • Цей спосіб попереднього завантаження було перевірено лише для
413 ‘eglibc’ 2.11.2 та ‘gettext’ 0.18.1.1 у системі GNU/Linux.
414 Повідомте авторові, якщо цей спосіб працює або не працює у вашій
415 системі (*note Звіти::).
418 File: help2man-uk.info.tmp, Node: Приклад, Next: Звіти, Prev: Локалізовані сторінки man, Up: Top
420 7 Приклад роботи ‘help2man’
421 ***************************
423 Припустімо, що якась програма з назвою ‘foo’ виводить такі дані:
428 Copyright (C) 2011 Free Software Foundation, Inc.
429 This is free software; see the source for copying conditions. There is NO
430 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
432 Written by A. Programmer.
434 GNU `foo' does nothing interesting except serve as an example for
437 Usage: foo [OPTION]...
440 -a, --option an option
441 -b, --another-option[=VALUE]
444 --help display this help and exit
445 --version output version information and exit
449 foo --option the same thing, giving `--option'
451 Про вади слід повідомляти на адресу <bug-gnu-utils@gnu.org>.
453 ‘help2man’ створити вхідні дані для програми ‘nroff’ для показу
454 сторінки підручника, формат яких буде приблизно таким:
456 FOO(1) User Commands FOO(1)
459 foo - manual page for foo 1.1
465 GNU `foo' does nothing interesting except serve as an example for
472 -b, --another-option[=VALUE]
475 --help display this help and exit
478 output version information and exit
484 the same thing, giving `--option'
487 Written by A. Programmer.
490 Report bugs to <bug-gnu-utils@gnu.org>.
493 Copyright © 2011 Free Software Foundation, Inc.
494 This is free software; see the source for copying conditions.
495 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
499 The full documentation for foo is maintained as a Texinfo manual.
500 If the info and foo programs are properly installed at your site,
505 should give you access to the complete manual.
507 foo 1.1 May 2011 FOO(1)
510 File: help2man-uk.info.tmp, Node: Звіти, Next: Доступність, Prev: Приклад, Up: Top
512 8 Як повідомити про вади та запропонувати удосконалення
513 *******************************************************
515 Якщо вами буде виявлено вади або у вас виникнуть пропозиції щодо
516 удосконалення цієї програми або підручника до неї, будь ласка, повідомте
517 про це, надіславши повідомлення на адресу <bug-help2man@gnu.org>.
519 Зауваження для перекладачів: переклади здійснюються за допомогою the
520 Translation Project (http://translationproject.org/), докладніший опис
521 можна знайти тут: <http://translationproject.org/html/translators.html>.
524 File: help2man-uk.info.tmp, Node: Доступність, Prev: Звіти, Up: Top
526 9 Як отримати ‘help2man’
527 ************************
529 Найсвіжішу версію цього пакунка можна знайти у інтернеті на дзеркалі
532 <http://ftpmirror.gnu.org/help2man/>
534 Якщо автоматичне переспрямовування не спрацює, список дзеркал можна
537 <http://www.gnu.org/order/ftp.html>
539 Крім того, якщо це потрібно, ви можете скористатися основним
541 <http://ftp.gnu.org/gnu/help2man/>
547 Node: Як викликати help2man
\7f5771
548 Node: Рекомендації щодо --help
\7f10479
549 Node: Включення тексту
\7f17955
550 Node: Використання Makefile
\7f21454
551 Node: Локалізовані сторінки man
\7f23162
552 Node: Приклад
\7f26477
554 Node: Доступність
\7f30278