Imported Upstream version 1.47.6
[platform/upstream/help2man.git] / help2man-uk.info
1 This is help2man-uk.info.tmp, produced by makeinfo version 6.5 from
2 help2man-uk.texi.
3
4 У цьому файлі міститься документація до програми GNU ‘help2man’.
5 Програму призначено для створення простих сторінок довідника (man) на
6 основі даних, виведених певною програмою, запущеною із параметрами
7 ‘--help’ та ‘--version’.
8
9    © Free Software Foundation, Inc., 1999–2015
10
11    Цей підручник можна копіювати без змін і поширювати, якщо в усіх
12 копіях збережено запис про авторські права та цей запис про можливість
13 копіювання.
14
15    Цей підручник можна копіювати, вносити до копії зміни і поширювати
16 створені копії, якщо виконано умови копіювання без змін, а уся похідна
17 робота повинна поширюватися за тих самих умов, що і цей підручник.
18
19    Переклади цього підручника іншими мовами можна копіювати і поширювати
20 відповідно до викладених вище умов щодо змінених версій, окрім того, що
21 ці умови може бути перекладено, якщо переклад офіційно затверджено
22 Фундацією вільного програмного забезпечення.
23 INFO-DIR-SECTION Розробка програмного забезпечення
24 START-INFO-DIR-ENTRY
25 * help2man-uk: (help2man-uk).  Програма для автоматичного створення
26                                  сторінок підручника (man).
27 END-INFO-DIR-ENTRY
28
29 \1f
30 File: help2man-uk.info.tmp,  Node: Top,  Next: Огляд,  Up: (dir)
31
32 ‘help2man’
33 **********
34
35 ‘help2man’ призначено для створення простих сторінок довідника (man) на
36 основі даних, виведених певною програмою, запущеною із параметрами
37 ‘--help’ та ‘--version’.
38
39 * Menu:
40
41 * Огляд::                 Огляд ‘help2man’.
42 * Як викликати help2man::      Як запустити‘help2man’.
43 * Рекомендації щодо --help::   Рекомендованеформатуванняданих,
44                                  виведенихза допомогою–help.
45 * Включення тексту::            Включеннядодаткового текстудо
46                                  виведенихпрограмою даних.
47 * Використання Makefile::      Використання‘help2man’ упоєднанні з
48                                  ‘make’.
49 * Локалізовані сторінки man::  Створеннясторінокпідручникамовами,відмін
50                                  нимивіданглійської.
51 * Приклад::                     Приклад роботи ‘help2man’.
52 * Звіти::                 Як повідомити про вади
53                                  тазапропонуватиудосконалення.
54 * Доступність::             Як отримати ‘help2man’.
55
56 \1f
57 File: help2man-uk.info.tmp,  Node: Огляд,  Next: Як викликати help2man,  Prev: Top,  Up: Top
58
59 1 Огляд ‘help2man’
60 ******************
61
62 ‘help2man’ призначено для автоматизованого створення простих сторінок
63 довідника (mna) на основі даних, виведених програмою, для якої
64 створюється відповідна сторінка.
65
66    Хоча сторінки підручника і не є обов’язковими для програм GNU, у
67 інших проектах, зокрема Debian, наявність таких сторінок є обов’язковою
68 (*note (стандарти)Сторінки man::)
69
70    Цю програму призначено для спрощення для авторів програмного
71 забезпечення створення сторінки підручника для дистрибутива з програмою
72 без потреби у постійній роботі з підтримання її актуальності.
73
74    Якщо програма здатна виводити достатньо коректні дані у відповідь на
75 додавання до команди стандартних параметрів ‘--help’ та ‘--version’,
76 ‘help2man’ може упорядкувати виведені програмою дані у щось, що є
77 достатньо якісною сторінкою підручника.
78
79 \1f
80 File: help2man-uk.info.tmp,  Node: Як викликати help2man,  Next: Рекомендації щодо --help,  Prev: Огляд,  Up: Top
81
82 2 Як запустити ‘help2man’
83 *************************
84
85 Формат команди запуску ‘help2man’:
86
87      help2man [ПАРАМЕТР]... ВИКОНУВАНИЙ ФАЙЛ
88
89    У ‘help2man’ передбачено підтримку таких параметрів:
90
91 ‘-n РЯДОК’
92 ‘--name=РЯДОК’
93      Використовувати РЯДОК як опис для розділу ‘NAME’ сторінки
94      підручника.
95
96      Типово, якщо немає нічого кращого, відповідний абзац буде таким:
97      ‘manual page for ПРОГРАМА НОМЕР ВЕРСІЇ’.
98
99      За допомогою цього параметра можна перевизначити розділ ‘[name]’
100      файла включення (*note Включення тексту::).
101
102 ‘-s РОЗДІЛ’
103 ‘--section РОЗДІЛ’
104      Використовувати для сторінки man розділ, вказаний аргументом
105      РОЗДІЛ.  Типовим розділом є 1.
106
107 ‘-m ПІДРУЧНИК’
108 ‘--manual=ПІДРУЧНИК’
109      Встановити назву для розділу підручника РОЗДІЛ, яка буде
110      центральною частиною заголовка сторінки.  Типово для ‘команд
111      користувача’ використовується розділ 1, для ‘ігор’ використовується
112      розділ 6, а для ‘програм для адміністрування системи’
113      використовуються розділи 8 та 1M.
114
115 ‘-S ДЖЕРЕЛО’
116 ‘--source=ДЖЕРЕЛО’
117      Запис джерела програми використовується як нижній колонтитул
118      сторінки і містить назву організації або комплекту програм,
119      частиною якого є програма.  Типовим значенням запису є назва
120      пакунка і номер версії.
121
122 ‘-L ЛОКАЛЬ’
123 ‘--locale=ЛОКАЛЬ’
124      Вибрати локаль для виведення результатів (типовою є локаль ‘C’).
125      Підтримку вказаної ЛОКАЛІ має бути передбачено одночасно у самій
126      програмі і у ‘help2man’ (*note Локалізовані сторінки man::).
127
128 ‘-i ФАЙЛ’
129 ‘--include=ФАЙЛ’
130      Включити матеріал з файла ФАЙЛ (*note Включення тексту::).
131
132 ‘-I ФАЙЛ’
133 ‘--opt-include=ФАЙЛ’
134      Варіант ‘--include’ для використання у шаблонних правилах Makefile,
135      для якого не потрібне існування файла ФАЙЛ.
136
137 ‘-o ФАЙЛ’
138 ‘--output=ФАЙЛ’
139      Вивести результат до файла ФАЙЛ, а не до ‘stdout’.
140
141 ‘-p ТЕКСТ’
142 ‘--info-page=ТЕКСТ’
143      Назва підручника Texinfo.
144
145 ‘-N’
146 ‘--no-info’
147      Придушити включення абзацу розділу ‘SEE ALSO’, який спрямовував би
148      читача до документації з Texinfo.
149
150 ‘-l’
151 ‘--libtool’
152      Викинути префікс ‘lt-’ з екземплярів назви програми у короткому
153      описі (‘libtool’ створює скрипти-обгортки у каталозі збирання, які
154      викликають програму ‘foo’ як ‘.libs/lt-foo’).
155
156 ‘--help’
157 ‘--version’
158      Вивести довідкові дані або дані щодо версії.
159
160    Типово ‘help2man’ передає виконуваному файлу стандартні параметри
161 ‘--help’ та ‘--version’.  Альтернативні параметри можна вказати так:
162
163 ‘-h ПАРАМЕТР’
164 ‘--help-option=ПАРАМЕТР’
165      Рядок параметра довідки.
166
167 ‘-v ПАРАМЕТР’
168 ‘--version-option=ПАРАМЕТР’
169      Рядок параметра версії.
170
171 ‘--version-string=РЯДОК’
172      Рядок версії.
173
174 ‘--no-discard-stderr’
175      Включити дані із stderr під час обробки результатів додавання
176      параметра.
177
178 \1f
179 File: help2man-uk.info.tmp,  Node: Рекомендації щодо --help,  Next: Включення тексту,  Prev: Як викликати help2man,  Up: Top
180
181 3 Рекомендації щодо ‘--help’
182 ****************************
183
184 У цьому розділі наведено рекомендації щодо того, що слід включати у
185 дані, які має виводити ваша програма у відповідь на додавання до
186 команди, якою вона запускається, параметра ‘--help’.  Виконання цих
187 рекомендацій надасть змогу ‘help2man’ вивести якісну сторінку man, а
188 також надасть користувачам кориснішу інформацію.
189
190    Див.  *note (стандарти)Інтерфейси командного рядка:: та *note
191 (стандарти)Сторінки man::, щоб ознайомитися з офіційними стандартами GNU
192 щодо використання параметра ‘--help’ та сторінок man.
193
194    • Коротке резюме щодо того, як запускати програму.  Якщо різні режими
195      роботи програми потребують використання різних способів запуску,
196      наведіть повний список варіантів.  Приклад (для зручності
197      скорочено):
198
199           Usage: cp [OPTION]... SOURCE DEST
200             or:  cp [OPTION]... SOURCE... DIRECTORY
201           ...
202
203      У цих коротких описах використовуйте замість назви програми
204      ‘argv[0]’, як є, без вилучення частини із записами каталогів.  Це
205      не збігається із канонічною (сталою) назвою програми, яка
206      використовується у команді з параметром ‘--version’.
207
208    • Дуже короткий опис призначення програми, зокрема типової поведінки.
209      Приклад для програми ‘cp’:
210
211           Копіює ДЖЕРЕЛО у ЦІЛЬ, або декілька ДЖЕРЕЛ у КАТАЛОГ.
212
213    • Список параметрів з відступом до позиції 2 у рядку.  Якщо у
214      програмі передбачено використання однолітерних параметрів, пункти
215      цих параметрів мають бути на початку рядка, а далі вже має бути
216      розширений еквівалентний запис (якщо такий передбачено).  Якщо до
217      параметра потрібно додавати аргумент, включіть його до опису,
218      надавши йому зрозумілої користувачеві назви.  Вирівняйте описи за
219      певною позицією у рядку.  Зауважте, що для того, щоб програма
220      ‘help2man’ могла належним чином розпізнати опис, його слід
221      відокремити від запису параметра принаймні двома пробілами, а у
222      багаторядковому описі другий і наступні рядки мають починатися з
223      однієї позиції у рядку.
224
225      Нижче наведено (редагований) приклад з опису параметрів програми
226      ‘cp’, з коротким і довгим варіантом параметра, лише довгим
227      варіантом параметра і лише коротким варіантом параметра:
228
229             -a, --archive                same as -dpR
230                 --backup[=CONTROL]       make a backup of each ...
231             -b                           like --backup but ...
232
233      Якщо програмі можна передавати багато параметрів, варто розділити
234      список параметрів на частини, наприклад, ‘Загальні’, ‘Керування
235      виведенням’ тощо.  Зазвичай, параметри варто упорядковувати за
236      абеткою (спершу за короткими варіантами записів параметрів, потім
237      за довгими) у межах кожної з частин або у межах усього списку, якщо
238      у ньому нема частин.
239
240    • Будь-які додаткові дані щодо поведінки програми, зокрема важливі
241      для роботи змінні середовища, додаткові відомості щодо параметрів
242      тощо.  Наприклад, для програми ‘cp’ можна навести дані щодо змінної
243      середовища ‘VERSION_CONTROL’ та розріджених файлів.
244
245    • Декілька прикладів типового використання, за вашим вибором.  Один
246      хороший приклад, зазвичай, вартий тисячі слів опису, отже варто
247      завжди включати до довідки приклади.
248
249    • На завершення, слід навести настанови щодо адреси, на яку слід
250      надсилати повідомлення про вади.  Типовою ПОШТОВОЮ АДРЕСОЮ є
251      ‘bug-ПРОГРАМА@gnu.org’.  Варто дотримуватися саме цієї форми, якщо
252      йдеться про програму GNU. Також варто згадати адресу домашньої
253      сторінки програми, пов’язані із її обговоренням списки листування
254      тощо.
255
256    Інтерфейси програмування ‘argp’ та ‘popt’ надають вам змогу вказати
257 описи параметрів для ‘--help’ з тією самою структурою, що решта описів
258 параметрів; вам варто скористатися цими підпрограмами для обробки
259 параметрів замість ‘getopt’.
260
261    Типово, у ‘help2man’ для виявлення розділів сторінки підручника
262 використовується певна евристика: наприклад, рядок із записом
263 ‘Параметри:’ призведе до того, що наступну за ним частину тексту буде
264 додано до розділу ‘ПАРАМЕТРИ’, а рядок, що починається зі слова
265 ‘Copyright’ стане частиною розділу ‘COPYRIGHT’.  Окрім цього, рядок, що
266 містить, наприклад, ‘*Слова*’ стане початком нового розділу, а рядок
267 ‘Слова:’ — нового підрозділу.
268
269 \1f
270 File: help2man-uk.info.tmp,  Node: Включення тексту,  Next: Використання Makefile,  Prev: Рекомендації щодо --help,  Up: Top
271
272 4 Включення додаткового тексту до виведених програмою даних
273 ***********************************************************
274
275 До створеної сторінки підручника можна додати статичний текст за
276 допомогою параметрів ‘--include’ та ‘--opt-include’ (*note Як викликати
277 help2man::).  Хоча можна використовувати файли з довільними назвами, для
278 певності ми рекомендуємо використовувати для файлів включень ‘help2man’
279 суфікс назви ‘.h2m’.
280
281    Формат даних у файлі, який додається за допомогою цього параметра,
282 має бути простим:
283
284      [розділ]
285      текст
286
287      /шаблон/
288      текст
289
290    Блоки тексту *roff вставляються до виведених даних або на початку
291 вказаного ‘[розділу]’ (без врахування регістру), або після абзацу, що
292 відповідає ‘/шаблону/’.
293
294    У шаблонах використовується синтаксис формальних виразів Perl, можна
295 використовувати модифікатори ‘i’, ‘s’ або ‘m’ (*note perlre(1):
296 (*manpages*)perlre.)
297
298    Рядки перед першим розділом або шаблоном, які починаються з набору
299 символів ‘-’, вважаються визначеннями параметрів.  Всі інші такі рядки
300 буде проігноровано, ними можна скористатися для коментування, ключових
301 слів RCS тощо.
302
303    Порядок виведення розділів (для включених розділів):
304
305      NAME
306      SYNOPSIS
307      DESCRIPTION
308      OPTIONS
309      _інше_
310      ENVIRONMENT
311      FILES
312      EXAMPLES
313      AUTHOR
314      REPORTING BUGS
315      COPYRIGHT
316      SEE ALSO
317
318    Будь-які розділи ‘[name]’ or ‘[synopsis]’ вказані у включеному файлі,
319 замінять собою відповідні розділи, створені у автоматичному режимі.  Ви
320 можете зберегти перший з цих розділів за допомогою параметра ‘--name’,
321 якщо захочете.
322
323    Інші розділи буде додано перед автоматично створеними даними
324 стандартних розділів, вказаних вище, або буде включено до _іншого_
325 (вище) у порядку, у якому їх вказано у файлі-включенні.
326
327    Можна явним чином вимагати розташовування тексту у розділі за
328 допомогою синтаксичної конструкції ‘[<розділ]’, ‘[=розділ]’ або
329 ‘[>розділ]’ для розташовування тексту перед, замість або після типових
330 виведених даних, відповідно.
331
332 \1f
333 File: help2man-uk.info.tmp,  Node: Використання Makefile,  Next: Локалізовані сторінки man,  Prev: Включення тексту,  Up: Top
334
335 5 Використання ‘help2man’ у поєднанні з ‘make’
336 **********************************************
337
338 Рекомендованим випадком використання ‘help2man’ у файлах Makefile є
339 випадок, коли сторінка довідника має залежати не від наявності
340 виконуваного файла, а від файлів початкових даних, у яких визначено
341 текст, який виводиться у відповідь на додавання параметрів ‘--help’ та
342 ‘--version’ до команди.
343
344    У такий спосіб можна забезпечити створення сторінки довідника
345 супровідником пакунка із включенням його до дистрибутива програми, без
346 потреби для користувача пакунка у встановленні програми ‘help2man’.
347
348    Приклад правила для програми ‘prog’:
349
350      prog.1: $(srcdir)/main.c
351              -$(HELP2MAN) --output=$@ --name='an example program' ./prog
352
353    Значення змінної ‘HELP2MAN’ можна встановити у ‘configure.in’ у один
354 з таких способів:
355
356      AM_MISSING_PROG(HELP2MAN, help2man)
357
358    для ‘automake’ або чимось таким:
359
360      AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
361
362    для ‘autoconf’.
363
364 \1f
365 File: help2man-uk.info.tmp,  Node: Локалізовані сторінки man,  Next: Приклад,  Prev: Використання Makefile,  Up: Top
366
367 6 Створення сторінок підручника мовами, відмінними від англійської
368 ******************************************************************
369
370 Сторінки підручника можна створити для будь-якої локалі, підтримку якої
371 передбачено у програмі та у ‘help2man’ за допомогою параметра ‘--locale’
372 (‘-L’).
373
374      help2man -L uk_UA@euro -o cp.uk.1 cp
375
376    Із поточним списком підтримуваних ‘help2man’ мов можна ознайомитися
377 тут: <http://translationproject.org/domain/help2man.html>.  Довідку щодо
378 надсилання нових перекладів наведено у розділі *note Звіти::.
379
380 6.1 Як змінити розташування каталогів повідомлень
381 =================================================
382
383 Якщо локалізовані сторінки підручника створюються з каталогу збирання
384 програми, ймовірно, встановлені до стандартного каталогу сторінки не
385 відповідатимуть (якщо їх взагалі буде встановлено) версії програми, яка
386 встановлюватиметься.
387
388    Разом з ‘help2man’ постачається попередньо завантажувана бібліотека,
389 яка перехоплюватиме виклики ‘bindtextdomain’, налаштовуючи адресу для
390 каталогів перекладів для домену, вказаного змінною ‘$TEXTDOMAIN’, і
391 перевизначаючи адресу каталогу, вказаного за допомогою змінної
392 ‘$LOCALEDIR’.
393
394    Приклад:
395
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" \
399        LOCALEDIR=tmp \
400        TEXTDOMAIN=ПРОГРАМА \
401        help2man -L uk_UA@euro -i ПРОГРАМА.uk.h2m -o ПРОГРАМА.uk.1 ПРОГРАМА
402      rm -rf tmp
403
404    накаже програмі ПРОГРАМА завантажити каталог повідомлень із
405 перекладами з ‘tmp’, а не з ‘/usr/share/locale’.
406
407    Примітки:
408    • Узагальнення локалі ‘uk_UA@euro’ до ‘uk’ у наведеному вище прикладі
409      виконується засобами ‘gettext’.  Якщо буде виявлено специфічнішу
410      відповідність, її також буде використано.
411
412    • Цей спосіб попереднього завантаження було перевірено лише для
413      ‘eglibc’ 2.11.2 та ‘gettext’ 0.18.1.1 у системі GNU/Linux.
414      Повідомте авторові, якщо цей спосіб працює або не працює у вашій
415      системі (*note Звіти::).
416
417 \1f
418 File: help2man-uk.info.tmp,  Node: Приклад,  Next: Звіти,  Prev: Локалізовані сторінки man,  Up: Top
419
420 7 Приклад роботи ‘help2man’
421 ***************************
422
423 Припустімо, що якась програма з назвою ‘foo’ виводить такі дані:
424
425      $ foo --version
426      GNU foo 1.1
427
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.
431
432      Written by A. Programmer.
433      $ foo --help
434      GNU `foo' does nothing interesting except serve as an example for
435      `help2man'.
436
437      Usage: foo [OPTION]...
438
439      Options:
440        -a, --option      an option
441        -b, --another-option[=VALUE]
442                          another option
443
444            --help        display this help and exit
445            --version     output version information and exit
446
447      Examples:
448        foo               do nothing
449        foo --option      the same thing, giving `--option'
450
451      Про вади слід повідомляти на адресу <bug-gnu-utils@gnu.org>.
452
453    ‘help2man’ створити вхідні дані для програми ‘nroff’ для показу
454 сторінки підручника, формат яких буде приблизно таким:
455
456      FOO(1)                         User Commands                        FOO(1)
457
458      NAME
459             foo - manual page for foo 1.1
460
461      SYNOPSIS
462             foo [OPTION]...
463
464      DESCRIPTION
465             GNU  `foo'  does nothing interesting except serve as an example for
466             `help2man'.
467
468      OPTIONS
469             -a, --option
470                    an option
471
472             -b, --another-option[=VALUE]
473                    another option
474
475             --help display this help and exit
476
477             --version
478                    output version information and exit
479
480      EXAMPLES
481             foo    do nothing
482
483             foo --option
484                    the same thing, giving `--option'
485
486      AUTHOR
487             Written by A. Programmer.
488
489      REPORTING BUGS
490             Report bugs to <bug-gnu-utils@gnu.org>.
491
492      COPYRIGHT
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
496             PARTICULAR PURPOSE.
497
498      SEE ALSO
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,
501             the command
502
503                    info foo
504
505             should give you access to the complete manual.
506
507      foo 1.1                          May 2011                           FOO(1)
508
509 \1f
510 File: help2man-uk.info.tmp,  Node: Звіти,  Next: Доступність,  Prev: Приклад,  Up: Top
511
512 8 Як повідомити про вади та запропонувати удосконалення
513 *******************************************************
514
515 Якщо вами буде виявлено вади або у вас виникнуть пропозиції щодо
516 удосконалення цієї програми або підручника до неї, будь ласка, повідомте
517 про це, надіславши повідомлення на адресу <bug-help2man@gnu.org>.
518
519    Зауваження для перекладачів: переклади здійснюються за допомогою the
520 Translation Project (http://translationproject.org/), докладніший опис
521 можна знайти тут: <http://translationproject.org/html/translators.html>.
522
523 \1f
524 File: help2man-uk.info.tmp,  Node: Доступність,  Prev: Звіти,  Up: Top
525
526 9 Як отримати ‘help2man’
527 ************************
528
529 Найсвіжішу версію цього пакунка можна знайти у інтернеті на дзеркалі
530 пакунків GNU:
531
532      <http://ftpmirror.gnu.org/help2man/>
533
534    Якщо автоматичне переспрямовування не спрацює, список дзеркал можна
535 знайти тут:
536
537      <http://www.gnu.org/order/ftp.html>
538
539    Крім того, якщо це потрібно, ви можете скористатися основним
540 дзеркалом FTP GNU:
541      <http://ftp.gnu.org/gnu/help2man/>
542
543 \1f
544 Tag Table:
545 Node: Top\7f1990
546 Node: Огляд\7f4199
547 Node: Як викликати help2man\7f5766
548 Node: Рекомендації щодо --help\7f10474
549 Node: Включення тексту\7f17950
550 Node: Використання Makefile\7f21449
551 Node: Локалізовані сторінки man\7f23157
552 Node: Приклад\7f26472
553 Node: Звіти\7f29342
554 Node: Доступність\7f30273
555 \1f
556 End Tag Table
557
558 \1f
559 Local Variables:
560 coding: utf-8
561 End: