8. Vytváření nápovědy
  1. Naše předchozí aplikace obsahovala v nabídce volby pro používání nápovědy, ale žádnou nápovědu se nám nepodařilo zobrazit. Nemáme zatím vytvořen soubor nápovědy. V této kapitole se budeme zabývat vytvářením nápovědy. Help Workshop je program, který používáme k vytváření souborů nápověd (.hlp), editování souborů projektů a obsahů nápověd a testování nápovědných souborů. Help Workshop bere informace z projektového souboru (.hpj), kombinuje je se soubory prvků nápověd (.rtf), bitovými mapami a ostatními zdroji do nápovědného souboru, který potom může být zobrazován programem WinHelp Windows (bude popsán v následující kapitole). Help Workshop je program hcw.exe.

    2. Není nutné vkládat všechny prvky nápovědy do jednoho nápovědného souboru. Např. pokud program, který dokumentujeme obsahuje modulární komponenty, pak je vhodné vytvořit samostatný nápovědný soubor pro každou komponentu. Pokud se uživatel rozhodne neinstalovat komponentu nebo přidá novou komponentu později, pak nápovědný soubor tvoří stále jednu jednotku. Jestliže přidáváme soubory k naší rodině nápovědných souborů po jejich vytvoření, pak je musíme reinicializovat. Reinicializaci nápovědného souboru provedeme příkazem
    winhelp -g filename.hlp
    kde filename.hlp je jméno nápovědného souboru, který chceme reinicializovat.
    Nyní se s vytvářením nápovědy seznámíme podrobněji. Nejprve se budeme zabývat vytvářením souborů prvků nápověd a základy jejich zápisu.
    Vytváření nápovědy zahájíme vytvořením souborů s jednotlivými prvky nápovědy. Tento soubor musí být ve formátu Rich Edit (musíme také použít příponu RTF). Otevřeme tedy nový soubor v nějakém textovém editoru, který umožňuje tento formát používat (např. MS Word; je vhodné si nejprve vyzkoušet vytvoření malého souboru nápovědy) a zapíšeme jednotlivé prvky nápovědy. Každý prvek nápovědy ukončíme pevným koncem stránky. Na začátek každého prvku připojíme potřebné poznámky pod čarou (podle následujícího popisu). Soubor s prvky nápověd uložíme.
    Identifikaci prvku nápovědy zadáváme jako poznámku pod čarou označenou znakem #. Umístíme kurzor na začátek prvku nápovědy a vložíme poznámku pod čarou #. Jméno identifikace prvku nápovědy má některá omezení: může obsahovat mezery, ale nesmí začínat nebo končit mezerou, nesmí být delší než 255 znaků a nesmí obsahovat znaky # = + @ * % !. Pokud používáme mapování, pak nesmí začínat číslicí. K umožnění sledování chyb Help Workshopem, začínáme všechny identifikace prvků, které mohou být volány z programu IDH_. Help Workshop uvede všechny nedefinované prvky, které začínají IDH_, do sekce [MAP] projektového souboru a vypíše varovaní pro prvky IDH_, které zde nejsou uvedeny. Pokud chceme použít skok na specifické místo v prvku nápovědy, pak vložíme identifikaci prvku nápovědy na toto místo.
    Pro prvek nápovědy zadáme také titulek. Umístíme kurzor na začátek prvku a zadáme poznámku pod čarou označenou $. Titulek může mít nejvýše 255 znaků.
    Prvek nápovědy můžeme také označit jako cíl ALink (vyhledávání prvků obsahujících A-klíčová slova). Umístíme kurzor na začátek prvku a vložíme poznámku pod čarou A. Jako poznámku pod čarou v tomto případě zapíšeme jedno nebo více klíčových slov, které oddělujeme středníkem. Klíčové slovo nesmí obsahovat více než 255 znaků, nesmí obsahovat znak odřádkování a mezery před a za klíčovým slovem jsou odstraněny. V klíčových slovech je rozlišována velikost písmen, ale Help Workshop předpokládá, že dvě klíčová slova, která se liší pouze velikostí písmen, jsou stejná. Help Workshop změní jedno z těchto klíčových slov tak, aby se shodovalo s druhým a vypíše varování.
    K vytvoření indexové položky pro prvek nápovědy umístíme na začátek prvku nápovědy poznámku pod čarou označenou K (makro KLink vyhledává prvky obsahující K-klíčová slova) a do poznámky zapíšeme seznam klíčových slov (mají stejná omezení jako u poznámky pod čarou A). V případě indexů lze vytvořit i druhou úroveň indexů. Provedeme to tak, že v poznámce zapíšeme klíčové slovo první úrovně indexu, které ukončíme středníkem a bezprostředně za tímto středníkem zapíšeme opět klíčové slovo první úrovně, následované čárkou nebo dvojtečkou a po mezeře zapíšeme klíčové slovo druhé úrovně indexu ukončené středníkem. Např. následující poznámka pod čarou K bude v položkách indexů zobrazena jak je uvedeno dále (červeně):
    macro; macro, library; macro, automatic; macro, complex; macro, simple
     macro
      automatic
      complex
      library
      simple
    Položky indexů jsou uvedeny v abecedním pořadí a to bez ohledu na jejich pořadí v poznámce pod čarou. Mezery před a za klíčovými slovy jsou odstraněny.
    Prvek nápovědy můžeme také zařadit do vyhledávání. Provedeme to vložením poznámky pod čarou označené +, na začátek prvku nápovědy. Jako poznámku pak zapíšeme vyhledávací kód, který nesmí obsahovat znaky # = + @ * % ! a mezer a nesmí být delší než 50 znaků. Pro použití vyhledávacích sekvencí musíme také aktivovat vyhledávací tlačítko v projektovém souboru. Help vytváří auto-vyhledávací sekvence pro prvky, které mají přidány poznámku pod čarou +, ale bez specifikace vyhledávacího kódu. Když používáme čísla ve vyhledávacích kódech, pak je vhodné používat úvodní nuly (001, 002, 003 atd.). Pokud nápovědný soubor má pouze jednu vyhledávací sekvenci, pak použijeme "auto" jako vyhledávací kód. Help Workshop automaticky vytváří prohlížecí sekvenci založenou na pořadí ve kterém prvky nápovědy jsou uvedeny v našich souborech.
    K označení prvku nápovědy k vyloučení nebo vložení do nápovědného souboru umístíme kurzor před ostatní poznámky pod čarou a vložíme poznámku pod čarou *. Zapíšeme jednu nebo více vytvářecích značek jako text poznámky. Vytvářecí značky oddělujeme středníky. V našem projektovém souboru (.hpj), pak specifikujeme, které prvky použít při vytváření. U vytvářecích značek se nerozlišuje velikost písmen. Prvky nápovědy bez vytvářecích značek jsou vždy zapojeny do vytváření a to stejně jako všechny prvky, které nejsou explicitně vyloučeny z vytváření v našem projektovém souboru.
    Pro specifikaci typu okna k zobrazení prvku umístíme kurzor na začátek prvku a vložíme poznámku pod čarou > a zapíšeme jméno typu okna jak je definován v našem projektovém souboru. Tato poznámka pod čarou specifikuje typ okna prvku nápovědy, při otevření ze stránky Index nebo Find nebo makrem ALink nebo KLink. Typy oken musí být definovány v našem projektovém souboru.
    Pro specifikaci spouštěného makra při otevření prvku nápovědy umístíme kurzor na začátek prvku nápovědy, ve kterém chceme zadané makro spouštět a vložíme poznámku pod čarou ! a jako text poznámky zapíšeme příkazy makra. Makra oddělujeme středníky a nepoužíváme odřádkování.
    Pro přidání nerolovatelné oblasti k prvku nápovědy se ujistíme, že paragraf nebo paragrafy, které chceme umístit do nerolovatelné oblasti jsou na začátku prvku nápovědy a na tyto paragrafy aplikujeme styl Keep With Next (nebo nějaký jeho ekvivalent - Svázat s následujícím). Nerolovací oblasti nelze přidat k prvkům, které budou zobrazeny ve vynořovacích oknech. Můžeme specifikovat různé barvy pozadí pro nerolovatelné a rolovatelné oblasti.
    K zabránění zalamování řádků textu umístíme kurzor někam do řádku, který nechceme zalamovat a aplikujeme styl Keep Lines Together (Svázat řádky). Pokud text paragrafu je širší než šířka okna, pak je přidán vodorovný posuvník.
    K vytvoření skoku na prvek nápovědy nebo vysvětlení hesla ve vynořovacím okně, umístíme kurzor přímo za text (nebo bitovou mapu), pro který chceme skok provést a zapíšeme identifikaci prvku na který chceme skočit (před identifikaci nezapisujeme mezeru). Vybereme textový prvek, pro který chceme provést skok a aplikujeme na něj styl dvojitého podtržení (pro skok na další prvek nápovědy) nebo styl jednoduchého podtržení (pro vysvětlení hesla). Dále vybereme následující identifikaci prvku a aplikujeme na něj styl Skryté. Pokud textový prvek končí znakem interpunkce, pak jej zahrneme do podtržení. Jinak se tento znak zobrazí až na začátku následujícího řádku. K zobrazení textového prvku v implicitní barvě textu (nezeleně), vložíme hvězdičku na začátek identifikace prvku nápovědy (zahrnujeme jej do skrytého textu). K zobrazení textového prvku v implicitní barvě textu (nezeleně) bez podtržení, vložíme znak % na začátek identifikace prvku nápovědy. K vytvoření skoku na prvek nápovědy do jiného nápovědného souboru, vložíme znak @ a jméno tohoto jiného nápovědného souboru na konec identifikace prvku nápovědy. Pro specifikace typu okna pro prvek, na který chceme skočit, vložíme na konec identifikace prvku nápovědy znak > a jméno okna.
    Pro přidání prvku, který spouští makro umístíme kurzor za text nebo odkaz na bitovou mapu a zapíšeme znak ! (bez mezery) a zapíšeme příkaz makra. Více maker oddělujeme dvojtečkou nebo středníkem. Vybereme text nebo odkaz na bitovou mapu a aplikujeme na něj styl dvojitého podtržení. Vybereme středník a příkaz makra a aplikujeme na něj styl skryté.
    Pro přidání bitové mapy k prvku nápovědy vložíme bitovou mapu přímo do souboru na místo jejího zobrazení. Jestliže chceme použít vícenásobné instance bitových map, vytvoříme spojení k jejich souboru pomocí následující syntaxe:
    {bmx filename.bmp}
    kde x specifikuje způsob zarovnávání (c - bitová mapa se bere jako znak, l - zarovnávání k levému okraji, r - zarovnávání k pravému okraji a t použité v kombinaci s některou z výše uvedenou hodnotou - bílé body bitové mapy jsou převedeny na barvu pozadí okna; může být použito pouze pro 16-ti barevné bitové mapy). Více bitových map můžeme specifikovat oddělením jejich jmen středníky.
    Pro přidání videa nebo animace k prvku nápovědy umístíme kurzor na místo, kam chceme přidat soubor multimedií a zapíšeme odkaz s následující syntaxí:
    {mci filename.ext}
    Pro konfiguraci bitové mapy na několik různých barevných palet s různým počtem barev, vytvoříme soubor bitové mapy pro každou paletu barev, umístíme kurzor na místo, kde bitová mapa má být zobrazena a vytvoříme příkaz bitové mapy, který obsahuje všechny tyto jména souborů (oddělujeme je středníky). WinHelp automaticky použije bitovou mapu, která nejvíce odpovídá nasatavení obrazovky počítače. Následuje příklad příkazu:
    {bml dog_16.bmp;dog_256.bmp;dog_mono.bmp}
  2. Po vytvoření souboru s prvky nápovědy se můžeme zabývat vytvářením projektového souboru nápovědy. Když se rozhodujeme jaký typ informací bude zobrazován v hlavním okně a jaký v sekundárním okně, pak si musíme uvědomit tato omezení:
    3. WinHelp obsahuje předdefinované okno nazvané hlavní okno, které má nabídku a řádek tlačítek. Toto hlavní okno můžeme přizpůsobit nebo vytvořit nová sekundární okna. Ve svém projektovém souboru můžeme definovat až 255 typů oken. WinHelp může zobrazit až 10 oken najednou. Můžeme přizpůsobit tyto vlastnosti okna: velikost a pozici, barvu pozadí, text titulku, řádek tlačítek, nabídky a prvky nabídek, stav udržování okna nad ostatními okny, automatická změna velikosti okna a makra spouštěná při otevření okna.
    Hlavní a sekundární okna mohou mít řádek tlačítek až s 22 tlačítky. Můžeme používat standardní množinu tlačítek nebo použít uživatelskou množinu tlačítek. K definování uživatelských tlačítek používáme makra. Tlačítka jsou přidávána na řádek tlačítek v pořadí ve kterém je specifikujeme. Tlačítka mohou obsahovat pouze text, nemohou obsahovat grafiku.
    Na rozdíl od sekundárních oken, hlavní okno může obsahovat nabídku. Můžeme použít standardní nabídky a příkazy nebo můžeme přidávat nové nabídky a prvky nabídky pomocí maker. Při volbě prvek nabídky spouští makra. Během používání nápovědy můžeme některé prvky nabídky znepřístupnit. Pro použití maker nabídky musíme být v hlavním okně. Pokud prvek nápovědy obsahuje makro, které přidává prvek k nabídce, ale prvek je zobrazen v sekundárním okně, pak makro nemá žádný efekt.
    Můžeme specifikovat makra, která jsou spouštěna, když uživatel otevře nápovědný soubor. Např. můžeme použít makra pro specifikaci volitelných tlačítek nebo prvků nabídky pro hlavní okno a zpřístupňování programů a možností mimo nápovědný systém. Můžeme také přiřadit makra k jednotlivým typům oken.
    Můžeme také vytvářet kontextově závislou nápovědu. Autoři nápovědy a vývojáři programů obvykle pracují společně při implementaci kontextově závislé nápovědy. Autoři nápovědy zapíší příslušné prvky nápovědy a vývojáři programu modifikují program k volání příslušných prvků nápovědy. Jako část této modifikace, vývojář přiřadí číselné hodnoty k prvkům pro které uživatel může požadovat informace. Potom můžeme mapovat tyto číselné hodnoty na příslušné identifikace prvků nápovědy v našem projektovém souboru. Když přiřazujeme identifikaci prvku nápovědy k senzitivnímu prvku nápovědy, pak první čtyři znaky v identifikaci prvku musí být IDH_.
    Trénovací karty jsou množina prvků nápovědy v sekundárních oknech, které mohou konfigurovat a zasílat instrukce a získávat informace od jiného programu. Toto je užitečné při seznamování s programem krok po kroku. Zda uživatel provedl krok správně může být automaticky zhodnoceno v následujícím kroku. Vývojář může použít API WinHelp ve svých programech k zasílání informací WinHelp. Autor nápovědy může použít makro TCard ve svých nápovědných souborech k zasílání informací programu.
    K vytvoření nového projektového souboru zvolíme v Help Workshopu File | New, dvojitě klikneme na Help Project, zapíšeme jméno vytvářeného projektového souboru a stiskneme OK. Když vytváříme projektový soubor, Help Workshop konfiguruje minimální nastavení nutné k vytvoření nápovědného souboru. Dříve než můžeme nápovědný soubor přeložit musíme stisknout tlačítko Files a specifikovat alespoň jeden soubor s prvky nápovědy.
    Ke specifikaci umístění souborů bitových map, stiskneme tlačítko Bitmaps a dále tlačítko Add a specifikujeme složku, která obsahuje soubory bitových map. Implicitně Help Workshop hledá soubory bitových map ve stejném adresáři ve kterém je umístěn projektový soubor a současný soubor s prvky nápověd a ve všech složkách obsahujících soubory s prvky nápověd. K odstranění složky se soubory bitových map, složku vybereme a stiskneme tlačítko Remove.
    K umožnění programu zobrazovat kontextovou nápovědu, stiskneme tlačítko Map a když chceme přidat individuální prvek pak stiskneme Add. Pokud chceme vložit hlavičkový soubor C, stiskneme Include. Když přiřazujeme identifikaci prvků ke kontextově senzitivním prvkům nápovědy, pak musíme jako první čtyři znaky v identifikaci použít IDH_. Help Workshop zajistí, aby prvky nápověd začínající těmito znaky mohl program volat. Během překladu, Help Workshop zobrazí seznam všech identifikací prvků nápověd, které jsou v našich souborech s prvky nápověd, ale nemají mapování na číselné hodnoty. Help Workshop také zobrazí seznam identifikací, které mají mapování na číselné hodnoty, ale nejsou v našich souborech s prvky nápověd. Používání konvence IDH_ nám pomáhá nalézt a řešit problémy s kontextově senzitivní nápovědou. Pokud chceme použít jinou předponu než IDH_, pak ji specifikujeme v dialogovém okně Map.
    Pro přezdívku jedné identifikace prvku na jiné, stiskneme tlačítko Alias, dále tlačítko Add a specifikujeme požadované nastavení. Přezdívky usnadňují přesměrování skoků na prvky nápověd beze změn v instancích skoků. Přezdívky jsou také užitečné, když provádíme změny, které působí na číselné hodnoty mapování (přezdívky umožňují zobrazit požadovaný prvek v nápovědném souboru beze změny kódu programu.
    Pro specifikaci titulku nápovědného souboru, stiskneme tlačítko Options a v části Help Title zapíšeme titulek. Titulek může mít až 127 znaků.
    Pro spuštění makra při kliknutí na položku indexu, stiskneme tlačítko Options, přejdeme na stránku Macros, stiskneme Add a specifikujeme požadované nastavení. Spuštění makra, když uživatel klikne na položce indexu je užitečné, pro spouštění průvodce, řady trénovacích karet nebo DLL. Klíčová slova zde přiřazena jsou zobrazena v indexech a to bez ohledu na to, zda jsou specifikována  jako K-poznámky pod čarou v prvcích nápověd. Specifikovaný titulek bude zobrazen pouze, pokud uživatel dvojitě klikne na klíčové slovo, které je spojeno s makrem a na jeden nebo více prvků nápověd. V tomto případě, klikneme na titulek v dialogovém okně Topics Found pro spuštění makra.
    Pro přidání tlačítka Browse do okna, stiskneme tlačítko Windows, přejdeme na stránku Buttons, v seznamu Window Type vybereme typ okna a ujistíme se, že v části Buttons je označeno Browse.
    Pro přiřazení souboru obsahu k nápovědnému souboru, stiskneme tlačítko Options, přejdeme na stránku Files a do části Contents File zapíšeme jméno souboru obsahu (.cnt).
    Dále se budeme zabývat přizpůsobením okna nápovědy. Pro přidání sekundárního okna, stiskneme tlačítko Windows, stiskneme Add a zapíšeme jméno sekundárního okna. Jako jméno okna nezapisujeme main. V seznamu, klikneme na jménu standardního okna, které chceme použít za základ sekundárního okna. Můžeme definovat až 255 sekundárních oken.
    Pro přizpůsobení hlavního okna nápovědy, stiskneme tlačítko Windows, stiskneme Add, zapíšeme main a stiskneme OK. Na různých stránkách specifikujeme požadované nastavení.
    K zajištění aby okno nápovědy bylo implicitně vrchním oknem, stiskneme tlačítko Windows, v seznamu Window Type vybereme okno a ujistíme se, že v části Window Attributes je označeno Keep Help Window On Top. Uživatelé mohou změnit toto nastavení kliknutím v okně nápovědy pravým tlačítkem myši a v zobrazené místní nabídce použijí volbu Keep Help On Top.
    Pro specifikaci titulku pro okno, stiskneme tlačítko Windows, v části Window Type vybereme typ okna a v části Title Bar Text zapíšeme titulek. Titulek je zobrazován na titulním řádku okna a na tlačítku řádku úloh. Pokud sekundární okno nemá titulek, ale soubor obsahu pro nápovědný soubor specifikuje titulek, pak je použit titulek ze souboru nápovědy. Když sekundární okno ani soubor obsahu nespecifikuje titulek, pak na titulním řádku není zobrazen žádný text.
    Ke specifikaci velikosti a pozice okna, stiskneme tlačítko Windows, přejdeme na stránku Position, v části Window Type vybereme typ okna a pro nastavení velikosti a pozice okna stiskneme tlačítko Auto-Sizer a provedeme požadované nastavení. Pokud chceme aby WinHelp určoval pozici okna, stiskneme Default Position. Velikost a pozici okna můžeme také nastavit manuálně v částech Left, Top, Width a Height. Když chceme velikost sekundárního okna nastavit na délku prvku, přejdeme na stránku General a ujistíme se, že je označeno Auto-Size Height (tato volba není dostupná v hlavním okně nápovědy).
    Pro specifikaci barvy pozadí okna, stiskneme tlačítko Window, přejdeme na stránku Color, v části Window Type vybereme typ okna a k výběru barvy pro nerolovatelnou a rolovatelnou oblast stiskneme tlačítko Change. Specifikovaná barva pozadí může být přepsána, pokud uživatel v místní nabídce okna nápovědy zvolí Use System Colors. Pokud použijeme transparentní bitovou mapu v rolovatelné oblasti i nerolovatelné oblasti stejného prvku nápovědy, pak transparentní oblast obou bitových map je zobrazena barvou pozadí rolovatelné oblasti.
    Pro přidání tlačítek k sekundárnímu oknu, stiskneme tlačítko Windows, přejdeme na stránku Buttons, v seznamu Window Type vybereme typ okna a ujistíme se, že v části Buttons jsou označeny požadovaná tlačítka, která chceme zobrazit. Pokud nechceme používat řádek tlačítek, pak žádné tlačítko v části Buttons nesmí být označeno.
    Pro přidání tlačítek k hlavnímu oknu nápovědy, stiskneme tlačítko Windows. Pokud je v seznamu Window Type, pak jej vybereme. Pokud zde není, pak stiskneme Add, zapišeme jméno main a stiskneme OK. Přejdeme na stránku Buttons a v části Buttons vybereme požadovaná tlačítka.
    Pro spuštění makra při otevření okna, stiskneme tlačítko Windows, přejdeme na stránku Macros, v seznamu Window Type vybereme typ okna, stiskneme Add a specifikujeme makro, které chceme spustit. K odstranění vybraného makra stiskneme tlačítko Remove. Pro specifikaci makra spouštěného při otevření nápovědného souboru, stiskneme tlačítko Config.
    Pro specifikaci implicitního prvku nápovědy pro soubor nápovědy, stiskneme tlačítko Options a v části Default Topic, zapíšeme identifikaci prvku nápovědy pro prvek, který chceme aby byl implicitní.
    Pro přidání informací o autorských právech, stiskneme tlačítko Options a v části Copyright Information, zapíšeme informace, které chceme zobrazit v dialogovém okně Version nebo když uživatel vkládá nebo tiskne text nápovědy. Můžeme specifikovat až 255 znaků pro dialogové okno Version. Pokud na konec textu zobrazovaného v dialogovém okně Version zapíšeme %date, pak Help Workshop při překladu nápovědného souboru sem vloží současné datum.
    Pro spuštění makra při otevírání nápovědného souboru, stiskneme tlačítko Config, dále stiskneme Add a specifikujeme požadované nastavení.
    Pro uložení datových souborů svázaných DLL v nápovědném souboru, stiskneme tlačítko Data Files a pro výběr datového souboru stiskneme Add. Ve jménech souborů datových DLL se rozlišuje velikost písmen. K získávání datových souborů, nápověda používá jméno souboru bez cesty.
    Pro specifikaci voleb komprese, stiskneme tlačítko Options, přejdeme na stránku Compression a specifikujeme požadované nastavení komprese. Překlad nápovědného souboru používající maximální kompresy je asi třikrát pomalejší než překlad stejného souboru bez komprese.
    K potlačení zpráv překladače, stiskneme tlačítko Options a pro skrytí poznámek se ujistíme, že není označena značka Notes. K potlačení zpráv o překladu zrušíme označení značky Progress.
    Pro uložení zpráv překladače do souboru, stiskneme tlačítko Options, přejdeme na stránku Files a v části Log File zadáme jméno souboru. Pokud chceme soubor uložit do jiné složky než je projektový soubor, pak specifikujeme cestu. Help Workshop může zobrazovat až 64 K slabik zpráv ve Windows 95 a až 1 M slabiku zpráv ve Windows NT. Při delších zprávách je můžeme uložit do souboru a zobrazit nějakým textovým editorem.
    Pro specifikaci kam ukládat dočasné soubory, stiskneme tlačítko Options, přejdeme na stránku Files a do části TMP Folder zapíšeme jméno složky, do které chceme ukládat dočasné soubory. Implicitně je použita složka specifikovaná proměnnou prostředí TEMP. Dočasné soubory jsou hlavně používány, když velikost nápovědného souboru překročí 8 M slabik.
    Pro specifikaci, které prvky vložit do vytvářeného souboru, stiskneme tlačítko Options, přejdeme na stránku Build Tags a přidáme značky pro prvky nápovědy, které mají být vloženy do nápovědného souboru. Prvky nápovědy bez vytvářecích značek jsou vždy zahrnuty do vytváření. Prvky nápovědy s vytvářecími značkami jsou zahrnuty pouze jestliže stránka Build Tags obsahuje jednu nebo více vytvářecích značek. Pokud specifikujeme vytvářecí značky v části Include nebo Exclude na stránce Build Tags, pak Help Workshop ignoruje všechny volby BUILD, které mohou být specifikovány.
    Pro generování indexového souboru pro celotextové vyhledávání, stiskneme tlačítko Options, přejdeme na stránku FTS a ujistíme se, že značka Generate Full Text Search Index je označena (a potom nastavíme další požadovaná nastavení). Při generování souborů indexů celotextového vyhledávání při překladu, musí být na stránce Compression označeny značky Maximum compression nebo Hall compression. Pokud nemáme vygenerován indexový soubor celotextového vyhledávání, pak WinHelp se dotazuje zda jej generovat, když poprvé otevřeme nápovědný soubor a přejdeme na stránku Find.
    Ke změně každého výskytu písma použitého v nápovědném souboru, stiskneme tlačítko Options, přejdeme na stránku Fonts, stiskneme Add a specifikujeme požadované nastavení. Tato procedura umožňuje změnit písmo použité v nápovědném souboru bez nutnosti reformátování textu v prvcích nápovědy v RTF souborech. Počet nahrazovaných písem není omezen.
    Pro změnu cesty ke zdrojovým souborům, když přemístíme náš projektový soubor, stiskneme tlačítko Options, přejdeme na stránku Files a pro specifikaci nové cesty stiskneme Edit. Substituce cesty není nutná, pokud všechny soubory jsou specifikovány relativně k umístění projektového souboru. Help Workshop automaticky používá relativní cesty, při přidávání souborů. Substituce cesty je užitečná, když přesouváme celý projekt na jiné místo.
    Pro specifikaci znaků, které identifikují druhou úroveň indexů, stiskneme tlačítko Options, přejdeme na stránku Sorting a do části pro specifikaci znaků oddělujících položky indexů, zapíšeme jeden nebo více znaků. Např. jestliže specifikujeme "@&%", pak řádek "display; display@configuring; keyboard; keyboard&configuring; mouse;mouse%configuring; network, configuring" bude v indexech zobrazen tímto způsobem:
    display
      configuring
     keyboard
      configuring
     mouse
      configuring
     network, configuring
    Implicitní znaky jsou čárka a dvojtečka. Libovolné znaky zde specifikované přepíší tyto implicitní znaky.
    Pro specifikaci jazyka nápovědného souboru, stiskneme tlačítko Options, přejdeme na stránku Sorting a specifikujeme požadovaný jazyk. Implicitně Help Workshop používá jazyk za základě regionálního nastavení specifikovaného v Control Panel. Pokud verze Windows nepodporuje specifikovaný jazyk, pak Help Workshop nemůže přeložit projektový soubor.
    Pro překlad souboru obsahu, označíme v nabídce File volbu Translation, otevřeme soubor obsahu (.cnt), vybereme hlavičku nebo prvek, který chceme přeložit a stisknreme Edit. Když volba Translatin je označena, pak můžeme modifikovat pouze viditelný text, který je zobrazen na stránce obsahu. Nelze modifikovat identifikaci prvku, jména souborů nebo jména oken.
  3. Dále se budeme zabývat vytvářením souboru obsahu. Soubor obsahu (.cnt) je textový soubor, který poskytuje instrukce pro stránku obsahu v dialogovém okně Help Topics a určuje zobrazování klíčových slov specifikovaných nápovědných souborů na stránkách Index a Find. Návrh tabulky obsahu provádíme specifikací:
    4. K vytvoření a editaci souboru obsahu používáme Help Workshop. Tabulka obsahu se nezobrazuje v dialogovém okně Help Topics dokud soubor obsahu neobsahuje alespoň jeden prvek, který skáče do dostupného nápovědného souboru. Přípustné skoky musí být uvedeny v souboru obsahu, když uživatel poprvé otevře přiřazený nápovědný soubor.
    Seznam klíčových slov je jeden z užitečných nástrojů, který můžeme poskytnout uživateli. V indexech můžeme také uvést synonyma, která pomáhají uživateli nalézt informaci. WinHelp také nabízí službu celotextového vyhledávání, což umožňuje uživateli prohledat celý text nápovědných souborů a nalézt požadovanou informaci. Ve většině případů, když uživatel přejde v dialogovém okně Help Topics na stránku Find poprvé, pak je zobrazen průvodce Find Setup, kde vytváříme index celotextového vyhledávání. Tento index obsahuje seznam všech slov v nápovědném souboru. Seznam indexů je také možno dodávat jako součást nápovědného souboru (soubor .fts).
    K vytvoření souboru obsahu zvolíme File | New, dvojitě klikneme na Help Contents, do části Default Filename zapíšeme jméno nápovědného souboru s většinou prvků nápovědy a do části Default Title zapíšeme text, který chceme zobrazit na titulním řádku dialogového okna Help Topics. Tento text je také zobrazován na titulním řádku oken, které nemají specifikovaný titulek v projektovém souboru. Stiskneme Add Above nebo Add Below a přidáme hlavičky a prvky, které chceme zobrazit na stránce obsahu. Pokud chceme vložit klíčová slova několika souborů na stránku Index, pak stiskneme Index Files a specifikujeme soubory, které chceme vložit.
    Pro specifikaci implicitního okna, ve kterém chceme zobrazovat prvky nápovědy, stiskneme tlačítko Edit v horním pravém rohu okna Help Workshopu a v části Default Window specifikujeme typ okna. Prvky jsou zobrazeny v implicitním okně, když je uživatel otevře ze stránek Index nebo Find, pokud není specifikováno jiné okno v poznámce pod čarou >. Prvky jsou také zobrazeny v implicitních oknech, když je uživatel otevře ze stránky obsahu, pokud položka obsahu neobsahuje specifikaci typu okna. Pokud implicitní okno není specifikováno, pak prvky jsou zobrazovány v hlavním okně nápovědy. Typ okna musí být definován v našem projektovém souboru.
    Pro přidání hlaviček na stránku obsahu, vybereme prvek nad nebo pod který chceme přidat hlavičku, stiskneme Add Above nebo Add Below a po výběru Heading zapíšeme do části Title hlavičku. Pomocí tlačítek Move Right a Move Left můžeme přiřadit až 9 úrovní hlaviček.
    Pro přidání prvku na stránku obsahu, vybereme prvek nad nebo pod který chceme přidat hlavičku, stiskneme Add Above nebo Add Below a po výběru Topic zapíšeme do části Title titulek a do části Topic ID zapíšeme identifikaci prvku (pokud prvek není v implicitním nápovědném souboru, pak do části Help File zapíšeme jméno nápovědného souboru se specifikovaným prvkem). Pokud prvek chceme zobrazit v jiném než implicitním okně, pak okno specifikujeme v části Window Type. Okno musí být definováno v projektovém souboru. Pokud nespecifikujeme informaci v Help File, pak WinHelp hledá prvek nápovědy v implicitním nápovědném souboru. Pokud nespecifikujeme informaci v části Window Type, pak WinHelp zobrazí okno v typu okna specifikovaném v implicitním nápovědném souboru. Pro přiřazení makra k prvku místo identifikace prvku zapíšeme do části Topic ID středník následovaný makrem (k oddělení více maker použijeme dvojtečku).
    Pro změnu úrovně hlavičky nebo prvku, vybereme prvek a stiskneme tlačítko Move Right nebo Move Left (jsou také přesunuty prvky nižších úrovní).
    Pro vložení dalších souborů obsahu, otevřeme hlavní soubor obsahu, klikneme na místě, kde chceme umístit informace z dalšího souboru obsahu, stiskneme Add Above nebo Add Below, vybereme volič Include a zapíšeme jméno vkládaného souboru obsahu. Pokud vložený soubor obsahu není dostupný při inicializaci nápovědného souboru, pak vložený soubor není zobrazen na stránce obsahu.
    Pro kombinaci klíčových slov z několika nápovědných souborů otevřeme soubor obsahu, stiskneme tlačítko Index Files, stiskneme Add, do části Help Title zapíšeme titulek souboru nápovědy. Titulek bude zobrazován, pokud uživatel zvolí Custom v průvodci Find Setup. Je také zobrazován v dialogovém okně Topics Found, pokud WinHelp hledá identický titulek prvku v jiném nápovědném souboru. Do části Help Filename dále zapíšeme jméno souboru nápovědy, jehož klíčová slova chceme přidat k našemu indexu. Všechny soubory nápovědy obsažené v indexech jsou prohledávány, když makro ALink nebo KLink je spuštěno.
    Pro povolení ALink a KLink skákat do ostatních nápovědných souborů, stiskneme tlačítko Link Files, stiskneme Add a pak zapíšeme jméno nápovědných souborů, které chceme prohledávat, když makro ALink nebo KLink je spuštěno. Není nutno přidávat soubory, které již máme vloženy do dialogového okna Index Files.
    Pro přidání další stránky do dialogového okna Help Topics, stiskneme Tabs a potom stiskneme Add. Do části Tab Name zapíšeme jméno, které chceme zobrazit na záložce a do části DLL Filename zapíšeme jméno souboru DLL, který poskytuje proceduru dialogu pro stránku.
  4. Dále se budeme zabývat překladem a testováním nápovědného souboru. Pro překlad nápovědného souboru stiskneme tlačítko Save and Compile.

    5. Pro překlad více než jednoho nápovědného souboru najednou, použijeme textový editor, vytvoříme ASCII textový soubor se seznamem úplných specifikací všech našich projektových souborů na samostatných řádcích. Specifikujeme projektové soubory v pořadí, ve kterém je chceme překládat. Tento soubor uložíme s příponou .hmk. Otevřeme Help Workshop a stiskneme tlačítko Compile. V části Project File zapíšeme jméno našeho .hmk souboru a stiskneme Compile.
    Pro zobrazení nápovědného souboru z Help Workshopu po překladu nápovědného souboru stiskneme tlačítko Run WinHelp a specifikujeme jméno nápovědného souboru. Pokud chceme zobrazit prvky jejichž identifikace je mapována na číselné hodnoty v našem projektovém souboru, pak zapíšeme jméno a umístění projektového souboru a stiskneme Refresh. Zobrazení nápovědy dosáhneme stiskem tlačítka View Help.
    Pro generování sestavy pro nápovědný soubor, zvolíme File | Report, do části Help Filename zapíšeme cestu a jméno nápovědného souboru, do části Output Filename zapíšeme cestu a jméno souboru do kterého chceme ukládat sestavu, v části Display vybereme typ požadované sestavy a stiskneme Report.
    K testování souboru obsahu, zvolíme Test | Contents File a zapíšeme jméno souboru, který chceme testovat. Help Workshop testuje syntax souboru a potom ověří všechny skoky na prvky specifikované v souboru obsahu (zobrazí zprávu, pokud skok nepracuje). Pokud náš soubor obsahu obsahuje vložené další soubory obsahu, pak musíme zajistit, aby pro testování byly dostupné.
    Pro simulaci volání programu API WinHelp zvolíme Test | WinHelp API, do části Help File zapíšeme úplnou specifikaci testovaného souboru, v seznamu Command vybereme příkaz, který chceme zaslat v API WinHelp, do části dole v dialogovém okně zapíšeme hodnotu, kterou chceme zaslat a stiskneme Call.
    Pro monitorování zpráv WinHelp, zvolíme View | WinHelp Messages a dále zvolíme View | Message Options a specifikujeme zprávy, která chceme zobrazit.
    Pro uzavření všech instancí WinHelp zvolíme Test | Close All Help. Toto je užitečné, pokud testujeme nápovědné soubory, protože WinHelp je spouštěn na pozadí.
  5. Pro vytvoření nápovědy pro naši aplikaci textového editoru Rich použijeme soubory s prvky nápověd Richedit.rtf, Keys.rtf a Term.rtf. Tyto soubory si můžete stáhnout. Prohlédněte si je, podívejte se také na použité poznámky pod čarou. V tomto případě použijeme již vytvořené soubory, při vytváření nápovědy v dalších aplikacích je již budeme vytvářet sami. Spustíme Help Workshop, zvolíme File | New, vybereme volbu Help Project a zadáme jméno projektového souboru (v našem případě zvolíme RichEdit, umístíme jej do adresáře, ve kterém máme projekt naší aplikace). Do projektového souboru vložíme výše uvedené tři soubory typu Rich. Provedeme to stiskem tlačítka Files a po stisku Add tyto soubory specifikujeme. Naše nápověda používá také několik souborů bitových map (jsou také mezi staženými soubory). Pokud tyto soubory máme ve stejném adresáři, jako je umístěn projektový soubor nápovědy, pak nemusíme zadávat adresář bitových map. Mohli bychom zadat ještě některé další volby (např. použití komprese u souboru nápovědy, určit tlačítka použitá v okně nápovědy), ale zatím se spokojíme pouze s tímto zadáním. Vytváření souboru nápovědy ukončíme stiskem tlačítka Save and Compile.

    6. Soubor nápovědy nyní již máme vytvořen. Potřebujeme jej ale ještě připojit k naši aplikaci. Provedeme to vložením jména nápovědného souboru do vlastnosti HelpFile objektu aplikace. Vytvoříme např. obsluhu události OnActivate hlavního formuláře s příkazy:
    Application->HelpFile = "RICHEDIT.HLP";
    RichEdit1->SetFocus();
    Nyní je již v naší aplikaci možno používat nápovědu. Podíváme-li se na příkazy, které nápovědu zobrazují, pak vidíme použití metody HelpCommand objektu aplikace. Co z nápovědy je zobrazeno určuje první parametr této metody. Při použití parametru HELP_CONTENTS je zobrazen prvek nápovědy s obsahem nápovědy (druhý parametr metody v tomto případě nemá význam). Parametr HELP_HELPONHELP určuje, že bude zobrazen obsah souboru nápovědy WinHlp32 (soubor popisující jak používat nápovědu). Druhý parametr metody v tomto případě opět nemá význam. Parametr HELP_PARTIALKEY určuje hledání prvku nápovědy podle indexů. Druhý parametr metody v tomto případě je adresa implicitního hledaného řetězce.
    Tím jsme vývoj této aplikace dokončili. Vyzkoušejte používání nápovědy.
  6. Pokuste se vytvořit pro předchozí nápovědný soubor i soubor obsahu.
  7. Vraťme se opět k popisu integrovaného ladícího prostředku. C++ Builder má některé další ladící nástroje. Dialogové okno Evaluate/Modify umožňuje zjistit současnou hodnotu proměnné a v případě potřeby tuto hodnotu modifikovat. Pokud klikneme na jménu proměnné ve zdrojovém kódu a v místní nabídce Editoru kódu zvolíme Evaluate/Modify, pak proměnná je vyhodnocena. Při volbě Run | Evaluate/Modify je nutno zadat jméno vyhodnocované proměnné. Položka Expression se používá k zadání jména proměnné nebo výrazu, který chceme vyhodnotit. Když stiskneme tlačítko Evaluate, pak zadaný výraz je vyhodnocen a výsledek zobrazen v položce Result. Pokud chceme změnit hodnotu proměnné, pak zadáme novou hodnotu do položky New Value a stiskneme tlačítko Modify. Při pokračování v práci programu je použita nová hodnota.

    8. Za běhu našeho programu můžeme prohlížet zásobník volání k zjištění pořadí volání funkcí našeho programu. Okno zásobníku volání zobrazíme volbou View | Call Stack. Toto okno zobrazuje seznam volaných funkcí v pořadí jejich volání. Nejpozději volaná funkce je uvedena na vrcholu okna. V seznamu jsou uváděny naše funkce, metody VCL a funkce obsažené v DLL Windows. Dvojitým kliknutím na jménu funkce v okně Zásobníku volání přejdeme do zdrojového kódu na tuto funkci. V případě funkce z DLL Windows, okno Zásobníku volání obsahuje adresu a jméno DLL. Při dvojitém kliknutí na takovéto funkci je zobrazeno okno CPU.
    Okno CPU umožňuje prohlížet náš program na úrovni asembleru. K zobrazení okna CPU zvolíme View | CPU. Tímto oknem se zatím nebudeme zabývat. Příkaz Goto Address je také nástroj ladění pro pokročilé. Když náš program skončí chybou, pak součástí chybové zprávy je adresa, na které k chybě došlo. Tímto příkazem se můžeme pokusit nalézt místo ve zdrojovém kódu, kde chyba nastala. Pokud chyba vznikla v našem kódu, pak kurzor je umístěn na řádek, který chybu způsobil. Pokud chyba vznikla mimo náš kód, je zobrazena zpráva, že adresu není možno nalézt.
  8. Krokování našeho kódu je nejzákladnější ladící operace. Ladící prostředek má dvě operace krokování: Step over a Trace Into. Step Over provede řádek zdrojového kódu a zastaví se na následujícím řádku. Tzn. že je proveden současný řádek a funkce, které jsou na tomto řádku volány jsou provedeny plnou rychlostí. Příkaz Trace Into umožňuje trasování provádět i uvnitř volaných funkcí. Při krokování (trasování) našeho programu lze používat další ladící techniky. Necháme provést následující řádek a podíváme se jak se změnily hodnoty proměnných, změníme hodnotu některé proměnné, případně provedeme jinou ladící operaci a provedeme další řádek.

    9. Dalším ladícím příkazem je Trace To Next Source Line. Tento příkaz není používán často. Má význam u zpětně volaných funkcí (funkce Windows volá některou z našich funkcí k provedení nějaké akce). Pokud prováděný řádek je volání funkce API, která používá zpětně volanou funkci, pak příkazem Trace To Next Source Line přejdeme na první řádek zpětně volané funkce.
  9. Ladění DLL se podobá ladění spustitelného souboru (např. do DLL umístíme body přerušení). Při ladění DLL vytvoříme testovací aplikaci a spustíme ji pod ladícím prostředkem. Někdy ale potřebujeme ladit DLL pro použití ze spustitelného souboru vytvořeného v jiném vývojovém prostředí. Např. můžeme vytvářet DLL, kterou budeme volat z aplikace Visual Basicu. Visual Basic ale nespustíme pod ladícím prostředkem C++ Builderu. Tuto situaci lze vyřešit tak, že řekneme C++ Builderu aby aplikaci Visual Basicu spustil jako hostitelskou aplikaci. To zadáme v dialogovém okně zobrazeném po volbě Run | Parameters. Do části Host Application zapíšeme specifikaci EXE souboru hostitelské aplikace, stiskneme tlačítko Load a hostitelská aplikace je spuštěna. Po spuštění hostitelské aplikace, můžeme ladit naši DLL stejně jako při použití testovací aplikace. Do DLL umístíme body přerušení a začneme s laděním.
  10. Deník událostí (Event Log) je speciální soubor, který obsahuje diagnostické zprávy (zprávy generované C++ Builderem, naší aplikací a někdy i samotným Windows). Např. je zde uvedeno, které moduly byly zavedeny, zda obsahují ladící informace, kdy byla naše aplikace spuštěna, kdy byla zastavena, kdy byl dosažen bod přerušení apod. K zobrazení Deníku událostí zvolíme View | Event Log. Deník událostí má místní nabídku, která umožňuje vyprázdnit deník, uložit jej do souboru nebo přidat komentáře k deníku. Je zde také volba Options, která umožňuje přizpůsobit Deník podle našich potřeb. Do Deníku můžeme zapisovat své vlastní zprávy pomocí funkce API OutputDebugString (má jeden parametr, kterým je text zprávy).
  11. Okno Modulového pohledu zobrazuje právě zavedené moduly, zdrojové soubory připojené k těmto modulům a symboly (funkce a proměnné) exportované z těchto modulů. Toto okno zobrazíme volbou View | Modules. Tímto oknem se nebudeme podrobněji zabývat.
  12. Když se program pokusí o zápis do paměti, kterou nevlastní, pak Windows zobrazí chybovou zprávu Access Violation. Následuje popis některých situací, které tuto chybu mohou způsobit. Jedním z důvodů vzniku této situace je použití neinicializovaného ukazatele. Neinicializovaný ukazatel obsahuje náhodná data. V lepším případě ukazuje mimo náš program a jeho použití je zachyceno touto chybovou zprávou. V horším případě ukazuje někam do našeho programu a způsobí různé nedefinované chyby. Z tohoto důvodu je vhodné ukazateli vždy po vytvoření přiřadit nějakou rozumnou hodnotu nebo alespoň NULL. Při použití ukazatele s hodnotou NULL, se program zastaví a ve zdrojovém kódu je označen řádek, který obsahuje použití tohoto ukazatele.

    13. Obdobná situace nastává, když zrušíme objekt na který ukazatel ukazuje. Je tedy vhodné po zrušení objektu nastavit ukazatel na tento objekt na NULL.
    Překročení horní meze pole také může způsobit tento problém. V některých případech si pouze přepíšeme nějaké informace uložené za polem a chyba se projeví později (špatně se hledá). V jiných případech je vypsána chybová zpráva. Je tedy vhodné na tuto situaci dávat dobrý pozor.
  13. Volby ladícího prostředku lze nastavovat na dvou úrovních, na úrovni projektu a na úrovni prostředí. S projektovými ladícími volbami jsme se již seznámili. Ladící volby prostředí nastavujeme na stránce Debugger dialogového okna zobrazeného po volbě Tools | Environment Options. Značka Integrated Debugging určuje zda je povoleno použití integrovaného ladícího prostředku. V části General jsou čtyři značky. Značka Map TD32 keystrokes on run určuje zda Editor kódu má používat mapování kláves použité v samostatném ladícím prostředku. Značka Mark buffers read-only on run nastavuje paměť Editoru kódu pouze na čtení, při spuštění programu pod ladícím prostředkem. Značka Inspectors stay on top určuje zda okno Inspektora ladění bude zobrazeno stále nad Editorem kódu. Značka Rearrange editor local menu on run změní vzhled místní nabídky Editoru kódu, při spuštění programu pod ladícím prostředkem. Sekce Event Log umožňuje nastavovat volby pro Deník událostí (je možno určit maximální počet zpráv a typy zpráv ukládané do deníku).

    14. Část Exceptions určuje, které výjimky budou zpracovány ladícím prostředkem a které budou zpracovány uživatelským programem.
    Tím je popis integrovaného ladícího prostředku dokončen.
8. Vytváření nápovědy