Heddley v1.1

aneb Vytvořte si nápovědu!

Mnozí z vás jednou vytvoří svůj vlastní program. Budete chtít, aby ho používali také ostatní, aby mu rozuměli - proto k němu napíšete nápovědu. Dnes už obvykle nápověda není obyčejný textový soubor, který se prohlíží pomocí primitivního prohlížeče typu PPMORE. Hitem se stala interaktivní nápověda ve formátu AmigaGuide(R).

Proč interaktivní nápověda?
Řekněme, že čtenáři popisujete způsob, jak vyplnit jednotlivé rámečky v nějakém requesteru ve vašem programu. Ale čtenář vaší nápovědy možná neví, co je to requester, k čemu slouží a jaké má ovládací prvky. Snadná pomoc: ze slova requester vytvořte tlačítko, po jehož stisknutí se objeví nová stránka nápovědy, obsahující všechny informace o requesterech, které by mohl váš čtenář potřebovat. Stiskem dalšího tlačítka na této stránce se vrátí původní stránka.
Toto je podstata interaktivní nápovědy: komunikace s uživatelem. Interaktivita samozřejmě není možná u obyčejných textů. Proto byl právě vymyšlen formát AmigaGuide(R) a vytvořena knihovna AmigaGuide.library, umožňující jeho praktické využití v různých programech. Tato knihovna je součástí operačního systému 3.0 a vyšších, lze také získat verzi pro nižší verze OS.

Formát nápovědy
Soubor s nápovědou může obsahovat informace o verzi nápovědy (za příkazem @$VER), autorovi (@author), o copyrightu (příkaz @(c)) a různé poznámky (@remark). Tak například první verze souboru nápovědy, kterou nějakému programu vytvoří Lenka Eslerová v roce 1995 v programu Heddley, může začínat následujícími řádky:

@$VER: 1.0 @author "Lenka Eslerová"
@(c) "1995" @remark Created with Heddley v1.1 (c) Edd Dumbill 1994

Základním prvkem struktury souboru jsou tak zvané uzly. Uzlem budeme rozumět ucelenou část textu týkající se obvykle jednoho tématu, která začíná příkazem @node <"jméno uzlu" "titulek"> a končí @endnode. Jednotlivé uzly mohou obsahovat různý text, odkazy na jiné uzly, mohou mít definovanou nadřazený uzel a uzly předchozí a následující. Každý uzel má také své jméno a titulek.

Význam vlastností uzlu
Jméno uzlu slouží k tomu, aby bylo možné se na text tohoto uzlu odkazovat. Nechť vaše nápověda obsahuje například text "...a v requesteru stiskněte gadget...". Chcete přitom, aby bylo slovo "gadget" ve tvaru tlačítka, a po kliknutí na toto tlačítko se objeví informace o tom, co je to gadget, která je obsažena v uzlu pojmenovaném, "_Gadget". Příslušný text uzlu o ovládání programu pak bude vypadat například takto:

@node "requesters" "Ovládání programu" ... a v requesteru stiskněte @{"gadget" link , "_Gadget" 13} ... @endnode

První text ve složených závorkách ohraničený uvozovkami je text, který bude vypsán na tlačítku. Příkaz "link" znamená "připoj"; zde se po stisku tlačítka má objevit obsah uzlu "_Gadget", parametr 13 oznamuje, že v okně má být text uzlu viditelný od 13. řádku. Tak se lze odkázat i na nějaké konkrétní místo v uzlu.
Titulek uzlu je text, který se při zobrazování textu daného uzlu vypisuje na liště okna nápovědy.
Nadřazený uzel vám dovoluje definovat, na který uzel se má přejít, pokud v prohlížeči nápovědy stisknete tlačítko Contents (obsah). Například k uzlu, jenž popisuje příkaz Tiskni z menu Soubory v nějakém textovém editoru, by bylo vhodné jako nadřazený uzel definovat ten, který popisuje menu Soubory jako celek. Příslušný řádek (měl by následovat hned za příkazem @node Tiskni) bude vypadat takto:

@toc "Menu Soubory"

Naopak by bylo vhodné, aby uzel popisující menu Soubory obsahoval několik tlačítek pro jednotlivé příkazy, které se v tomto menu nacházejí (samozřejmě s příslušnými odkazy).
Prohlížeč nápovědy kromě skoků pomocí odkazů umožňuje prohlížení nápovědy po uzlech tak, jak jdou za sebou. Normálně se přitom prohlížejí v tom pořadí, v kterém jste je zapsali do souboru s nápovědou. Toto pořadí však můžete změnit nadefinováním předchozího uzlu (příkazem @prev "jméno uzlu") a uzlu následujícího (@next "uzel").
Tyto příkazy tedy slouží k úplnému popsání struktury souboru s nápovědou. Formát AmigaGuide vám však také dovoluje formátování textu jednotlivých uzlů pomocí níže uvedených příkazů. Tyto příkazy ale mají efekt pouze pro OS 3.0 a vyšší. U nižších verzí se zobrazuje pouze prostý text, některé verze nahrazují změnu stylu písma svislou bílou linkou.
Lze využívat různé styly písma: příkaz @{b} zapíná tučné písmo, @{i} zapíná kurzívu, @{u} zapíná podtržené písmo, @{ub} vypíná tučné písmo atd.
Nastavit můžete také barvu popředí a pozadí. Tak například příkaz @{fg shine} nastavuje pro popředí následujícího textu tu barvu, kterou máte ve Workbenchi zvolenou jako "shine". Příkazem @{fg text} se vrací běžná barva textu.
Jak vidíte, tento formát vám dovolí napsání velmi přehledné nápovědy. Jestliže jste si dobře prohlédli způsob zápisu jednotlivých příkazů, je vám již určitě jasné, že budete-li chtít soubor s nápovědou ve formátu AmigaGuide vytvořit přímo, ručně, v některém textovém editoru, dá vám to spoustu práce. A proto je zde program Heddley, který vám většinu této práce ušetří (texty uzlů za vás ale samozřejmě nenapíše).

Heddley v1.1
Autorem tohoto programu je Edd Dumbill, verze 1.18, o které zde bude řeč, byla vytvořena v roce 1994; jde o sharewarový produkt s registračním poplatkem 25 DM.
Pro provozování programu potřebujete KS 2.04 nebo vyšší a AmigaGuide.library V34+ (pro interní nápovědu a funkci Test database; jinak se bez ní obejdete). Doporučuje se procesor alespoň 68020, neboť s klasickou 68000 se dočkáte tempa splašeného šnečka.
Heddley otevírá své okno na obrazovce Workbenche. V horní a dolní části okna najdete několik ovládacích tlačítek, hlavní část zabírá seznam uzlů v dokumentu. Práci s programem nejspíše zahájíte stiskem tlačítka Load (pro úpravy již existujícího souboru s nápovědou) nebo New (pro vytvoření nového souboru). Zabývejme se vytvořením úplně nového souboru.
Po stisku tlačítka New se v seznamu uzlů objeví jediný uzel Main. Tento uzel je povinný v každém souboru s nápovědou, a jeho obsah se objevuje při prohlížení jako první. Abychom mohli dobře uspořádat strukturu souboru s nápovědou, vytvoříme si nejprve všechny uzly, které budeme potřebovat (zatím prázdné) a propojíme je. Příslušné texty doplníme později. Jeden nový uzel připojíme příkazem Add (viz spodní tlačítka). Objeví se na konci seznamu (zde: za uzlem Main), zatím je pojmenovaný "Document_0". Klikneme na jeho řádek, a pak ve spodní řadě tlačítek stiskneme Attrib. Objeví se okno, v němž lze editovat atributy (vlastnosti) tohoto uzlu.
V horní části okna atributů najdeme dva textové rámečky Doc ID (identifikátor uzlu) obsahuje jméno uzlu; místo stávajícího jména "Document_0" sem vepíšeme své vlastní pojmenování nového uzlu. Do rámečku Title (titulek) zadáme titulek, který se bude objevovat na liště okna, viz výše. Následují rámečky pro určení uzlu nadřazeného, následujícího a předchozího. Do těchto rámečků nelze zapisovat přímo: stiskem tlačítka umístěného vlevo od příslušného rámečku však vyvoláme seznam všech existujících uzlů a požadovaný vybereme dvojitým kliknutím. Editaci atributů ukončíme tlačítkem OK.
Pokud dodatečně zjistíme, že některý z připravených uzlů nebudeme potřebovat, smažeme jej tlačítkem Delete.
Obvykle není nutné definovat předchozí a následující uzel zůstanou-li příslušné údaje nedefinované, prohlížeč bere pořadí uzlů tak, jak za sebou následují v souboru. Proto také přidáváme uzly v nějakém logickém pořadí, což nám mimo jiné usnadní orientaci, bude-li seznam uzlů delší. Může se však stát, že na některý uzel zapomeneme; jestliže jej přidáme později, bude v seznamu umístěn na nevhodném místě. Jeho umístění snadno změníme pomocí tlačítek Up a Dn, kterými lze vybraný uzel posunovat v seznamu vpřed či vzad.
Předpokládejme, že máme strukturu souboru již nadefinovanou. Nyní musíme vepsat texty jednotlivých uzlů. Postup si ukážeme například na textu uzlu Main.
Označíme tento uzel jako aktuálně zpracovávaný tím, že klikneme na příslušný řádek v seznamu uzlů. Mezi spodními tlačítky stiskneme Edit. Objeví se nové okno s textem uzlu zformátovaným tak, jak by se ve stávajícím stavu jevil v nápovědě. Nyní v menu zvolíme příkaz Edit text. Tím se text aktuálního uzlu včetně příkazů přenese do připojeného editoru (jestliže si nenastavíte jiný editor, volá se standardně Ed, který se dodává s Workbenchem). Náš uzel Main je dosud prázdný, můžeme tedy veškerý jeho text vytvořit zde, nebo si je[ předem připravit v nějakém jiném editoru a pouze jej nahrát příkazem Load New Text.
V připojeném editoru můžeme text libovolně editovat; je však zbytečné vepisovat jakékoliv příkazy (viz dále). Jsme-li spokojeni, zvolíme příkaz Uložit a skončit (nebo ekvivalent, závisí na konkrétním editoru). Změny se okamžitě projeví na vzhledu textu v okně s obsahem aktuálního uzlu.
Nyní můžeme přistoupit k úpravám. Označíme text, jehož styl chceme změnit a v menu Buttons zvolíme položku Apply text style (aplikuj styl textu, lze také kombinací Amiga - S); v oblevivším se okně si zvolíme kromě stylu (tučné písmo, podtržené, kurzíva) také barvu popředí a pozadí. Účinek všech změn ihned vidíme!!
Chceme-li vytvořit odkaz, označíme text, který má být na tlačítku, a zvolíme v menu Buttons příkaz Make into button (vyrob tlačítko; lze rovněž klávesami Amiga - M). Objeví se requester pro editaci tlačítka, v němž najdeme následující položky: V prvním rámečku je pro naši orientaci uveden text, který bude umístěn na zpracovávaném tlačítku (je to ten text, který jsme označili).
Cyklovací gadget But. Type (typ tlačítka) určuje typ akce, která se provede při stisku tlačítka v nápovědě: tlačítku lze takto přiřadit vnitřní odkaz (v rámci zpracovávaného souboru, to je nejčastější varianta) nebo vnější odkaz (do jiného souboru), ARexxový script nebo příkaz, příkaz Amiga DOSu (ten se případně vepíše do rámečku Command), nebo toto tlačítko může sloužit k ukončení prohlížení nápovědy. Chceme-li tlačítko využít k odkazům, je nutné jméno uzlu, na nějž bude odkazovat, vepsat do rámečku Document, nebo tento uzel vybrat v seznamu, který se obleví po stisku tlačítka Choose Doc (vyber uzel). Někdy nám nestačí specifikovat odkazovaný uzel, chceme také určit, od kterého řádku se má v okně objevit (zvláště pokud jsou jednotlivé uzly rozsáhlejší). Potom číslo příslušného řádku vepíšeme do rámečku Line #. Budeme-li si přát, aby se po stisku tlačítka pro odkazovaný uzel otevřelo nové okno, zatrhneme položku New wnd.
Editaci tlačítka ukončíme stiskem Okay. Pokud nyní zjistíme, že takové tlačítko jsme vlastně vůbec nechtěli vytvořit nebo jsme jej vytvořili špatně (například mělo mít text "obrazovka", ale počáteční "o" nám nějak "vypadlo"), můžeme vytvořené tlačítko smazat: v menu Buttons zvolíme příkaz Delete button a klikneme na tlačítko, jež chceme odstranit. Program požádá o potvrzení a tlačítko smaže. Takto lze zrušit libovolný počet tlačítek. Režim mazání zrušíme opětovnou volbou téhož příkazu.
Text uzlu již máme hotový, pěkně zformátovaný, všechny odkazy nadefinované. Editaci aktuálního uzlu tedy ukončíme příkazem Exit v menu Document nebo jednoduše kliknutím na zavírací gadget okna s textem uzlu.
Tímto podle mého názoru snadným a přehlednym způsobem upravíme všechny uzly v dokumentu. Zbývá provést závěrečné úpravy, které budou korunovat naše dílo. Stiskneme tlačítko Info v horní řadě. Objeví se okno pro editaci atributů celé databáze.
Pomocí tlačítka Help můžeme nadefinovat uzel s nápovědou pro používání AmigaGuide. Jde o text, který se objeví, pokud uživatel během práce s nápovědou stiskne klávesu Help nebo stejnojmenné tlačítko v prohlížeči.
Do následujících rámečků vepište informace o verzi, autoru nápovědy (to jste vy) a copyrightu (obvykle rok vytvoření nápovědy).
Zatržením rámečku Wrap můžete prohlížeči nařídit aby text na konci řádku automaticky zalamoval, a v rámečku Font můžete určit sadu písma, kterou se má vaše nápověda zobrazovat. Tyto příkazy však mají význam pouze pro OS 3.0 a vyšší.
Hotovou databázi uložíme stiskem tlačítka Save v horní řadě.

Preference
Pracujeme-li s nějakým programem častěji, bude nás zajímat nastavení preferencí. Zde stačí v hlavním menu zvolit příkaz Prefs... V requesteru si pak můžeme nastavit barvy, které bude Heddley používat pro text a pozadí, font a velikost, kterým bude naše texty zobrazovat, určíme text, se kterým má spolupracovat, a požadovanou šířku textu (na tuto šířku bude program všechny texty zalamovat, obvykle se nastavuje 76 znaků).

Testování
Pravděpodobně si během práce budete chtít zkontrolovat aktuální stav nápovědy. Nemusíte kvůli tomu spouštět prohlížeč nápovědy, stačí zvolit příkaz "Test database" v hlavním menu. Program vám nabídne nápovědu v přesně stejném stavu, jak byste ji viděli v prohlížeči.

Závěrem
Na závěr ještě pár argumentů "pro" Pokud máte vlastní zkušenosti s vytvářením AmigaGuide nápovědy a pozorně jste četli tento článek, dáte mi asi za pravdu, že Heddley je program velmi užitečný. Pro ty, kdo stále ještě pochybují, mám přichystané další argumenty a shrnutí:
- program umí automaticky vytvořit rejstřík pojmů
- znovu připomínám užitečnou funkci Test database, která vám již během práce umožní zkontrolovat výsledek
- Heddley má vlastní on-line nápovědu (samozřejmě ve formátu AmigaGuide)
- kromě ukládání ve formátu AmigaGuide lze výsledek také exportovat ve formátech ASCII, ANSI a HTML (poslední formát se používá například pro AMosaic, jistě ho znají všichni, kdo už někdy četli interaktivní časopisy na Internetu)
- Heddley podporuje formátování textu a nastavení barev (od OS 3.0)
- spolupracuje s vaším oblíbeným editorem
- vzhledem k narůstající oblibě editoru GoldED a jeho nesporné vhodnosti pro podobné účely se s programem Heddley dodává několik ARexxových maker pro další usnadnění spolupráce GoldEDu a Heddley.
S programem mám vlastní vynikající zkušenosti, v této rané verzi jsem zatím narazila pouze na jediný drobný problém: Heddley se neumí správně vyrovnat s "křížením" tlačítka a například tučného písma - je ale pravdou, že podobné kombinace se snad ani nikde nevyskytují. Doporučuji všem tvůrcům, aby se s tímto "hitem" co nejdříve seznámili. Odmítnout lze snad jen slovy: "Heddley? Já mám času dost..."

Vytlačiť článok

Pozn.: články boli naskenované ako text a preto obsahujú aj zopár chýb. Taktiež neručíme za zdrojové kódy (Asm, C, Arexx, AmigaGuide, Html) a odkazy na web. Dúfame, že napriek tomu vám táto databáza dobre poslúži.

Žiadna časť nesmie byť reprodukovaná alebo inak šírená bez písomného povolenia vydavatela © ATLANTIDA Publishing

AMIGA REVIEW

ATLANTIDA NEWS