Jak na pro­jek­ty v ja­zy­ce C

© Damig, 2004 – 2016
Koncept

Pomoc! Kde najdu dokumentaci?
Nápověda v různých systémech

Každý operační systém má svá vlastní specifika pro práci s nápovědou, zvláště s tou technickou. V této části se podíváme na to, jaké jsou v jednotlivých systémech možnosti práce s technickou dokumentací programátorských knihoven. Zde pomineme online zdroje, protože s těmi se na všech systémech pracuje stejně, tedy pomocí webového prohlížeče. Tady nás zajímá především offline nápověda a programy pro její zpřístupnění a vyhledávání v ní.

Pomoc, jsem v Unixu

Ať už používáte Linuxovou distribuci doma nebo jste se ocitli před nějakým unixovým systémem třeba ve škole, nepanikařte. Jazyk C je v Unixu doma, respektive vznikl právě proto, aby v něm mohl být napsán první Unix. Díky tomu se zde programátor k relevantním informacím, stejně jako k dalším programátorským nástrojům, dostane velmi snadno.

Základní dokumentace je dostupná přímo v textové konzoli, shellu. Samozřejmě ji jde zobrazit i v hezčí formě například pomocí webového prohlížeče (viz dále). Umět ji používat v textové konzoli se ale docela hodí, protože ji pak můžete používat, třeba když se k unixovému systému připojujete vzdáleně (například z Windows přes SSH programem Putty). Různé vývojářské editory a vývojová prostředí pak umí tuto textovou dokumentaci převést a zobrazit ve formě HTML stránek s hypertextovými odkazy a různě v nich vyhledávat. Například info stránky jsou ale hypertextové samy o sobě, i při zobrazení v textové konzoli.

Manuálové stránky

V unixových systémech jsou manuálové stránky nejobvyklejším způsobem nápovědy k programům s CLI. Poskytují vyčerpávající popis fungování a používání programů, ale i knihovních funkcí jazyka C. Ve své základní podobě neobsahují hypertextové odkazy, obsahují pouze text členěný do kapitol a velmi jednoduché formátování. V této části si ukážeme základní použití. Zobrazení manuálových stránek ve webovém prohlížeči si popíšeme později.

Spouští se v textové konzoli příkazem man stránka, kde jako parametr doplníte název programu nebo v našem případě knihovní funkce, o níž chcete získat podrobnější informace. Například pro podrobnější informace o programu man napište do příkazového řádku man man.

Samotné ovládání prohlížeče není složité.

  • Enter, šipky – jemné rolování stránky
  • Mezera, PgUp, PgDown – rolování o stránku
  • Home, End – posuv na začátek, konec
  • h – zobrazí detailní informace o ovládání prohlížeče
  • q – ukončení
  • /text – vyhledávání. Napište /-s a potom stiskněte Enter. Pokud chcete vyhledávat další výskyt stejného textu, napište pouze / (lomítko) a potom Enter.

Manuálové stránky jsou členěny do devíti sekcí podle svého účelu. V první úrovni jsou umístěny manuálové stránky systémových programů jako man, bash, apod. Programátorská dokumentace knihovních funkcí je až ve třetí sekci. Zde najdeme kompletní dokumentaci k systémovým knihovnám jazyka C a ostatních, které jsou v systému nainstalovány.

Někdy se stane, že požadovaná knihovní funkce má stejné jméno jako nějaký nainstalovaný program. Toto je případ knihovní funkce printf. V Linuxu má stejné jméno program, který se používá pro formátovaný tisk hodnot v shellových skriptech. Spustíme-li v příkazovém řádku příkaz man printf, zobrazí manuálová stránka programu printf. Pro zobrazení manuálové stránky knihovní funkce je potřeba zadat jako první parametr číslo požadované sekce, tedy man 3 printf. V našem případě je to číslo 3, protože ve třetí sekci se nachází dokumentace ke knihovním funkcím.

Nabízí se otázka, jak zjistit, že k zadanému jménu existuje více manuálových stránek. Pro toto máme příkazy whatis a apropos. Ukázka 1. demonstruje rozdíl v jejich použití. Oba příkazy vytisknou seznam stránek, které vyhovují zadání. U každé vypsané manuálové stránky se v závorce zobrazí číslo sekce, ve které se manuálová stránka nachází a dále následuje stručný jednořádkový popis, čeho se daná stránka týká.

Pokud byste chtěli zobrazit seznam všech manuálových stránek, které jsou v nějaké sekci k dispozici (tj. jsou nainstalovány), lze k tomu použít příkaz apropos -s 3 ., kde parametry -s 3 udávají v jaké sekci se bude hledat. Koncová tečka je žolík. Znamená tedy všechny existující manuálové stránky. S tímto příkazem ale opatrně, protože ten seznam může být opravdu velmi dlouhý. Chcete-li si jej přesto prohlédnout, je lepší zobrazit výsledek stránkovaně apropos -s 3 . | less nebo přesměrovat výstup příkazu do textového souboru apropos -s 3 . > seznamstranek.txt a pro zobrazení pak použít nějaký prohlížeč nebo textový editor.

$ whatis printf
printf (1)           - format and print data
printf (3)           - formatted output conversion

$ apropos printf
asprintf (3)         - print to allocated string
dprintf (3)          - print to a file descriptor
fprintf (3)          - formatted output conversion
fwprintf (3)         - formatted wide-character output conversion
printf (1)           - format and print data
printf (3)           - formatted output conversion
snprintf (3)         - formatted output conversion
sprintf (3)          - formatted output conversion
swprintf (3)         - formatted wide-character output conversion
vasprintf (3)        - print to allocated string
vdprintf (3)         - print to a file descriptor
vfprintf (3)         - formatted output conversion
vfwprintf (3)        - formatted wide-character output conversion
vprintf (3)          - formatted output conversion
vsnprintf (3)        - formatted output conversion
vsprintf (3)         - formatted output conversion
vswprintf (3)        - formatted wide-character output conversion
vwprintf (3)         - formatted wide-character output conversion
wprintf (3)          - formatted wide-character output conversion
Příkaz whatis tiskne seznam přesně odpovídacích stránek, zatímco apropos vyhledává příbuzné stránky.

Info stránky

Info stránky na rozdíl od manuálových stránek obsahují text s hypertextovými odkazy na jiné info stránky. Jsou používány hlavně pro tutoriály, tedy dokumentace členěné do tématických kapitol, kde spíše než konkrétní funkce chcete vyhledávat témata jako alokace paměti, zpracování textu, atd. O knihovních funkcích, které jsou pro dané téma relevantní se dozvíte právě z tohoto obecnějšího textu, který často obsahuje i ukázky kódu.

Program info funguje v textové konzoli stejně jako program man, takže je možno jej použít i na textových terminálech bez přítomnosti grafického systému. Použití je podobné jako u manuálových stránek, jako parametr příkazu info se zadává název info stránky, například info info.

Základní ovládání je totožné s ovládáním prohlížeče manuálových stránek, včetně vyhledávání. Přibylo ovládání hypertextových odkazů. V textu poznáte hypertextový odkaz tak, že je zleva uvozen hvězdičkou a zprava jednou nebo dvěma dvojtečkami, * takto::. Když na tento odkaz najedete kurzorem třeba pomocí šipek, stiskněte klávesu Enter. Zpátky k výchozímu odkazu se dostanete pomocí klávesy L.

Chcete-li zobrazit info stránky věnující se knihovně jazyka C, použijte příkaz info libc. Zobrazí se seznam kapitol, které můžete začít číst. V seznamu kapitol jsou i kapitoly Function Index a Type Index. Obsahují rejstřík všech použitelných funkcí a datových typů. Když zde najdete svou funkci, vede hypertextový odkaz do kapitoly, která popisuje její použití. Mějte však na paměti, že některé důležité informace se mohou nacházet i v okolních kapitolách.

Příkaz info dokáže zobrazit i podkapitoly zadaného tutoriálu. Například info libc Memory zobrazí rovnou kapitolu Memory. Pokud nezadáte žádný parametr nebo název, kterému žádná dokumentace neodpovídá, zobrazí se seznam všech info stránek, které jsou k dispozici. Povede-li se vám zadat název, ke kterému není žádná info stránka, ale existuje k němu manuálová stránka, zobrazí se ona manuálová stránka.

Nápověda v KDE a v Gnome

V dnešní době jste v unixových systémech odkázáni pouze na textový terminál zejména v případech, kdy se k počítači (rozumějte serveru) připojujete vzdáleně. Například z Windows programem Putty nebo z Linuxu či Mac OS X příkazem ssh. Pokud ovšem máte na svém počítači nainstalovánu některou ze současných běžně používaných Linuxových distribucí, nejspíše pracujete v nějakém grafickém prostřední pro správu oken. Mezi nejrozšířenější patří KDE a Gnome. Gnome najdete jako výchozí prostředí v Ubuntu nebo Fedoře, KDE pak v Kubuntu nebo v openSUSE. Všechny mně známé distribuce dovolují dodatečnou instalaci jiných prostředí pro správu oken.

V prostředí KDE to je s nápovědou celkem jednoduché. Máte-li nainstalovány správné manuálové a info stránky, můžete si je prohlížet zabudovaným prohlížečem nápovědy nebo ve svém webovém prohlížeči. Prohlížeč nápovědy se spouští klávesou F1, případně přímo z nabídky programů. Zobrazení manuálových a info stránek demonstrují obrázek 1. a obrázek 2. Všimněte si umístění manuálových a info stránek v seznamu všech dokumentací v levé části obrazovky.

Jak manuálové, tak i info stránky lze v KDE zobrazit i ve výchozím webovém prohlížeči. Stačí ve spouštěči aplikací (startovací menu) nebo na ploše (Alt+F2, viz obrázek 3.) napsat man: případně rovnou man:printf a odpovídající manuálová stránka se zobrazí ve webovém prohlížeči. Podobně to funguje i v případě info stránek, kde použijete například info:libc.

V Gnome to také nápovědou není nijak složité. Výchozí aplikace pro zobrazení nápovědy se zde jmenuje Yelp. Umí zobrazovat nápovědu v HTML, manuálové i info stránky a pár dalších formátů. Nápovědu lze opět spustit klávesou F1, z hlavní nabídky nebo z menu kterékoli aplikace. Nápověda se zobrazuje v hypertextové podobě a samozřejmě v ní lze i vyhledávat.

Nainstalujete-li si nějaké vývojové prostředí pro jazyk C, jako Code::Blocks (kdekoli), KDevelop (v KDE), Anjuta (v Gnome) nebo Eclipse (kdekoli), můžete použít jejich zabudovaný systém nápovědy. V některých případech si budete muset doinstalovat balíček s nápovědou dodatečně nebo nápovědu v těchto aplikacích nakonfigurovat tak, aby byla schopná zobrazovat manuálové a info stránky.

Centrum nápovědy umí zobrazit pěkně formátované manuálové stránky.
Zobrazení info stránek v Centru nápovědy KDE.
Spouštěč aplikací v KDE zobrazený pomocí Alt+F2 umožňuje zobrazovat manuálové a info stránky v okně webového prohlížeče.

Pomoc, mám Apple

Protože Mac OS X je unixový systém, fungují zde jak manuálové, tak info stránky. Oboje můžete spustit z Terminálu stejným způsobem, který byl popsán výše. Samozřejmým předpokladem je, že je máte správně nainstalovány. Terminálová aplikace také umožňuje hledání manuálových stránek komfortnějším způsobem pomocí položky menu Nápověda. Osobně nemám s Mac OS X zkušenosti, takže nevím, zda jde tuto nápovědu zobrazit i komfortněji ve standardním prohlížeči nápovědy. Dá se ale předpokládat, že když si nainstalujete nějaké vývojové prostředí pro jazyk C, například Code::Blocks nebo Xcode, nějaký druh nápovědy ke standardní knihovně jazyka C bude dostupný přímo v nich nebo jej půjde pro tato prostředí doinstalovat (v Code::Blocks se o toto stará Help plugin).

Pomoc, jsem ve Windows!

To vám tedy nezávidím ;-). Samozřejmě můžete s trochou opatrnosti používat online dokumentaci (obsahuje i PDF soubor pro offline použití). Dokumentace využívající zabudovaný prohlížeč nápovědy ovšem vždy přináší větší komfort při jejím používání. V současné době je však s dokumentací v nativním formátu trochu problém (časem se ale bude zmenšovat).

Starší verze Windows používaly pro nápovědu soubory s koncovkou .hlp. Od doby Windows Vista však tato nápověda již není podporována. Pro zobrazení v novějších systémech Windows je potřeba doinstalovat program WinHlp32.exe.

Od Windows 98 se pro nápovědu používají i soubory s koncovkou .chm. Tento formát je v současnosti preferovaným formátem pro nápovědu. Chcete-li si vytvořit vlastní soubor s nápovědou z HTML stránek, můžete použít volně dostupný nástroj HTML Help Workshop.

Protože Windows není POSIX kompatibilní systém, nepoužívá manuálové stránky. Prohlížeč manuálových stránek si ovšem můžete doinstalovat spolu se systémem Cygwin, který umožňuje používat různé GNU a Open Source nástroje ve Windows. V základní instalaci ovšem obsahuje pouze manuálové stránky pro poskytované programy, nikoli pro funkce ze standardní knihovny jazyka C.

V plnotučných, komerčních IDE naleznete samozřejmě i potřebnou dokumentaci jazyka a knihoven. U jednodušších vývojových prostředí si obvykle musíte dokumentaci opatřit sami. Například u oblíbeného IDE Code::Blocks si můžete doinstalovat (resp. zapnout při instalaci) Help plugin, který vám dovolí přímo z IDE spouštět různé druhy nápovědy, včetně manuálových stránek (funguje na unixových systémech), .hlp a .chm formátů (funguje ve Windows) a dokonce jej můžete nakonfigurovat, aby vyhledával na internetu nebo v lokálních webových stránkách. Na webové stránce najdete i odkaz na dokumentace k jazykům C/C++ ve formátu .chm, vygenerovaném z webových stránek cppreference.com.