lexgrog - przetwarza nagłówki stron podręcznika ekranowego
lexgrog [
-m|
-c] [
-dfw?V] [
-E
kodowanie_znaków]
plik ...
lexgrog jest implementacją w
lexie tradycyjnych
narzędzi “zgadywanki groffa”. Ze swojej linii
poleceń czyta listę plików, które mogą
być albo źródłami stron podręcznika albo
preformatowanymi stronami “cat”, i wyświetla ich nazwy i
opisy, tak jak są używane przez
apropos i
whatis,
albo listę filtrów preprocesora wymaganych przez stronę
podręcznika zanim zostanie przekazana do
nroff lub
troff,
albo obie te listy.
Jeżeli wejście
lexgrog jest w złym formacie, to
wypisze on komunikat “parse failed”; może to być
użyteczne dla zewnętrznych programów
sprawdzających poprawność stron podręcznika.
Jeżeli jednym z plików wejściowych
lexgroga jest
“-”, to będzie czytał ze swojego standardowego
wejścia; jeśli plik wejściowy jest skompresowany, to go
automatycznie zdekompresuje.
-
-d, --debug
- Wyświetla informację diagnostyczną
(debug).
-
-m, --man
- Przetwarza wejście jako pliki
źródłowe stron podręcznika ekranowego. Jest to
zachowanie domyślne, jeśli nie podano ani --man, ani
--cat.
-
-c, --cat
- Przetwarza wejście jako sformatowane
wcześniej strony podręcznika ekranowego (“strony
cat”). --man i --cat nie mogą być
użyte jednocześnie.
-
-w, --whatis
- Wyświetla nazwę i opis z
nagłówka strony podręcznika ekranowego,
używanego przez apropos i whatis. Jest to
domyślne zachowanie, jeżeli nie podano ani --whatis,
ani --filters.
-
-f, --filters
- Wyświetla listę filtrów potrzebnych do
wstępnego przetworzenia strony podręcznika zanim zostanie
sformatowana przez program nroff lub troff.
-
-E kodowanie_znaków, --encoding
kodowanie_znaków
- Nadpisuje odgadnięte kodowanie znaków strony
podręcznika, ustawiając je na
kodowanie_znaków.
-
-?, --help
- Wyświetla komunikat pomocy i kończy
pracę.
- --usage
- Wyświetla krótki opis użycia programu
i kończy pracę.
-
-V, --version
- Wyświetla informację o wersji.
- 0
- Program zakończony bez żadnych
błędów.
- 1
- Błąd użycia.
- 2
-
lexgrog nie umiał przetworzyć jednego
lub więcej spośród plików
wejściowych.
$ lexgrog man.1
man.1: "man - an interface to the system reference manuals"
$ lexgrog -fw man.1
man.1 (t): "man - an interface to the system reference manuals"
$ lexgrog -c whatis.cat1
whatis.cat1: "whatis - display manual page descriptions"
$ lexgrog broken.1
broken.1: parse failed
mandb (oparty na tym samym kodzie, co
lexgrog) przetwarza
sekcję
NAZWA (
NAME) znajdującą się
samej górze strony podręcznika ekranowego, szukając w
niej nazw i opisów. Mimo że parser jest całkiem
tolerancyjny, ponieważ musi sobie radzić z rożnymi
formatami, które były używane na przestrzeni lat, to
jednak czasem nie potrafi wyciągnąć potrzebnych
informacji.
Jeżeli używany jest tradycyjny zbiór makr
man, to
poprawna sekcja
NAZWA wygląda tak jak poniżej:
.SH NAZWA foo \- program, który coś robi
Niektóre programy do obsługi stron podręcznika
wymagają, aby separator ‘\-’ był dokładnie
taki, jak to pokazano;
mandb jest bardziej tolerancyjny,
jednakże w celu zachowania kompatybilności z innymi systemami
dobrym pomysłem jest pozostawienie znaku odwrotnego ukośnika.
Po lewej stronie może występować kilka nazw, rozdzielonych
od siebie przecinkami. Nazwy zawierające białe znaki są
ignorowane, aby uniknąć nieprawidłowego zachowania przy
niektórych źle sformatowanych sekcjach
NAZWA. Tekst po
prawej stronie ma dowolną postać i może zajmować
wiele linii. Jeżeli w tej samej stronie podręcznika
udokumentowanych jest kilka programów z różnymi opisami,
powinna być użyta poniższa forma:
.SH NAZWA foo, bar \- programy, które coś robią .br baz \- program, który nic nie robi
(Zamiast makra .br można użyć makra, które zaczyna
nowy akapit, na przykład .PP.)
Podczas używania pochodzącego z systemów BSD zbioru makr
mdoc poprawna sekcja
NAZWA powinna wyglądać tak
jak poniżej:
.Sh NAZWA .Nm foo .Nd program, który coś robi
Jest kilka powszechnych przyczyn, dla których przetwarzanie whatis
kończy się fiaskiem. Czasami autorzy stron podręcznika
zastępują ‘.SH NAZWA’ przez ‘.SH
MÓJPROGRAM’, co powoduje, że
mandb nie potrafi
odnaleźć potrzebnych informacji. Czasami autorzy
umieszczają wprawdzie sekcję NAZWA, ale zawierają w niej
dowolny tekst zamiast używać ‘nazwa \- opis’.
Jednakże każda składania przypominająca
powyższą powinna być akceptowana.
apropos(1),
man(1),
whatis(1),
mandb(8)
lexgrog próbuje przetwarzać pliki zawierające
żądania .so, jednakże będzie zdolny to
zrobić tylko wtedy, gdy pliki te są poprawnie zainstalowane w
hierarchii stron podręcznika ekranowego.
Autorami kodu używanego przez program
lexgrog do przetwarzania
stron podręcznika są:
Wilf. ([email protected]).
Fabrizio Polacco ([email protected]).
Colin Watson ([email protected]).
Colin Watson napisał obecne wcielnie interfejsu linii poleceń i
tę stronę podręcznika ekranowego.
https://gitlab.com/man-db/man-db/-/issues
https://savannah.nongnu.org/bugs/?group=man-db
Wojciech Kotwica w 1999 roku przetłumaczył
część stron podręcznika pakietu man-db i
udostępnił je w ramach Projektu Tłumaczenia Manuali.
Robert Luberda tłumaczenie zaktualizował i uzupełnił
w roku 2008.