REBOL DOCUMENTAION suggestions for improvement

Discussion in 'Rebol' started by YueM, Jan 24, 2010.

  1. Gerard

    Gerard New Member

    Hi YueM,

    The idea to Post on AltMe is fine too but I would prefer if the community was able to get a larger visibility,
    like was suggested on the REBOL ML, some time ago.

    I am revisiting my code before publishing - and then after some thought, I even prefer to post it before it becomes fully revised
    so to help others to follow and even offer their own suggestions to improve it in some way that may differ from my own view.

    I planned to post my code and discuss its evolution here and then when it will be ready, to publish it and some documentation
    on REBOL.ORG for others to follow the great steps of the evolved final product.

    I think this the most central place we have for the moment and one that will and should last around the REBOL community,
    one that is also visible from the Search Engines like Google.

    May be there will be many in between versions and resulting alternatives that will be published, since I see this more like a tutorial
    where many roads could be taken,even if in the final a single one or two will be offered for comparative review to newcomers.

    My only bug with this series is that I am not really knowing anything formal about UML or other diagramming standard and I even don't use any diagramming tool
    for the moment - only some hand drawn diagrams to better illustrate and understand what I do for myself.

    When I left for illness back in 1997, Objects were not very often used here and only DFDs and ERDs were used in my vicinity and even then I had not really
    learned them well enough to be able to really use them in a useful manner, so in this area too I have all to relearn from the start.

    Until I become fluent with these standards and tools, I hope someone will submit some diagrams when the need will appear to do so.
    I will then be able to comment them but I dont' pretend to be able to do a lot more for the moment.


    Probably that my first submitted draft will not have a way to ensure persistence for the objects I will create. They will be added soon after the first release.

    My first design questions relates to : "What is the better way to keep track of my different Serial-Ids, since I wil need many of them and I have to keep the count of any one of them,
    and eventually I also want to be able to independently reset any one of them".

    For the moment I use independent 'words (like Therapist-Sid or Visit-Sid for maintaining each one of them but I plan to move all of them to
    some list contained in a Block to be called 'Sids, to minimize the the duplicate operations that will act upon each of them.

    The price to pay for this flexibility comes in a more complex way to add, retrieve, modify and delete each one of them when necessary.
    These functionalities (data and functions) should be kept external to the Objects that will need these services - a bit like other OO languages do it when using
    some Class variables and methods instead of using some Instance variables and methods that then have to be part of every object instead of being shared by them all.

    Don't know yet how it will be implemented but I thought that I could use some 2-level contexts to keep these things separate. The external one for things to be shared but kept seperate
    and an internal one to keep every object required for the app.

    My next post will show my first experiment to realize this... and it will then evolve a bit at a time ! since I can't go quicker either.
    Not much time left before the preparation of the near to come taxes ...


    When the objects will be functional, I'll try to adapt the command line entry for a GUI use.
    And then I would like to compare how each one of the offered tools can be used for a quick personal comparative review.
  2. YueM

    YueM New Member

    what is also missing is "the Rebol Way of doing things" .

    I read somewhere comments from Carl saying that people are programming in Rebol in an unrebol like way. So the question I have, can someone show examples of how to do things in rebol using the correct rebol way ?

    Is rebol a functional language ? I don't see recursion used a lot in the scripts I have come across, from Nick's tutorial or from the cook books. so I would like to ask the community , what is the Rebol style ?

    an experienced reboler should publish articles like "the Rebol Way of doing things".

    personally what I have found so far, it looks like Rebol uses a more procedural style.
  3. YueM

    YueM New Member

    I am reading the Rebol view developer's guide.html .

    section 15.1 is View facets.

    can someone show me a script where they use offset facet for a button or a text field ? what I find frustrating apart from the absence of meaningful documentation is the inconsistency in the way the language is .

    let me show what I mean, in the same section 15.1, for the effect facet. I was trying and found out that the following syntax is needed to use the effect facet.

    view layout [ button "hello" effect [ gradient 123.0.0]]

    ok it works . the tuple can be changed to whatever gradient you want.

    I gave it a try for the offset facet, trying to set the position of the button at 100x200. in other languages which have more consistent syntax , you would intituitively try the following, based on the way the previous OFFSET example works.

    view layout [ button "hello" offset [ 100x200]]
    guess what ? it didn't work... and I still cannot figure out how to get it to work.

    see the inconsistency of the dialect ? why sometimes things work this way, sometimes things work a different way ? It feels more like the dialect is a patch work, rather than an intelligent design to me, and the documentation section 15.1 doesn't even have a snippet to show how to use that offset facet.

    I even tried

    view layout [ button "hello" offfset 100x200]

    it failed miserably as well.

    now imagine you have to go try each one of the facet to figure out how they work, how much time you are going to waste ? so where's the productivity gain ? I can read the fx ruby - create lean and mean guis with ruby book, in a week and know exactly right away hot to use all the features I need. with Rebol Vid, I' m still struggling to learn its features after putting in much more time in.


    I am not sure if Carl ever pays any visit to this site, however I wish he could read this comment, so that VID for R3 doesn't suffer from the same inconsistency. everything should be consistent, so that even if you are using some new feature, intituitively you should be able to figure out how to use the feature.

    (as I have that nagging feeling that Rebol may never improve its documentation, so we will be wasting lots of time just trying to understand how it works) , I have just started learning Ruby because they have so much better documentation. in Ruby they call it POLS there, meaning principle of least surprise. this is something that Rebol should learn from Ruby. and I find that my learning progress is a lot better with Ruby.
  4. Graham

    Graham Developer Staff Member

    I just skimmed the View docs.

    It says 'Effect takes a word! or a block! so that's why your block! works.

    Offset is however a keyword to set the offset of the layout vis the parent window.

    I would have expected that this would work

    view layout [ button "Hello" with [ offset: 100x100 ] ]

    but it doesn't .. perhaps because offset is normally set using the 'at dialect word.

    view layout [ at 100x100 button "hello" ]
  5. henrikmk

    henrikmk New Member

    YueM, VID is built around maintaining an invisible cursor position, when laying out elements. The process is not much different from typing text. Hence words like 'at, 'pad, 'return, 'guide, 'across and 'below for specifying layout position and direction. You start in the upper left corner and simply move right or down to a new line, and when you want to go "crazy", you use 'at. For more intelligence on where to position things, use 'guide in combination with 'at. To adjust spacing, you can use 'pad and 'space. 'origin sets the upper left corner. There is also a 'tab option, but I never use it.

    Furthermore, consider faces like objects "stamped" onto a sheet with the 'layout function. The process that occurs during "stamping" is:

    1. See what layout word we're expecting in the dialect.
    2. OK, it's 'at, which is a layout keyword and not a face. So place the cursor at where it's requested.
    3. Next word...
    4. OK, it's a 'button, so we go get a standard button from system/view/vid/vid-styles
    5. Grab the specs as specified in the dialect.
    6. There are two types of specs: Some are directly recognized by datatype, like size and color. Others are typed in with a keyword: 'effect, edge, 'font, 'para, 'doc, 'feel, 'with, 'effects, 'keycode, 'rate, 'colors, 'texts, 'help, 'user-data. (Notice no 'offset)
    7. Graft the specs onto a copy of the standard button.
    8. Now we move the offset, by using the size of the face and requested spacing.
    9. "Stamp"! The face is added to the face tree.
    10. Run the button's 'init facet.
    11. Next layout word or stop if at end.

    Graham,

    The reason 'offset doesn't work, is because the 'offset keyword would be a attached to the face, but offset is already determined earlier by the cursor position and the next position is determined partially by the face size and partially the layout direction, so the position is ready for the next round. The 'offset facet is set by the layout engine in point 2 and 8 without interference from the face itself.

    I can understand why offset not being there is a surprise, but the overall layout system is simple, if one just compares it to typing text with a cursor in a word processor. It's possible to add an 'offset keyword, if one wants to.

    Do a "source layout" to get an overall feel of what's going on. Not everything happens in there, but the main part happens there.

    Some examples:

    view layout [at 50x50 box red] ; places a red box at 50x50

    view layout [here: guide box 100x100 blue at here box 50x50 red] ; places two boxes on top of each other

    view layout [across box red box green box blue return box yellow box orange] ; "typing in some boxes"

    view layout [box red box green box blue return box yellow box orange] ; "typing in some boxes in Chinese?" Layout direction is by default downward ('below)

    view layout [box red pad -20x-20 box blue] ; overlapping boxes. note how the blue box doesn't "push" the layout spacing to its left. It's because it goes beyond the horizontal origin point at the top left of the red box.

    Hope this helps a bit.
  6. YueM

    YueM New Member

    Thanks Graham

    I did try the WITH , although I didn't show it in the my sample code. I just wanted to show the inconsistency with the example. so it looks like the offset cannot be used as freely as the other facets.

    effect takes a block , I get it. Since a block can be of 0 or multiple values. they could have used the same syntax for all the other facets as well.

    since you can use effect [ gradient 123.0.0] syntax, It would have been more consistent for example if I could use offset [ 20x20] . this is why I was saying it doesn't look like it is an intelligent or coherent design. people may disagree with me but it feels more to me like they have been navigating by sight, just adding pieces ad hoc.

    For the sake of discussion I am using offset here in my example , but it could apply to any other facet.
  7. YueM

    YueM New Member

    Thanks Henrik for the explanations and samples.

    I had tried the AT , however I wanted to use the offset as that would have given me a more consistent and more useful way of writing code than using the at. that's a personal preference.
    I would rather use offset: 20x20 than AT 20x20 in coding, the first approach would allow me to control the position dynamically when the program is running.

    I have one question about the facets, help svv/vid-styles/label/facets and it returns me "middle bold feel none doc " . I don't see anything that suggest colors there and yet I can use

    label "hello" 300x20 blue

    1st question : can you explain that to me ? how can it accept 300x20 which is size and blue which is font color when size and color don't show up, in the svv/vid-styles/label/facets field


    2nd question : when I do help svv/facet-words there are a lot of facets that come up . how can you tell which facet words apply to what style ? Is there a way to find out ?

    3rd question : how do I find out what are the available colors that is supported by vid? what field contains that ?

    4th question: I tried help bold - it returns "no information on bold" and yet we can use bold in vid . where do I look for the definition of bold ?
  8. Graham

    Graham Developer Staff Member

    Help returns help on Rebol functions ..... it doesn't return any help on the special dialects.
  9. Graham

    Graham Developer Staff Member

    Apparently, offset is special.

    You can set it using

    but the offset gets overwritten when the layout is processed.

    Do the other facet's need a block? Probably not ....
  10. Graham

    Graham Developer Staff Member

    The colors are not part of VID but are defined by View. So, you can at the console type

    help blue

    these are the colors in the source

    black: 0.0.0
    coal: 64.64.64
    gray: 128.128.128
    pewter: 170.170.170
    silver: 192.192.192
    snow: 240.240.240
    white: 255.255.255

    blue: 0.0.255
    green: 0.255.0
    cyan: 0.255.255
    red: 255.0.0
    yellow: 255.255.0
    magenta: 255.0.255

    navy: 0.0.128
    leaf: 0.128.0
    teal: 0.128.128
    maroon: 128.0.0
    olive: 128.128.0
    purple: 128.0.128

    orange: 255.150.10
    oldrab: 72.72.16
    brown: 139.69.19
    coffee: 76.26.0
    sienna: 160.82.45
    crimson: 220.20.60
    violet: 72.0.90
    brick: 178.34.34
    pink: 255.164.200
    gold: 255.205.40
    tan: 222.184.135
    beige: 255.228.196
    ivory: 255.255.240
    linen: 250.240.230
    khaki: 179.179.126
    rebolor: 142.128.110
    wheat: 245.222.129
    aqua: 40.100.130
    forest: 0.48.0
    water: 80.108.142
    papaya: 255.80.37
    sky: 164.200.255
    mint: 100.136.116

    reblue: 38.58.108
    base-color: 200.200.200
    yello: 255.240.120
  11. Graham

    Graham Developer Staff Member

    bold is just a short hand version of

  12. Gerard

    Gerard New Member

    YueM,

    About Docs and coding style, here is one of the last AltMe chats I got while searching for a coding style document on Google:

    http://www.rebol.net/altweb/rebol3/chat174.html

    What I had found about the REBOL coding style is referenced by them too in the link above. I post it again for your convenience.

    http://www.rebol.com/r3/docs/concepts/scripts-style.html

    Carl also gave some hints in a past post about how REBOL coding should look like in practice (optimized code) from an example. I couldn't find it yet but here is some discussion he got about the subject. If I find it later, I'll post it to you.

    http://www.rebol.com/article/0102.html

    And here is his view about REBOL vs the Functional paradigm :

    http://www.rebol.com/article/0206.html
  13. YueM

    YueM New Member

    hI Graham,

    Thank you for sending the list of all the colors that exist in view.

    I went back to help system/view but couldn't find a field that contains the available colors.

    at the risk of me sounding like a broken record, is it possible for you to let me know how you got those values ? i.e what field contain all thos values ? or how did you list them all ?
  14. YueM

    YueM New Member

    thanks Gerard,

    the http://www.rebol.com/r3/docs/concepts/scripts-style.html, I did see it . It was not what I was looking for.

    however what I was referring to is more the rebol way of doing things ? because somewhere there was a comment from Carl , that people are not using Rebol, the Rebol way.
    what are they doing that doesn't look Rebol like ?

    So that's why I was looking some articles that taught people what is the correct way of programming in Rebol .. not formatting and header details.

    for example of a correct way of doing loops in ruby , the ruby way of doing loops are using the code blocks. people don't use the for loop as much, although the for loop exists. so this is considered the correct way of doing loop in ruby, from what I have read. you get the idea ?


    example of using code block:

    my_list.each { |x| puts x }


    so knowing that this is the way to do loop in Ruby , that's what I will use. this is just one example of the way of doing something in ruby, there are many others.

    so for Rebol, since Carl said that some people are not using Rebol the Rebol way...., so what is the Rebol way of doing things ?
  15. Graham

    Graham Developer Staff Member

    The help system is incomplete.

    I just downloaded the SDK sources and looked at them.
  16. YueM

    YueM New Member

    Ok. thanks Graham, the list you provided is a very useful list to keep near by for reference.
  17. endo

    endo New Member

    listing of vid colors

    try help tuple! in console to get the list of all available colors.
  18. YueM

    YueM New Member

    Thanks Endo, that's a very good tip. this is what I have been looking for.
  19. YueM

    YueM New Member

    did anybody try the funct . The funct documentation says everything inside the funct is a local variable. However it doesn't look to me this is the case.

    The funct local values behave erratically.

    e.g

    rebol [ ]

    gValue: 35 ; global gValue

    afunc: funct [ ] [ print gValue]


    bfunc: funct [ ] [
    print gValue

    gValue: 433

    print gValue

    ]


    then I call afunc followed by calling bfunc

    inside afunc :-

    gValue = 35 !!! this should not be 35, it should be isolated from the global gValue 35. why is it seeing the Global gValue ? is there an explanation for that ?



    inside bfunc :-

    gValue = none, then gValue = 433 which looks ok to me. as gValue in bfunc should be a local value and should not see the global gValue.

    to me that looks like a bug. funct should have its own copy of local gValue and should not be showing 35 in afunc

    anyone has any clue why it behaves like this ?
  20. Graham

    Graham Developer Staff Member

    If you're expecting that no globals be visible inside a funct, then you couldn't do anything!

    Even 'print would be unknown.

Share This Page