man-pages(7) Miscellaneous Information Manual man-pages(7) NAZWA man-pages - konwencje pisania linuksowych stron podrecznika ekranowego SKLADNIA man [sekcja] tytul OPIS Strona opisuje konwencje, do ktorych powinno sie stosowac podczas pisania stron podrecznika ekranowego dla projektu Linux man-pages, ktory dokumentuje interfejs programistyczny w przestrzeni uzytkownika udostepniany przez jadro Linux i biblioteke GNU C. Z tego powodu projekt dotyczy glownie sekcji 2 podrecznika systemowego, wielu podrecznikow z sekcji 3, 4 i 7 oraz niektorych podrecznikow z sekcji 1, 5 i 8. Konwencje opisane tutaj moga sie takze przydac autorom podrecznikow z innych projektow. Sekcje stron podrecznika ekranowego Sekcje podrecznika man sa tradycyjnie definiowane nastepujaco: 1 Komendy uzytkownika (programy) Komendy moga byc wykonywane przez uzytkownika z powloki. 2 Wywolania systemowe Funkcje opakowuja operacje wykonywane przez jadro. 3 Wywolania biblioteczne Wszystkie funkcje biblioteczne z wylaczeniem opakowan wywolan systemowych (wiekszosc z funkcji libc). 4 Pliki specjalne (urzadzenia) Pliki w /dev pozwalajace na dostep do urzadzenia poprzez jadro. 5 Formaty plikow i pliki konfiguracyjne Opisuja rozne czytelne dla czlowieka formaty plikow i pliki konfiguracyjne. 6 Gry Gry i zabawne programiki dostepne w systemie. 7 Przeglad, konwencje i roznorodne Przeglad i opsi roznych tematow, konwencje, protokoly, standardy kodowania znakow, standardowego wygladu systemu plikow i inne. 8 Polecenia do zarzadzania systemem Komendy takie, jak mount(8), ktore wywolywac moze tylko root . Pakiety makr Nowe strony podrecznika powinny byc pisane z uzyciem pakietu makr groff an.tmac opisanego w man(7). Wybor ten podyktowany jest zachowaniem spojnosci: przytlaczajaca wiekszosc istniejacych podrecznikow linuksowych uzywa tego pakietu makr. Konwencje wygladu pliku zrodlowego Prosimy ograniczac dlugosc linii kodu zrodlowego do maksymalnie 75 znakow, jesli jest to mozliwe. Pomaga to unikac zawijania wierszy w niektorych programach pocztowych podczas przesylania lat do podrecznikow ekranowych. Linia tytulowa Pierwsza komenda strony podrecznika powinno byc polecenie TH: .TH tytul sekcja data zrodlo rozdzial-podrecznika Argumenty komendy sa nastepujace: tytul Tytul strony podrecznika, pisany w calosci duzymi literami (np. MAN-PAGES). sekcja Numer sekcji, w ktorej strona powinna sie znalezc (np. 7). data Data ostatniej nietrywialnej zmiany dokonanej w podreczniku. W projekcie man-pages konieczna aktualizacja tych dat jest wykonywana automatycznie przez skrypty, dlatego nie ma koniecznosci zawierania recznej aktualizacji w latce). Daty powinny byc zapisywane w postaci RRRR-MM-DD. zrodlo Nazwa i wersja projektu udostepniajacego strone podrecznika (niekoniecznie bedzie to pakiet, ktory udostepnia sama funkcjonalnosc). rozdzial-podrecznika Zwykle pole to powinno pozostac puste, jako ze wartosc domyslna jest wystarczajaca. Rozdzialy stron podrecznika Ponizsza lista pokazuje rozdzialy konwencjonalne lub sugerowane. Wiekszosc stron podrecznika powinna zawierac przynajmniej wyroznione rozdzialy. Prosimy pisac nowe strony podrecznika w taki sposob, by rozdzialy pojawialy sie w takiej kolejnosci, w jakiej sa podane na liscie. NAZWA BIBLIOTEKA [Zwykle tylko w sekcjach 2 i 3] SKLADNIA KONFIGURACJA [Zwykle tylko w sekcji 4] OPIS OPCJE [Zwykle tylko w sekcjach 1 i 8] STATUS ZAKONCZENIA [Zwykle tylko w sekcjach 1 i 8] WARTOSC ZWRACANA [Zwykle tylko w sekcjach 2 i 3] BLEDY [Zwykle tylko w sekcjach 2 i 3] SRODOWISKO PLIKI ATRYBUTY [Zwykle tylko w sekcjach 2 i 3] WERSJE [Zwykle tylko w sekcjach 2 i 3] STANDARDY HISTORIA UWAGI ZASTRZEZENIA USTERKI PRZYKLADY AUTORZY [Odradzane] ZGLASZANIE BLEDOW [Nieuzywane w projekcie man-pages] PRAWA AUTORSKIE [Nieuzywane w projekcie man-pages] ZOBACZ TAKZE W celu zachowania spojnosci i dla lepszego zrozumienia przekazywanych informacji prosimy uzywac zwyczajowych naglowkow wszedzie, gdzie maja zastosowanie. Jesli jest to konieczne, mozna uzyc wlasnych naglowkow, zwlaszcza gdy sprawia, ze tekst latwiej bedzie zrozumiec (moze byc to szczegolnie uzyteczne w sekcjach 4. i 5.). Jednakze zanim uzyje sie wlasnych naglowkow, prosimy rozwazyc uzycie naglowkow zwyczajowych i umieszczenie podrozdzialow (.SS) w rozdzialach opisanych tymi naglowkami. Ponizej opisujemy zawartosc kazdej z powyzszych sekcji. NAZWA Nazwa strony podrecznika systemowego. Podrecznik man(7) zawiera wazne detale na temat wierszy ktore powinny znalezc sie za poleceniem .SH NAZWA. Wszystkie slowa w tym wierszu (lacznie ze slowami wystepujacymi zaraz za "\-") powinny byc pisane malymi literami z wyjatkiem konwencji terminologii lub wymagan jezykowych, ktore mowia inaczej. BIBLIOTEKA Biblioteka udostepniajaca symbol. Pokazywana jest tu ogolna nazwa biblioteki, nastepnie, w nawiasie, nazwa pliku biblioteki oraz, jesli to potrzebne, flaga konsolidatora wymaganego do podlinkowania do niego programu (libfoo[, -lfoo]). SKLADNIA Zwiezle podsumowanie interfejsu polecenia lub funkcji. W przypadku polecen pokazuje skladnie polecenia i jego argumenty (lacznie z opcjami); pogrubienie jest uzywane dla tekstu wpisywanego doslownie, a kursywa oznacza zastepowalne argumenty. Nawiasy kwadratowe ([]) otaczaja argumenty opcjonalne, linie pionowe (|) rozdzielaja mozliwe wybory, a wielokropek (...) oznacza mozliwosc powtarzania. W wypadku funkcji pokazuje wszystkie wymagane deklaracje danych lub dyrektywy #include, po ktorych nastepuje deklaracja funkcji. Jezeli do uzyskania deklaracji funkcji (lub zmiennej) z pliku naglowkowego wymagane jest zdefiniowanie makra testujacego, to informacja o tym powinna zostac umieszczona w rozdziale SKLADNIA (SYNOPSIS), tak jak to opisano w feature_test_macros(7). KONFIGURACJA Szczegoly konfiguracji urzadzenia. Ta sekcja zazwyczaj wystepuje tylko w 4. sekcji stron podrecznika ekranowego. OPIS Opis tego, co robi dany program, funkcja lub format. Objasnia interakcje z plikami i standardowym wejsciem oraz wartosci zwracane na standardowym wyjsciu i standardowym wyjsciu bledow. Pomijane sa szczegoly dotyczace implementacji i rzeczy wewnetrzne programu, chyba ze sa istotne dla zrozumienia interfejsu programu. Opisuje normalne przypadki uzycia; objasnienie opcji powinno sie znalezc w rozdziale OPCJE. Przy opisywaniu nowego zachowania lub nowych flag wywolania systemowego lub funkcji bibliotecznej, prosze pamietac o zanotowaniu wersji jadra lub biblioteki C ktora wprowadzila te zmiane. Zalecana metoda przestawienia tej informacji przy flagach jest postac czesci listy .TP, w nastepujacej formie (tutaj dla nowej flagi wywolania systemowego): XYZ_FLAG (od Linuksa 3.7) Opis flagi... Dolaczenie informacji o wersji jest szczegolnie wazne dla uzytkownikow ktorzy sa zmuszeni korzystac ze starszego jadra lub biblioteki C (co jest powszechne w przypadku np. systemow wbudowanych). OPCJE Opis opcji wiersza polecen akceptowane przez program oraz sposob, w jaki wplywaja na jego zachowanie. Rozdzial powinien sie pojawiac tylko w sekcjach 1. i 8. stron podrecznika ekranowego. KOD WYJSCIA Okresla mozliwe wartosci kodow zakonczenia programu oraz warunki, ktore powoduja zwrocenie tych wartosci. Rozdzial powinien sie pojawiac tylko w sekcjach 1. i 8. stron podrecznika ekranowego. WARTOSC ZWRACANA W sekcjach 2. i 3. stron podrecznika, rozdzial ten okresla liste wartosci, ktore opisywana funkcja biblioteczna zwroci funkcji ja wywolujacej, oraz warunki, w ktorych dana wartosc bedzie zwracana. BLEDY W sekcjach 2. i 3. stron podrecznika jest to lista wartosci, ktore moga byc przypisane zmiennej errno w razie wystapienia bledu, lacznie z informacjami o przyczynach tego bledu. Gdy wiele roznych warunkow wywoluje ten sam blad, preferowanym podejsciem jest utworzenie odrebnych wpisow listy (z powtorzonymi nazwami bledow) dla kazdego z warunkow. W ten sposob jasna bedzie rozdzielnosc warunkow, w ktorych wystapil blad, lista moze byc czytelniejsza oraz mozna podac dodatkowe informacje specyficzne dla kazdego z warunkow (np. wersje jadra, w ktorej po raz pierwszy wystapil dany warunek). Elementy listy powinny byc wymienione w porzadku alfabetycznym. SRODOWISKO Lista wszystkich zmiennych srodowiskowych, wplywajacych na program i opis tego wplywu. PLIKI Lista plikow uzywanych przez program lub funkcje, takich jak pliki konfiguracyjne, pliki uruchomieniowe oraz pliki uzywane w czasie dzialania programu. Nalezy podac pelna sciezke do pliku, w ktorej podczas instalacji powinno sie zmodyfikowac katalogi, tak zeby odpowiadaly preferencjom uzytkownika. Wiele programow domyslnie instaluje sie w /usr/local, tak ze strona podrecznika powinna uzywac /usr/local jako podstawowego katalogu. ATRYBUTY Podsumowanie roznych atrybutow funkcji udokumentowanych na danej stronie podrecznika. Wiecej informacji w podreczniku attributes(7). WERSJE Podsumowanie systemow, na ktorych API zachowuje sie odmiennie lub gdzie wystepuje podobne API. STANDARDY Opisuje standardy lub konwencje zwiazane z opisywana w podreczniku funkcja lub opisywanym poleceniem. Preferowane terminy do uzycia w roznych standardach sa wypisane jako naglowki w standards(7). Ten rozdzial powinien odnotowywac obecne standardy, z ktorymi zgodne jest API. Jesli API nie jest zamieszczone w zadnym standardzie, ale zwyczajowo istnieje w innych systemach, prosimy wymienic te systemy. Jesli wywolanie jest specyficzne dla Linuksa lub GNU, rowniez nalezy o tym poinformowac. Nalezy zamiescic rowniez wzmianke, jesli jest dostepne w BSD. Jesli rozdzial zawiera tylko i wylacznie liste standardow (a tak jest zazwyczaj), lista ta powinna byc zakonczona kropka ("."). HISTORIA Zwiezle podsumowanie wersji jadra Linux lub glibc, w ktorych pojawilo sie wywolanie systemowe lub funkcja biblioteczna, albo w ktorej znacznie zmienilo sie jej dzialania. Z zasady kazda strona podrecznika opisujaca nowy interfejs powinna zawierac rozdzial HISTORIA. Niestety wiele istniejacych stron nie dolacza tych informacji (gdyz nie bylo to wymagane w czasie pisania tych stron). Chetnie przyjmiemy laty poprawiajace ten problem, jednakze z perspektywy programisty informacje o wersji maja najprawdopodobniej znaczenie tylko w przypadku interfejsow jadra dodanych w Linuksie 2.4 lub kolejnych (tj. zmiany w stosunku do Linuksa 2.2) oraz w przypadku funkcji bibliotecznych dolozonych do glibc od wersji 2.1 (tj. zmiany w stosunku do wersji 2.0). Strona podrecznika syscalls(2) takze dostarcza informacji o wersjach jadra, w ktorych pojawily sie rozne wywolania systemowe. Stare wersje standardow nalezy odnotowac tutaj, zamiast w rozdziale STANDARDY, przykladami sa standardy implementacji SVr4 i 4.xBSD albo SUS, SUSv2 i XPG. UWAGI Roznorodne uwagi. W sekcjach 2. i 3. stron podrecznika ekranowego moze byc uzyteczne podzielenie tego rozdzialu na podrozdzialy (SS) nazywane Uwagi linuksowe i Uwagi dotyczace biblioteki glibc. W sekcji 2 prosze uzyc naglowka Roznice biblioteki C/jadra aby opisac uwagi dotyczace roznic (jesli takie wystepuja) miedzy funkcja opakowujaca biblioteki C dla wywolania systemowego i surowym interfejsem wywolania systemowego zapewnianym przez jadro. ZASTRZEZENIA Ostrzezenia o czestym sposobie blednego stosowania API przez uzytkownikow, niebedace bledem API ani bledem projektowym. USTERKI Opis ograniczen, znanych usterek lub niedogodnosci oraz innych problematycznych aktywnosci. PRZYKLADY Jeden lub wiecej przykladow opisujacych, jak funkcja, plik lub polecenie sa uzywane. Szczegoly dotyczace pisania przykladowych programow opisano w sekcji Przykladowe programy ponizej. AUTORZY Lista autorow dokumentacji lub programu. Uzywanie sekcji AUTORZY nie jest zalecane. Ogolnie lepiej jest nie zasmiecac kazdej strony (z uplywem czasu coraz wieksza) lista autorow. Podczas pisania lub znaczacego zmieniania strony podrecznika, nalezy umiescic informacje o prawach autorskich jako komentarz w stronie zrodlowej. Autorzy sterownikow urzadzen, ktorzy chcieliby podac adres, pod ktorym nalezy zglaszac bledy, powinny umiescic go w rozdziale USTERKI. ZGLASZANIE BLEDOW Projekt man-pages nie uzywa rozdzialu ZGLASZANIE BLEDOW w stronach podrecznika systemowego. Informacje na ten temat sa dostarczane w sekcji KOLOFON generowanej skryptem. Wiele projektow dodaje jednak rozdzial ZGLASZANIE BLEDOW. Zaleca sie umieszczenie go blisko konca strony. PRAWA AUTORSKIE Projekt man-pages nie uzywa rozdzialu PRAW AUTORSKICH w stronach podrecznika, informacje na ten temat znajduja sie bowiem w zrodle strony. W stronach, w ktorych ten rozdzial jest obecny, zaleca sie umieszczenie go blisko konca strony, tuz nad ZOBACZ TAKZE. ZOBACZ TAKZE Rozdzielona przecinkami lista powiazanych stron podrecznika, po ktorej moga wystepowac inne powiazane strony lub dokumenty. Lista powinna byc posortowana po numerze sekcji, a nastepnie alfabetycznie po nazwie. Nie nalezy umieszczac kropki na koncu listy. Gdy w ZOBACZ TAKZE znajduje sie wiele dlugich nazw podrecznikow systemowych to, w celu poprawienia przejrzystosci tekstu, mozna uzyc dyrektyw .ad l (nie wyrownuj do prawej strony) i .nh (nie dziel). Aby zapobiec dzieleniu pojedynczych nazw podrecznikow nalezy je poprzedzic lancuchem "\%". Biorac pod uwage rozproszona i autonomiczna nature projektow WiOO i jej dokumentacji, czesto jest konieczne i w wielu przypadkach pozadane, aby sekcja ZOBACZ TEZ zawierala odniesienia do podrecznikow systemowych udostepnianych przez inne projekty. KONWENCJE REDAKCYJNE I DOTYCZACE FORMATOWANIA Ponizsze podrozdzialy opisuja wybor szczegolowych rozwiazan dotyczacych preferowanego sposobu formatowania oraz redagowania roznych rozdzialow w projekcie man-pages. SKLADNIA Nalezy umiescic prototyp(y) funkcji w .nf/.fi, aby uniknac wypelniania. Gdy w skladni wskazany jest wiecej niz jeden prototyp funkcji, prototypy nie powinny byc zwykle rozdzielone pustym wierszem. Mozna je jednak zastosowac (uzywajac .PP) w nastepujacych przypadkach: o do rozdzielenia dlugiej listy prototypow funkcji w powiazane grupy (zob. np. list(3)); o w innych przypadkach poprawiajacych czytelnosc. W SKLADNI, dlugi prototyp funkcji moze wymagac kontynuacji w nowym wierszu. Wiersz ten nalezy wciac zgodnie z nastepujacymi zasadami: (1) Jesli istnieje pojedynczy prototyp wymagajacy kontynuacji, nalezy wyrownac wiersz kontynuacji tak, aby zaczynal sie tuz pod poczatkiem listy argumentow z wiersza powyzej, biorac pod uwage przypadek renderowania na urzadzeniu ze stala szerokoscia fontu (np. na xterm) (wyjatek: wciecie mozna dostosowac, aby uniknac bardzo dlugiego wiersza kontynuacji lub aby zapobiec kolejnemu wierszowi kontynuacji, gdy prototyp funkcji jest bardzo dlugi). Przyklad: int tcsetattr(int fd, int optional_actions, const struct termios *termios_p); (2) Jednak gdy wiele funkcji w SKLADNI wymaga wierszy kontynuacji i nazwy funkcji moga miec rozna dlugosc, nalezy wyrownac wszystkie wiersze kontynuacji, aby zaczynaly sie w tej samej kolumnie. Daje to lepsze renderowanie w wyjsciu PDF (poniewaz SKLADNIA uzywa fontu o zmiennej szerokosci, w ktorym spacje sa renderowane jako znaki wezsze niz wiekszosc pozostalych). Przyklad: int getopt(int argc, char * const argv[], const char *optstring); int getopt_long(int argc, char * const argv[], const char *optstring, const struct option *longopts, int *longindex); WARTOSC ZWRACANA Preferowanym sposobem zapisu ustawienia errno jest "ustawiane jest errno wskazujac blad" lub podobne. Jest to spojne z redakcja uzyta w POSIX.1 oraz FreeBSD. ATRYBUTY Dalsze uwagi: o Prosze opakowywac tabele w tym rozdziale w .ad l/.ad, aby uniknac wypelniania tekstu oraz w .nh/.hy aby wylaczyc dzielenie slow. o Prosze upewnic sie, ze tabela zajmuje cala szerokosc strony, korzystajac z opisu lbx do jednej z kolumn (zwykle pierwszej, choc w niektorych przypadkach dobrym wyborem jest ostatnia, jesli zawiera duzo tekstu). o Mozna swobodnie stosowac makro T{/T} pozwalajac na przelamanie komorek tabeli na wiele wierszy (pamietajac, ze strony moga byc czasem renderowane na szerokosc mniejsza niz 80 kolumn). Aby zobaczyc zastosowania powyzszych uwag, nalezy sprawdzic zrodla roznych stron podrecznika. STYLISTYKA Ponizsze podrozdzialy opisuja preferowany styl w projekcie man-pages. Szczegoly nie sa opisane, dobrym zrodlem jest zwykle Chicago Manual of Style, prosze rowniez przeszukac pliki obecne w drzewie zrodel projektu. Uzywanie jezyka neutralnego plciowo Tam gdzie sie tylko da, nalezy uzywac jezyka neutralnego plciowo. Do tego celu mozna posluzyc sie slowami "they" ("them", "themself", "their"). Konwencje formatowania do stron podrecznika opisujacych polecenia W przypadku stron podrecznika opisujacych polecenia (zwykle w sekcji 1 i 8), argumenty zawsze sa podawane kursywa, nawet w rozdziale SKLADNIA. Nazwa polecenia i jego opcji powinny byc zawsze formatowe w pogrubieniu. Konwencje formatowania do stron podrecznika opisujacych funkcje W przypadku stron podrecznika opisujacych funkcje (zwykle w sekcji 2 i 3), argumenty zawsze sa podawane kursywa, nawet w rozdziale SKLADNIA, w ktorym reszta funkcji jest podana w pogrubieniu: int myfunction(int argc, char **argv); Nazwy zmiennych podobnie jak nazwy argumentow powinny byc pisane kursywa. Kazde odwolanie do programu, funkcji itp. bedacych tematem biezacej strony podrecznika, powinno byc zapisane czcionka pogrubiona, po ktorej powinna wystepowac para nawiasow zapisanych czcionka roman (zwykla). Na przyklad w stronie podrecznika fcntl(2) odwolania do tematu tej strony beda zapisane jako fcntl(). Preferowanym sposobem zapisania tego w pliku zrodlowym strony jest: .BR fcntl () (Uzywanie tego formatu zamiast "\fB...\fP()" upraszcza pisanie narzedzi przetwarzajacych pliki zrodlowe stron podrecznika ekranowego). Uzywanie semantycznych przelaman wierszy W zrodlach strony podrecznika nowe zdania powinny rozpoczynac sie od nowego wiersza, dlugie zdania nalezy przelamac zgodnie z interpunkcja (na przecinkach, dwukropkach itp.), a dlugie zdania podrzedne nalezy podzielic na wyrazenia. Ta konwencja zwana czasem "semantycznym przelamaniem wiersza" ulatwia zwizualizowanie latek, ktore czesto dzialaja na poziomie poszczegolnych zdan, zdan podrzednych lub wyrazen. Listy Wystepuja rozne rodzaje list: Oznaczone zdania Uzywane do listy znacznikow i ich opisow. Gdy znaczniki sa stalymi (makrami lub liczbami) sa pogrubione. Prosze korzystac z makra .TP (ang. Tagged Paragraph). Niniejszy podrozdzial "Oznaczone zdania" jest dobrym przykladem tego typu listy. Listy numerowane Elementy sa poprzedzone liczba w nawiasie (1), (2). Oznaczaja liste krokow posiadajacych okreslona kolejnosc. Jesli wystepuja podkroki, sa numerowane jako (4.2). Listy pozycyjne Elementy sa poprzedzone liczba (indeksem) w nawiasach kwadratowych [4], [5]. Oznaczaja pola w zestawie. Pierwszym indeksem bedzie: 0 Jesli reprezentuje pole w strukturze danych C, aby zachowac spojnosc z tablicami. 1 Gdy reprezentuje pole pliku, aby zachowac spojnosc z narzedziami takimi jak cut(1). Listy alternatywne Elementy sa poprzedzone literami w nawiasie (a), (b). Reprezentuja zestaw (zwykle) rozlacznych alternatyw. Listy punktowane Elementy sa poprzedzone symbolem punktora (\[bu] - ang. bullet). Zwykle oznaczane jest w ten sposob wszystko, co nie pasuje do innych typow list. Uwagi numerowane Nie sa to tak naprawde listy, ale skladnia jest identyczna do "list pozycyjnych". Pomiedzy symbolem listy a jej elementami powinny byc dokladnie 2 spacje. Nie dotyczy to "oznaczonych zdan", korzystajacych z domyslnych regul wciec. Konwencje formatowania (ogolne) Akapity nalezy rozdzielac odpowiednimi markerami (zwykle .P albo .IP). Nie nalezy rozdzielac akapitow pustymi wierszami, gdyz powoduje to nieprawidlowe renderowanie w niektorych formatach wyjsciowych (takich jak PostScript i PDF). Nazwy plikow (niezaleznie od tego, czy sa pelnymi sciezkami czy odniesieniami do plikow naglowkowych) sa zawsze pisane kursywa (np. ), z wyjatkiem nazw wystepujacych w rozdziale SKLADNIA (SYNOPSIS), w ktorym pliki dolaczane sa wyrozniane pogrubieniem (np. #include ). Odwolania do standardowych plikow naglowkowych dolaczanych powinny zawierac nazwe pliku naglowkowego w nawiasach trojkatnych, tak jak to jest przyjete w jezyku C (np. ). Makra specjalne, ktore sa zwykle pisane duzymi literami, sa pogrubiane (np. MAXINT). Wyjatek: nie pogrubiamy slowa NULL. Podczas wyliczania listy kodow bledow, kody sa pogrubiane (taka lista zwykle uzywa makra .TP). Pelne polecenia, jesli sa dlugie, powinny byc zapisywane w nowych wierszach odpowiednio wcietych, z pustym wierszem przed i po poleceniu, na przyklad: man 7 man-pages Jesli polecenie jest krotkie, to moze byc zawarte bezposrednio w tekscie zdania i napisane kursywa, na przyklad man 7 man-pages. W tym wypadku, mozna rozwazyc uzycie w odpowiednich miejscach polecenia spacji nierozdzielajacych (\~). Opcje polecenia powinny byc zapisywane kursywa (np. -l). Wyrazenia, jesli nie sa zapisywane w osobnych, wcietych liniach, powinny byc podawane kursywa. Ponownie, jesli wyrazenie jest wlaczone do zwyklego tekstu, to wlasciwe moze byc uzywanie spacji nierozdzielajacych w tym wyrazeniu. Przy pokazywaniu przykladowej sesji powloki, wejscie uzytkownika nalezy pogrubic, na przyklad $ date Thu Jul 7 13:01:27 CEST 2016 Wszelkie odwolania do innych stron podrecznika powinny byc pisane przy uzyciu pogrubionej czcionki dla nazwy strony, po ktorej - bez rozdzielania spacjami - zawsze powinien nastepowac numer sekcji pisany czcionka zwykla (niepogrubiona), np. intro(2). Preferowany sposob zapisania tego w kodzie zrodlowym strony jest nastepujacy: .BR intro (2) (Dodawanie numerow sekcji w odwolaniach pozwala narzedziom takim jak man2html(1) na utworzenie stron zawierajacych poprawne odnosniki hipertekstowe). Znaki kontrolne powinny byc zapisywane czcionka pogrubiona, bez cytatow np. ^X. Pisownia Od wersji 2.59 pakiet man-pages uzywa pisowni amerykanskiej (wczesniej byla to losowa mieszanina pisowni amerykanskiej i brytyjskiej). Prosimy przestrzegac tej konwencji dotyczacej pisowni we wszystkich nowo pisanych stronach podrecznika ekranowego i podczas przesylania nam lat do istniejacych stron. Oprocz ogolnie znanych roznic jest tez kilka subtelniejszych zmian ktorych trzeba pilnowac. o Amerykanski angielski czesciej uzywa form "backward", "upward", "toward" itd. a angielski zwykle "backwards", upwards", "towards" itd. o Sa sprzeczne opinie na temat "acknowledgement" i "acknowledgment". To drugie dominuje, ale nie jest uniwersalnie stosowane w amerykanskim agielskim. Pierwsze jest stosowane przez POSIX oraz w licencji BSD. W projekcie Linux man-pages uzywa sie "acknowledgement". Wersje BSD Klasyczny schemat zapisu wersji BSD to x.yBSD, gdzie x.y to wersja (np. 4.2BSD). Prosze unikac form takich jak BSD 4.3. Wielkie litery W podsekcjach ("SS") wielka litera nalezy pisac tylko pierwsze slowo w tytule, z wyjatkiem sytuacji gdy innego zapisu wymagaja zasady jezykowe lub nazwy wlasne. Na przyklad: .SS Unikod w Linuksie Wciecia definicji struktur, logow sesji powloki itp. Definicje struktur, logi z sesji powloki itp dolaczane do tekstu powinny zawierac wciecia o dlugosci 4 spacji (tj. powinny byc umieszczone w bloku otoczonym przez .in +4n i .in) i nalezy je formatowac za pomoca makr .EX i .EE oraz otoczyc odpowiednimi znacznikami akapitow (.P albo .IP). Przyklad: .P .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .P Preferowane terminy Ponizsza tabela pokazuje czesc preferowanych terminow w stronach podrecznika, glownie w celu zapewnienia spojnosci miedzy poszczegolnymi podrecznikami. Termin Niezalecany Uwagi ---------------------------------------------------------------- - bit mask bitmask built-in builtin Epoch epoch Do epoki Uniksa (00:00:00, 1 Jan 1970 UTC) 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 reserved port, system port real-time realtime, real time run time runtime saved set-group-ID saved group ID, saved set-GID saved set-user-ID saved user ID, saved set-UID set-group-ID set-GID, setgid set-user-ID set-UID, setuid superuser super user, super-user superblock super block, super-block 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 Chyba ze odnosi sie do wyniku "uname -m" itp. zeros zeroes Zob. tez Zapis z dywizem przydawek zlozonych ponizej. Terminy niezalecane Ponizsza tabela pokazuje czesc niezalecanych terminow w stronach podrecznika, razem z proponowanymi alternatywami, glownie w celu zapewnienia spojnosci miedzy poszczegolnymi podrecznikami. Niezalecane Zalecane Uwagi --------------------------------------------------------- 32bit 32-bit podobnie 8-bit, 16-bit, etc. current process calling process Czesty blad programistow jadra piszacych strony podrecznika ekranowego manpage man page, manual page 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 Znaki towarowe Prosze uzywac poprawnego zapisu znakow towarowych. Ponizsza lista zawiera poprawne zapisy roznych znakow towarowych, ktore sa niekiedy zapisywane niepoprawnie: DG/UX HP-UX UNIX UnixWare NULL, NUL, wskaznik null i bajt null A wskaznik null jest wskaznikiem wskazujacym na nic i pojawia sie zwykle jako stala NULL. NUL jest bajtem null, bajtem o wartosci 0, reprezentowanym w C jako stala znakowa '\0'. Preferowanym terminem na wskaznik jest "wskaznik null" lub "NULL"; prosze unikac terminu "wskaznik NULL". Preferowanym terminem w kontekscie bajtow jest "bajt null". Prosze unikac terminu "NUL", poniewaz jest on latwy do pomylenia z "NULL". Prosze starac sie nie uzywac rowniez "bajt zerowy" i "znak null". Bajt ktory przerywa lancuch C powinien byc opisywany jako "przerywajacy bajt null"; lancuchy te mozna nazwac "null-terminated", lecz prosze unikac terminu "NUL-terminated". Odnosniki Odnosniki tworzy sie para makr .UR/.UE (zob. groff_man(7)). W ten sposob tworzy sie poprawne odnosniki ktorych mozna uzyc w przegladarce internetowej przy renderowaniu strony przez np.: BROWSER=firefox man -H nazwa-strony Uzywanie e.g., i.e., etc., a.k.a. i podobnych Ogolnie rzecz biorac powinno sie unikac skrotow takich jak "e.g.", "i.e.", "etc.", "cf.", "a.k.a." na rzecz pelnego zapisu ("for example", "that is", "and so on", "compare to", "also known as"). Jedynym miejscem gdzie skroty sa dopuszczone to krotkie wtracenia (np. takie jak to). Zawsze nalezy zapisywac te skroty z kropka. Dodatkowo "e.g." i "i.e." powinny zawsze konczyc sie przecinkiem. Pauza "em" Sposobem zapisu pauzy "em" -- znaku ktory pojawia sie na obu koncach tego wtracenia -- w *roff jest macro "\[em]". Na terminalu ASCII pauza "em" jest zwykle renderowana jako dwa dywizy, lecz w innych sytuacjach pokazuje sie jako dluga pauza. Pauza "em" w jezyku angielskim powinna byc zapisywana bez otaczajacych ja spacji. Zapis z dywizem przydawek zlozonych Terminy zlozone powinny byc zapisywane z dywizem, gdy sa uzywane w formie przydawki. Przyklady: 32-bit value command-line argument floating-point number run-time check user-space function wide-character string Zapis z dywizem przedrostkow multi, non, pre, re, sub itd. Ogolna tendencja we wspolczesnym angielskim jest nie stosowanie zapisu po przedrostkach takich jak "multi", "non", "pre", "re", "sub" itd. Strony podrecznika powinny z reguly stosowac sie do tej zasady tam, gdzie przedrostki sa uzywane w naturalnych dla angielskiego konstrukcjach z prostymi przedrostkami. Ponizsza lista daje poglad na preferowane formy: interprocess multithreaded multiprocess nonblocking nondefault nonempty noninteractive nonnegative nonportable nonzero preallocated precreate prerecorded reestablished reinitialize rearm reread subcomponent subdirectory subsystem Dywizy powinny byc zachowane w przedrostkach uzywanych w niestandardowych dla angielskiego slowach, w znakach towarowych, rzeczownikach tego wymagajacych, akronimach lub zwrotach zlozonych. Przyklady: non-ASCII non-English non-NULL non-real-time Prosze zauwazyc, ze "re-create" i "recreate" to dwa odrebne czasowniki, przy czym prawdopodobnie chcemy wykorzystac ten pierwszy. Tworzenie optymalnych glifow Gdy wymagany jest prawdziwy znak minus (np. w przypadku liczb takich jak -1, w przypadku strony podrecznika zawierajacej odniesienia do innych stron takie jak utf-8(7) lub przy zapisywaniu opcji z poczatkowym dywizem, takich jak ls -l), prosze uzywac nastepujacej postaci w zrodlach stron podrecznika: \- Zalecenie to dotyczy tez przykladow kodu. Uzycie prawdziwego znaku minusa ma na celu: o Lepsze renderowanie w sytuacjach innych niz terminal ASCII, w szczegolnosci w PDF i na terminalach Unicode/UTF-8. o Generowanie glifow, ktore po skopiowaniu z wyrenderowanych stron utworza prawdziwy znak minusa przy wklejeniu na terminal. Aby utworzyc znak pojedynczego prostego cudzyslowu ktory wyswietla sie poprawnie w stronach ASCII, UTF-8 i PDF prosze uzywac "\[aq]" ("cytowania apostrofu") np. \[aq]C\[aq] gdzie C jest cytowanym znakiem. Zalecenie do tyczy sie rowniez stalych znakowych uzywanych w przykladach kodu. Tam, gdzie wymagany jest prawidlowy znak karety (^) renderujacy sie poprawnie w terminalu i w PDF-ie, prosze uzyc "\[ha]". Jest to szczegolnie konieczne w przykladach kodu, aby uzyskac prawidlowe renderowanie karety w formacie PDF. Surowy znak "~" daje kiepskie renderowanie w PDF-ie. Zamiast tego nalezy uzyc "\[ti]". Jest to szczegolnie konieczne w przykladach kodu, aby uzyskac prawidlowe renderowanie w formacie PDF. Przykladowe programy i sesje powloki Strony podrecznika moga zawierac przykladowe programy pokazujace, jak uzywac wywolania systemowego lub funkcji bibliotecznej. Jednakze prosze zauwazyc, ze: o Przykladowe programy powinny byc pisane w jezyku C. o Zamieszczenie programu przykladowego jest konieczne i uzyteczne tylko wtedy, gdy program ten pokazuje cos, czego nie mozna w prosty sposob zawrzec w tekstowym opisie demonstrowanego interfejsu. Program przykladowy nie robiacy nic poza wywolywaniem funkcji interfejsu zazwyczaj nie ma wiekszego sensu. o Przykladowe programy powinny byc krotkie (dobry przyklad czesto mozna zademonstrowac w mniej niz 100 wierszy kodu), choc w niektorych przypadkach do prawidlowego zilustrowania uzycia API konieczne sa dluzsze programy. o Zalecany jest kod ekspresywny. o Tam gdzie to przydatne, nalezy stosowac komentarze. Cale zdania w komentarzach zamieszczanych w oddzielnych wierszach nalezy zakonczyc kropka. Kropki nalezy zwykle unikac w komentarzach wtraconych (stosowanych w tym samym wierszu co kod); sa one zreszta zwykle krotkimi rownowaznikami, a nie pelnymi zdaniami. o Przykladowe programy nie powinny sprawdzac bledow wywolan systemowych czy funkcji bibliotecznych. o Przykladowe programy powinny byc kompletne i powinny sie kompilowac za pomoca cc -Wall bez wypisywania zadnych ostrzezen. o Kiedy tylko to mozliwe i wlasciwe, programy przykladowe powinny pozwalac na eksperymenty, roznicujac swoje zachowanie zaleznie od wejscia (idealnie pochodzacego z argumentow linii polecen lub alternatywnie z wejscia czytanego przez program). o Przykladowe programy powinny byc sformatowane w stylu "Kernighan & Ritchie" z wcieciami o rozmiarze czterech spacji (nie nalezy uzywac znakow tabulacji w kodzie zrodlowym!). Mozna uzyc ponizszego polecenia do sformatowania swojego kodu zrodlowego do stylu bliskiego pozadanemu: indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c o W celu zachowania spojnosci, wszystkie przykladowe programy powinny sie konczyc jednym z ponizszych: exit(EXIT_SUCCESS); exit(EXIT_FAILURE); Prosze unikac ponizszych form w celu zakonczenia programu: exit(0); exit(1); return n; o Jesli przed kodem zrodlowym znajduje sie wyczerpujace wyjasnienie, kod zrodlowy powinien byc oznaczony podrozdzialem Kod zrodlowy programu, jak w przykladzie: .SS Kod zrodlowy programu Zawsze nalezy go zastosowac, jesli wyjasnienie zawiera log z sesji powloki. Wlaczajac sesje powloki pokazujaca uzycie programu lub innej wlasciwosci systemu: o Nalezy umiescic log z sesji powyzej kodu zrodlowego. o Nalezy wciac log z sesji czterema spacjami. o Nalezy uzywac czcionki pogrubionej dla tekstu wprowadzanego przez uzytkownika, tak aby odroznic go od tekstu produkowanego przez system. Przyklady wygladu przykladowych programow mozna znalezc w wait(2) i pipe(2). PRZYKLADY Wzorcowymi przykladami tego, jak powinny wygladac strony podrecznikow z pakietu man-pages, sa strony pipe(2) i fcntl(2). ZOBACZ TAKZE man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7), mdoc(7) TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Przemek Borys , Robert Luberda i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.06 31 pazdziernika 2023 r. man-pages(7)