1This is help2man-pl.info.tmp, produced by makeinfo version 6.7 from
2help2man-pl.texi.
3
4Ten plik opisuje polecenie GNU ‘help2man’, tworzące proste strony
5podręcznika man z wyjścia ‘--help’ oraz ‘--version’ innych poleceń.
6
7   Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
82011, 2012, 2013, 2014, 2015, 2020, 2021 Free Software Foundation, Inc.
9
10   Zezwala się na tworzenie i rozprowadzanie dokładnych kopii tego
11podręcznika, pod warunkiem zachowania we wszystkich kopiach informacji o
12prawach autorskich oraz niniejszej informacji.
13
14   Zezwala się na kopiowanie i rozprowadzanie zmodyfikowanych wersji
15tego podręcznika na takich warunkach, jak dokładnych kopii, pod
16warunkiem, że całe dzieło pochodne jest rozprowadzanie na warunkach
17takich samych, jak niniejsze.
18
19   Zezwala się na kopiowanie i rozprowadzanie tłumaczeń tego podręcznika
20na inny język na takich warunkach, jak wersje zmodyfikowane, z wyjątkiem
21tego, że niniejsze oświadczenie może wystąpić w tłumaczeniu
22zaaprobowanym przez Free Software Foundation.
23INFO-DIR-SECTION Rozwijanie oprogramowania
24START-INFO-DIR-ENTRY
25* help2man-pl: (help2man-pl).  Automatyczne tworzenie stron podręcznika
26				 man.
27END-INFO-DIR-ENTRY
28
29
30File: help2man-pl.info.tmp,  Node: Top,  Next: Przegląd,  Up: (dir)
31
32‘help2man’
33**********
34
35Polecenie ‘help2man’ tworzy proste strony podręcznika man z wyjścia
36‘--help’ oraz ‘--version’ innych poleceń.
37
38* Menu:
39
40* Przegląd::		      Przegląd polecenia ‘help2man’.
41* Uruchamianie help2man::     Jak uruchomić polecenie ‘help2man’.
42* Zalecenia --help::	      Zalecenia dotyczące formatowania
43				wyjścia‘--help’.
44* Dołączanie tekstu::	      Dołączanie dodatkowego tekstu na wyjściu.
45* Użycie Makefile::	      Użycie polecenia ‘help2man’ z
46				poziomuprogramu ‘make’.
47* Zlokalizowane strony man::  Tworzenie stron podręcznika man w
48				językuojczystym.
49* Przykład::		      Przykładowe wyjście polecenia‘help2man’.
50* Kontakt::		      Zgłaszanie błędów i propozycji.
51* Dostępność::		      Pozyskiwanie programu ‘help2man’.
52
53
54File: help2man-pl.info.tmp,  Node: Przegląd,  Next: Uruchamianie help2man,  Prev: Top,  Up: Top
55
561 Przegląd polecenia ‘help2man’
57*******************************
58
59‘help2man’ to narzędzie do automatycznego generowania prostych stron
60podręcznika man z wyjścia programów.
61
62   Mimo że strony podręcznika man są opcjonalne dla programów GNU, inne
63projekty - takie jak Debian - wymagają ich (*note (standards)Man
64Pages::)
65
66   Ten program ma na celu zapewnienie autorom programów prostej metody
67dołączania stron podręcznika man bez potrzeby utrzymywania tego
68dokumentu.
69
70   Po wskazaniu programu tworzącego w miarę standardowe opisy jako
71wyjście opcji ‘--help’ oraz ‘--version’, polecenie ‘help2man’ potrafi
72przekształcić te opisy w coś przypominającego stronę podręcznika.
73
74
75File: help2man-pl.info.tmp,  Node: Uruchamianie help2man,  Next: Zalecenia --help,  Prev: Przegląd,  Up: Top
76
772 Jak uruchomić ‘help2man’
78**************************
79
80Składnia przy uruchamianiu programu ‘help2man’ jest następująca:
81
82     help2man [OPCJA]... PROGRAM
83
84   ‘help2man’ obsługuje następujące opcje:
85
86‘-n ŁAŃCUCH’
87‘--name=ŁAŃCUCH’
88     Użycie ŁAŃCUCHA jako opisu dla akapitu ‘NAZWA’ strony podręcznika.
89
90     Domyślnie (przy braku czegokolwiek lepszego) akapit ten zawiera
91     ‘strona podręcznika dla PROGRAM WERSJA’.
92
93     Ta opcja nadpisuje sekcję pliku dołączanego ‘[nazwa]’ (*note
94     Dołączanie tekstu::).
95
96‘-s SEKCJA’
97‘--section SEKCJA’
98     Użycie SEKCJI jako sekcji dla strony podręcznika man.  Domyślną
99     sekcją jest 1.
100
101‘-m PODRĘCZNIK’
102‘--manual=PODRĘCZNIK’
103     Ustawienie nazwy sekcji podręcznika na PODRĘCZNIK; nazwa jest
104     używana jako wyśrodkowany nagłówek na stronie podręcznika.
105     Domyślnie używane nazwy to: ‘Polecenia użytkownika’ dla stron z
106     sekcji 1, ‘Gry’ dla sekcji 6 oraz ‘Narzędzia administracyjne’ dla
107     sekcji 8 oraz 1M.
108
109‘-S ŹRÓDŁO’
110‘--source=ŹRÓDŁO’
111     Źródło programu służy jako stopka strony, zwykle zawiera nazwę
112     organizacji lub kolekcji, w której skład wchodzi program.
113     Domyślnie wartość tego pola to nazwa i wersja pakietu.
114
115‘-L LOKALIZACJA’
116‘--locale=LOKALIZACJA’
117     Wybór lokalizacji wyjścia (domyślnie ‘C’).  Zarówno program, jak i
118     ‘help2man’ muszą obsługiwać podaną LOKALIZACJĘ (*note Zlokalizowane
119     strony man::)
120
121‘-i PLIK’
122‘--include=PLIK’
123     Dołączenie treści z PLIKU (*note Dołączanie tekstu::).
124
125‘-I PLIK’
126‘--opt-include=PLIK’
127     Wariant ‘--include’ do wykorzystania w regułach szablonów Makefile,
128     nie wymagający istnienia PLIKU.
129
130‘-o PLIK’
131‘--output=PLIK’
132     Zapis wyjścia do PLIKU zamiast na ‘standardowe wyjście’.
133
134‘-p TEKST’
135‘--info-page=TEKST’
136     Nazwa podręcznika Texinfo.
137
138‘-N’
139‘--no-info’
140     Pominięcie dołączania akapitu ‘ZOBACZ TAKŻE’ kierującego czytelnika
141     do dokumentacji Texinfo.
142
143‘-l’
144‘--libtool’
145     Pominięcie przedrostka ‘lt-’ z wystąpień nazwy programu w sekcji
146     składni (‘libtool’ tworzy skrypty obudowujące w katalogu budowania,
147     wywołujące ‘foo’ jako ‘.libs/lt-foo’).
148
149‘--help’
150‘--version’
151     Wyświetlenie opisu lub informacji o wersji.
152
153   Domyślnie ‘help2man’ przekazuje do programu wykonywalnego standardowe
154opcje ‘--help’ oraz ‘--version’, ale można przekazać alternatywne nazwy
155przy użyciu opcji:
156
157‘-h OPCJA’
158‘--help-option=OPCJA’
159     Łańcuch określający opcję pomocy.
160
161‘-v OPCJA’
162‘--version-option=OPCJA’
163     Łańcuch określający opcję informacji o wersji.
164
165‘--version-string=ŁAŃCUCH’
166     Łańcuch określający wersję.
167
168‘--no-discard-stderr’
169     Dołączenie standardowego wyjścia diagnostycznego przy analizie
170     wyjścia z opcji.
171
172
173File: help2man-pl.info.tmp,  Node: Zalecenia --help,  Next: Dołączanie tekstu,  Prev: Uruchamianie help2man,  Up: Top
174
1753 Zalecenia dotyczące opcji ‘--help’
176************************************
177
178Poniżej można znaleźć trochę zaleceń, co powinno zawierać wyjście dla
179opcji ‘--help’.  Uwzględnienie ich pozwala programowi ‘help2man’
180wygenerować możliwie najlepiej reprezentacyjną stronę man, a także
181bezpośrednio pomóc użytkownikom.
182
183   Oficjalne standardy GNU dotyczące opcji ‘--help’ oraz stron man można
184znaleźć w dokumentach: *note (standards)Command-Line Interfaces:: oraz
185*note (standards)Man Pages::.
186
187   • Streszczenie opisu składni, jak uruchamiać program.  Jeśli różne
188     sposoby użycia programu mają różne składnie, należy wypisać
189     wszystkie.  Na przykład (zmodyfikowane dla zwięzłości):
190
191          Składnia: cp [OPCJA]... ŹRÓDŁO CEL
192              albo: cp [OPCJA]... ŹRÓDŁO... KATALOG
193          ...
194
195     W opisie składni programu należy używać ‘argv[0]’ w niezmienionej
196     postaci, bez usuwania katalogu.  Różni się to od kanonicznej
197     (stałej) nazwy programu, używanej w wyjściu opcji ‘--version’.
198
199   • Bardzo krótkie wyjaśnienie, co program robi, z uwzględnieniem
200     zachowania domyślnego i/lub typowego.  Na przykład, dla polecenia
201     ‘cp’:
202
203          Skopiowanie ŹRÓDŁA do CELU lub ŹRÓDŁA/ŹRÓDEŁ do KATALOGU.
204
205   • Lista opcji z wcięciem do kolumny 2.  Jeśli program obsługuje opcje
206     jednoznakowe, należy umieścić je jako pierwsze, a po nich
207     odpowiadające im opcje długie (jeśli istnieją).  Jeśli opcja
208     przyjmuje argument, należy go dołączyć, nadając mu znaczącą nazwę.
209     Opisy można wyrównać do wygodnej kolumny.  Uwaga: w celu poprawnego
210     rozpoznania przez ‘help2man’, opisy muszą być oddzielone od opcji
211     przynajmniej dwiema spacjami, a opisy kontynuowane w kolejnych
212     liniach muszą zaczynać się od tej samej kolumny.
213
214     Poniżej (zmodyfikowany) fragment z polecenia ‘cp’, pokazujący opcję
215     krótką z odpowiadającą jej opcją długą, opcję wyłącznie długą oraz
216     opcję wyłącznie krótką:
217
218            -a, --archive                to samo co -dpR
219                --backup[=TRYB]          robienie kopii zapasowej każdego ...
220            -b                           jak --backup, ale ...
221
222     W przypadku programów przyjmujących wiele opcji, może być warto
223     podzielić listę opcji na sekcje, takie jak na przykład ‘Globalne’,
224     ‘Sterowanie wyjściem’, czy cokolwiek mającego sens w konkretnym
225     przypadku.  Zwykle najlepiej opcje wypisywać w kolejności
226     alfabetycznej (najpierw dla opcji krótkich, potem długich) w ramach
227     każdej sekcji, lub całej listy, jeśli nie ma sekcji.
228
229   • Wszystkie przydatne dodatkowe informacje o zachowaniu programu,
230     takie jak zmienne środowiskowe wpływające na działanie, dalsze
231     wyjaśnienia opcji itp.  - na przykład ‘cp’ wyjaśnia zmienną
232     ‘VERSION_CONTROL’ oraz pliki rzadkie.
233
234   • Kilka przykładów typowego użycia, wedle uznania.  Jeden dobry
235     przykład często warty jest tysiąca słów opisu, więc jest zalecany.
236
237   • Na zakończenie linia oznajmująca, w jaki sposób zgłaszać błędy
238     pocztą elektroniczną.  Zwykle ADRESEM będzie ‘bug-PROGRAM@gnu.org’;
239     proszę w miarę możliwości używać tej postaci dla programów GNU.
240     Dobrze także wskazać stronę domową programu, inne listy pocztowe
241     itp.
242
243   Interfejsy programowe ‘argp’ i ‘popt’ pozwalają przekazać opisy opcji
244dla ‘--help’ w tej samej strukturze, co reszta definicji opcji; można
245rozważyć użycie tych funkcji do analizy opcji zamiast funkcji ‘getopt’.
246
247   Domyślnie ‘help2man’ stosuje heurystykę do identyfikowania części
248strony podręcznika: linia zawierająca ‘Opcje:’ spowoduje pojawienie się
249następującego po niej tekstu w sekcji ‘OPCJE’, a linia zaczynająca się
250od ‘Copyright’ pojawi się z sekcji ‘COPYRIGHT’.  Niezależnie od tej
251heurystyki, linia zawierająca ‘*Słowa*’ rozpocznie nową sekcję, a
252‘Słowa:’ nową podsekcję.
253
254
255File: help2man-pl.info.tmp,  Node: Dołączanie tekstu,  Next: Użycie Makefile,  Prev: Zalecenia --help,  Up: Top
256
2574 Dołączanie do wyjścia dodatkowego tekstu
258******************************************
259
260W wygenerowanej stronie można dołączyć dodatkowy statyczny tekst
261korzystając z opcji ‘--include’ oraz ‘--opt-include’ (*note Uruchamianie
262help2man::).  Chociaż pliki te mogą mieć dowolne nazwy, dla spójności
263sugerujemy dla plików dołączanych przez ‘help2man’ używać rozszerzenia
264‘.h2m’.
265
266   Format plików dołączanych tymi opcjami jest prosty:
267
268     [sekcja]
269     tekst
270
271     /wzorzec/
272     tekst
273
274   Bloki dosłownego tekstu *roff są wstawiane na wyjściu na początku
275wskazanej ‘[sekcji]’ (bez rozróżniania wielkości liter) lub po akapicie
276pasującym do ‘/wzorca/’.
277
278   Wzorce wykorzystują składnię perlowych wyrażeń regularnych; mogą po
279nich wystąpić modyfikatory ‘i’, ‘s’ lub ‘m’ (*note perlre(1):
280(*manpages*)perlre.).
281
282   Linie przed pierwszą sekcją lub wzorcem, zaczynające się od ‘-’, są
283przetwarzane jako opcje.  Cała reszta jest po cichu ignorowana i może
284być wykorzystana jako komentarze, słowa kluczowe RCS itp.
285
286   Kolejność sekcji na wyjściu (w ramach sekcji obecnych) to:
287
288     NAZWA
289     SKŁADNIA
290     OPIS
291     OPCJE
292     _inne_
293     ŚRODOWISKO
294     PLIKI
295     PRZYKŁADY
296     AUTOR
297     ZGŁASZANIE BŁĘDÓW
298     COPYRIGHT
299     ZOBACZ TAKŻE
300
301   Jakiekolwiek sekcje ‘[nazwa]’ i ‘[składnia]’, występujące w
302dołączanym pliku, zastąpią tekst, który byłby utworzony automatycznie
303(choć nadal nazwę można nadpisać w razie potrzeby opcję ‘--name’).
304
305   Pozostałe sekcje są dołączane do automatycznie utworzonego wyjścia
306dla standardowych sekcji podanych powyżej, lub dołączane w miejscu
307_inne_ (p.  wyżej) w takiej kolejności, w jakiej wystąpiły w dołączanym
308pliku.
309
310   Umiejscowienie tekstu wewnątrz sekcji można jawnie określić przy
311użyciu składni ‘[<sekcja]’, ‘[=sekcja]’ lub ‘[>sekcja]’, aby umieścić
312tekst odpowiednio przed, zamiast lub po domyślnym wyjściu.
313
314
315File: help2man-pl.info.tmp,  Node: Użycie Makefile,  Next: Zlokalizowane strony man,  Prev: Dołączanie tekstu,  Up: Top
316
3175 Użycie programu ‘help2man’ wraz z ‘make’
318******************************************
319
320Sugerowany sposób użycia narzędzia ‘help2man’ w plikach Makefile to
321utworzenie zależności strony podręcznika nie od programu wykonywalnego,
322ale od plików źródłowych, w których zdefiniowane jest wyjście opcji
323‘--help’ oraz ‘--version’.
324
325   Metoda ta pozwala na wygenerowanie strony podręcznika przez
326utrzymującego projekt i dołączenie w dystrybucji, dzięki czemu
327użytkownik końcowy nie musi mieć zainstalowanego programu ‘help2man’.
328
329   Przykładowa reguła dla programu ‘prog’ może wyglądać następująco:
330
331     prog.1: $(srcdir)/main.c
332             -$(HELP2MAN) --output=$@ --name='przykładowy program' ./prog
333
334   Wartość zmiennej ‘HELP2MAN’ można ustawić ‘configure.in’ używając na
335przykład:
336
337     AM_MISSING_PROG(HELP2MAN, help2man)
338
339   w przypadku korzystania z narzędzia ‘automake’ albo:
340
341     AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
342
343   w przypadku samego narzędzia ‘autoconf’.
344
345
346File: help2man-pl.info.tmp,  Node: Zlokalizowane strony man,  Next: Przykład,  Prev: Użycie Makefile,  Up: Top
347
3486 Wytwarzanie stron podręcznika w języku ojczystym
349**************************************************
350
351Strony podręcznika można wygenerować dla dowolnej lokalizacji
352obsługiwanej jednocześnie przez program oraz polecenie ‘help2man’ przy
353użyciu opcji ‘--locale’ (‘-L’).
354
355     help2man -L pl_PL -o cp.pl.1 cp
356
357   Języki aktualnie obsługiwane przez ‘help2man’ oraz *note Kontakt::,
358jak zgłaszać nowe tłumaczenia, można znaleźć na stronie
359<http://translationproject.org/domain/help2man.html>.
360
3616.1 Zmiana umiejscowienia katalogów komunikatów
362===============================================
363
364Przy tworzeniu zlokalizowanych stron podręcznika z katalogu budowania
365programu jest dość prawdopodobne, że tłumaczenia zainstalowane w
366standardowym miejscu nie będą (o ile w ogóle są zainstalowane) właściwe
367dla właśnie budowanej wersji programu.
368
369   Wraz z programem ‘help2man’ jest dostarczana biblioteka ładowalna,
370przechwytująca wywołania ‘bindtextdomain’, konfigurujące położenie
371katalogów komunikatów dla domeny określonej przez zmienną ‘$TEXTDOMAIN’
372i nadpisująca to położenie ścieżką podaną przez zmienną ‘$LOCALEDIR’.
373
374   Na przykład:
375
376     mkdir -p tmp/pl/LC_MESSAGES
377     cp po/pl.gmo tmp/pl/LC_MESSAGES/PROG.mo
378     LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
379       LOCALEDIR=tmp \
380       TEXTDOMAIN=PROG \
381       help2man -L pl_PL -i PROG.pl.h2m -o PROG.pl.1 PROG
382     rm -rf tmp
383
384   spowoduje, że PROG wczyta katalog komunikatów z ‘tmp’ zamiast
385‘/usr/share/locale’.
386
387   Uwagi:
388   • Uogólnienie ‘pl_PL’ do ‘pl’ w powyższym przykładzie jest wykonywane
389     przez ‘gettext’; gdyby było dostępne bardziej konkretne
390     dopasowanie, byłoby także przemapowane.
391
392   • To ładowanie biblioteki było testowane tylko z bibliotekami
393     ‘eglibc’ 2.11.2 i ‘gettext’ 0.18.1.1 na systemie GNU/Linux; jeśli
394     nie działa w innym przypadku, proszę to zgłosić (*note Kontakt::).
395
396
397File: help2man-pl.info.tmp,  Node: Przykład,  Next: Kontakt,  Prev: Zlokalizowane strony man,  Up: Top
398
3997 Przykładowe wyjście ‘help2man’
400********************************
401
402Dla hipotetycznego programu ‘foo’, dającego następujące wyjście:
403
404     $ foo --version
405     GNU foo 1.1
406
407     Copyright (C) 2011 Free Software Foundation, Inc.
408     Ten program jest wolnodostępny; warunki kopiowania są opisane w źródłach.
409     Autorzy nie dają ŻADNYCH gwarancji, w tym również gwarancji PRZYDATNOŚCI
410     DO SPRZEDAŻY LUB DO KONKRETNYCH CELÓW.
411
412     Program napisał A. Programista.
413     $ foo --help
414     GNU `foo' nie robi nic ciekawego, poza służeniem jako przykład dla programu
415     `help2man'.
416
417     Składnia: foo [OPCJA]...
418
419     Opcje:
420       -a, --option      opcja
421       -b, --another-option[=WARTOŚĆ]
422                         inna opcja
423           --help        wyświetlenie tego opisu i zakończenie
424           --version     wypisanie informacji o wersji i zakończenie
425
426     Przykłady:
427       foo               nic nie robi
428       foo --option      to samo, z podaniem `--option'
429
430     Błędy prosimy zgłaszać na adres <bug-gnu-utils@gnu.org>.
431
432   ‘help2man’ utworzy wejście dla programu ‘nroff’ dla strony
433podręcznika man, która będzie sformatowana podobnie do poniższej:
434
435     FOO(1)                     Polecenia użytkownika                    FOO(1)
436
437     NAZWA
438            foo - strona podręcznika dla foo 1.1
439
440     SKŁADNIA
441            foo [OPCJA]...
442
443     OPIS
444            GNU  `foo'  nie robi nic ciekawego, poza służeniem jako przykład dla
445            programu `help2man'.
446
447     OPCJE
448            -a, --option
449                   opcja
450
451            -b, --another-option[=WARTOŚĆ]
452                   inna opcja
453
454            --help wyświetlenie tego opisu i zakończenie
455
456            --version
457                   wypisanie informacji o wersji i zakończenie
458
459     PRZYKŁAD
460            foo    nic nie robi
461
462            foo --option
463                   to samo, z podaniem `--option'
464
465     AUTOR
466            Program napisał A. Programista.
467
468     ZGŁASZANIE BŁĘDÓW
469            Błędy prosimy zgłaszać na adres <bug-gnu-utils@gnu.org>.
470
471     COPYRIGHT
472            Copyright © 2011 Free Software Foundation, Inc.
473            Ten program jest wolnodostępny; warunki kopiowania są opisane w źródłach.
474            Autorzy nie dają ŻADNYCH gwarancji, w tym również gwarancji PRZYDATNOŚCI
475            DO SPRZEDAŻY LUB DO KONKRETNYCH CELÓW.
476
477     ZOBACZ TAKŻE
478            Pełna dokumentacja dla programu foo jest utrzymywana jako podręcznik
479            Texinfo. Jeśli programy info oraz foo są właściwie zainstalowane,
480            polecenie
481
482                   info foo
483
484            powinno udostępnić kompletny podręcznik.
485
486     foo 1.1                          Maj 2011                           FOO(1)
487
488
489File: help2man-pl.info.tmp,  Node: Kontakt,  Next: Dostępność,  Prev: Przykład,  Up: Top
490
4918 Zgłaszanie błędów i propozycji
492********************************
493
494Aby zgłosić napotkany problem lub propozycję, prosimy skontaktować się
495pod adresem <bug-help2man@gnu.org>.
496
497   Uwaga do tłumaczy: tłumaczenia są obsługiwane poprzez Translation
498Project (http://translationproject.org/), szczegóły pod adresem
499<http://translationproject.org/html/translators.html>.
500
501
502File: help2man-pl.info.tmp,  Node: Dostępność,  Prev: Kontakt,  Up: Top
503
5049 Pozyskiwanie programu ‘help2man’
505**********************************
506
507Najnowsza wersja tego pakietu jest dostępna w sieci z serwerów
508lustrzanych GNU:
509
510     <http://ftpmirror.gnu.org/help2man/>
511
512   Jeśli automatyczne przekierowanie się nie powiedzie, listę serwerów
513można uzyskać pod:
514
515     <http://www.gnu.org/order/ftp.html>
516
517   Albo, w razie potrzeby, można użyć głównego serwera ftp GNU:
518     <http://ftp.gnu.org/gnu/help2man/>
519
520
521Tag Table:
522Node: Top1235
523Node: Przegląd2276
524Node: Uruchamianie help2man3089
525Node: Zalecenia --help6195
526Node: Dołączanie tekstu10432
527Node: Użycie Makefile12563
528Node: Zlokalizowane strony man13757
529Node: Przykład15876
530Node: Kontakt18773
531Node: Dostępność19248
532
533End Tag Table
534
535
536Local Variables:
537coding: utf-8
538End:
539