1 This is help2man-pl.info.tmp, produced by makeinfo version 6.7 from
4 Ten plik opisuje polecenie GNU ‘help2man’, tworzące proste strony
5 podręcznika man z wyjścia ‘--help’ oraz ‘--version’ innych poleceń.
7 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
8 2011, 2012, 2013, 2014, 2015, 2020, 2021 Free Software Foundation, Inc.
10 Zezwala się na tworzenie i rozprowadzanie dokładnych kopii tego
11 podręcznika, pod warunkiem zachowania we wszystkich kopiach informacji o
12 prawach autorskich oraz niniejszej informacji.
14 Zezwala się na kopiowanie i rozprowadzanie zmodyfikowanych wersji
15 tego podręcznika na takich warunkach, jak dokładnych kopii, pod
16 warunkiem, że całe dzieło pochodne jest rozprowadzanie na warunkach
17 takich samych, jak niniejsze.
19 Zezwala się na kopiowanie i rozprowadzanie tłumaczeń tego podręcznika
20 na inny język na takich warunkach, jak wersje zmodyfikowane, z wyjątkiem
21 tego, że niniejsze oświadczenie może wystąpić w tłumaczeniu
22 zaaprobowanym przez Free Software Foundation.
23 INFO-DIR-SECTION Rozwijanie oprogramowania
25 * help2man-pl: (help2man-pl). Automatyczne tworzenie stron podręcznika
30 File: help2man-pl.info.tmp, Node: Top, Next: Przegląd, Up: (dir)
35 Polecenie ‘help2man’ tworzy proste strony podręcznika man z wyjścia
36 ‘--help’ oraz ‘--version’ innych poleceń.
40 * Przegląd:: Przegląd polecenia ‘help2man’.
41 * Uruchamianie help2man:: Jak uruchomić polecenie ‘help2man’.
42 * Zalecenia --help:: Zalecenia dotyczące formatowania
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
49 * Przykład:: Przykładowe wyjście polecenia‘help2man’.
50 * Kontakt:: Zgłaszanie błędów i propozycji.
51 * Dostępność:: Pozyskiwanie programu ‘help2man’.
54 File: help2man-pl.info.tmp, Node: Przegląd, Next: Uruchamianie help2man, Prev: Top, Up: Top
56 1 Przegląd polecenia ‘help2man’
57 *******************************
59 ‘help2man’ to narzędzie do automatycznego generowania prostych stron
60 podręcznika man z wyjścia programów.
62 Mimo że strony podręcznika man są opcjonalne dla programów GNU, inne
63 projekty - takie jak Debian - wymagają ich (*note (standards)Man
66 Ten program ma na celu zapewnienie autorom programów prostej metody
67 dołączania stron podręcznika man bez potrzeby utrzymywania tego
70 Po wskazaniu programu tworzącego w miarę standardowe opisy jako
71 wyjście opcji ‘--help’ oraz ‘--version’, polecenie ‘help2man’ potrafi
72 przekształcić te opisy w coś przypominającego stronę podręcznika.
75 File: help2man-pl.info.tmp, Node: Uruchamianie help2man, Next: Zalecenia --help, Prev: Przegląd, Up: Top
77 2 Jak uruchomić ‘help2man’
78 **************************
80 Składnia przy uruchamianiu programu ‘help2man’ jest następująca:
82 help2man [OPCJA]... PROGRAM
84 ‘help2man’ obsługuje następujące opcje:
88 Użycie ŁAŃCUCHA jako opisu dla akapitu ‘NAZWA’ strony podręcznika.
90 Domyślnie (przy braku czegokolwiek lepszego) akapit ten zawiera
91 ‘strona podręcznika dla PROGRAM WERSJA’.
93 Ta opcja nadpisuje sekcję pliku dołączanego ‘[nazwa]’ (*note
98 Użycie SEKCJI jako sekcji dla strony podręcznika man. Domyślną
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
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.
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
123 Dołączenie treści z PLIKU (*note Dołączanie tekstu::).
127 Wariant ‘--include’ do wykorzystania w regułach szablonów Makefile,
128 nie wymagający istnienia PLIKU.
132 Zapis wyjścia do PLIKU zamiast na ‘standardowe wyjście’.
136 Nazwa podręcznika Texinfo.
140 Pominięcie dołączania akapitu ‘ZOBACZ TAKŻE’ kierującego czytelnika
141 do dokumentacji Texinfo.
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’).
151 Wyświetlenie opisu lub informacji o wersji.
153 Domyślnie ‘help2man’ przekazuje do programu wykonywalnego standardowe
154 opcje ‘--help’ oraz ‘--version’, ale można przekazać alternatywne nazwy
158 ‘--help-option=OPCJA’
159 Łańcuch określający opcję pomocy.
162 ‘--version-option=OPCJA’
163 Łańcuch określający opcję informacji o wersji.
165 ‘--version-string=ŁAŃCUCH’
166 Łańcuch określający wersję.
168 ‘--no-discard-stderr’
169 Dołączenie standardowego wyjścia diagnostycznego przy analizie
173 File: help2man-pl.info.tmp, Node: Zalecenia --help, Next: Dołączanie tekstu, Prev: Uruchamianie help2man, Up: Top
175 3 Zalecenia dotyczące opcji ‘--help’
176 ************************************
178 Poniżej można znaleźć trochę zaleceń, co powinno zawierać wyjście dla
179 opcji ‘--help’. Uwzględnienie ich pozwala programowi ‘help2man’
180 wygenerować możliwie najlepiej reprezentacyjną stronę man, a także
181 bezpośrednio pomóc użytkownikom.
183 Oficjalne standardy GNU dotyczące opcji ‘--help’ oraz stron man można
184 znaleźć w dokumentach: *note (standards)Command-Line Interfaces:: oraz
185 *note (standards)Man Pages::.
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):
191 Składnia: cp [OPCJA]... ŹRÓDŁO CEL
192 albo: cp [OPCJA]... ŹRÓDŁO... KATALOG
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’.
199 • Bardzo krótkie wyjaśnienie, co program robi, z uwzględnieniem
200 zachowania domyślnego i/lub typowego. Na przykład, dla polecenia
203 Skopiowanie ŹRÓDŁA do CELU lub ŹRÓDŁA/ŹRÓDEŁ do KATALOGU.
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.
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ą:
218 -a, --archive to samo co -dpR
219 --backup[=TRYB] robienie kopii zapasowej każdego ...
220 -b jak --backup, ale ...
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.
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.
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.
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
243 Interfejsy programowe ‘argp’ i ‘popt’ pozwalają przekazać opisy opcji
244 dla ‘--help’ w tej samej strukturze, co reszta definicji opcji; można
245 rozważyć użycie tych funkcji do analizy opcji zamiast funkcji ‘getopt’.
247 Domyślnie ‘help2man’ stosuje heurystykę do identyfikowania części
248 strony podręcznika: linia zawierająca ‘Opcje:’ spowoduje pojawienie się
249 następującego po niej tekstu w sekcji ‘OPCJE’, a linia zaczynająca się
250 od ‘Copyright’ pojawi się z sekcji ‘COPYRIGHT’. Niezależnie od tej
251 heurystyki, linia zawierająca ‘*Słowa*’ rozpocznie nową sekcję, a
252 ‘Słowa:’ nową podsekcję.
255 File: help2man-pl.info.tmp, Node: Dołączanie tekstu, Next: Użycie Makefile, Prev: Zalecenia --help, Up: Top
257 4 Dołączanie do wyjścia dodatkowego tekstu
258 ******************************************
260 W wygenerowanej stronie można dołączyć dodatkowy statyczny tekst
261 korzystając z opcji ‘--include’ oraz ‘--opt-include’ (*note Uruchamianie
262 help2man::). Chociaż pliki te mogą mieć dowolne nazwy, dla spójności
263 sugerujemy dla plików dołączanych przez ‘help2man’ używać rozszerzenia
266 Format plików dołączanych tymi opcjami jest prosty:
274 Bloki dosłownego tekstu *roff są wstawiane na wyjściu na początku
275 wskazanej ‘[sekcji]’ (bez rozróżniania wielkości liter) lub po akapicie
276 pasującym do ‘/wzorca/’.
278 Wzorce wykorzystują składnię perlowych wyrażeń regularnych; mogą po
279 nich wystąpić modyfikatory ‘i’, ‘s’ lub ‘m’ (*note perlre(1):
280 (*manpages*)perlre.).
282 Linie przed pierwszą sekcją lub wzorcem, zaczynające się od ‘-’, są
283 przetwarzane jako opcje. Cała reszta jest po cichu ignorowana i może
284 być wykorzystana jako komentarze, słowa kluczowe RCS itp.
286 Kolejność sekcji na wyjściu (w ramach sekcji obecnych) to:
301 Jakiekolwiek sekcje ‘[nazwa]’ i ‘[składnia]’, występujące w
302 dołączanym pliku, zastąpią tekst, który byłby utworzony automatycznie
303 (choć nadal nazwę można nadpisać w razie potrzeby opcję ‘--name’).
305 Pozostałe sekcje są dołączane do automatycznie utworzonego wyjścia
306 dla 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
310 Umiejscowienie tekstu wewnątrz sekcji można jawnie określić przy
311 użyciu składni ‘[<sekcja]’, ‘[=sekcja]’ lub ‘[>sekcja]’, aby umieścić
312 tekst odpowiednio przed, zamiast lub po domyślnym wyjściu.
315 File: help2man-pl.info.tmp, Node: Użycie Makefile, Next: Zlokalizowane strony man, Prev: Dołączanie tekstu, Up: Top
317 5 Użycie programu ‘help2man’ wraz z ‘make’
318 ******************************************
320 Sugerowany sposób użycia narzędzia ‘help2man’ w plikach Makefile to
321 utworzenie zależności strony podręcznika nie od programu wykonywalnego,
322 ale od plików źródłowych, w których zdefiniowane jest wyjście opcji
323 ‘--help’ oraz ‘--version’.
325 Metoda ta pozwala na wygenerowanie strony podręcznika przez
326 utrzymującego projekt i dołączenie w dystrybucji, dzięki czemu
327 użytkownik końcowy nie musi mieć zainstalowanego programu ‘help2man’.
329 Przykładowa reguła dla programu ‘prog’ może wyglądać następująco:
331 prog.1: $(srcdir)/main.c
332 -$(HELP2MAN) --output=$@ --name='przykładowy program' ./prog
334 Wartość zmiennej ‘HELP2MAN’ można ustawić ‘configure.in’ używając na
337 AM_MISSING_PROG(HELP2MAN, help2man)
339 w przypadku korzystania z narzędzia ‘automake’ albo:
341 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
343 w przypadku samego narzędzia ‘autoconf’.
346 File: help2man-pl.info.tmp, Node: Zlokalizowane strony man, Next: Przykład, Prev: Użycie Makefile, Up: Top
348 6 Wytwarzanie stron podręcznika w języku ojczystym
349 **************************************************
351 Strony podręcznika można wygenerować dla dowolnej lokalizacji
352 obsługiwanej jednocześnie przez program oraz polecenie ‘help2man’ przy
353 użyciu opcji ‘--locale’ (‘-L’).
355 help2man -L pl_PL -o cp.pl.1 cp
357 Języki aktualnie obsługiwane przez ‘help2man’ oraz *note Kontakt::,
358 jak zgłaszać nowe tłumaczenia, można znaleźć na stronie
359 <http://translationproject.org/domain/help2man.html>.
361 6.1 Zmiana umiejscowienia katalogów komunikatów
362 ===============================================
364 Przy tworzeniu zlokalizowanych stron podręcznika z katalogu budowania
365 programu jest dość prawdopodobne, że tłumaczenia zainstalowane w
366 standardowym miejscu nie będą (o ile w ogóle są zainstalowane) właściwe
367 dla właśnie budowanej wersji programu.
369 Wraz z programem ‘help2man’ jest dostarczana biblioteka ładowalna,
370 przechwytująca wywołania ‘bindtextdomain’, konfigurujące położenie
371 katalogów komunikatów dla domeny określonej przez zmienną ‘$TEXTDOMAIN’
372 i nadpisująca to położenie ścieżką podaną przez zmienną ‘$LOCALEDIR’.
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" \
381 help2man -L pl_PL -i PROG.pl.h2m -o PROG.pl.1 PROG
384 spowoduje, że PROG wczyta katalog komunikatów z ‘tmp’ zamiast
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.
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::).
397 File: help2man-pl.info.tmp, Node: Przykład, Next: Kontakt, Prev: Zlokalizowane strony man, Up: Top
399 7 Przykładowe wyjście ‘help2man’
400 ********************************
402 Dla hipotetycznego programu ‘foo’, dającego następujące wyjście:
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.
412 Program napisał A. Programista.
414 GNU `foo' nie robi nic ciekawego, poza służeniem jako przykład dla programu
417 Składnia: foo [OPCJA]...
421 -b, --another-option[=WARTOŚĆ]
423 --help wyświetlenie tego opisu i zakończenie
424 --version wypisanie informacji o wersji i zakończenie
428 foo --option to samo, z podaniem `--option'
430 Błędy prosimy zgłaszać na adres <bug-gnu-utils@gnu.org>.
432 ‘help2man’ utworzy wejście dla programu ‘nroff’ dla strony
433 podręcznika man, która będzie sformatowana podobnie do poniższej:
435 FOO(1) Polecenia użytkownika FOO(1)
438 foo - strona podręcznika dla foo 1.1
444 GNU `foo' nie robi nic ciekawego, poza służeniem jako przykład dla
451 -b, --another-option[=WARTOŚĆ]
454 --help wyświetlenie tego opisu i zakończenie
457 wypisanie informacji o wersji i zakończenie
463 to samo, z podaniem `--option'
466 Program napisał A. Programista.
469 Błędy prosimy zgłaszać na adres <bug-gnu-utils@gnu.org>.
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.
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,
484 powinno udostępnić kompletny podręcznik.
486 foo 1.1 Maj 2011 FOO(1)
489 File: help2man-pl.info.tmp, Node: Kontakt, Next: Dostępność, Prev: Przykład, Up: Top
491 8 Zgłaszanie błędów i propozycji
492 ********************************
494 Aby zgłosić napotkany problem lub propozycję, prosimy skontaktować się
495 pod adresem <bug-help2man@gnu.org>.
497 Uwaga do tłumaczy: tłumaczenia są obsługiwane poprzez Translation
498 Project (http://translationproject.org/), szczegóły pod adresem
499 <http://translationproject.org/html/translators.html>.
502 File: help2man-pl.info.tmp, Node: Dostępność, Prev: Kontakt, Up: Top
504 9 Pozyskiwanie programu ‘help2man’
505 **********************************
507 Najnowsza wersja tego pakietu jest dostępna w sieci z serwerów
510 <http://ftpmirror.gnu.org/help2man/>
512 Jeśli automatyczne przekierowanie się nie powiedzie, listę serwerów
515 <http://www.gnu.org/order/ftp.html>
517 Albo, w razie potrzeby, można użyć głównego serwera ftp GNU:
518 <http://ftp.gnu.org/gnu/help2man/>
523 Node: Przegląd
\7f2271
524 Node: Uruchamianie help2man
\7f3084
525 Node: Zalecenia --help
\7f6190
526 Node: Dołączanie tekstu
\7f10427
527 Node: Użycie Makefile
\7f12558
528 Node: Zlokalizowane strony man
\7f13752
529 Node: Przykład
\7f15871
530 Node: Kontakt
\7f18768
531 Node: Dostępność
\7f19243