Posledně jsme se seznámili se základními dokumenty popisujícími Emacs a poskytujícími uživateli podrobnou nápovědu. Tentokrát se zaměříme na programy, které kvalitní info dokumentací nedisponují. Povíme si také něco o klávesových příkazech a zastavíme se u příkazů pro rychlé získání nápovědy.

Dokumentace k programům

Řada emacsovských programů definuje nějaké módy, ať už hlavní nebo vedlejší. V případě takových programů můžete využít příkazu C-h m, který zobrazí dokumentaci pro všechny momentálně aktivní módy. Přitom popis aktivního hlavního módu obvykle naleznete až na konci výpisu dokumentace, musíte tedy zobrazenou nápovědou trochu zalistovat, hledáte-li informaci právě o hlavním módu.

Naprostá většina programů obsahuje stručnější či obsáhlejší popis v úvodních komentářích ve svém zdrojovém textu. Obvykle tam naleznete informaci o instalaci, základní návod k použití a popis nejdůležitějších konfiguračních proměnných. Pokud se zdrojový kód nachází někde ve stromu emacsovských adresářů, naleznete jej nejsnáze pomocí příkazu M-x locate-library (tento příkaz může být též užitečný v případě, kdy si nejste jisti, zda se vám náhodou místo instalované nejnovější verze nezavádí nějaký zapomenutý exemplář daného programu). Pokud neznáte ani jméno programového souboru a znáte například pouze jméno jeho hlavní funkce, zkuste C-h f. Tento příkaz kromě popisu funkce vypíše i jméno souboru, ze kterého byla načtena. To může být spojeno s určitými obtížemi:

• Můžete se dozvědět, že funkce je built-in. Pak není definována v žádném elispovském souboru, nýbrž je definována ve zdrojových textech v jazyce C.
• Můžete se dozvědět, že se jedná o compiled Lisp function, ale už ne to, kde se její definice nachází. To znamená, že funkce je sice elispovská, ale zakompilovaná v binárce Emacsu kvůli sdílení paměti nebo byla definována dynamicky v těle jiné funkce a tudíž není znám soubor s její definicí.

V druhém případě lze stále ještě použít tags. Máte-li Emacs instalován v adresáři directory, vygenerujete příkazem

rm -f TAGS
find directory -name '*.el' -print | xargs etags -a

Zdrojové texty jsou zajímavé nejen z hlediska úvodních komentářů. Pokročilejší uživatel si v nich najde zajímavé defvary. Pro uživatele vládnoucí (na první pohled magickou) schopností programovat v Elispu jsou pak zdrojové texty pravým pokladem. Lze v nich nalézt nesčetné množství tipů a zajímavostí a nezřídka do nich člověk nahlédne právě proto, aby zjistil "jak se něco dělá". Programujete-li v Elispu a nemůžete najít návod pro nějakou věc po manuálech, zkuste si vzpomenout, kde jste odpovídající chování již viděli. Návod pak najdete ve zdrojových textech příslušného programu. (Pro neznalce Elispu to celé může znít jako pokus o vtip, ale skutečnost je jiná. Elisp je velmi čitelný jazyk a nalézt něco v jeho zdrojových textech je obvykle daleko snazší, než si možná myslíte.)

Vraťme se zpátky k běžnému uživateli. Může se stát, že narazíte na rozsáhlý balík se špatnou dokumentací (jako je například w3) a potřebujete jej zkonfigurovat. Pokud autor disponuje alespoň elementární mírou úcty k uživateli, tak dokumentuje přinejmenším konfigurační proměnné pomocí customize. (Pokud nevíte, co to customize je, nahlédněte do menu "Help" a zvolte odpovídající položku; pozor, standardně je přítomna až v Emacsu 20.) Na první pohled se může zdát, že customize je zde pouze pro uživatele, kteří si neumí zkonfigurovat Emacs editací souboru ~/.emacs. Ve skutečnosti však má tento mechanismus i významnou vedlejší funkci - naleznete zde totiž hierarchicky uspořádané konfigurační proměnné s popisem a možností je ihned nastavit a případně i uložit. A pak už vlastně žádnou další dokumentaci ke konfiguraci balíku podporujícího customize nepotřebujete!

Poučení pro tvůrce elispovských programů:

• Své programy v úvodních komentářích stručně dokumentujte.
• Uživatelské proměnné deklarujte pomocí defcustom, nikoliv pomocí defvar.
• Pokud není již z názvu funkce či proměnné zcela zřejmé, k jakému účelu slouží, nezapomeňte ji vybavit dokumentačním řetězcem. To platí i pro triviální funkce - ušetří to hledání definice funkce při četbě zdrojových textů.
• Zejména bezpodmínečně dokumentujte všechny interaktivní funkce a uživatelské proměnné.
• Podrobně dokumentujte módy, které váš program definuje.

Klávesy

Nejčastější otázkou bývá: "Co tato klávesová zkratka vlastně dělá?" Nechcete-li být obtěžováni dlouhými výklady, použijte C-h c. To se hodí zejména v případě, kdy si chcete připojit funkci třeba na nějakou funkční klávesu a potřebujete znát její jméno pro zapsání odpovídající definice do ~/.emacs. Pokud chcete získat kompletní nápovědu k funkci dané klávesy, použijte C-h k.

Pokud naopak nevíte, pomocí kterých kláves lze nějakou funkci vyvolat, můžete zkusit:

• Podívat se do menu. Lze-li funkci vyvolat klávesovou zkratkou, má tuto zkratku příslušná položka menu u sebe uvedenu.
• Funkci provést prostřednictvím zadání jejího plného jména po M-x. Je-li dosažitelná i klávesovou zkratkou, Emacs vás na to po jejím provedení (v Emacsu 19 před jejím provedením) upozorní.
• Použít příkaz C-h w. Výhodou tohoto příkazu je to, že vám zobrazí *všechny* klávesové kombinace, pomocí kterých lze zadaný příkaz vyvolat.

Často se též stává, že něco nechtěně zmáčknete a ono to provede zajímavý příkaz, který dosud neznáte. Rádi byste věděli, který příkaz to byl, protože je vám ihned jasné, že jej teď budete naprosto nezbytně a opakovaně potřebovat. Pomůže vám příkaz C-h l, který zobrazí posledních 100 stisknutých kláves. Mimochodem, víte, proč není dobré odcházet od neuzamčeného Emacsu, ve kterém jste se právě přihlásili na vzdálený počítač se zadáním hesla?

Někteří lidé mají vyvinutější smysl pro systematičnost. Ti se pak s náhodným boucháním do klávesnice nespokojí a chtějí vidět všechno najednou. Pro ty je ideální příkaz C-h b. Ano, je to trochu přehnané, ani tento příkaz nemůže zobrazit spočetně mnoho příkazů Emacsu, takže zobrazí pouze aktuálně dostupné klávesové kombinace. Ty jsou samozřejmě závislé na momentálně aktivních hlavních a vedlejších módech. Pokud vás zajímají pouze příkazy začínající určitým prefixem, můžete si je nechat vypsat zadáním prefixu následovaného stiskem C-h. Například příkazy pro práci s registry, záložkami a obdélníkovými bloky si vypíšete pomocí C-x r C-h. Typické příkazy aktuálního hlavního módu pak pomocí C-c C-h.

Proměnné a funkce

Jedním z nejmocnějších příkazů nápovědy Emacsu je apropos. Apropos příkazy vám umožní vyhledat funkci nebo proměnnou podle regulárního výrazu. Zadáte regulární výraz a Emacs vám vypíše všechny funkce a proměnné, které zná a které tomuto výrazu odpovídají. Kliknutím nebo stiskem RET na dané položce z vyhledaného seznamu se vám zobrazí dokumentace k odpovídající funkci nebo proměnné. Apropos existuje ve třech základních variantách:

• C-h a vyhledává mezi uživatelskými příkazy (interaktivní funkce).
• C-u C-h a vyhledává mezi uživatelskými příkazy a uživatelskými proměnnými.
• M-x apropos prohledává celý jmenný prostor.

Na první pohled nemusí být zřejmé, o jak mocný nástroj se jedná. Kdo se ale naučí apropos efektivně používat, ušetří si spoustu hledání v manuálech a ve zdrojových textech. Například potřebujete obrátit pořadí řádků v souboru. Stačí si uvědomit, že s obráceným pořadím by mohlo mít něco společného anglické slovo "reverse". Zjevně by se mělo jednat o uživatelský příkaz, takže zadáte C-h a reverse RET a ve zobrazeném výsledku již odpovídající funkci snadno naleznete. Nebo provádíte sofistikovanou konfiguraci Gnus a potřebujete pro své účely najít nějaký vhodný hook. Použijete M-x apropos ^\(gnus\|message\|nn\).*hook RET stoprocentní jistotu, že před sebou vidíte kompletní seznam všech hooků, které můžete použít. Nebo vás zajímají možnosti BibTeX módu. Aplikujete tedy C-u C-h a ^bibtex RET. (Tento příklad je poněkud umělý, spíše byste na tomto místě použili customize.)

Pozor na malou záludnost: Některé programy jsou zaváděny prostřednictvím autoload mechanismu až při vyžádání jejich funkcí. Do doby jejich zavedení žádný z příkazů pro popis funkce nebo proměnné a tím pádem ani apropos neví o existenci většiny funkcí a proměnných definovaných v tomto balíku. Chcete-li proto hledat například něco týkající se Gnus, je dobré nejprve Gnus spustit a chvíli s nimi pracovat, protože teprve potom je načtena většina programových souborů Gnus a nebudete se marně snažit najít dosud nezavedenou proměnnou. Totéž platí pro příklad s BibTeXem - před aplikací apropos nejprve otevřete libovolný (třeba prázdný) .bib soubor.

Poučení pro programátory v Elispu:

• Dbejte na vhodnou volbu jmen proměnných a funkcí, mějte na paměti situaci uživatele používajícího apropos.
• Rozlišujte interní a uživatelské proměnné pomocí hvězdičky v dokumentačním řetězci funkce defvar či makra defcustom.
• Přečtěte si sekci "Documentation Tips" v manuálu Elispu. Budete pak schopni lépe dodržovat dokumentační konvence, které usnadní situaci uživateli, tj. tomu, pro koho dokumentaci píšete.

Příště