Curl Docs

[RobertShiplett]

Not complicating at all - better to discuss what could make the terrific Docs Viewer even better, right?

I found Java developers baffled by this value at top-level idea - so I focussed on using {value } about a variable in {text } at top-level:

The candidate surname is "Smith" on the form.

|| But unwrapped that text fails to display in a PlainDocument !!

{text The candidate surname is "Smith" on the form.}

by first showing plain text in a {text } expression and then adding a variable.

{text The candidate surname is {value last-name} on the form.}

Fortunately, these little one-line demos work fine in any {example } window in the Docs Viewer - and we can use {example } in HTML training pages ...

In two of the other expression-based languages that I use ( Rebol and the ICON-variants), Rebol appears at first to have a syntactic advantage with :word and word: but in short order gives rise to baffling conundrums (evident by following Rebol guru discussion threads, though the true-believers insist on the simplicity and clarity of that language.) Icon and Unicon also can have issues as well (and there is now Object Icon and Converge.)

I take my "cue" from the Curl trademarked "gentle curve" and where there is an obvious bump, try to smooth it out.

Example: newbies to Rebol have to learn that PRINT does not return a value.

So, in short, I find it helps to demo an HTML page with text but NO markup and then a default Curl page with text but no expressions. It can lead to an "ah-hah".

And then there is Tcl, whose followers insist it is obvious to all who persist in using Tcl ...

$Nobody has ever asked me, "So what is the sigil ?" when learning Curl. Or not yet.

Non-issues that I never raise: why the programming world has not adopted nul and abandoned both null and nil. Thankfully the letter "O" is not used as an alternative to 0 [zero] in hex and in auto-casting. Or is it in some language?

I agree with Robert in the meaning that first-time users of Curl could easily have difficulty understanding where and when should they use {value} to evaluate an expression, although I have already been used to the usage of it and find it's really great .

The difficulty for understanding {value} is especially obvious when using at the top level of a curl applet file. To understand this, a user must know a DefaultDocument or PlainDocument will add an object without being defined with a varirable to it's layout container (a TextFlowBox) by default , while a variable definition will be kept as a variable only and value of this variable won't be added to it's layout container implicitly. So when you want a variable to be added to a DefaultDocument or PlainDocument, eithier use {value var} at the top level of the *Document, or wrap this variable with another Graphical container like a Fill or Frame or anything else, which is then instantiated directly at the top level of *Document without being assigned to any variable.

Am I complicating this topic ?