Curl Docs

[RobertShiplett]

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}

With one small change the layout flips:

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.

[c-s]

Your new example is also longer...

Also {value} is pretty fundamental, so I would say rather the opposite -- examples using it seem valuable.

[tdeng]

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 ?

[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 ?