.\" -*- coding: UTF-8 -*- '\" t .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler .\" (faith@cs.unc.edu and dwheeler@ida.org) .\" and (C) Copyright 2007 Michael Kerrisk .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" 2007-05-30 created by mtk, using text from old man.7 plus .\" rewrites and additional text. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH man\-pages 7 "15 czerwca 2024 r." "Linux man\-pages 6.9.1" .SH NAZWA man\-pages \- konwencje pisania linuksowych stron podręcznika ekranowego .SH SKŁADNIA \fBman\fP [\fIsekcja\fP] \fItytuł\fP .SH OPIS Strona opisuje konwencje, do których powinno się stosować podczas pisania stron podręcznika ekranowego dla projektu Linux \fIman\-pages\fP, który dokumentuje interfejs programistyczny w przestrzeni użytkownika udostępniany przez jądro Linux i bibliotekę GNU C. Z tego powodu projekt dotyczy głównie sekcji 2 podręcznika systemowego, wielu podręczników z sekcji 3, 4 i 7 oraz niektórych podręczników z sekcji 1, 5 i 8. Konwencje opisane tutaj mogą się także przydać autorom podręczników z innych projektów. .SS "Sekcje stron podręcznika ekranowego" Sekcje podręcznika man są tradycyjnie definiowane następująco: .TP \fB1 Komendy użytkownika (programy)\fP Komendy mogą być wykonywane przez użytkownika z powłoki. .TP \fB2 Wywołania systemowe\fP Funkcje opakowują operacje wykonywane przez jądro. .TP \fB3 Wywołania biblioteczne\fP Wszystkie funkcje biblioteczne z wyłączeniem opakowań wywołań systemowych (większość z funkcji \fIlibc\fP). .TP \fB4 Pliki specjalne (urządzenia)\fP Pliki w \fI/dev\fP pozwalające na dostęp do urządzenia poprzez jądro. .TP \fB5 Formaty plików i pliki konfiguracyjne\fP Opisują różne czytelne dla człowieka formaty plików i pliki konfiguracyjne. .TP \fB6 Gry\fP Gry i zabawne programiki dostępne w systemie. .TP \fB7 Przegląd, konwencje i różnorodne\fP Przegląd i opsi różnych tematów, konwencje, protokoły, standardy kodowania znaków, standardowego wyglądu systemu plików i inne. .TP \fB8 Polecenia do zarządzania systemem\fP .\" .TP .\" .B 9 Kernel routines .\" This is an obsolete manual section. .\" Once it was thought a good idea to document the Linux kernel here, .\" but in fact very little has been documented, and the documentation .\" that exists is outdated already. .\" There are better sources of .\" information for kernel developers. Komendy takie, jak \fBmount\fP(8), które wywoływać może tylko root . .SS "Pakiety makr" Nowe strony podręcznika powinny być pisane z użyciem pakietu makr \fBgroff an.tmac\fP opisanego w \fBman\fP(7). Wybór ten podyktowany jest zachowaniem spójności: przytłaczająca większość istniejących podręczników linuksowych używa tego pakietu makr. .SS "Konwencje wyglądu pliku źródłowego" Prosimy ograniczać długość linii kodu źródłowego do maksymalnie 75 znaków, jeśli jest to możliwe. Pomaga to unikać zawijania wierszy w niektórych programach pocztowych podczas przesyłania łat do podręczników ekranowych. .SS "Linia tytułowa" Pierwszą komendą strony podręcznika powinno być polecenie \fBTH\fP: .P .RS \fB\&.TH\fP \fItytuł sekcja data źródło rozdział\-podręcznika\fP .RE .P Argumenty komendy są następujące: .TP \fItytuł\fP Tytuł strony podręcznika, pisany w całości dużymi literami (np. \fIMAN\-PAGES\fP). .TP \fIsekcja\fP Numer sekcji, w której strona powinna się znaleźć (np. \fI7\fP). .TP \fIdata\fP Data ostatniej nietrywialnej zmiany dokonanej w podręczniku. W projekcie \fIman\-pages\fP konieczna aktualizacja tych dat jest wykonywana automatycznie przez skrypty, dlatego nie ma konieczności zawierania ręcznej aktualizacji w łatce). Daty powinny być zapisywane w postaci RRRR\-MM\-DD. .TP \fIźródło\fP Nazwa i wersja projektu udostępniającego stronę podręcznika (niekoniecznie będzie to pakiet, który udostępnia samą funkcjonalność). .TP \fIrozdział\-podręcznika\fP .\" Zwykle pole to powinno pozostać puste, jako że wartość domyślna jest wystarczająca. .SS "Rozdziały stron podręcznika" Poniższa lista pokazuje rozdziały konwencjonalne lub sugerowane. Większość stron podręcznika powinna zawierać przynajmniej \fIwyróżnione\fP rozdziały. Prosimy pisać nowe strony podręcznika w taki sposób, by rozdziały pojawiały się w takiej kolejności, w jakiej są podane na liście. .P .RS .TS l l. \fBNAZWA\fP BIBLIOTEKA [Zwykle tylko w sekcjach 2 i 3] \fBSKŁADNIA\fP KONFIGURACJA [Zwykle tylko w sekcji 4] \fBOPIS\fP OPCJE [Zwykle tylko w sekcjach 1 i 8] STATUS ZAKOŃCZENIA [Zwykle tylko w sekcjach 1 i 8] WARTOŚĆ ZWRACANA [Zwykle tylko w sekcjach 2 i 3] .\" May 07: Few current man pages have an ERROR HANDLING section,,, .\" ERROR HANDLING, BŁĘDY [Zwykle tylko w sekcjach 2 i 3] .\" May 07: Almost no current man pages have a USAGE section,,, .\" USAGE, .\" DIAGNOSTICS, .\" May 07: Almost no current man pages have a SECURITY section,,, .\" SECURITY, ŚRODOWISKO PLIKI ATRYBUTY [Zwykle tylko w sekcjach 2 i 3] WERSJE [Zwykle tylko w sekcjach 2 i 3] STANDARDY HISTORIA UWAGI ZASTRZEŻENIA USTERKI PRZYKŁADY .\" AUTHORS sections are discouraged AUTORZY [Odradzane] ZGŁASZANIE BŁĘDÓW [Nieużywane w projekcie man\-pages] PRAWA AUTORSKIE [Nieużywane w projekcie man\-pages] \fBZOBACZ TAKŻE\fP .TE .RE .P W celu zachowania spójności i dla lepszego zrozumienia przekazywanych informacji \fIprosimy używać zwyczajowych nagłówków wszędzie\fP, \fIgdzie mają zastosowanie\fP. Jeśli jest to konieczne, można użyć własnych nagłówków, zwłaszcza gdy sprawią, że tekst łatwiej będzie zrozumieć (może być to szczególnie użyteczne w sekcjach 4. i 5.). Jednakże zanim użyje się własnych nagłówków, prosimy rozważyć użycie nagłówków zwyczajowych i umieszczenie podrozdziałów (\fI.SS\fP) w rozdziałach opisanych tymi nagłówkami. .P Poniżej opisujemy zawartość każdej z powyższych sekcji. .TP \fBNAZWA\fP Nazwa strony podręcznika systemowego. .IP Podręcznik \fBman\fP(7) zawiera ważne detale na temat wierszy które powinny znaleźć się za poleceniem \fB.SH NAZWA\fP. Wszystkie słowa w tym wierszu (łącznie ze słowami występującymi zaraz za "\[rs]\-") powinny być pisane małymi literami z wyjątkiem konwencji terminologii lub wymagań językowych, które mówią inaczej. .TP \fBBIBLIOTEKA\fP Biblioteka udostępniająca symbol. .IP Pokazywana jest tu ogólna nazwa biblioteki, następnie, w nawiasie, nazwa pliku biblioteki oraz, jeśli to potrzebne, flaga konsolidatora wymaganego do podlinkowania do niego programu (\fIlibfoo\fP[, \fI\-lfoo\fP]). .TP \fBSKŁADNIA\fP Zwięzłe podsumowanie interfejsu polecenia lub funkcji. .IP W przypadku poleceń pokazuje składnię polecenia i jego argumenty (łącznie z opcjami); pogrubienie jest używane dla tekstu wpisywanego dosłownie, a kursywa oznacza zastępowalne argumenty. Nawiasy kwadratowe ([]) otaczają argumenty opcjonalne, linie pionowe (|) rozdzielają możliwe wybory, a wielokropek (\&...) oznacza możliwość powtarzania. W wypadku funkcji pokazuje wszystkie wymagane deklaracje danych lub dyrektywy \fB#include\fP, po których następuje deklaracja funkcji. .IP .\" FIXME . Say something here about compiler options Jeżeli do uzyskania deklaracji funkcji (lub zmiennej) z pliku nagłówkowego wymagane jest zdefiniowanie makra testującego, to informacja o tym powinna zostać umieszczona w rozdziale SKŁADNIA (SYNOPSIS), tak jak to opisano w \fBfeature_test_macros\fP(7). .TP \fBKONFIGURACJA\fP Szczegóły konfiguracji urządzenia. .IP Ta sekcja zazwyczaj występuje tylko w 4. sekcji stron podręcznika ekranowego. .TP \fBOPIS\fP Opis tego, co robi dany program, funkcja lub format. .IP .\" If there is some kind of input grammar or complex set of subcommands, .\" consider describing them in a separate .\" .B USAGE .\" section (and just place an overview in the .\" .B DESCRIPTION .\" section). Objaśnia interakcję z plikami i standardowym wejściem oraz wartości zwracane na standardowym wyjściu i standardowym wyjściu błędów. Pomijane są szczegóły dotyczące implementacji i rzeczy wewnętrzne programu, chyba że są istotne dla zrozumienia interfejsu programu. Opisuje normalne przypadki użycia; objaśnienie opcji powinno się znaleźć w rozdziale \fBOPCJE\fP. .IP Przy opisywaniu nowego zachowania lub nowych flag wywołania systemowego lub funkcji bibliotecznej, proszę pamiętać o zanotowaniu wersji jądra lub biblioteki C która wprowadziła tę zmianę. Zalecaną metodą przestawienia tej informacji przy flagach jest postać części listy \fB.TP\fP, w następującej formie (tutaj dla nowej flagi wywołania systemowego): .RS 16 .TP \fBXYZ_FLAG\fP (od Linuksa 3.7) Opis flagi... .RE .IP Dołączenie informacji o wersji jest szczególnie ważne dla użytkowników którzy są zmuszeni korzystać ze starszego jądra lub biblioteki C (co jest powszechne w przypadku np. systemów wbudowanych). .TP \fBOPCJE\fP Opis opcji wiersza poleceń akceptowane przez program oraz sposób, w jaki wpływają na jego zachowanie. .IP .\" .TP .\" .B USAGE .\" describes the grammar of any sublanguage this implements. Rozdział powinien się pojawiać tylko w sekcjach 1. i 8. stron podręcznika ekranowego. .TP \fBKOD WYJŚCIA\fP Określa możliwe wartości kodów zakończenia programu oraz warunki, które powodują zwrócenie tych wartości. .IP Rozdział powinien się pojawiać tylko w sekcjach 1. i 8. stron podręcznika ekranowego. .TP \fBWARTOŚĆ ZWRACANA\fP W sekcjach 2. i 3. stron podręcznika, rozdział ten określa listę wartości, które opisywana funkcja biblioteczna zwróci funkcji ją wywołującej, oraz warunki, w których dana wartość będzie zwracana. .TP \fBBŁĘDY\fP W sekcjach 2. i 3. stron podręcznika jest to lista wartości, które mogą być przypisane zmiennej \fIerrno\fP w razie wystąpienia błędu, łącznie z informacjami o przyczynach tego błędu. .IP Gdy wiele różnych warunków wywołuje ten sam błąd, preferowanym podejściem jest utworzenie odrębnych wpisów listy (z powtórzonymi nazwami błędów) dla każdego z warunków. W ten sposób jasna będzie rozdzielność warunków, w których wystąpił błąd, lista może być czytelniejsza oraz można podać dodatkowe informacje specyficzne dla każdego z warunków (np. wersję jądra, w której po raz pierwszy wystąpił dany warunek). .IP \fIElementy listy powinny być wymienione w porządku alfabetycznym\fP. .TP \fBŚRODOWISKO\fP Lista wszystkich zmiennych środowiskowych, wpływających na program i opis tego wpływu. .TP \fBPLIKI\fP Lista plików używanych przez program lub funkcję, takich jak pliki konfiguracyjne, pliki uruchomieniowe oraz pliki używane w czasie działania programu. .IP .\" May 07: Almost no current man pages have a DIAGNOSTICS section; .\" "RETURN VALUE" or "EXIT STATUS" is preferred. .\" .TP .\" .B DIAGNOSTICS .\" gives an overview of the most common error messages and how to .\" cope with them. .\" You don't need to explain system error messages .\" or fatal signals that can appear during execution of any program .\" unless they're special in some way to the program. .\" .\" May 07: Almost no current man pages have a SECURITY section. .\".TP .\".B SECURITY .\"discusses security issues and implications. .\"Warn about configurations or environments that should be avoided, .\"commands that may have security implications, and so on, especially .\"if they aren't obvious. .\"Discussing security in a separate section isn't necessary; .\"if it's easier to understand, place security information in the .\"other sections (such as the .\" .B DESCRIPTION .\" or .\" .B USAGE .\" section). .\" However, please include security information somewhere! Należy podać pełną ścieżkę do pliku, w której podczas instalacji powinno się zmodyfikować katalogi, tak żeby odpowiadały preferencjom użytkownika. Wiele programów domyślnie instaluje się w \fI/usr/local\fP, tak że strona podręcznika powinna używać \fI/usr/local\fP jako podstawowego katalogu. .TP \fBATRYBUTY\fP Podsumowanie różnych atrybutów funkcji udokumentowanych na danej stronie podręcznika. Więcej informacji w podręczniku \fBattributes\fP(7). .TP \fBWERSJE\fP Podsumowanie systemów, na których API zachowuje się odmiennie lub gdzie występuje podobne API. .TP \fBSTANDARDY\fP Opisuje standardy lub konwencje związane z opisywaną w podręczniku funkcją lub opisywanym poleceniem. .IP Preferowane terminy do użycia w różnych standardach są wypisane jako nagłówki w \fBstandards\fP(7). .IP Ten rozdział powinien odnotowywać obecne standardy, z którymi zgodne jest API. .IP Jeśli API nie jest zamieszczone w żadnym standardzie, ale zwyczajowo istnieje w innych systemach, prosimy wymienić te systemy. Jeśli wywołanie jest specyficzne dla Linuksa lub GNU, również należy o tym poinformować. Należy zamieścić również wzmiankę, jeśli jest dostępne w BSD. .IP Jeśli rozdział zawiera tylko i wyłącznie listę standardów (a tak jest zazwyczaj), lista ta powinna być zakończona kropką ("."). .TP \fBHISTORIA\fP Zwięzłe podsumowanie wersji jądra Linux lub glibc, w których pojawiło się wywołanie systemowe lub funkcja biblioteczna, albo w której znacznie zmieniło się jej działania. .IP Z zasady każda strona podręcznika opisująca nowy interfejs powinna zawierać rozdział HISTORIA. Niestety wiele istniejących stron nie dołącza tych informacji (gdyż nie było to wymagane w czasie pisania tych stron). Chętnie przyjmiemy łaty poprawiające ten problem, jednakże z perspektywy programisty informacje o wersji mają najprawdopodobniej znaczenie tylko w przypadku interfejsów jądra dodanych w Linuksie 2.4 lub kolejnych (tj. zmiany w stosunku do Linuksa 2.2) oraz w przypadku funkcji bibliotecznych dołożonych do glibc od wersji 2.1 (tj. zmiany w stosunku do wersji 2.0). .IP Strona podręcznika \fBsyscalls\fP(2) także dostarcza informacji o wersjach jądra, w których pojawiły się różne wywołania systemowe. .P Stare wersje standardów należy odnotować tutaj, zamiast w rozdziale STANDARDY, przykładami są standardy implementacji SVr4 i 4.xBSD albo SUS, SUSv2 i XPG. .TP \fBUWAGI\fP Różnorodne uwagi. .IP W sekcjach 2. i 3. stron podręcznika ekranowego może być użyteczne podzielenie tego rozdziału na podrozdziały (\fBSS\fP) nazywane \fIUwagi linuksowe\fP i \fIUwagi dotyczące biblioteki glibc\fP. .IP W sekcji 2 proszę użyć nagłówka \fIRóżnice biblioteki C/jądra\fP aby opisać uwagi dotyczące różnic (jeśli takie występują) między funkcją opakowującą biblioteki C dla wywołania systemowego i surowym interfejsem wywołania systemowego zapewnianym przez jądro. .TP \fBZASTRZEŻENIA\fP Ostrzeżenia o częstym sposobie błędnego stosowania API przez użytkowników, niebędące błędem API ani błędem projektowym. .TP \fBUSTERKI\fP Opis ograniczeń, znanych usterek lub niedogodności oraz innych problematycznych aktywności. .TP \fBPRZYKŁADY\fP Jeden lub więcej przykładów opisujących, jak funkcja, plik lub polecenie są używane. .IP Szczegóły dotyczące pisania przykładowych programów opisano w sekcji \fIPrzykładowe programy\fP poniżej. .TP \fBAUTORZY\fP Lista autorów dokumentacji lub programu. .IP \fBUżywanie sekcji AUTORZY nie jest zalecane\fP. Ogólnie lepiej jest nie zaśmiecać każdej strony (z upływem czasu coraz większą) listą autorów. Podczas pisania lub znaczącego zmieniania strony podręcznika, należy umieścić informacje o prawach autorskich jako komentarz w stronie źródłowej. Autorzy sterowników urządzeń, którzy chcieliby podać adres, pod którym należy zgłaszać błędy, powinny umieścić go w rozdziale USTERKI. .TP \fBZGŁASZANIE BŁĘDÓW\fP Projekt \fIman\-pages\fP nie używa rozdziału ZGŁASZANIE BŁĘDÓW w stronach podręcznika systemowego. Informacje na ten temat są dostarczane w sekcji KOLOFON generowanej skryptem. Wiele projektów dodaje jednak rozdział ZGŁASZANIE BŁĘDÓW. Zaleca się umieszczenie go blisko końca strony. .TP \fBPRAWA AUTORSKIE\fP Projekt \fIman\-pages\fP nie używa rozdziału PRAW AUTORSKICH w stronach podręcznika, informacje na ten temat znajdują się bowiem w źródle strony. W stronach, w których ten rozdział jest obecny, zaleca się umieszczenie go blisko końca strony, tuż nad ZOBACZ TAKŻE. .TP \fBZOBACZ TAKŻE\fP Rozdzielona przecinkami lista powiązanych stron podręcznika, po której mogą występować inne powiązane strony lub dokumenty. .IP Lista powinna być posortowana po numerze sekcji, a następnie alfabetycznie po nazwie. Nie należy umieszczać kropki na końcu listy. .IP Gdy w ZOBACZ TAKŻE znajduje się wiele długich nazw podręczników systemowych to, w celu poprawienia przejrzystości tekstu, można użyć dyrektyw \fI.ad l\fP (nie wyrównuj do prawej strony) i \fI.nh\fP (nie dziel). Aby zapobiec dzieleniu pojedynczych nazw podręczników należy je poprzedzić łańcuchem "\[rs]%". .IP Biorąc pod uwagę rozproszoną i autonomiczną naturę projektów WiOO i jej dokumentacji, często jest konieczne i w wielu przypadkach pożądane, aby sekcja ZOBACZ TEŻ zawierała odniesienia do podręczników systemowych udostępnianych przez inne projekty. .SH "KONWENCJE REDAKCYJNE I DOTYCZĄCE FORMATOWANIA" Poniższe podrozdziały opisują wybór szczegółowych rozwiązań dotyczących preferowanego sposobu formatowania oraz redagowania różnych rozdziałów w projekcie \fIman\-pages\fP. .SS SKŁADNIA Należy umieścić prototyp(y) funkcji w \fI.nf\fP/\fI.fi\fP, aby uniknąć wypełniania. .P Gdy w składni wskazany jest więcej niż jeden prototyp funkcji, prototypy \fInie\fP powinny być zwykle rozdzielone pustym wierszem. Można je jednak zastosować (używając \fI.PP\fP) w następujących przypadkach: .IP \[bu] 3 do rozdzielenia długiej listy prototypów funkcji w powiązane grupy (zob. np. \fBlist\fP(3)); .IP \[bu] w innych przypadkach poprawiających czytelność. .P W SKŁADNI, długi prototyp funkcji może wymagać kontynuacji w nowym wierszu. Wiersz ten należy wciąć zgodnie z następującymi zasadami: .IP (1) 5 Jeśli istnieje pojedynczy prototyp wymagający kontynuacji, należy wyrównać wiersz kontynuacji tak, aby zaczynał się tuż pod początkiem listy argumentów z wiersza powyżej, biorąc pod uwagę przypadek renderowania na urządzeniu ze stałą szerokością fontu (np. na xterm) (wyjątek: wcięcie można dostosować, aby uniknąć bardzo długiego wiersza kontynuacji lub aby zapobiec kolejnemu wierszowi kontynuacji, gdy prototyp funkcji jest bardzo długi). Przykład: .IP .in +4n .nf \fBint tcsetattr(int \fP\fIfd\fP\fB, int \fP\fIoptional_actions\fP\fB,\fP \fB const struct termios *\fP\fItermios_p\fP\fB);\fP .fi .in .IP (2) Jednak gdy wiele funkcji w SKŁADNI wymaga wierszy kontynuacji i nazwy funkcji mogą mieć różną długość, należy wyrównać wszystkie wiersze kontynuacji, aby zaczynały się w tej samej kolumnie. Daje to lepsze renderowanie w wyjściu PDF (ponieważ SKŁADNIA używa fontu o zmiennej szerokości, w którym spacje są renderowane jako znaki węższe niż większość pozostałych). Przykład: .IP .in +4n .nf \fBint getopt(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP \fB const char *\fP\fIoptstring\fP\fB);\fP \fBint getopt_long(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP \fB const char *\fP\fIoptstring\fP\fB,\fP \fB const struct option *\fP\fIlongopts\fP\fB, int *\fP\fIlongindex\fP\fB);\fP .fi .in .SS "WARTOŚĆ ZWRACANA" .\" Before man-pages 5.11, many different wordings were used, which .\" was confusing, and potentially made scripted edits more difficult. Preferowanym sposobem zapisu ustawienia \fIerrno\fP jest "ustawiane jest \fIerrno\fP wskazując błąd" lub podobne. Jest to spójne z redakcją użytą w POSIX.1 oraz FreeBSD. .SS ATRYBUTY .\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf Proszę zauważyć, co następuje: .IP \[bu] 3 Proszę opakowywać tabelę w tym rozdziale w \fI.ad\ l\fP/\fI.ad\fP, aby uniknąć wypełniania tekstu oraz w \fI.nh\fP/\fI.hy\fP aby wyłączyć dzielenie słów. .IP \[bu] Proszę upewnić się, że tabela zajmuje całą szerokość strony, korzystając z opisu \fIlbx\fP do jednej z kolumn (zwykle pierwszej, choć w niektórych przypadkach dobrym wyborem jest ostatnia, jeśli zawiera dużo tekstu). .IP \[bu] Można swobodnie stosować makro \fIT{\fP/\fIT}\fP pozwalając na przełamanie komórek tabeli na wiele wierszy (pamiętając, że strony mogą być czasem renderowane na szerokość mniejszą niż 80 kolumn). .P Aby zobaczyć zastosowania powyższych uwag, należy sprawdzić źródła różnych stron podręcznika. .SH STYLISTYKA Poniższe podrozdziały opisują preferowany styl w projekcie \fIman\-pages\fP. Szczegóły nie są opisane, dobrym źródłem jest zwykle Chicago Manual of Style, proszę również przeszukać pliki obecne w drzewie źródeł projektu. .SS "Używanie języka neutralnego płciowo" .\" Tam gdzie się tylko da, należy używać języka neutralnego płciowo. Do tego celu można posłużyć się słowami "they" ("them", "themself", "their"). .SS "Konwencje formatowania do stron podręcznika opisujących polecenia" W przypadku stron podręcznika opisujących polecenia (zwykle w sekcji 1 i 8), argumenty zawsze są podawane kursywą, \fInawet w rozdziale SKŁADNIA\fP. .P .\" Nazwa polecenia i jego opcji powinny być zawsze formatowe w pogrubieniu. .SS "Konwencje formatowania do stron podręcznika opisujących funkcje" W przypadku stron podręcznika opisujących funkcje (zwykle w sekcji 2 i 3), argumenty zawsze są podawane kursywą, \fInawet w rozdziale SKŁADNIA\fP, w którym reszta funkcji jest podana w pogrubieniu: .P \fB int myfunction(int \fP\fIargc\fP\fB, char **\fP\fIargv\fP\fB);\fP .P Nazwy zmiennych podobnie jak nazwy argumentów powinny być pisane kursywą. .P Każde odwołanie do programu, funkcji itp. będących tematem bieżącej strony podręcznika, powinno być zapisane czcionką pogrubioną, po której powinna występować para nawiasów zapisanych czcionką roman (zwykłą). Na przykład w stronie podręcznika \fBfcntl\fP(2) odwołania do tematu tej strony będą zapisane jako \fBfcntl\fP(). Preferowanym sposobem zapisania tego w pliku źródłowym strony jest: .P .EX .BR fcntl () .EE .P .\" (Używanie tego formatu zamiast "\[rs]fB...\[rs]fP()" upraszcza pisanie narzędzi przetwarzających pliki źródłowe stron podręcznika ekranowego). .SS "Używanie semantycznych przełamań wierszy" .\" W źródłach strony podręcznika nowe zdania powinny rozpoczynać się od nowego wiersza, długie zdania należy przełamać zgodnie z interpunkcją (na przecinkach, dwukropkach itp.), a długie zdania podrzędne należy podzielić na wyrażenia. Ta konwencja zwana czasem "semantycznym przełamaniem wiersza" ułatwia zwizualizowanie łatek, które często działają na poziomie poszczególnych zdań, zdań podrzędnych lub wyrażeń. .SS Listy Występują różne rodzaje list: .TP Oznaczone zdania Używane do listy znaczników i ich opisów. Gdy znaczniki są stałymi (makrami lub liczbami) są pogrubione. Proszę korzystać z makra \fB.TP\fP (ang. \fBT\fPagged \fBP\fParagraph). .IP Niniejszy podrozdział "Oznaczone zdania" jest dobrym przykładem tego typu listy. .TP Listy numerowane Elementy są poprzedzone liczbą w nawiasie (1), (2). Oznaczają listę kroków posiadających określoną kolejność. .IP Jeśli występują podkroki, są numerowane jako (4.2). .TP Listy pozycyjne Elementy są poprzedzone liczbą (indeksem) w nawiasach kwadratowych [4], [5]. Oznaczają pola w zestawie. Pierwszym indeksem będzie: .RS .TP \fB0\fP Jeśli reprezentuje pole w strukturze danych C, aby zachować spójność z tablicami. .PD 0 .TP \fB1\fP Gdy reprezentuje pole pliku, aby zachować spójność z narzędziami takimi jak \fBcut\fP(1). .PD .RE .TP Listy alternatywne Elementy są poprzedzone literami w nawiasie (a), (b). Reprezentują zestaw (zwykle) rozłącznych alternatyw. .TP Listy punktowane Elementy są poprzedzone symbolem punktora (\fB\[rs][bu]\fP \- ang. \fBbu\fPllet). Zwykle oznaczane jest w ten sposób wszystko, co nie pasuje do innych typów list. .TP Uwagi numerowane Nie są to tak naprawdę listy, ale składnia jest identyczna do "list pozycyjnych". .P .\" Pomiędzy symbolem listy a jej elementami powinny być dokładnie 2 spacje. Nie dotyczy to "oznaczonych zdań", korzystających z domyślnych reguł wcięć. .SS "Konwencje formatowania (ogólne)" Akapity należy rozdzielać odpowiednimi markerami (zwykle \fI.P\fP albo \&\fI.IP\fP). \fINie\fP należy rozdzielać akapitów pustymi wierszami, gdyż powoduje to nieprawidłowe renderowanie w niektórych formatach wyjściowych (takich jak PostScript i PDF). .P Nazwy plików (niezależnie od tego, czy są pełnymi ścieżkami czy odniesieniami do plików nagłówkowych) są zawsze pisane kursywą (np. \fI\fP), z wyjątkiem nazw występujących w rozdziale SKŁADNIA (SYNOPSIS), w którym pliki dołączane są wyróżniane pogrubieniem (np. \fB#include \fP). Odwołania do standardowych plików nagłówkowych dołączanych powinny zawierać nazwę pliku nagłówkowego w nawiasach trójkątnych, tak jak to jest przyjęte w języku C (np. \fI\fP). .P Makra specjalne, które są zwykle pisane dużymi literami, są pogrubiane (np. \fBMAXINT\fP). Wyjątek: nie pogrubiamy słowa NULL. .P Podczas wyliczania listy kodów błędów, kody są pogrubiane (taka lista zwykle używa makra \fB\&.TP).\fP .P Pełne polecenia, jeśli są długie, powinny być zapisywane w nowych wierszach odpowiednio wciętych, z pustym wierszem przed i po poleceniu, na przykład: .P .in +4n .EX man 7 man\-pages .EE .in .P Jeśli polecenie jest krótkie, to może być zawarte bezpośrednio w tekście zdania i napisane kursywą, na przykład \fIman 7 man\-pages\fP. W tym wypadku, można rozważyć użycie w odpowiednich miejscach polecenia spacji nierozdzielających (\fB\[rs]\[ti]\fP). Opcje polecenia powinny być zapisywane kursywą (np. \fI\-l\fP). .P Wyrażenia, jeśli nie są zapisywane w osobnych, wciętych liniach, powinny być podawane kursywą. Ponownie, jeśli wyrażenie jest włączone do zwykłego tekstu, to właściwe może być używanie spacji nierozdzielających w tym wyrażeniu. .P Przy pokazywaniu przykładowej sesji powłoki, wejście użytkownika należy pogrubić, na przykład .P .in +4n .EX $ \fBdate\fP Thu Jul 7 13:01:27 CEST 2016 .EE .in .P Wszelkie odwołania do innych stron podręcznika powinny być pisane przy użyciu pogrubionej czcionki dla nazwy strony, po której \- bez rozdzielania spacjami \- \fIzawsze\fP powinien następować numer sekcji pisany czcionką zwykłą (niepogrubioną), np. \fBintro\fP(2). Preferowany sposób zapisania tego w kodzie źródłowym strony jest następujący: .P .EX .BR intro (2) .EE .P (Dodawanie numerów sekcji w odwołaniach pozwala narzędziom takim jak \fBman2html\fP(1) na utworzenie stron zawierających poprawne odnośniki hipertekstowe). .P Znaki kontrolne powinny być zapisywane czcionką pogrubioną, bez cytatów np. \fB\[ha]X\fP. .SS Pisownia Od wersji 2.59 pakiet \fIman\-pages\fP używa pisowni amerykańskiej (wcześniej była to losowa mieszanina pisowni amerykańskiej i brytyjskiej). Prosimy przestrzegać tej konwencji dotyczącej pisowni we wszystkich nowo pisanych stronach podręcznika ekranowego i podczas przesyłania nam łat do istniejących stron. .P Oprócz ogólnie znanych różnic jest też kilka subtelniejszych zmian których trzeba pilnować. .IP \[bu] 3 Amerykański angielski częściej używa form "backward", "upward", "toward" itd. a angielski zwykle "backwards", upwards", "towards" itd. .IP \[bu] Są sprzeczne opinie na temat "acknowledgement" i "acknowledgment". To drugie dominuje, ale nie jest uniwersalnie stosowane w amerykańskim agielskim. Pierwsze jest stosowane przez POSIX oraz w licencji BSD. W projekcie Linux man\-pages używa się "acknowledgement". .SS "Wersje BSD" Klasyczny schemat zapisu wersji BSD to \fIx.yBSD\fP, gdzie \fIx.y\fP to wersja (np. 4.2BSD). Proszę unikać form takich jak \fIBSD 4.3\fP. .SS "Wielkie litery" W podsekcjach ("SS") wielką literą należy pisać tylko pierwsze słowo w tytule, z wyjątkiem sytuacji gdy innego zapisu wymagają zasady językowe lub nazwy własne. Na przykład: .P .in +4n .EX \&.SS Unikod w Linuksie .EE .in .\" .SS "Wcięcia definicji struktur, logów sesji powłoki itp." Definicje struktur, logi z sesji powłoki itp dołączane do tekstu powinny zawierać wcięcia o długości 4 spacji (tj. powinny być umieszczone w bloku otoczonym przez \fI.in\ +4n\fP i \fI.in\fP) i należy je formatować za pomocą makr \&\fI.EX\fP i \fI.EE\fP oraz otoczyć odpowiednimi znacznikami akapitów (\fI.P\fP albo \&\fI.IP\fP). Przykład: .P .in +4n .EX \&.P \&.in +4n \&.EX int main(int argc, char *argv[]) { return 0; } \&.EE \&.in \&.P .EE .in .SS "Preferowane terminy" Poniższa tabela pokazuje część preferowanych terminów w stronach podręcznika, głównie w celu zapewnienia spójności między poszczególnymi podręcznikami. .ad l .TS l l l --- l l ll. Termin Niezalecany Uwagi bit mask bitmask built\-in builtin Epoch epoch T{ Do epoki Uniksa (00:00:00, 1 Jan 1970 UTC) T} filename file name filesystem file system hostname host name inode i\-node lowercase lower case, lower\-case nonzero non\-zero pathname path name pseudoterminal pseudo\-terminal privileged port T{ reserved port, system port T} real\-time T{ realtime, real time T} run time runtime saved set\-group\-ID T{ saved group ID, saved set\-GID T} saved set\-user\-ID T{ saved user ID, saved set\-UID T} set\-group\-ID set\-GID, setgid set\-user\-ID set\-UID, setuid superuser T{ super user, super\-user T} superblock T{ super block, super\-block T} symbolic link symlink timestamp time stamp timezone time zone uppercase upper case, upper\-case usable useable user space userspace username user name x86\-64 x86_64 T{ Chyba że odnosi się do wyniku "uname\ \-m" itp. T} zeros zeroes .TE .P Zob. też \fIZapis z dywizem przydawek złożonych\fP poniżej. .SS "Terminy niezalecane" Poniższa tabela pokazuje część niezalecanych terminów w stronach podręcznika, razem z proponowanymi alternatywami, głównie w celu zapewnienia spójności między poszczególnymi podręcznikami. .ad l .TS l l l --- l l l. Niezalecane Zalecane Uwagi 32bit 32\-bit T{ podobnie 8\-bit, 16\-bit, etc. T} current process calling process T{ Częsty błąd programistów jądra piszących strony podręcznika ekranowego T} manpage T{ man page, manual page T} minus infinity negative infinity non\-root unprivileged user non\-superuser unprivileged user nonprivileged unprivileged OS operating system plus infinity positive infinity pty pseudoterminal tty terminal Unices UNIX systems Unixes UNIX systems .TE .ad .\" .SS "Znaki towarowe" Proszę używać poprawnego zapisu znaków towarowych. Poniższa lista zawiera poprawne zapisy różnych znaków towarowych, które są niekiedy zapisywane niepoprawnie: .IP .TS l. DG/UX HP\-UX UNIX UnixWare .TE .SS "NULL, NUL, wskaźnik null i bajt null" A \fIwskaźnik null\fP jest wskaźnikiem wskazującym na nic i pojawia się zwykle jako stała \fINULL\fP. \fINUL\fP jest \fIbajtem null\fP, bajtem o wartości 0, reprezentowanym w C jako stałą znakowa \fI\[aq]\[rs]0\[aq]\fP. .P Preferowanym terminem na wskaźnik jest "wskaźnik null" lub "NULL"; proszę unikać terminu "wskaźnik NULL". .P Preferowanym terminem w kontekście bajtów jest "bajt null". Proszę unikać terminu "NUL", ponieważ jest on łatwy do pomylenia z "NULL". Proszę starać się nie używać również "bajt zerowy" i "znak null". Bajt który przerywa łańcuch C powinien być opisywany jako "przerywający bajt null"; łańcuchy te można nazwać "null\-terminated", lecz proszę unikać terminu "NUL\-terminated". .SS Odnośniki Odnośniki tworzy się parą makr \fI.UR\fP/\fI.UE\fP (zob. \fBgroff_man\fP(7)). W ten sposób tworzy się poprawne odnośniki których można użyć w przeglądarce internetowej przy renderowaniu strony przez np.: .P .in +4n .EX BROWSER=firefox man \-H nazwa\-strony .EE .in .SS "Używanie e.g., i.e., etc., a.k.a. i podobnych" Ogólnie rzecz biorąc powinno się unikać skrótów takich jak "e.g.", "i.e.", "etc.", "cf.", "a.k.a." na rzecz pełnego zapisu ("for example", "that is", "and so on", "compare to", "also known as"). .P Jedynym miejscem gdzie skróty są dopuszczone to \fIkrótkie\fP wtrącenia (np. takie jak to). .P Zawsze należy zapisywać te skróty z kropką. Dodatkowo "e.g." i "i.e." powinny zawsze kończyć się przecinkiem. .SS "Pauza \(dqem\(dq" Sposobem zapisu pauzy "em" \[em] znaku który pojawia się na obu końcach tego wtrącenia \[em] w *roff jest macro "\[rs][em]". Na terminalu ASCII pauza "em" jest zwykle renderowana jako dwa dywizy, lecz w innych sytuacjach pokazuje się jako długa pauza. Pauza "em" w języku angielskim powinna być zapisywana \fIbez\fP otaczających ją spacji. .SS "Zapis z dywizem przydawek złożonych" Terminy złożone powinny być zapisywane z dywizem, gdy są używane w formie przydawki. Przykłady: .IP .TS l. 32\-bit value command\-line argument floating\-point number run\-time check user\-space function wide\-character string .TE .SS "Zapis z dywizem przedrostków multi, non, pre, re, sub itd." Ogólną tendencją we współczesnym angielskim jest nie stosowanie zapisu po przedrostkach takich jak "multi", "non", "pre", "re", "sub" itd. Strony podręcznika powinny z reguły stosować się do tej zasady tam, gdzie przedrostki są używane w naturalnych dla angielskiego konstrukcjach z prostymi przedrostkami. Poniższa lista daje pogląd na preferowane formy: .IP .TS l. interprocess multithreaded multiprocess nonblocking nondefault nonempty noninteractive nonnegative nonportable nonzero preallocated precreate prerecorded reestablished reinitialize rearm reread subcomponent subdirectory subsystem .TE .P Dywizy powinny być zachowane w przedrostkach używanych w niestandardowych dla angielskiego słowach, w znakach towarowych, rzeczownikach tego wymagających, akronimach lub zwrotach złożonych. Przykłady: .IP .TS l. non\-ASCII non\-English non\-NULL non\-real\-time .TE .P .\" Proszę zauważyć, że "re\-create" i "recreate" to dwa odrębne czasowniki, przy czym prawdopodobnie chcemy wykorzystać ten pierwszy. .SS "Tworzenie optymalnych glifów" Gdy wymagany jest prawdziwy znak minus (np. w przypadku liczb takich jak \-1, w przypadku strony podręcznika zawierającej odniesienia do innych stron takie jak \fButf\-8\fP(7) lub przy zapisywaniu opcji z początkowym dywizem, takich jak \fIls\ \-l\fP), proszę używać następującej postaci w źródłach stron podręcznika: .P .in +4n .EX \[rs]\- .EE .in .P Zalecenie to dotyczy też przykładów kodu. .P .\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/ Użycie prawdziwego znaku minusa ma na celu: .IP \[bu] 3 Lepsze renderowanie w sytuacjach innych niż terminal ASCII, w szczególności w PDF i na terminalach Unicode/UTF\-8. .IP \[bu] Generowanie glifów, które po skopiowaniu z wyrenderowanych stron utworzą prawdziwy znak minusa przy wklejeniu na terminal. .P Aby utworzyć znak pojedynczego prostego cudzysłowu który wyświetla się poprawnie w stronach ASCII, UTF\-8 i PDF proszę używać "\[rs][aq]" ("cytowania apostrofu") np. .P .in +4n .EX \[rs][aq]C\[rs][aq] .EE .in .P gdzie \fIC\fP jest cytowanym znakiem. Zalecenie do tyczy się również stałych znakowych używanych w przykładach kodu. .P Tam, gdzie wymagany jest prawidłowy znak karety (\[ha]) renderujący się poprawnie w terminalu i w PDF\-ie, proszę użyć "\e[ha]". Jest to szczególnie konieczne w przykładach kodu, aby uzyskać prawidłowe renderowanie karety w formacie PDF. .P .\" Surowy znak "\[ti]" daje kiepskie renderowanie w PDF\-ie. Zamiast tego należy użyć "\e[ti]". Jest to szczególnie konieczne w przykładach kodu, aby uzyskać prawidłowe renderowanie w formacie PDF. .SS "Przykładowe programy i sesje powłoki" Strony podręcznika mogą zawierać przykładowe programy pokazujące, jak używać wywołania systemowego lub funkcji bibliotecznej. Jednakże proszę zauważyć, że: .IP \[bu] 3 Przykładowe programy powinny być pisane w języku C. .IP \[bu] Zamieszczenie programu przykładowego jest konieczne i użyteczne tylko wtedy, gdy program ten pokazuje coś, czego nie można w prosty sposób zawrzeć w tekstowym opisie demonstrowanego interfejsu. Program przykładowy nie robiący nic poza wywoływaniem funkcji interfejsu zazwyczaj nie ma większego sensu. .IP \[bu] Przykładowe programy powinny być krótkie (dobry przykład często można zademonstrować w mniej niż 100 wierszy kodu), choć w niektórych przypadkach do prawidłowego zilustrowania użycia API konieczne są dłuższe programy. .IP \[bu] Zalecany jest kod ekspresywny. .IP \[bu] Tam gdzie to przydatne, należy stosować komentarze. Całe zdania w komentarzach zamieszczanych w oddzielnych wierszach należy zakończyć kropką. Kropki należy zwykle unikać w komentarzach wtrąconych (stosowanych w tym samym wierszu co kod); są one zresztą zwykle krótkimi równoważnikami, a nie pełnymi zdaniami. .IP \[bu] Przykładowe programy nie powinny sprawdzać błędów wywołań systemowych czy funkcji bibliotecznych. .IP \[bu] Przykładowe programy powinny być kompletne i powinny się kompilować za pomocą \fIcc\ \-Wall\fP bez wypisywania żadnych ostrzeżeń. .IP \[bu] Kiedy tylko to możliwe i właściwe, programy przykładowe powinny pozwalać na eksperymenty, różnicując swoje zachowanie zależnie od wejścia (idealnie pochodzącego z argumentów linii poleceń lub alternatywnie z wejścia czytanego przez program). .IP \[bu] Przykładowe programy powinny być sformatowane w stylu "Kernighan & Ritchie" z wcięciami o rozmiarze czterech spacji (nie należy używać znaków tabulacji w kodzie źródłowym!). Można użyć poniższego polecenia do sformatowania swojego kodu źródłowego do stylu bliskiego pożądanemu: .IP .in +4n .EX indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c .EE .in .IP \[bu] W celu zachowania spójności, wszystkie przykładowe programy powinny się kończyć jednym z poniższych: .IP .in +4n .EX exit(EXIT_SUCCESS); exit(EXIT_FAILURE); .EE .in .IP Proszę unikać poniższych form w celu zakończenia programu: .IP .in +4n .EX exit(0); exit(1); return n; .EE .in .IP \[bu] Jeśli przed kodem źródłowym znajduje się wyczerpujące wyjaśnienie, kod źródłowy powinien być oznaczony podrozdziałem \fIKod źródłowy programu\fP, jak w przykładzie: .IP .in +4n .EX \&.SS Kod źródłowy programu .EE .in .IP Zawsze należy go zastosować, jeśli wyjaśnienie zawiera log z sesji powłoki. .P Włączając sesję powłoki pokazującą użycie programu lub innej właściwości systemu: .IP \[bu] 3 Należy umieścić log z sesji powyżej kodu źródłowego. .IP \[bu] Należy wciąć log z sesji czterema spacjami. .IP \[bu] Należy używać czcionki pogrubionej dla tekstu wprowadzanego przez użytkownika, tak aby odróżnić go od tekstu produkowanego przez system. .P Przykłady wyglądu przykładowych programów można znaleźć w \fBwait\fP(2) i \fBpipe\fP(2). .SH PRZYKŁADY Wzorcowymi przykładami tego, jak powinny wyglądać strony podręczników z pakietu \fIman\-pages\fP, są strony \fBpipe\fP(2) i \fBfcntl\fP(2). .SH "ZOBACZ TAKŻE" \fBman\fP(1), \fBman2html\fP(1), \fBattributes\fP(7), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7), \fBmdoc\fP(7) .PP .SH TŁUMACZENIE Tłumaczenie niniejszej strony podręcznika: Przemek Borys , Robert Luberda i Michał Kułach . .PP Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License w wersji 3 .UE lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI. .PP Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej .MT manpages-pl-list@lists.sourceforge.net .ME .