Thread Rating:
  • 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Curl Docs
08-25-2011, 12:01 AM, (This post was last modified: 08-25-2011, 12:23 AM by RobertShiplett.)
#1
Curl Docs
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.
Robert Shiplett, Curlr
Fredericton NB

Canada
Reply
08-25-2011, 09:26 AM,
#2
RE: Curl Docs
Your new example is also longer...

Also {value} is pretty fundamental, so I would say rather the opposite -- examples using it seem valuable.
Reply
08-25-2011, 12:32 PM,
#3
RE: Curl Docs
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 Big Grin.

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 ?
Reply
08-26-2011, 12:14 AM, (This post was last modified: 08-26-2011, 12:21 AM by RobertShiplett.)
#4
RE: Curl Docs
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 ... Rolleyes

$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? Wink



(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 Big Grin.

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 ?

Robert Shiplett, Curlr
Fredericton NB

Canada
Reply


Possibly Related Threads...
Thread Author Replies Views Last Post
Brick Curl macros introduction (part 1) RobertShiplett 4 6,993 04-25-2015, 05:28 PM
Last Post: glennmcgrath
  server-side Curl issue : TocDocument RobertShiplett 3 5,691 02-09-2015, 02:11 PM
Last Post: Sumeraxe
  Curl with HTML widget + CintaNotes RobertShiplett 0 4,444 09-08-2014, 07:42 AM
Last Post: RobertShiplett
  Curl for the new Kodansh kanji books RobertShiplett 0 3,032 09-07-2014, 08:51 PM
Last Post: RobertShiplett
  Curl on Facebook - another page RobertShiplett 0 3,737 02-01-2014, 02:29 AM
Last Post: RobertShiplett
  Curl for CoffeeScript folks RobertShiplett 0 4,758 06-29-2013, 02:52 AM
Last Post: RobertShiplett
  Curl JavaScript bytecodes RobertShiplett 0 4,939 06-19-2013, 10:33 PM
Last Post: RobertShiplett
  jinja2 templates for Curl RobertShiplett 0 4,147 06-14-2013, 08:33 AM
Last Post: RobertShiplett
  Curl and QNX RobertShiplett 0 4,932 04-24-2013, 11:38 PM
Last Post: RobertShiplett
  WikizPad Curl personal wiki RobertShiplett 0 4,115 03-11-2013, 01:09 AM
Last Post: RobertShiplett
Forum Jump:


Users browsing this thread:
1 Guest(s)

MyBB SQL Error

MyBB has experienced an internal SQL error and cannot continue.

SQL Error:
1017 - Can't find file: 'mybb_threadviews' (errno: 2)
Query:
INSERT INTO mybb_threadviews (tid) VALUES('234')