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.
--
Mark Wieder
ahsoftw...@gmail.com
_______________________________________________
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
