Skript slouží k úpravě Template souboru, podle kterého vytváří GgStat statistiky do profilu. Skript sice zjednodušuje úpravu Template souboru, ale nutnost něco o tom vědět zůstává. I v tomto však skript práci usnadňuje, protože prostým kliknutím zobrazuje ukázkový příklad nebo stručné vysvětlení příkazů či parametrů.

Plugin je v beta verzi, zatím má problémy s uložením některých nastavení v inicializační části. Zdá se, že není příliš zajmu o jeho využití, tak jsem jeho dokončení odložil na dobu, kdy nebude co jiného na práci.

Plugin to edit the Templates, under which creates GgStat statistics to the profile. The plugin simplifies editing the Template file, but need something know about it remains. In this work, however, the script makes it easier, simply because clicking displays a example, or a brief explanation of commands or parameters.

The plugin is beta version and has issues with saving some settings in the initialization section. It seems that not much interest in its use, so I postponed the completion of his time when not what else to do.

• gord, gord [at] nekde [dot] cz

• Diskuze o tomto skriptu se nachází na stránkách Geocaching.cz.

Modifikace textového Template souboru, který používá GgStat pro generovaní statistiky, je pro mnoho uživatelů zvyklých na klikací windowsí programy příliš komplikovaná a nepřehledná. Množství příkazů, rozmanitost parametrů a vazby mezi některými příkazy jen přispívají ke složitosti - i když zároveň poskytují obrovské možnosti v tvorbě své vlastní a jedinečné statistiky.

Asi není vhodné tímto nástrojem vytvářet Template soubor úplně z nuly, protože musí obsahovat řadu nastavení, což zatím není automaticky vygenerováno (možná někdy v budoucnu). Skript je opravdu určen k úpravě jiného Template souboru nebo jiných souborů.

Dlouho jsem váhal, zda něco takového vůbec dělat - variabilita Template souboru mě od toho dlouho odrazovala. Ovšem četné dotazy uživatelů na fóru ukazovaly, že mnoho lidí nechápe ani princip, a to mě postupně přesvědčilo, abych se do toho vrhnul.

Neříkám, že pluginem jde upravit úplně všechno a tak, jako při úpravě textového souboru. To určitě možné není a nikdy ani nebude. Mým cílem bylo umožnit většinu změn udělat klikací metodou a relativně pohodlně. V tom nejhorším případě skript uživateli alespoň pomůže najít ten správný příkaz. Stačí zvolit správnou oblast, z které má příkaz být (tabulka, graf, mapa, …) a pak vybrat mezi nabízenými příkazy.

Výsledkem mého snažení je skript, který se po svém spuštění pokusí najít hlavní Template soubor. Umístění a jméno tohoto souboru zjištuje z konfigurace Autostatu. Pokud soubor najde:

• načte jej a načte i všechny do něj vnořené soubory se šablonami
• analyzuje jednotlivé příkazy, zkontroluje jejich parametry
• pokusí se příkazy přeskupit tak, aby byly u sebe ty, které k sobě funkčně patří (vytvoří skupiny - viz níže)
• vyčlení některé příkazy nebo skupiny příkazů, které dělají největší problémy, a umožní jejich pohodlnější úpravu tak, aby byl uživatel co možná nejvíce oproštěn od znalosti správné syntaxe (doplnění řádků do tabulky zajímavých čísel, úprava barev, definice TAGů pro použití v tabulkách)
• nabídne načtenou šablonu (resp. příkazy všech souborů, s kterými šablona pracuje) k úpravě v jakémsi poloklikacím režimu

Téměř každý prvek formulářů je opatřen tooltipem (bublinou), které zobrazuje nápovědu, vysvětlivky nebo podrobnější informace o prvku. Uznávám, že první použití může vypadat poněkud nepřehledně, ale neměl jsem jiný nápad jak se se složitostí konfigurace vypořádat. Klidně mi pošlete připomínky, třeba je někdy zapracuji.

Základní okno formuláře je rozděleno do několika částí:

1. nahoře je část věnovaná souborům; vlevo je cesta a jméno hlavního Template souboru (šablony) a vpravo seznam všech souborů, které byly načteny. “Bublina” tohoto seznamu informuje mimo jiné o tom, kterým příkazem byl aktuálně vybraný soubor použit. Pokud je v některém ze souborů neuložená změna, je to indikováno malým vykřičníkem
2. záložky pro definici/úpravu barevných profilů, definici/úpravu TAGů a definici/úpravu doplňkových řádků do tabulky zajímavých čísel (vždy jsou dostupné jen záložky, které mají smysl)
3. hlavní a největší část formuláře je rozdělena do dvou zeznamů - vlevo seznam s příkazy použitými (šablona) a vpravo s použitelnými
4. nad seznamem možných příkazů je seznam oblastí, do kterých jsou příkazy rozděleny pro snadnější vyhledávání. Některé příkazy jsou zařazeny do více oblastí
5. při úpravé parametrů příkazu je hlavní část nahrazena seznamem možných parametrů a prvkem pro nastavení hodnoty vybraného parametru
6. oba hlavní seznamy jsou odděleny funkčními tlačítky pro úpravu příkazů
7. pod seznamy jsou zaškrtávací tlačítka pro změnu zobrazení a tlačítko pro zobrazení příkladu použití příkazu ve webovém prohlížeči

Uživatel si může přizpůsobit zobrazení šablony tak, aby v daný okamžik vyhovovalo jeho potřebě. Při zobrazení šablony může kdykoli:

1. potlačit zobrazení inicializační části Template souboru
2. potlačit zobrazení komentářů
3. sbalit nebo rozbalit vybranou skupinu příkazů (případně všechny skupiny najednou)
4. skočit na první příkaz vybraného souboru
5. identifikovat soubor, z kterého vybraný příkaz pochází

Vlastní ovládání hlavního okna formuláře:

1. kliknutím na soubor v seznamu souborů přeskočí kurzor v Template na první zobrazený příkaz z tohoto souboru. Pokud šablona neobsahuje žádný zobrazený příkaz, je o tom uživatel informován
2. kliknutim na příkaz v šabloně se naopak přesune kurzor v seznamu souborů na ten soubor, který obsahuje příslušný příkaz
3. dvojklik na příkazu v šabloně způsobí rozbalení skupiny, je-li to možné, nebo úpravu parametrů příkazu
4. pravé myšítko v šabloně zobrazuje detaily (pro většinu uživatelů možná až moc podrobné) o právě označeném příkazu

V seznamu s příkazy šablony souboru jsou zvýrazněny ty příkazy, jejichž parametry nejsou v souladu s jejich definicí resp. dokumentací k programu GgStat. Ke kontrole parametrů dochází při načtení souboru a pak při každé úpravě jednotlivého příkazu.

Text v seznamech často přesahuje pravou hranici seznamu. Nenašel jsem způsob, jak seznamu přidat vodorovné rolovátko, tak jsem alespoň umožnil zvětšování hlavního okna. Jeho velikosti se pak přizpůsobují i šířky seznamů a stane se čitelným větší část textu v řádku.

Úprava šablony je hlavním účelem skriptu. Při úpravě příkazů skript pomáhá s nastavením parametrů - určením počtu a typu, a tam, kde je to možné, nabídne na výběr z povolených možností. Po zadání parametrů ještě provede hrubou kontrolou zadaných hodnot.

Skript se pokouší některé detaily před uživatelem skrýt nebo přinejmenším zjednodušit nastavení zejména tím, že:

1. barvy definuje výběrem barvy a ne zadáním RGB složek, definuje barevné profily a uživatel jednoduše klikáním přepíná mezi nimi
2. sloučí všechny příkazy pro definici TAGu do jediného pseudopříkazu a tam, kde má být TAG použit, si uživatel jednoduše vyberte ze seznamu definovaných TAGů
3. sloučí všechny příkazy pro přidávání řádků do tabulky zajímavých čísel pod jediné jméno řádku a uživatel jen seřadí v jakém pořadí mají být řádky přidany
4. seskupí příkazy pro modifikaci tabulek, grafů a map (nadpis, šířky, počty zobrazených řádků, řádky pod tabulkou, …) tak, že je zřejmé co k čemu patří a co co ovlivňuje. K takové skupině nedovolí přidat příkaz, který tam nepatří

Jsou ale věci, které uživatel při úpravě prostě musí znát. Proto je u každého příkazu zobrazen jeho krátký popis a pokud je dostupný ukázkový příklad v dokumentaci GgStatu, tak jej umožní zobrazit jednoduchým kliknutím na příslušné tlačítko ve formuláři (ikonka s okem vpravo dole pod seznamem možných příkazů).

Tooltipy (bubliny zobrazené na jednotlivých prvcích formuláře, zejména u seznamů) poskytují další podrobnosti o vybrané položce šablony (příkazu). Nedejte se zmást tím, že některé informace jsou pro vás třeba nesrozumitelné . Primárně mi sloužili k ladění a myslím, že se budou hodit při hlášení chyb. Vzhledem ke komplikovanosti textových parametrů nepředpokládám, že by počáteční verze skriptu pracovala vždy správně.

K úpravě příkazů slouží tlačítka mezi oběma seznamy a umožňují:

1. přidání příkazu (kopie příkazu z pravého seznamu za aktuální příkaz v šabloně)
2. vymazání aktuálního příkazu v šaboně
3. přesun aktuálního příkazu v rámci šablony o příkaz dolů nebo nahoru. Při této změně je zohledněn i přechod mezi soubory či přesouvání příkazu přes bloky příkazů
4. úprava příkazů většinou spočívá v přechodu na stránku s parametry příkazu, kde se po zvolení příslušného parametru vyvolá oditační pole nebo se zobrazí seznam po výběr z daných možností
5. některé příkazy lze upravovat jen zprostředkovaně úpravou celého bloku (TAGy, barvy) na samostatné záložce. Výsledek takové úpravy může být později použit jako parametr jiného příkazu

Hodně jsem se snažil zjednodušit nastavení parametrů všech příkazů, ale nejsem všemocný. Již tak děsivou variabilitu textové konfigurace rozšiřují všemožné pluginy do GgStatu a musel bych být Pýthie, abych věděl, co kdy bude který plugin umožňovat. Pluginy mohou vracet GgStatu prakticky cokoli od hodnot přes konfigurační příkazy až po výkonné prezentační příkazy a mohou i prezentaci přímo produkovat, aniž by se o ni GgStat dozvěděl.

Pokud tedy plugin vrací nějaké nastavení (definici proměnné příkazem SETVAR, nastavení šířky a podobně), skript se nemá šanci k takové hodnotě dostat a spravně ji použít, protože není zaznamenaná v Template souboru. To může přinášet potíže, jejichž vyvrcholením může být až nemožnost použít nějakou proměnnou jako parametr příkazu. Ponechal jsem proto ve sktiptu jakousi nouzovou cestu, která by mohla pomoci:

1. dočasně příkaz zapoznámkujte
2. řádek upravte jako text
3. příkaz opět povolte (je možné, že bude hlášena nějaká chyba, ale co jiného s tím nadělám)

Nebo v případě hodnot vracených pluginem můžete příkazem SETVAR vytvořit stejnou proměnnou s libovolnou hodnotou a příkaz zařadit před volání pluginu. Plugin pak hodnotu přepíse. Ovšem příkaz SETVAR zajistí, že skript zná jméno proměnné a může s ní pracovat.

K takové potřebě by mělo docházet opravdu jen minimálně, je to jakási daň za to, že ostatní parametry lze upravovat relativně snadno.

Právě tento problém je důvodem k tomu, že jsem ponechal v seznamech možných příkazů i ty, které jsou obsluhovány jiným způsobem (součást skupiny nebo nastavitelné najednou - barvy, TAGy, …). Za normálních podmínek by nemělo být potřeba takový příkaz zadávat samostatně. Ovšem v nouzi se to může hodit.

Jak již bylo řečeno, skript seskupuje některé příkazy do skupin tak, jak k sobě logicky patří. Skupina se vytvoří automaticky při načtení template souboru nebo při přidání příkazu, který je hlavním příkazem skupiny. Za hlavní příkaz skupiny je považován vždy příkaz vytvářející viditelný prvek ve statistice (příkaz pro vytvoření tabulky, mapy, grafu). Ostatní příkazy ve skupině mají pomocný charakter a upravují vzhled nebo jiné parametry. Hlavná příkaz je od ostatních příkazů ve skupině barevně odlišen.

Vložením hlavního příkazu se vždy vkládá celá skupina (obsahující na počátku právě jen ten hlavní příkaz) a smazáním hlavního příkazu se maže celá skupina.

Sbalené skupiny TABMENU	Rozbalená skupina příkazů pro tabulku autorů

Skupiny se rozbalují a sbalují dvojklikem a příkazu uvádějícím skupinu (se symbolem + nebo -).

Pokud je označen první řádek skupiny, pravý seznam příkazů obsahuje jen ty příkazy, které je možné do skupiny zařadit. Je tedy poměrně snadné najít příkaz, kterým vhodně ovlivnit tu kterou tabulku či mapu. Tím se výrazně zvýší přehlednost, ovladatelnost a znemožní se zadávání chybných a nesmyslných příkazů či hodnot.

Práce s barvami je značně odlišná od původního příkazu COLORS a maskuje se za definici barevných profilů. Každý příkaz COLORS (s různými barvami) je převeden na jeden barevný profil, který nese své jméno. Seznam definovaných barevných profilů je k dispozici na záložce Barevné profily, kde lze s nimi snadno pracovat. Jednotlivé barvami se upraví dvojklikem na příslušné barevné položce.

Má-li být některý barevný profil použit, jen se vloží příkaz COLORS s příslušným jménem barevného profilu. Je to výrazně přehlednější než dlouhý řádek nic neříkajících RGB položek, kde člověk rychle ztratí přehled o tom, která položka co znamená.

Při načítání Template souboru je automaticky detekováno opakované použití téhož barevného profilu a nové jméno mu není přiřazeno. Pokud je nalezen profil, který dosud nebyl pojmenován, je mu vygenerováno jedinečné jméno, jež si uživatel může později nastavit tak, aby pro něj bylo dostatečně srozumitelné. Jméno se ukládá do Template souboru jako interní příkaz, aby příště již mohlo být použito a nebylo třeba profil znova pojmenovávat.

Protože počet barev v barevném profilu je relativně omezený, využívá GgStat jednotlivé barvy i k jiným účelům než je jejich hlavní určení. U každé barvy je “bublina”, která upřesňuje její použití.

Při ukládání příkazů do Template souboru jsou všechny barevné profily uloženy jako zvlaštní poznámka, takže je program GgStat bude ignorovat, ale skript je při příštím načtení Template souboru dokáže využít a profily správně pojmenovat.

Při úvodním načtení Template souboru skript separuje příkazy pro definici TAGu a vytvoří z nich samostatný seznam. Ten je možné upravovat na samostatné záložce, kde je současně zobrazen seznam všech kategorií TAGů definovaných v GeoGetu.

V příkazech, které mají použít definovaný TAG je pak možné jako hodnotu parametru vybrat jeden z již definovaných TAGů a uživatel se nemusí zabývat jejich správnou definicí. Doporučuji pojmenovávat definované TAGy tak, abyste později jasně již podle jména poznali, že se jedná o TAG (např. vždy začít jmeno “Tag_”). Není to sice nutné, ale výrazně to zpřehlední Template soubor pro úpravy.

Nadpisy standardních sloupců (příkazy LANG_TAG_Index, …) nejsou přiřazeny k jednotlivým tagům a je možné je nastavit kterékoli TAG-tabulce samostatně a přitom každé jinak.

Při úvodním načtení Template souboru skript analyzuje příkazy, jejichž účelem je vytvářet a přidávat k tabulce zajímavých čísel další řádky a tyto příkazy vyčleňuje ze šablony. Sdružené příkazy jsou souhrnně zobrazeny na záložce Řádky zajímavých čísel tak, aby jejich úprava byla pro uživatele co nejjednodušší.

Naopak při zápisu šablony do souboru jsou informace o řádcích rozděleny zpět do příkazů a příkazy jsou zapsány pohromadě bez ohldu na to, jak byly původně po souboru (souborech) roztroušeny.

Přidání nové řádku k tabulce zajistí následující kroky:

1. v záložce Řádky zajímavých čísel vytvořte novou položku a nastavte jména a hodnoty v obou sloupcích
2. do šablony někam před příkaz SomeNumbers (nejlépe do skupiny této tabulky - A) vložte příkaz APPEND_NUMBERS (B, C). Při vložení příkazu se automaticky otevře možnost vybrat z definovaných řádků. Vyberte požadovaný řádek, klikněte na Použít jako parametr a pak na tlačítko Použít

Některé příkazy umožňují použití hodnoty, kterou má GgStat nastavenou jako výsledek některé své činnosti (počet nalezených keší, …). Seznam všech použitelných proměnných, které jsou pro k dispozici, zahrnuje standardní proměnné GgStatu i proměnné definované příkazem SETVAR.

Program automaticky doplní popis o text založky podle pořadí příkazu TABMENU a podle všech příkazů DEFINETABMENU v inicializační sekci.

Konfigurace skriptu v podstatě žádná není. Sript jen předpokládá standardní umístění skriptu Autostat k tomu, aby si automaticky našel hlavní Template soubor a aby nebylo potřeba ručního načítání. Z jeho konfigurace také používá domovské souřadnice pro generování náhledu statistiky.

Při ručním načítání je automaticky zvolen adresář s implicitní instalací GgStatu, odkud jsou také zobrazovány ukázkové příklady použítí jednotlivých příkazů.

Ostatní konfigurace programu je uložena v souboru GgSatTune.CmdPar.ini a nedopuručuji do ní zasahovat bez důkladného seznámení s funkcí programu GgStat.exe. Jediné, co běžný uživatel může měnit relativně bez nebezpečí, je první sekce Type, která obsahuje barvu a řez fontu, jímž budou vypsány příkazy příslušné kategorie. V dalších sekcích již soubor obsahuje seznam všech příkazů GgStatu, jejich parametrů, odkazy na nápovědu a ukázkové příklady, ale také některé příkazy používané interně jen v GsStatTune. Jejich chybným nastavením může dojít nejen k chybné funkci skriptu, ale možná také k jeho úplnému zhroucení.

Pokud je vstupní kódování odlišné od cp1250, je vše převedeno na utf-8 a pak na ANSI pro správné zobrazení ve Windows. Opačný postup je použit při ukládání změněných souborů zpět na disk. Nemám vyzkoušena všechna vstupní kódování a umím si představit, že to při některých obskurních typech může činit potíže. Dejte vědět. V každém případě bude dělat problémy zpracování souborů s jiným kódováním než je nastaveno příkazem INCODING a bude dělat problémy i čeština v řádcích uvedených před tímto příkazem. Rovněž si dejte pozor na samostatné zpracování souborů, které neobsahují příkaz INCODING, ty budou zpracovány jako by bylo nastaveno INCODING cp1250 (tedy ANSI).

Pokud jsou v šabloně načteny pluginy do GgStatu a blok pluginu je rozbalen, všechny jeho příkazy jsou chápány jako komentář, protože se nejedná o příkazy GgStatu . Proto je také nelze upravovat, mazat ani přidávat. K tomu je nutné použít běžný textový editor neměnící formát prostého textového souboru (norepad, notepad+, PSPad, …).

Některé příkazy načtené z Template souboru nejsou v seznamu příkazů vůbec zobrazeny, protože jsou obslouženy samostatnou záložkou, na které se pak definuje více parametrů pro několik souvisejících příkazů najednou. Například pro tabulku zajímavých čísel je to současná definice parametrů pro 2 příkazy LANG_NUMBERS_* a DEFINENUMBERS, definici pak použije příkaz APPEND_NUMBERS. Podobně je to pro TAGy a barvy. Při uložení příkazů do souboru jsou odpovídající příkazy uloženy bezprostředně před “hlavní příkaz” (např. APPEND_NUMBERS).

Při uložení jsou do výstupního souboru s šablonou vkládány interní příkazy, které usnadňují další práci skriptu. Pořadí řádků může být ve vytvořeném Template souboru drobně odlišné od pořadí před načtením. To by nemělo být na závadu, skript si příkazy seskupuje podle svého tak, jak mu k sobě pasují. Jediný optický problem může být s prázdnými řádky a komentáři na konci bloků. Ale funkčnost šablony v GgStatu by neměla být dotčena.

Při ukládání příkazů zpět do souboru jsou vynechány přebytečné mezery oddělující parametry příkazů. Není to ani dobře ani špatně, je to vlastnost.

Skript zatím nedokáže rozumně pracovat s TAGy a SETVAR nastavenými z pluginů GgStatu (GgsExpr, …). Protože není možné, aby znal všechny příkazy všech skriptů, nedokáže určit, které parametry a v jakém tvaru vrací plugin zpět GgStatu . Pokud chcete, aby je skript mohl použít, definujte je libovolně před voláním pluginu. Tím o nich bude skript vědět a příslušný plugin jim správnou hodnotu nastaví v průběhu své činnosti při generování statistiky.

• První veřejná verze, není ostrá, jen zkušenějším k vyzkoušení a připomínkám