Obok stron manuala to właśnie format Info jest najpopularniejszym sposobem prezentowania dokumentacji pod Linuksem. Jest on spotykany praktycznie tylko w projektach GNU (GNU w zasadzie nie uznało stron manuala jako sensownego formatu, stąd strony manuala załączane w projektach GNU są tradycyjnie bardzo skąpe i zwykle zawierają dokładnie to samo, co wynik 'polecenie --help' - cała "prawdziwa" dokumentacja jest zawarta w stronach info. Generalnie Info zawsze zawierają więcej informacji niż manuale, o ile oczywiście można wybierać między tymi formami dokumentacji.

Ale wracając do rzeczy - Info różni się od manuali kilkoma "detalami" - z czego niektóre są ważne dla użytkowników, niektóre zaś dla administratorów. Użytkownik zapewne "doceni" koszmar jakim jest oficjalna przeglądarka stron Info, mogąca służyć jako przykład jak nie powinno się robić takich rzeczy (ale jest po części tłumaczona tym, że jest zasadzie kawałkiem kodu Emacsa wyrwanym poza swoje środowisko). Użytkownik też zauważy zalety, jakie niesie z sobą hipertekstowość Info, a więc łatwe do nawigowania spisy treści i rozdziały, albo możliwość uruchomienia przeglądarki od razu w konkretnym rozdziale dokumentacji. Administrator jednak zainteresuje się "technikaliami" jakie związane są z Info. Tak samo musimy zrobić i my - niestety.

W przypadku stron manuala instalacja jest prosta - wystarczy umieścić plik strony manuala w odpowiednim katalogu i presto! - już jest dostępny. Łatwiej nie można. Info ma jednak inny "pomysł" na załatwianie takich spraw: po pierwsze, jeden dokument Info może być albo zawarty w jednym pliku, albo podzielony na dziesiątki mniejszych - nie wpływa to jednak w żaden sposób na treści zwracane przez przeglądarkę, dzielenie dokumentacji na kawałki miało na celu jedynie "odciążenie" przeglądarki od ładowania za jednym zamachem całej dokumentacji, która, w zależności od opisywanych treści, może mieć nawet kilka megabajtów (np. około 2.5MB dla glibc.info). Po drugie, w każdym katalogu z dokumentami Info (np. /usr/share/info) musi istnieć specjalny plik-indeks, o nazwie "dir" (choć np. alternatywna przeglądarka Info/manuali, pinfo, nie wymaga już tego pliku - niestety oprócz kolorowania nie oferuje zbyt wielu funkcji oryginalnej przeglądarki Info czy choćby nawet pagera "less", autor nie miał chyba wystarczająco wiele czasu by się nią zająć - ktoś mógłby się nią zaopiekować).

Więc są dwie charakterystyczne cechy Info - pierwsza to rozbijanie jednej dokumentacji na kilka/kilkanaście plików (nie zawsze jednak spotykane), druga to istnienie czegoś nieznanego w świecie manuali - centralnych indeksów.

Wieloczłonowość Info

Cecha ta wiąże się obecnie raczej z odczuciami estetycznymi niż z racjonalnością, nie ma już wiele powodów by utrzymywać pliki Info w "wieloczłonowej" formie, ja w każdym razie wolę, gdy glibc instaluje jeden większy plik glibc.info niż 20 mniejszych, numerowanych pliczków. Ot, tak jakoś wolę. Sam nie wiem tak naprawdę dlaczego. Pakiety z oprogramowaniem jednak będą zwykle instalowały "rozczłonkowaną" dokumentację, częściowo dlatego, że taki jest domyślny tryb pracy narzędzia makeinfo którego używa się do tworzenia plików Info. Narzędzie to operuje na specjalnych plikach źródłowych texinfo, o rozszerzeniu (zwykle) .texi (geneza tego formatu jest dosyć pokrętna, to mariaż kilku wcześniejszych formatów ze szczyptą magii którą dodał RMS). Z plików tych można tworzyć, obok domyślnych plików Info, także dokumentację HTML, DocBook czy ogólny XML. W momencie tworzenia dokumentacji można za pomocą opcji '--no-split' wymusić stworzenie jednego, dużego pliku zamiast wielu małych. Chcesz tak robić? Nie musisz, nie ma to wpływu na samą funkcjonalność Info, ale tak jest zwykle z "względami estetycznymi". W każdym razie, po instalacji próbnej pakietu zawierającego dokumentację Info sprawdź, czy zamieszcza on dokumentację dzieloną na dziesiątki małych plików. Zwykle tak właśnie będzie (choć kilka nowych projektów jakie widziałem już tak nie robi! :) Cały "numer" polega na tym, by przy budowaniu pakietu wygenerować na nowo całą dokumentację Info. Czyli gdzieś w sekcji %install będziesz musiał usunąć całą zawartość %{buildroot}%{_infodir} i od nowa skompilować dokumenty Info. Z moich doświadczeń wynika, że najwygodniej jest wejść do katalogu zawierającego źródła texinfo dokumentacji, a stamtąd uruchomić coś w stylu:

makeinfo --no-split foo.texi -o %{buildroot}%{_infodir}/foo.info

To w 90% przypadków załatwia sprawę. Czasem trzeba jeszcze podać jakieś katalogi z "inkludami" dla dokumentu texinfo, opcją "-I". A czasem jeszcze bardziej nakombinować - najlepiej w takich chwilach usunąć z danego katalogu wszystkie wynikowe *.info, uruchomić "make" i patrzeć, w jaki sposób są na nowo generowane. Czasem trudne może być samo znalezienie odpowiednich plików źródłowych, gdy projekt jest bardzo rozległy i ma wiele podkatalogów - wtedy pomaga zwykle wyszukiwanie plików *.info, pliki źródłowe zazwyczaj leżą gdzieś w pobliżu.

W każdym razie powinieneś mieć teraz w %{buildroot}%{_infodir} już na nowo "zrobione" dokumenty Info, w zgrabniutkich, dużych plikach. Po jednym na każdy dokument Info.

Czasem zdarzają się programy, które dostarczają dokumentację Info już w odpowiednio "skondensowanej" formie i nie trzeba tego ręcznie zmieniać. Tutaj mam jedną radę czysto techniczną - w pliku .spec należy wówczas używać czegoś takiego:

%{_infodir}/*

Bo jeśli kiedyś, w przyszłości pakiet zacznie jednak rozbijać Info na malutkie Infiki to możesz tego nie zauważyć nawet. Dlatego lepsze jest albo wymienianie każdego pliku Info osobno (jeśli jest jeden-dwa, to żaden problem), albo użycie wzorca w stylu

%{_infodir}/*.info.gz

bo taki wzorzec nie powinien nigdy pasować do Info wieloczłonowych, i "jakby co", to rpmbuild da nam cynk ;) Tutaj warto też od razu podać inną regułę: jeśli nie ingerujesz w to, co "make install" wrzuca do katalogu %{_infodir}, to zrób chociaż jedno - usuwaj pliki "dir" z pakietów. Te pliki nie mają prawa nigdy znaleźć się w końcowym pakiecie, wyjaśnienie znajdziesz poniżej.

Plik indeksu Info

Indeksy są tą bardziej kłopotliwą częścią całego systemu Info. Indeks taki, zawarty w pliku "dir" funkcjonuje jako coś w rodzaju "spisu treści" - jest to plik tekstowy w który zarejestrowany musi być każdy zainstalowany w danym katalogu dokument Info. Gdy uruchomisz samo "info", bez podania tematu jaki cię interesuje, to zobaczysz stronę "początkową" która jest właśnie wszystkimi dostępnymi indeksami z wszystkich katalogów z dokumentami Info. Każdy plik Info zawiera w nagłówku pewne informacje, opisujące dane jakie powinien umieścić w indeksie. Czasem będzie to jeden wpis, czasem kilkanaście bardziej szczegółowych.

Procedura "instalacyjna" jest dosyć uciążliwa - każdy nowy plik należy zarejestrować w indeksie za pomocą programu "install-info. Jeśli potem ma się zamiar usunąć plik jakiegoś dokumentu Info, to używając "install-info" najpierw należy go wyrejestrować, a dopiero potem usunąć. Może to być skrajnie uciążliwe. Niewygodne jest choćby to, że by wyrejestrować jakiś plik trzeba mieć go ciągle dostępnego (inaczej install-info nie wie, które wpisy usunąć z indeksu). Niestety trzeba brać na siebie ten cały cyrk, bo inaczej info nie będzie miało pojęcia o dostępności jakiegoś podręcznika, nie będzie on zarejestrowany w indeksie. Można sobie z tym problemem radzić na kilka sposobów, ale skoro ma to być artykuł o RPM, to nas interesuje tylko ten fragment, który jest powiązany z budowaniem/instalowaniem pakietu.

Można wykorzystać sekcje %post i %preun aby rejestrować/wyrejestrowywać dokumenty Info. Jest to "najniższa" metoda na robienie tego, bardzo męcząca jeśli idzie o pisanie plików .spec. Wiąże się z wklepywaniem dwóch linijek poleceń dla każdego dokumentu Info zawartego w pakiecie. Można też zrezygnować z rejestrowania plików Info i robić to ręcznie, sporadycznie - ale to nie pasuje do automatyzacji systemu RPM. Można też uprościć sobie pracę i zamiast rejestrować pojedyncze pliki po prostu usuwać stary indeks i generować nowy, używając wszystkich dostępnych dokumentów Info - ale to może trwać nawet kilkanaście, a na wolnych maszynach kilkadziesiąt sekund - wydłużając o tyle instalację każdego pakietu zawierającego dokumenty Info. Ja na swoje potrzeby wybrałem coś pośredniego - napisałem skrypt, który sam zajmuje się dbaniem o aktualność indeksu, robiąc to raczej inteligentnie, pomijając pliki już zarejestrowane, wyrejestrowując pliki już niedostępne, oraz dorabiając minimalne wpisy w indeksie dla dokumentów Info, które same takich wpisów nie zapewniają (niedoróbki, ale się trafiają - np. dokumentacja "bc"). W przyszłości może funkcję wyrównywania layoutu gotowego indeksu, np. w PLD na razie robi się to pracowicie patchując dokumentację Info - ale mój skrypt mógłby to robić z dowolnymi dokumentami Info, przezroczyście dla użytkownika i administratora.

Skrypt uruchamia się w kontekście jakiegoś katalogu z dokumentacją, tworzy sobie tam jeden mały ukryty plik (na późniejszy użytek), a następnie dba o aktualność indeksu. Jeśli nie trzeba nic zmieniać, to nic nie robi. Jeśli coś doszło, to on to wykryje. Jeśli czegoś ubyło, to też to wykryje. Skrypt wykorzystuje ogólnodostępne narzędzia, takie jak zgrep (z pakietu gzip), install-info (tak czy siak konieczny, z pakietu texinfo) no i diff. Oprócz tego kilka tradycyjnych shellowych "narządek" takich jak rm, ls czy cut. Starałem się zachować wymagania na jak najniższym poziomie, tak by nie trzeba było używać basha czy perla. I udało się - skrypt spełnia doskonale swoją rolę, jest bardzo szybki, a dodatkowo mogę z radością zakomunikować, że łata przy okazji kilka niedostatków samego install-info.

Wystarczyło go wrzucić do /usr/bin lub /usr/local/bin (lub gdziekolwiek indziej), a potem jeszcze zmodyfikować nieco mój ~/.rpmmacros poprzez dodanie linijki:

%tidyinfo /usr/bin/tidyinfo %{_infodir}

Od tej chwili w plikach .spec mam dostępne nowe makro - %tidyinfo. Jeśli pakiet zawiera dokumentację Info, to w sekcjach %post oraz %postun wystarczy je wywołać. Reszta się "zrobi sama" - nieważne ile plików zawierał pakiet, czy były dodawane czy usuwane itp. Niezależnie od tych szczegółów wystarczy, że wpiszę w pliku .spec

%post
%tidyinfo

%postun
%tidyinfo

Makra tego używam z powodzeniem już od jakiegoś czasu i znacznie uprościło mi ono zarządzanie dokumentacją Info. Dodatkowo jeśli zechcę dodać jakąś funkcjonalność, to wystarczy prawdopodobnie przerobić nieco skrypt - pakiety nie muszą być przebudowywane.

O, przy okazji opracowałem sobie ciut lepszy plik podświetlania składni dla ViM-a - nieco poprawiony, podświetla makro %tidyinfo, tagi NoSource/NoPatch oraz parę innych rzeczy których w oryginale zabrakło. Wystarczy go wrzucić do ~/.vim/syntax/

Inne rozmaitości związane z Info

Regenerowanie dokumentacji Info stwarza kilka nowych możliwości. Po pierwsze można ustalić długość wierszy w wynikowych plikach za pomocą stosownej opcji "makeinfo" - oryginalny browser Info niestety nie dostosowuje szerokości tekstu do szerokości urządzenia - jest to, jak dla mnie, wielka wada, bo nie pozwala na optymalne wykorzystanie nieco szerszych terminali. Jeśli mamy zamiar zwykle używać urządzenia o jednej, stałej szerokości, to możemy wygenerować sobie dokumentację pod jego szerokość.

Druga opcja którą może warto rozważyć to fakt, że "makeinfo" nie musi koniecznie produkować dokumentacji Info. Może też tworzyć np. dokumentację html. Jeśli ktoś ma zamiar przebudowywać tak czy siak większość pakietów w swoim systemie (np. systemy klasy LFS), to przy odpowiednim podejściu i odrobinie wysiłku można zbudować sobie alternatywny mechanizm dokumentacji, oparty o html. To wcale nie jest takie trudne i samemu się nad tym zastanawiam. Jakiś sprytny skrypt by wyszukiwał potrzebne strony i uruchamiał je w ulubionej przeglądarce (Ognioptak lub ELinks). Wygodna, znajoma nawigacja, możliwość zakładania zakładek, trzeba by tylko dobudować do tego jakiś szkielet który by to obsługiwał, ale to nie powinno być trudne. Zamiast Info dokumentacja w html - warto się nad tym zastanowić. Kilka skryptów, określone miejsce na dysku na cele składowiska dokumentacji, parę makr dla rpmbuild żeby całość jak najbardziej zautomatyzować. Być może kiedyś sobie coś takiego opracuję, bo pomysł zaczyna mi się podobać. Wadą jest znowu rozbicie - poszczególne węzły dokumentacji muszą być umieszczone w osobnych plikach. Do tego nie można takiej dokumentacji tak łatwo kompresować, bo pojawi się problem z jej odczytem w przeglądarkach (choć ELinks bezproblemowo odczytuje skompresowany html). Ale być może wygoda korzystania z takiej dokumentacji by przeważała. Jeśli już coś robisz samemu, to możesz to przy okazji uczynić trochę lepszym, prawda? Tutaj jednak trzeba też zaznaczyć, że strony manuala również można zamienić na html. Wtedy może warto by było pójść o krok dalej i całą dokumentację systemu, man oraz info, przerobić na html i dorobić jeden, spójny interfejs który by pozwalał na więcej, niż obecnie man lub info (np. wyszukiwanie manuali według słów kluczowych w opisie lub treści - coś w stylu bardziej zaawansowanego "apropos")... Mi by się takie coś chyba spodobało, ELinks jako przeglądarka byłby znakomity...