Chyba v nápovědě.

neutr · 11. 7. 2014 05:51:10

Nápověda pro příkaz GoSub obsahuje chybu a několik nedostatků, které si matně pamatuji z poměrně dávné historie.
Chybu obsahují oba nejnovější balíky AOO a LO (je opisována od 'OOo' nepaměti). Navíc tam není úplně korektní popis vlastností respektive účelu, nebo rozdílu mezi GoSub a GoTo.
ApacheOffice obsahuje navíc alternativu ON ..GoSub Sub1, Sub1,...Sub255. Tato verze funguje i na LO 4.2.5 a je škoda, že pro LO není uvedena.

Princip chyby je v definici řádků :

iInputa = Int(InputBox$ "Zadejte první číslo: ","NumberInput"))
iInputb = Int(InputBox$ "Zadejte druhé číslo: ","NumberInput"))

Chyba spočívá v tom, že nejsou uzavřeny správně závorky pro InputBox. Správně je to takto :

iInputa = Int(InputBox$ ("Zadejte první číslo: ","NumberInput"))
iInputb = Int(InputBox$ ("Zadejte druhé číslo: ","NumberInput"))

Navíc oba balíky ukazují stejně neúplný překlad obsahu výstupních hlášení. V definici 'Print' je uvedeno: Print "Odmocnina z ";iInputb;" is";iInputc. Chtělo by to změnit to 'is' na 'je'. Totéž platí o 'NumberInput'. To by mohlo být nahrazeno 'Číselný vstup', nebo 'VstupČíslem' ap.

Další skutečností je to, že 'InputBox$' je pravděpodobně pozůstatek původně asi nutné deklarace InputBoxu. To není potřeba. Funguje to i bez dolaru - jen 'InputBox'.

Nakonec ještě popis upozornění, které varuje před syntaktickou chybou :
Opět oba balíky stejně - cituji :
Pokud program narazí na příkaz Return, kterému nepředchází GoSub, OpenOffice Basic vrátí chybovou zprávu. Pomocí Exit Sub nebo Exit Function zajistíte, že program opustí Sub nebo Function před dosažením příkazu Return.
V popisu by mělo být uvedeno, že GoSub bez RETURN se chová stejně jako GoTo. Pokud je definováno RETURN musí být v kódu také zastavení Sub/Function s podobou buď 'Exit Sub/Function', nebo 'STOP' mezi voláním GoSubXYZ a jeho 'návěštím'.
Prakticky by to mohlo být doporučení povinné sekvence :
Exit Sub/Function
Návěští:
---------- nebo :
Stop
Návěští:
---------- Nedodržení této sekvence vede k chybě (původní popis změnit), která neumožní opustit Sub/Function a tím dojde k zastavení s chybovým hlášením. (Chyba je podobná nekonenečnému - neuzavřenému cyklu.)

Správně by podle mne kód v nápovědách měl vypadat následovně :

Sub ExampleGoSub
Dim iInputa As Single
Dim iInputb As Single
Dim iInputc As Single
    iInputa = Int(InputBox( "Zadejte první číslo: ","Číselný Vstup"))
    iInputb = Int(InputBox( "Zadejte druhé číslo: ","Číselný Vstup"))
    iInputc=iInputa
    GoSub SquareRoot
    Print "Odmocnina z ";iInputa;" je";iInputc
    iInputc=iInputb
    GoSub SquareRoot
    Print "Odmocnina z ";iInputb;" je";iInputc
REM ----------Povinná sekvence začátek
    Exit Sub 
SquareRoot:
REM ----------Povinná sekvence Konec
    iInputc=sqr(iInputc)
    Return
End Sub

PS: Nevím, jestli náhodou není tato chyba součástí originální nápovědy. Pokud je tomu tak a nejnovější originál chybu obsahuje, chtělo by to postoupit k opravě jako bug.

Editoval neutr (11. 7. 2014 06:07:39)

neutr · 13. 7. 2014 09:21:49

A ještě jeden nedostatek. Tentokrát jde o popis zobrazování dialogů. Taktéž si pamatuji, že je to staré jako OOo. V obou balících přibližně stejně ale AOO tam toho má následovně mnohem více. Cituji :

Zobrazení dialogu pomocí kódu programu.
V okně LibreOffice BASIC vytvořeného dialogu opusťte Editor dialogů klepnutím na záložku s názvem modulu, ke kterému je dialog přiřazen. Záložka s názvem modulu je na spodní straně okna.
Vytvořte rutinu Dialog1Show s následujícím kódem. V tomto příkladu bude název vytvořeného dialogu "Dialog1" dále z LO:

Sub Dialog1Show
    BasicLibraries.LoadLibrary("Tools")
    oDialog1 = LoadDialog("Standard", "Dialog1")
    oDialog1.Execute()
End Sub
'Bez použití funkce "LoadDialog" je možné kód vyvolat takto:
Sub Dialog1Show
    DialogLibraries.LoadLibrary("Standard")
    oDialog1 = CreateUnoDialog( DialogLibraries.Standard.Dialog1 )
    oDialog1.Execute()
End Sub

Pouze 'modrý text' trošku - ale naprosto nedostatečně napovídá jak spouštět dialogy. Oba uvedené kódy (makra) platí pouze pro dialogy v knihovně 'Moje makra Standard'.
Potíž je v tom, že také knihovna v aktivním dokumentu má v drtivé většině případů stejný název 'Standard'. Když tam ale zadáme podle návodu to první z maker - nemůže to chodit ani náhodou. Bude chodit pouze to druhé. S tím se většinou všichni smíří a dál nepátrají. V sešitě totiž není knihovna 'Tools', takže pokud ji tam vlastnosručně nevytvoříme nemůže to dobře dopadnout.
Správně by tam měl být důkladnější popis nejméně této skutečnosti : Dialog lze spustit pouze makrem ze stejné knihovny. Při volání makrem z jiné knihovny dojde k chybě a to i v případě, že se volá dialog umístěný v knihovně sešitu makrem z knihovny 'Moje makra Standard'.
Pro všechny různé knihovny podle umístění je univerzálním kódem pouze druhý případ. Makro, které se spouští s voláním knihovny ''Tools'' funguje nad všemi dokumenty, ale ne přímo v nich. Toto makro může volat jen dialogy v knihovnách na úrovni 'Moje makra Standard'. Dialogy v konkrétních dokumentech takto volat nelze.
Navíc volání pomocí funkce "LoadDialog" bychom použili asi jen v případě deklarování pomocí Option Explicid. Běžně se dialogy v knihovnách na úrovni 'Moje makra Standard' dají zavolat i bez této funkce (makrem, které volá knihovnu ''Tools'').

Testoval jsem to na LO 4.2.5 a AOO 4.1.0

Editoval neutr (13. 7. 2014 09:31:44)

strepon · 24. 7. 2014 19:25:22

Podíval jsem se na první příspěvek - jsou to velmi dobré postřehy, díky za ně.
- rozdíl mezi GoSub a GoTo - oba příkazy se mi zdají dobře popsané, nějaké konkrétní nedostatky?
- On...GoSub - v LO má nápovědu také, viz tady
- $ a chybějící závorky u InputBox - poslal jsem do nápovědy příslušný patch, zbytečné dolary byly ještě asi v dalších pěti příkladech, jednou opět dokonce s nefunkčním kódem
- NumberInput, is - nedokončený překlad, opravil jsem
- doplnění k Exit Sub/Function - možná by stačilo jen doplnit poznámku "Pokud program narazí na příkaz Return...", co takhle k ní přidat něco ve smyslu "před každým návěštím by proto mělo být Exit sub/fun nebo Return"?

neutr · 25. 7. 2014 06:02:24

Ad 1. Tedy komentář k tomu prvnímu příspěvku.
Nejsem si jistý co myslíte tímto : - rozdíl mezi GoSub a GoTo - oba příkazy se mi zdají dobře popsané, nějaké konkrétní nedostatky? s návazností na toto : - doplnění k Exit Sub/Function - možná by stačilo jen doplnit poznámku "Pokud program narazí na příkaz Return..."
Stávající popis GoSub není přímo chybný, ale k výstižnému popisu má hodně daleko.
A. - GoSub se poměrně hodně vymyká běžnému pojetí makra. Běžné makro se spustí a pak podle pořadí kódu něco dělá. Tady :
1. Start (Sub..+ dle potřeby parametry)
2. Deklarace
3. Definice
4. Výkonný kód - i více operací ap.
5. ukončení práce (End Sub, nebo End Function)
GoSub prakticky nikdy nemůže dojet až k End Sub. Existuje jediná vyjímka : - Když se 'Returny' přeskočí pomocí GoTo respektive On Error GoTo. Ve všech ostatních případech prostě makro na 'Return' musí narazit a tím vznikne chyba. To se musí vysvětlit!
Znamená to, že běžná makra a funkce pracují v pořadí kódu - začnou na začátku a skončí na konci. GoSub skončí v prostředku a ne na konci jako všechny ostatní Sub/Func.
Aby to neskončilo chybou (syntaktická chyba) Tak to musí být ošetřeno zejména nápovědou. Problém je v možné různorodosti :
1. - Může to být v Sub (subroutine) nebo
2. - Může to být ve Function (to je řešeno napůl jako výraz Sub/Function) Už jen z toho může začátečník tlouct hlavou o klávesnici :-( - a není to jediné větvení problému).
3. - Ukončit 'bez chyby' lze pomocí GoTo. Prostě se dá skok za 'returny' (nutný popis vztahu mezi GoSub a GoTo - jsou to velice příbuzné funkce - zase začátečník neví která bije - co když je to chyba nápovědy?)
4. - Ukončit 'bez chyby' lze pomocí 'ON ERROR GOTO' - to je ale sémanticky nesprávně. (Nenecháme způsobit chybu, abychom ji následně mohli přeskočit.)
5. - Doporučený (já jsem užil 'povinný') postup je pomocí Exit Sub.
6. - Alternativně správný postup je ukončení pomocí 'STOP'.
7. - Problém kdy použít 'EXIT SUB' a kdy naopak 'STOP' je zde také na místě, ale patřilo by to do nápovědy k těmto obecným funkcím samostatně. Bylo by možné to popsat v této pasáži a pak na ni odkazovat v obou lokálních nápovědách.
PRINCIP UŽITÍ EXIT SUB nebo STOP :
- V nápovědě pro STOP je uveden tento příklad :

Sub ExampleStop
Dim iVar As Single
    iVar = 36
    Stop
    MsgBox Sqr(iVar)
End Sub

Testoval to někdo? - Je to bohapustý nesmysl !!! Tohle makro by mělo dát hlášku pomocí MsgBoxu - odmocninu z celku 36 = 6. - Ale po spuštění makra se nic nestane - ani nemůže. STOPka zarazí vše - je to univerzální brzda pro vše co je spuštěno!!
Mohlo by to být upraveno na :

Sub ExampleStop
Dim iVar As Single
    iVar = 36
    MsgBox Sqr(iVar)
    Stop
End Sub

Pak ale nikdo nepozná, že stopka funguje - protože totéž se stane když tam prostě STOP nebude!!
Takže popis funkce EXIT a STOP je také nedostatečná a dá se to vše napravit například právě na GoSub.
B. - Popis Vztahu mezi GoSub a GoTo - zejména s odkazem na možnost ukončit GoSub pomocí GoTo, nebo to, že GoSub bez Return je shodné s GoTo ap.
C. - Popis EXIT/STOP
Popis funkce EXIT je proveden kvalitně a dobře. Popis STOP cituji Zastaví provádění programu Basic. není špatně, ale zejména začátečníkovi není jasný rozdíl a tedy vhodnost užití té - které funkce EXIT - či STOP. Takže u STOPu by mělo být jedinou větičkou připsáno, že STOP zastaví úplně všechny spuštěné Sub a Function a nejen tu ve které je tato funkce definována.
Právě proto je popis STOP téměř nemožný na příkladu ve formě kódu. Ten co jsem uváděl z nápovědy jako kód - by bylo stupidní i pro funkci EXIT (Sub, Function, Do..).

Takže popis pro GoSub má mnoho variant a není jednoduché lapidárně vyjádřit jak se má tato funkce systémově zastavit aby neskončila chybou. Promítají se zde problémy podobnosti s funkcí GoTo (ON Error GoTo, nebo také rozdílnost mezi Exit (něco) a STOP (úplně vše).
Je to opravdu dost netypická funkce a zasloužila by alespoň jeden odstavec, který by vnesl jasno do všech výše uvedených problematik - a nejen GoSub.
Faktem je, že jsem doporučil 'povinnou sekvenci'. Což je také unikát. Výraz povinné není příliš relevantní už proto, že tuto chybovost lze sekundárně využít například pro vstup do makra stejně jako je tomu v případě příkazu PRINT. Spíš ale půjde o to vyvolat skok a pak větvení pomocí ON ERROR GOTO z jiných důvodů - záměrně otestovat nějakou vlastnost.

Já osobně užívám nápovědu velice často pro účely příspěvků do fóra. Tyhle 'maličkosti' mne dost iritují, ale je jich hodně a nikoho to moc nikdy nezajímalo. Jen na dokreslení :
Ve Writer existuje 'Styl obrázku - Obrázek' - to je stupidita jak se patří. Styl se dá běžně editovat. Když to vyzkoušíme, zjistíme že styl 'obrázek' je jenom slovo za kterým se skrývá skutečný styl - ale rámce! Byl jsem kritizován, že styl obrázek existuje - je mezi názvy stylů.
Já si sice dovedu vysvětlit proč tam to slovo je - ale reálný styl ne. Je to asi připraveno k budoucímu 'dodělání' skutečného sylu s možností editace. Tak takovéhle maličkosti mne iritují i když jsem si zvykl, že koncepčnost a důslednost není dokonalá. Jen bych dodal, že já to moc nepotřebuji - ale co Ti kdož začínají?

Ne vždy je ku prospěch věci ořezat exaktně na minimum - nejlépe holé věty. Na tohle jsou zvyklí například právníci, nebo lidé vysokoškolsky vzdělaní, ale běžný uživatel je většinou zmaten a nápovědu opustí s nedůvěrou, kterou si ponese hodně dlouho v paměti.

Editoval neutr (25. 7. 2014 06:09:55)

strepon · 25. 7. 2014 18:19:55

Jen jedna konkrétní reakce: Možná bylo záměrem autora kritizované nápovědy ke Stop, aby v příkladu přidání Stop způsobilo viditelnou změnu. Ale jasně, mohlo být na začátku uvedeno, že je účelem, aby se výsledek nezobrazil.

Obecně: Rád nápovědu doplním nebo upravím, ale změna musí být opodstatněná a musí být jasně uveden její návrh (jako to bylo v případě výborné připomínky o dolarech a chybném kódu). Nemůžu ale zkoumat a ověřovat výše uvedené texty a vymýšlet na jejich základě úpravy.

neutr · 25. 7. 2014 20:10:26

Ne ne. To byla reakce spíš ma tohle - doplnění k Exit Sub/Function - možná by stačilo jen doplnit poznámku "Pokud program narazí na příkaz Return...", co takhle k ní přidat něco ve smyslu "před každým návěštím by proto mělo být Exit sub/fun nebo Return"?

Logika by měla být matematická a nebo alespoň kognitivně lingvistická. V tomto případě jde o maličkost - chybu vyjádření a možná slovíčkaření co takhle k ní přidat něco ve smyslu "před každým návěštím by proto mělo být Exit sub/fun nebo Return"? - Jak před každým návěštím? Pouze a jenom mezi posledním GoSub a prvním 'Return'.
------- Návěští nemusí být jedno - může jich být třeba 50 - ale ta systémová stopka musí být před prvním 'Return'. Právě proto jsem psal to o té povinné sekvenci. Takže navrhovaný výraz opravdu není to správní ořechové.
Omlouvám se - docela mne mrzí že jsem s tím vůbec začal. Nikoho to doposud netrápilo tak proč bych se tím měl začínat zrovna já a po tolika letech.

K tomu STOPu - když by v nápovědě bylo připsáno že se nic nezobrazí protože je tam 'STOP' tak je to ještě jiné. Ten kdo to kopíruje pochopí, že by se to mělo zobrazit když by tam STOP nebylo. Takže měl by tam být příklad bez 'Stop' a pak se 'Stop' - aby to bylo patrné - co dělá 'STOP'. Ale i to je věcně nedostatečné. STOP zastaví všechny aktivní procesy. A tohle vysvětlit je o hodně těžší. Vůbec se k tomu žádný příklad ve formě kódu nehodí. Lze jen slovem popsat oč jde. Ale to co tam je dnes tak to nestačí i když je to správně. Pro začátečníka je 'Basic' a 'makro' (nebo funkce) totéž. K pochopení je potřeba pozitivní a negativní vymezení pojmu 'Basic' versus Sub, nebo function. A nyní zase nevím, jestli tohle padne na úrodnou půdu :-(

Já se k tomu už vracet nechci. Nežádám uznání a tím méně kritiku, či sveřepé oponování. Chtěl jsem jen apelovat na obyčejný selský rozum v zájmu nováčků, kteří z některých pasáží nápovědy musí mít v hlavě guláš. A je toho poměrně dost co není logické, nebo je to jenom out dík nevhodnému příkladu.

Takže se omlouvám - je to jen můj problém - Vás se to netýká.

Editoval neutr (25. 7. 2014 20:13:02)

lp. · 3. 8. 2014 01:01:27

Poslední úvahy jsem nepochopil.

Funkce GoSub a On var GoSub/GoTo jsou pozůstatky z prehistorie vývoje programovacích jazyků. Funkce GoSub řešila potřebu/zvyk programátorů využívat více vstupních bodů do procedur, On ... GoSub/GoTo byla implementace tabulky skoků.

Úplný popis použití je o něco složitější, než si neutr myslí.

Co v popisu chybí je důrazné varování před použitím těchto příkazů - kdo to použije ať sám nese následky a nestěžuje si, - případně odkaz na ekvivalentní programové konstrukce.

neutr · 3. 8. 2014 08:17:28

I když uvádíte na začátku "Poslední úvahy jsem nepochopil.", tak hned v následujícím odstavci mi dáváte nepřímo za pravdu.
- Ano jsou to pozůstatky z prehistorie programování, ale
1. - Existují pro některé záležitosti jiné příkazy (funkce), ale ne pro všechny. To je pravda v rámci cyklů (smyček). Existují ale potřeby, na které DO..LOOP nestačí. Skoky prostě být musí.
2. - Když už skoky být musí, a také jsou, pak je potřeba je dobře popsat. A jeden z důvodů je právě to, že pro 'některé případy možného užití' jsou vhodnější smyčky. - To by mělo být popsáno možná i názorným příkladem kódu.
3. - Variantnost skoků je veliká jak ve smyslu syntaxe, tak i užití. Tím nemám na mysli možné podmíněčné spuštění ON [parametr] GoSub + až 255 větvení. To co jsem 'kritizoval' bylo vyjádření : -
"co takhle k ní přidat něco ve smyslu "před každým návěštím by proto mělo být Exit sub/fun nebo Return"?. To je nesmyslné. To by sice asi šlo udělat, ale u druhého a každého dalšího návěští by to nikdy program nepoužil. Z toho důvodu je tam RETURN. Takže mezi prvním Return a druhým návěštím je prostor, kam program nikdy 'nevkročí' - totéž mezi všemi dalšími Return-návěští.
4. - Variantnost tak jak mám na mysli je právě způsob ukončení GoSub. GoSub musí bez zastavení skončit chybou vždy, protože pokud tam není zastavení nutně dojde ke srážce kód - Return. Připodobnit se to dá k trychtýři, který má výpustní místo v prostředku - tedy mezi kódem a returny. Tohle není vysvětleno správně.
Vlastní ukončení - jakým prostředkem se to udělá je jiná věc. Možností je více a rozhodnutí kterou možnost použít záleží na účelu. Jedním druhem možných ukončení jsou skoky (GoTo) zejména na konec za poslední Return. (On Local ERROR GoTO, ON ERROR GoTo, ON Proměnná GoTo a GoTo)
Na první pohled je nesmyslné volat chybové 'ERROR', ale v programátor může předpokládat, že pokud není chyba, bude GoSub ukončena v rámci provádění kódu (volaných procedur). Takže když chyba vznikne, skočí program někam (nejspíš na konec). Šlo by pak o 'nasimulování' ELSE.
Mimo rodinu GoTo je to STOP, EXIT SUB, nebo zavolání podprogramu, nebo funkce kde dojde k ukončení pomocí STOP. A tyto varianty by chtělo jak zdůvodnít, tak dát vhodný příklad ve formě kódu.
Ono to není v originální nápovědě, a v rámci kontinuity by se to mělo navrhnout pro balík obecně. V rámci české nápovědy snadno dojde k tomu, že se toto v příští verzi vypustí dík změně na originálu. Takže tohle je moje motivace ale nejdříve pro 'lp.' :

Já Vám musím znovu poděkovat. Byly časy, kdy jsem dík nápovědě neuměl najít způsob práce v array. Jde zase o nedostatečnost nápovědy. To, že existuje rychlé vykonávání kódu jsem věděl. Nevěděl jsem jak to napsat, nebo zjistit. Angličtinu jen čtu a ještě mizerně a i s překladačem nejsou výsledky hledání dobré. Dochází k promíchání pojmů CellArray, Array, ArrayFormula.
Jediný Vy jste mi pomohl k pochopení jak na to. Ono to není až tak moc dávno a tak si to dobře pamatuju. A mojí motivací v tomto příspěvku (ale i v jiných) je pomoc uživatelům, kteří jsou na nápovědu odkázáni. (I v české nápovědě jde o tak ořezané vyjádření, že tomu může porozumět zcela a možná hned i napoprvé jen programátor - ale ne začátečník. A co potom asi s anglickou nápovědou - že? Ta je na tom stejně a i dobrý angličtinář by se neměl dočíst v anglické verzi více, nežli v té české. Dohledání z netu nemá atribut jistoty - je to přesně to co hledám?)

Takže já si myslím, že když už v nápovědě něco je, mělo by to být výstižné a příklady použitelné. Nejen tedy z pohledu znalého uživatele (programátora), ale zejména začátečníka. Proto jsem připsal poslední větu.
Strepon napsal v článcích výzvu ke spolupráci na překladech - zejména chyby a podobně. Tak jsem pár věcí napsal, ale zase je jen mým problémem dojem, že by to mělo být provedeno nad rámec holých vět tak aby to pochopil alespoň průměrný uživatel. Ale nelíbí se mi, že by tam měly zůstávat nesmysly a chyby jen proto, že je to moc práce - ověřit si to, popřípadě upravit. Navíc akceptuji potřebu koncepce v rámci originální nápovědy - a to může být problém.
Abych nebyl zaujatý. Vyšla nová verze LO 4.3 a tam je už něco z toho, co jsem zde uváděl zahrnuto. Za to musím streponovi poděkovat a pochválit ho.

Tato rubrika "připomínky k překladu" myslím může být využívána i k dotazům typu 'co to znamená', 'tohle nefunguje', a nebo jednoduše 'tomuhe nerozumín'.

OpenOffice.cz - web věnovaný kancelářským balíkům OpenOffice.org

#1 11. 7. 2014 05:51:10

Chyba v nápovědě.

#2 13. 7. 2014 09:21:49

Re: Chyba v nápovědě.

#3 24. 7. 2014 19:25:22

Re: Chyba v nápovědě.

#4 25. 7. 2014 06:02:24

Re: Chyba v nápovědě.

#5 25. 7. 2014 18:19:55

Re: Chyba v nápovědě.

#6 25. 7. 2014 20:10:26

Re: Chyba v nápovědě.

#7 3. 8. 2014 01:01:27

Re: Chyba v nápovědě.

#8 3. 8. 2014 08:17:28

Re: Chyba v nápovědě.

Zápatí