Why do I feel that the reason for all this "wierdness" is because LCB
has been written from C++ programmers from the ground up,
while LiveCode still (well, just about) hangs onto to its HyperCard
heritage.
LiveCode, at its best, preserves the clarity that was the best thing
about HyperCard (certainly mind-blowingly refreshing
after my baptism with FORTRAN and PASCAL); LCB, not doing that, is as
opaque as its heritage.
It has been suggested before that the LiveCode team have, maybe
unwittingly, started moving away from the
HyperCard-like simplicity that was what made LiveCode so obviously the
best successor to HyperCard; with LCB they
don't even have to pay lip service to that . . .
I am extremely grateful to you, Mark, that you were the one who took the
first critical plunge . . .
Richmond.
On 5/17/17 10:27 pm, Mark Wieder via use-livecode wrote:
On 05/17/2017 12:09 AM, Ali Lloyd via use-livecode wrote:
Mark, it would be lovely if you could be more specific. What parts of
the
docs in particular could be improved and how? What specific sticking
points
did you have?
Oh, where to start? Here are some thoughts off the top of my head:
Well, I'd love to have more parity between LCS and LCB as far as
keywords and syntax, but I guess that's outside the scope of the
documentation per se. But finding that constants like comma and quote
aren't defined in LCB was a shock. Indeed, even defining a constant
doesn't seem possible. Or at least it's not documented. Searching for
"constant" gives nothing, even though "PiConstant" is in the dictionary.
I have no idea what the dictionary for ScriptObject is telling me. It
has a link to MyScriptObject which has no useful information other
than referring me back to ScripObject. The description "Use the
resolve script object, or my script object to obtain an object of type
ScriptObject" is self-referential at best. The Summary is better "an
opaque type..." yep - it's opaque all right.
The dictionary entries for LCB commands are arcane CamelCase words
seemingly drawn from thin air. CanvasOperationDrawImage, for example,
has the syntax of "draw [ from mSrcRect of ] mImage into mDestRect of
mCanvas". The syntax statement is understandable, but the entry should
be "draw", not "CanvasOperationDrawImage".
Similarly, searching for "format" brings up
"BooleanFormattedAsString", "FormatBooleanAsString",
"FormatNumberAsString", and "NumberFormattedAsString". These refer to
either the "format" command or the "formatted as string" modifier. The
description field "Use NumberFormattedAsString when you want to
manipulate a numeric value as text" doesn't reference the proper
syntax for the modifier per the example.
And nothing in the "format" commands that came up in the search helped
me figure out how to format a hex number as decimal, which is what I
was looking for based on LCS expectations. There's no "see also"
section which might have pointed me to the "convert" commands. The
description of Operand as "An expression that evaluates to a number"
isn't specific enough to help... is "FE" a number even though it's a
hex number? Is "0xFE" a number"? Does a number have to be an integer
(digging into StringPasedAsNumber would indicate no, but why is it
necessary to do the digging)? Is 0123.50 a number? What's it's string
value? Does it have the leading zero? The trailing zero? Can I control
the output format?
Once I finally tried searching for convert (mind you, I don't want to
*convert* the number, just display it differently) I was faced with a
similar situation: "BaseConvert" (the syntax of which is actually
"Operand converted from base Source to base Target"),
"BaseConvertFrom" (with a syntax of "Operand converted from base
Source", "BaseConvertTo" (syntax of "operand converted to base
Target", and a reference to the com.livecode.typeconvert library.
So looking at BaseConvert, the Operand is specified as "An expression
that evaluates to a string." Fair enough - I give it a hex number and
I expect a decimal number out the back end. What's the format for a
hex number? Is it "0xHH"? Just "HH"? Something else? Can I specify a
leading zero? Number of expected decimal digits (what if I need three
digits even if one or two are leading zeros?) These are easy in LCS,
not so much in LCB.
Is it even possible to set the various delimiters? The documentation
only talks about retrieving them. The description talks about the
calling (script) handler's <type>Delimiter property... is this an
actual property of the object or is just a shorthand way of talking
about "the <type>Delimiter"?
I clicked on "type" in the Filters section. What does that do? All it
seems to do is narrow my choices down to ScriptObject (see above).
The pointer type isn't documented.
Why is the "point" operator documented as "PointMake"? Is this just to
differentiate between the "point" creator keyword and the "point"
object keyword?
Some major strengths of LCS are missing in LCB, or at least don't
appear to be in the documentation. Chunks, for instance. It's possible
to get character chunks (and the [first|last] modifier in the offset
functions are *very* nice), but there's no conception of words. This
results in some ugly, convoluted, and error-prone coding to deal with
things that are not only easy in LCS, but IMNSHO one of the things
that makes LiveCode such a productive environment. I'm hoping this is
just a documentation failure and not a missing feature.
The StringToJString and StringFromJString examples handler use the
"foreign handler" construct, but "foreign" isn't in the dictionary.
Nor is the "binds to" syntax. Nor the JObject or JString objects. Nor
the "unsafe" keyword.
_______________________________________________
use-livecode mailing list
use-livecode@lists.runrev.com
Please visit this url to subscribe, unsubscribe and manage your subscription
preferences:
http://lists.runrev.com/mailman/listinfo/use-livecode
