Pokud máte jasno, co chcete v nápovědě najít, přejděte na další kapitolu s praktickými ukázkami. Tady se podíváme, k čemu jsou dobré různé druhy dokumentací.
Než se podíváme, kde a jak hledat informace, musíme si ujasnit, co konkrétně chceme hledat. Někdy se vám totiž může stát, že sice najdete v zásadě správné informace, ale budete zklamaní z toho, jakou formou jsou podány. Když totiž stojíte o rychlé nalezení konkrétní specifické informace, jako například o počet a význam parametrů nějaké knihovní funkce, může vám být na obtíž hromada populárně naučného povídání okolo. A opačně, když stojíte o vysvětlení, jak funguje práce s pamětí, je nepříjemné to dedukovat ze suchého popisu funkcí, které se tím zabývají. No a nakonec často víte, co chcete dělat (např. alokovat paměť), ale nevíte, jaké všechny funkce jsou k dispozici, abyste mohli vybrat tu nejlepší pro řešení vašeho problému. Pak potřebujete nějaký šikovně udělaný rejstřík funkcí orientovaný podle témat.
Existují různé druhy dokumentací a zdrojů informací pro programátory. Nás budou zajímat zdroje zabývající se standardní knihovnou funkcí jazyka C, dále pak zdroje popisující samotný jazyk a nakonec i použití různých programátorských nástrojů.
Uživatelský manuál obsahuje informace o programech nebo knihovnách z uživatelského hlediska. Poradí vám, jak je nainstalovat, nastavit a zprovoznit. V případě programů vám ukáže, s jakými parametry jdou spouštět, pokud jde o programy s GUI, popíše vám strukturu menu. Je to podobné tomu papíru, co vám jako první vypadne z krabice, když si koupíte novou ledničku. Při hledání na internetu použijte klíčová slova user manual a guide.
Slušně napsané programy mají uživatelský manuál zabudovaný v sobě. U programů s GUI jej najdete v menu Nápověda (Help), u programů s CLI můžete vyzkoušet spuštění s přepínači -h, --help nebo /?. V unixových systémech je kromě toho zvykem poskytovat ke každému programu manuálovou stránku zobrazovanou příkazem man jmenoprogramu (viz další kapitola).
Tutoriál poskytuje základní představu o hlavních rysech jazyka nebo knihovny, základních konstrukcích a oblastech použití. Obvykle jde o souvislý text, tématicky členěný do kapitol. Jednotlivé funkce jsou popisovány postupně podle toho, jak se to hodí k vysvětlovanému tématu, často na příkladech. Specifickým příkladem tutoriálu může být učebnice programovacího jazyka. Tyto webové stránky se také dají pokládat za tutoriál.
Tutoriál je dobrý výchozí bod, když o tématu vašeho zájmu (alokace paměti, zpracování vstupu a výstup, atd.) potřebujete získat všeobecný rozhled. Konkrétní funkce zde zřejmě budou zmíněny, možná zde najdete i ukázky kódu, ale detailnější informace o daných funkcích hledejte spíše v referenčním manuálu.
Toto je to pravé místo kam jít, když víte přesně, co hledáte. Obsahuje vyčerpávající popis všech knihovních konstant, proměnných, funkcí a jejich parametrů (nebo příkazů jazyka, pokud jde o manuál k jazyku), ale i kapitoly věnující se obecnějším tématům, které zasadí použití jednotlivých funkcí do vzájemného kontextu.
Referenční manuál může mít strukturu podobnou tutoriálu, tedy kapitoly se souvislým textem. Na rozdíl od tutoriálu ale bývá mnohem přesnější a kompletnější. Druhou možností je referenční manuál organizovaný jako seznam konkrétních položek, v našem případě funkcí a datových typů, kde u každé položky jsou uvedeny všechny relevantní informace, které se k ní váží a to i za cenu, že některé informace jsou uváděny duplicitně. Výhodou je, že se v takovém manuálu dobře vyhledává podle jmen funkcí. Příkladem takového manuálu jsou manuálové stránky v unixových systémech.
Třetí možností je tutoriál kombinující prvky obou předchozích typů, tedy jak obecné kapitoly, tak seznam konkrétních položek. Příkladem takového manuálu jsou GNU info stránky knihovny libc nebo jejich online podoba.
Znáte-li tedy jméno funkce, najdete zde vyčerpávající a přesný popis parametrů, návratové hodnoty a chování v různých situacích, včetně reakcí na různé chybové stavy. Protože knihovna obvykle obsahuje funkce vyhovující různým verzím standardů jazyka spolu s funkcemi, které jsou bonusovým rozšířením výrobce, poskytuje manuál u každé funkce i výčet standardů, kterým daná funkce vyhovuje. Kromě toho u každé funkce obvykle najdete i seznam příbuzných funkcí, zabývajících se stejnou tématikou.
Kromě zmíněných typů dokumentace se ještě můžete setkat s normami jazyka C a jeho knihoven, respektive s jejich náčrty (angl. draft)Mezinárodní organizace pro normalizaci (ISO). Poslední verze náčrtů před konečným schválením obvykle bývá konečné verzi velmi blízko.'>. Obsahuje precizní a jednoznačné informace a používá matematické formalismy pro popis syntaxe jazyka. Slouží především pro výrobce překladačů a knihoven. Pro běžného uživatele to obvykle není ten nejlepší zdroj informací, ne kvůli nedostatku informací, ale jejich přílišnému množství.
Programovací jazyky i jejich knihovny procházejí vývojem. Aby bylo možné vytvářet programy, které jsou přenositelné, jsou různé verze jazyka a knihoven popsány pomocí norem, které se každých několik let aktualizují.
Přenositelností mám na mysli, že jednou napsaný a odladěný program bude na úrovni zdrojového kódu beze změn použitelný na různých operačních systémech (opravdu jde psát programy, jejichž kód je totožný pro Linux, jiné unixové systémy i Windows). Zároveň je takový program přeložitelný na překladačích od různých výrobců. Bez norem jazyka, které dodržují jak výrobci překladačů, tak výrobci operačních systémů, ale i samotní programátoři, by něco takového nebylo možné.
Chcete-li psát přenositelné programy, a zejména pokud s programováním začínáte, tak byste to měli chtít, protože si tím značně zjednodušíte život, měli byste si v dokumentaci k jednotlivým knihovním funkcím všímat, jaké normě jazyka daná funkce vyhovuje. Nejdůležitější jsou normy ISO, ANSI, případně POSIX. Například v manuálových stránkách si těchto zkratek všímejte v kapitole CONFORMING TO, která popisuje, jakým normám dané funkce vyhovují.
ISO je označení mezinárodní normy. V současnosti nejnovější verzí jazyka C je ta, která je popsaná normou neformálně označovanou jako ISO C11, která byla schválena v roce 2011 (její oficiální označení je ISO/IEC 9899:2011). Předchozí verze z roku 1999 byla značená ISO C99. Použijete-li ve svém programu pouze funkce, které jsou v dokumentaci označeny jednou z těchto zkratek, nebudete mít problémy s přenositelností.
ANSI je označení standardů používaných v USA. Zkratkou ANSI C je obvykle označována starší verze jazyka C z konce 80. let 20. století. Tato norma byla později přejata i ISO. Uvidíte-li někde zkratky ANSI C, ISO C89, ISO C90, jedná se o tutéž verzi jazyka C a jeho knihoven.
Poslední významná zkratka, která vás může zajímat je POSIX jde o normu popisující unixové systémy. Funkce patřící pod tuto normu jsou zároveň součástí rozhraní unixového systému. Funkce podle standardu ISO C zároveň spadají do normy POSIX, opačně už to platit nemusí.
Pokud se dokumentace, kterou používáte odvolává na tyto normy, je pravděpodobně bezpečné ji používat. Zdroje, které normy jazyka neřeší, nepoužívejte. Nemáte u nich jistotu, co vlastně popisují.