+- Curl Global Community (https://communities.curl.com)
+-- Forum: Blogs (https://communities.curl.com/forumdisplay.php?fid=17)
+--- Forum: Tech blog (https://communities.curl.com/forumdisplay.php?fid=18)
+---- Forum: Robert blog (https://communities.curl.com/forumdisplay.php?fid=20)
+---- Thread: Curl Docs (/showthread.php?tid=234)
Curl Docs - RobertShiplett - 08-25-2011
With Curl 8 we have an opportunity to evolve the Curl documentation through an iteration.
Here is an example from Curl 7 live docs for MultiTabAccordion in the Documentation Viewer:
Code:
{let list:ListBox = {ListBox "A", "B", "C"}}
{let f:Frame = {Frame "empty"}}
{MultiTabAccordion
{TabPane
label="Row",
{HBox spacing=4pt, "A", "B", "C"}
},
{TabPane
label="Column",
{VBox spacing=4pt, "A", "B", "C"}
},
{TabPane
label="List",
first-active-control = list,
{VBox "Choose One", list}
}
}
{value f}Code:
{let list:ListBox = {ListBox "A", "B", "C"}}
{let f:Frame = {Frame {paragraph "empty or more goes here"}}}
{MultiTabAccordion
{TabPane
label="Row",
{HBox spacing=4pt, "A", "B", "C"}
},
{TabPane
label="Column",
{VBox spacing=4pt, "A", "B", "C"}
},
{TabPane
label="List",
first-active-control = list,
{VBox "Choose One", list}
}
}
{value f}But what is more of a concern for new users of Curl is the use of {value } and when it is required.
Compare this alternative:
Code:
{def listbox = {ListBox "A", "B", "C"}}
{def framed-msg = {Frame {paragraph "empty area for Fill or more goes here"}}}
{VBox height=100pt,
{MultiTabAccordion || -------- here is the accordion declaration
{TabPane
label="Row",
{HBox spacing=4pt, "A", "B", "C"}
},
{TabPane
label="Column",
{VBox spacing=4pt, "A", "B", "C"}
},
{TabPane
label="List",
first-active-control = listbox,
{VBox "Choose One", listbox}
}
}, || --------------- end of accordion declaration
{Fill height=8pt},
framed-msg
}Gone is the single-character name "f" variable and the listbox is not named "list".
With proper indentation in place (seemingly not possible in this post format), I think that this is an improvement.
RE: Curl Docs - c-s - 08-25-2011
Your new example is also longer...
Also {value} is pretty fundamental, so I would say rather the opposite -- examples using it seem valuable.
RE: Curl Docs - tdeng - 08-25-2011
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 ?
RE: Curl Docs - RobertShiplett - 08-26-2011
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?
(08-25-2011, 12:32 PM)tdeng Wrote: 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 ?