REBOL DOCUMENTAION suggestions for improvement

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

  1. YueM

    YueM New Member

    i was going through the rebol documentations and I have some questions/ suggestions to improve them.

    It's all small things that add up to a lot for a beginner like me who tries to learn the language.


    case 1:- showing someone how to fish, (rather than give him a fish when he is hungry), will keep him fed for the rest of his life.

    http://rebol.net/wiki/VID_User_Guide#Options



    Options

    An option is a special keyword followed by a specification block.

    For example:

    image effect [colorize blue]

    text-list data list-values

    EFFECT and DATA are the option keywords, followed by their data.



    how do I find the other available option keywords ? this should be added in the documentation.


    same thing for http://rebol.net/wiki/VID_Tutorial#Style_Variations . how do i find the other available style variations ?

    same thing for http://rebol.net/wiki/VID_User_Guide#Attributes. how do i find the other available attributes ?


    There are many places where you have the same problem in the documentation. can someone fix them please ?


    case 2:- consistency will avoid confusion

    http://rebol.net/wiki/VID_Tutorial#Style_Variations
    http://rebol.net/wiki/VID_User_Guide#Attributes

    they are using different terms - style variations and attributes. they don't look different to me (though I must admit I don't know anything about them). can we fix them to avoid confusion to beginners ?


    I hope someone reading this post has the authority to amend the documentations to add those little suggestions I have made. This will be of immense help to beginners in the future. I am a beginner myself and I know what pains I am having today to learn the language.
  2. Graham

    Graham Developer Staff Member

    The incomplete nature of the user documentation has been a long standing complaint, and non of us had the ability to fix it.

    However, the whole website is being shifted to a wiki ... which hopefully means that we will be able to amend such details in the future.
  3. YueM

    YueM New Member

    Graham,

    with reference to the following

    mage effect [colorize blue]

    text-list data list-values

    EFFECT and DATA are the option keywords, followed by their data.



    do you know how to list all the other attributes ? show me an example with "image" and "text-list"

    how could I get those information from the help system ? this is what any serious programmer would like to know.

    thanks
  4. Graham

    Graham Developer Staff Member

    What is unclear to many new users is that VID, or visual interfaces dialect, is not part of the language.

    As the name states, it is a special dialect used by the function 'layout to do graphical composition. And that's why 'help on any of the dialect words turns up nothing.

    Search on text-list and effect facet on this page http://www.rebol.com/docs/view-guide.html to find the examples you want.
  5. Gerard

    Gerard New Member

    REBOL View and VID documentation improvement

    Graham and YueM,

    Both of you are right. I always found it difficult to get a full grasp of the internal model of the REBOL GUI system from the doc only.
    First when I needed some particular styles, like the data grid, I didn't find them and to create some new ones required more knowledge that I have about this subject.

    So I never used REBOL a lot for this main reason. I could not transpose my former knowledge fron VB and its forms to the REBOL GUI. What I found of some help to get a better understanding are the works about REB GUI and the work from Henrik but nevertheless, I didn't step in for further tests... may be with time I will become proficient enough but this is not the case for now.

    I would even prefer to pay for some more professional ready to use styles as I did recently when acquiring my new RunRev platform wich includes a lot of ready-to-use tools but deserves a lot less power than REBOL as a language.

    As a user, I dont't think I have to develop these tools myself because they don't already exist. I appreciate the fact I can develop them but this is of no interest to me for the moment and as is I can't deliver true full-fledged GUI based apps without investing to much effort and time. I'd prefer to pay for them and use them off the shelf. By the time they are available may be I will begin mixing some front-end using external OS dependant GUIs and get my back-end power from REBOL.
  6. Jason

    Jason Developer / Handyman Staff Member

    Graham should make a few Jing Tutorials explaining difficult Rebol concepts.
  7. YueM

    YueM New Member

    Hi Graham,

    "show me an example with "image" and "text-list" . I just wanted to ensure there is no confusion, I am not asking an example of how to use image or text-list.

    because you are very experienced with Rebol, I just wanted to see how you would go about based on your experience with Rebol ( in your day to day , development activities) , to check the other attributes that exist for example with the "image" and "text-list".

    this will help me dig further other attributes for other styles, once I know what and where to look for. Granted , Vid is not part of Rebol, however I believe there should be a way to get those information. Unfortunately I am not good enough at this point to do that.

    what worries me the most is not being able to take advantage of the features of Rebol only because there is no documentation. you see drop-down style exist, but it is not show in the vid documentation. so that's why I want to be able to find all the other information by myself with or without documentation.

    Thanks.
  8. YueM

    YueM New Member

    hi Gerard,

    yes I agree, VID is a bit weak right now in the Styles (widgets) area. there a lot of basic widgets (which come standard with java or .net ) that are missing here. table or data grid is one of them. yes it is difficult to just call a table or data grid in your program and populate it with data from a database.

    Or again , could they already exist without us being aware of it, because they are not documented anywhere ?
  9. Graham

    Graham Developer Staff Member

    YueM,

    I just google for tthe docs because I've read them before and I know approximately where they are.

    I don't keep the details in my head since I don't use VID much at all.

    If you want an easier to use GUI with better documentation, use RebGUI instead. It has a table, and once it had a grid....
  10. Gerard

    Gerard New Member

    Yuem and Graham,

    Yes there are somereal great improvements done to existing styles and user documentation
    outside of RT too like :

    RebGui http://www.dobeash.com/rebgui.html

    Henrik extensions http://www.mail-archive.com/rebol-bounce@rebol.com/msg04635.html
    and his links :
    http://www.hmkdesign.dk/rebol/vid/docs/vid-extension-kit.html
    http://www.hmkdesign.dk/rebol/vid/src/vid-ext-kit.r
    http://www.hmkdesign.dk/rebol/vid/tools/style-browser.r

    Maxim's own alternative Glayout (part of Steel)
    http://www.pointillistic.com/open-REBOL/moa/steel/glayout/glayout-demo.html

    Of them Henrik Extensions seems the nearest to cover my styles needs and his documentation about how to create/add a new style is well done but it's not reasonable to think that this can be done by a beginning or average programmer not familiar with this kind of programming (a bit of View internals knowledge is required to work and extend any REBOL based GUI).

    Just look at how much attributes has his new VID extension dialect !!! What a great job !
    The same is true for Maxim's work and RebGUI authors too.

    Not sure I already have all the necessary knowledge to help create something new like this ...
    for what is missing - like a data-grid for example.

    And I am not sure I can afford all the time required to help Henrik and Maxim test everything as I originally planned to do so.

    I would have preferred to invest my efforts into a semi-automated scripted based system to help automate these tests.
    but REBOL 2 doesn't support the Insert action in the wait-list of events, so I don't know how to ask for REBOL to simulate keyboard and mice actions like a human would do them.

    This can be done easily for other external GUIs but not for REBOL at this time, if I well understood the official View doc.

    Gerard
  11. YueM

    YueM New Member

    Gerard,

    thanks I like the glayout module from maxim. the other problem is that VID for Rebol 3 looks different from Rebol2. so far they can't compete with Swing or .Net widgets which are in a league by themselves, way above Rebol's gui.

    I don't like RebGui, looks too bland, they are "flat" and look like 80s gui, not really 3 dimensional as today's widgets should be. although the docs are better than elsewhere. I think they should improve its look.

    will look at Henry's examples later.
  12. henrikmk

    henrikmk New Member

    Unfortunately the VID Extension Kit is not moving right now, and so is missing some important bits, but as far as I'm concerned, it's the best option for creating large user interfaces, as in the sheer amount of windows, widgets, forms and whatnot that need to be managed. It implements a bit of intelligence in the management of a user interface.

    The problem for VID is less architecture and more the sheer lack of completeness. Carl intended it as a demo of View and thus spent only a week on it back in 2000. It was interpreted as the official GUI, however, and it has just stuck ever since.

    It's just a huge amount of work to provide a decent array of styles for the average user and there are just no complete sets of styles, only patches and a few single styles provided individually by some developers. The problem for RebGUI is a focus on minimalism, so working with large user interfaces becomes tedious, but it has a better array of styles than VID.

    BTW, there are much more in depth docs on the VID Extension Kit at my new server here, and one doc will help you to write styles under standard VID:

    http://97.107.135.89/www.hmkdesign.dk/project.rsp?id=vid-ext-kit&page=docs

    R3 is a different ball-game as it has a different, simpler and much better graphics engine and the shortcomings that R2 View has are not present in R3. It should start moving here in February.
  13. Gerard

    Gerard New Member

    Hi Graham and others,

    VID is not the only subject about which nore could be done for beginners.

    As a new learner of REBOL,

    I found it difficult (and it is yet true for some parts I didn't get the meaning) to get information and programming examples about what tools and answers
    REBOL has to offer to programmers relative to the following particular programming languages concepts, when compared to older, more traditional programming languages.

    For the theoretical information part I would complete it in the Documentation section

    For the coding examples related to the programming part, I would be pleased if they were posted separately - a bit like
    Carl did it with its cook book and others did in many books and tutorials that already exist.

    Here are the themes about which that could be added some specific information to help clarify the whole thing :

    1) Global and synthetic view of the REBOL architecture, generally called a PROGRAMMER'S MODEL ;

    The best image I got about this architecture was found from : http://en.wikipedia.org/wiki/REBOL

    2) The way the main SYSTEM Object structure intimately relates with other parts of REBOL.

    Many advanced programmers often talked about and gave some disparate cues about the following aspects of REBOL
    but almost nothing formal was systematically assembled and sufficiently well organized (from my own POV) to answer the
    needs of newcomers, especially for those already experienced with other programming languages :

    - the multi-layered nature of REBOL itself with all of the paradigms it supports)

    - functional programming support (this is the most easy part since not too much difference with other languages)
    . Nick Antonaccio's web site covers this in good part but projects require so many other knowledge that
    sometimes it is a bit hard to get all this absorbed ...

    - reflexive language with symbolic processing support (data is code duality like some symbolic languages - Lisp and
    Logo) ,
    . Rebtutorial.com does it too but the level is not for the true beginner - it's more appropriate for more experienced
    programmers

    - extensible and prototype based OO (SYSTEM object structure and how incrementally adding/redefining a new word
    relates to the main dictionary structure (binding) on which REBOL is based - like in FORTH),
    . Rebtutorial.com does it again but the level is not for the true beginner - it's more appropriate for more
    experienced programmers
    . The official REFERENCE book helped too but not too many examples - only a single big one was used instead !!!

    - the many existing DIALECTS used and the way they can be intermixed for exchange of data between the many
    parts (SYSTEM object, DO, MAKE object/function, PARSE)
    . The REBOL.ORG library gives some examples but dometimes not so many detailed explanations
    . Rebtutorial references helps for this too.

    - the low-level IO part (IO ports, protocol, scheme) - now a better info is available for R3
    . Nick's RebTris example, Gabriele Santilli's console based and REBOLFORCES REBOLWEEK mags helped me too

    - the Context Sensitive grammar upon which REBOL is based (a good example is the Parse command for creating new
    definitions of already existing words to be used in particular contexts called dialects)
    . REBOL.ORG, old RebSites (now not well maintained - many unusable sites).
    . Carl S., Gregg Irwin amd Gabriele Santilli many dialects as much as RebTutorial helped me.
    . Graham Chiu http://compkarori.com/vanilla/display/rebol-main does a great indexing job too - just discovering it

    For the practical parts requiring examples and explanations in the SMALL, I would have found them most useful when using the different dialects offered, but mostly when using the DO dialect :

    Found that to start-up with, I would have found those themes useful
    (and they could be made more useful if related to other languages similar/related design concepts) :

    Some pedagogical "follow the guide" series like this one would be very useful and appreciated :
    http://peter.michaux.ca/articles/scheme-from-scratch-introduction

    The RebTutorial.com and Nick's web sites like the many existing external forums that exist already partly fulfill these roles but the results don't get easily indexed and grouped together - so they aren't very reusable easily.

    Here are the points I asked myself questions about and couldn't find much info about :

    0- How to use existing/develop new tools (High level debugging/tracing techniques and space/time evaluation
    techniques for better profliing and discovering how REBOL uses the internal resources (stack, memory, CPU)
    1- Local vs global variables scoping for functions and Objects (explicit useful concrete but kept simple BINDING examples) ,
    2- Arguments/parameters passing vs variable sharing
    - default values testing/assignment (if none? vs unless ...)
    - optional params vs refinement use)
    - pass by value, pass by ref, pass by name (for series -> word: value vs set 'word value vs word: copy value)
    3- Addition/redefinition/destruction of words in global dictionary (Set 'word vs bind)
    4- Dynamic modification of objects and other advanced data structures
    - OO based data structures vs Associative lists respective advantages vs conversions from one to the other
    - efficiently implementing and managing Lists of objects
    5- How to design good scripts using REBOL coding style, and its own OO style,
    6- How to use internal and external tools for managing code (Ladislav's, Maxim's and R3 tools),
    7- How to document scripts using literate programming based Wetan (Gabriele's RLP) emitter for MakeDOC 3

    So getting from the PITS (Programming in the Small) to PITL (Programming in the Large) the right way.
    Myself I never developed PITL projects so I have everything to learn about managing code efficiently.

    Don't forget that for getting the best results, the study of new material is often based on small well-defined projects
    (often related to the kind of day-to-day one programmer already did for itself or a customer)

    My 2 cents - based on my own needs.
  14. Gerard

    Gerard New Member

    As a first try to experiment, I would suggest a small project that could talk to many of us.

    It could be called business related but it's not.
    I plan to do it for my own pleasure and leveraging my learning while having some fun.
    In fact if follows the many visits My old mother did last year in near by hospital.
    To my great surprise, the management of the patients transportation system, based on the visits calendar, was and is done manually on paper.

    So I aksed myself if it would be hard to develop some helper functions to help manage more efficiently this situation.
    But neverI planned neither I plan to offer them such an app for some money. It's a simple personal challenge and a good subject for learning REBOL

    Here is a textual description of this proposed project and the reasons I see it a good candidate as short term project for REBOL learning.

    The system will need some minimalist GUI support for entry, even if the first version can be worked without it.
    It is simple enough (5 to 10 data stores - main objects) but offers some possible implementation alternatives based on different data structures (Association lists vs objects lists).
    So for my learning objectives it represents some challenges and a good basis for comparative efficiency/difficulty review.

    I leave it up to you if it can be selected as part of a first learning series. I can drive the series but I will then simply be the secretary, summarizing the questions asked and decisions taken by the group
    during the analysis/design phases. Then we will have to decide (not to be followed in the proposed order by every people) of a main development track to start with.

    In my head the track to be retained should/will be related to the involved difficulty level first and the folowing rewrites should require more advanced knowledge, for efficiency/flexibility/experimentation purposes.
    Then after I plan to keep a log of the decisions taken and the doc that will evolve from the process, so it could later serve as a learning basis for newcomers.

    Here is the summary description of the project : Health Care Transportation Management System

    Some patients have to come to the Hospital for getting one or more interventions each week for many weeks.
    The duration of each intervention can go from 15 minutes to many hours, all being placed consecutively in a single visit, to minimize unnecessary transportations.
    So there is some planning to be done from the transportation system manager since it has to optimize his route taking into account that :

    - Some route must transport the patients that reside not too far apart from each other and have visits placed in a relatively similar time - for keeping them for a minimal time before and after their visit
    (however the automated system has not to decide for itself of the best route od the patient to be taken for a given road - it's done by hand. the system simply has to help the manager to take his decision
    - Each patient resides in a sector of a town and many sectors can be grouped into a region so they can be placed inside a single route.
    - The manager can ask foir some lists and reports to help him plan his routes (patients/sector, patiens/day/time period, etc...).

    During each visit any patient can receive one or more interventions from one or more therapists. Each therapist offers a specific action during his intervention.
    Sometimes it's a simple do-nothing action, at other times it's an observation (examination/evaluation) or a specific therapist related treatment (ergotherapist, nutritionist, physiotherapist, medicine, etc...)

    Each intervention starts and ends at a precise time point and some separation has to be done between the planned proposed intervention and the one that is really implemented.
    Furthermore each intervention can be cancelled (abandoned), moved to another visit or replaced by a new intervention. The intervention can also be implemented by another therapist when the planned one is unavailable.

    Normally on file opening one therapist is assigned to each new patient. Another therapist can be substituted for the first one in case the first one is absent for a long period of time.

    Each therapist daily calendar is reported on a big global weekly calendar that is updated daily and serves each friday as the basis for the transport planning of the next week.
    Then the transportation manager calls, the day before each route has to start, each patient that wiil be part of every route, giving him or her the time he will take her from his/her home to get it to the Hospital and the time he will be back home.

    Say it will be sufficient for the moment.
    If you are interested, I could plan on some first data structures and operations and we could interactively state on the one which will be retained to start with.

    For example, for each patient, we'll need a serial ID generated by the system (this is a constraint I impose since this is an interesting frequent useful feature to implement),
    and then some place to keep his assigned main therapist (on file opening), his status, his planned/implemented/suspended visit dates with start/end times (they will be deduced from the individual intervention dates/times coming from the main calendar),
    all with the sector where the patient lives in and the route number that has been manually assigned to the patient.

    For the moment I plan to store separately every intervention details for each visit. However plans to easily modify every data structure later should be taken into account from the start.
    This generally helps to choose the data structures that will better support this kind of modification.

    If anybody has some ideas to share with me and other members for discussion about the conceptual data items required to support this design, I would like to know how we can discuss them here without
    getting into to much details. May be we can discuss these details in a separate Thread called "Health Care Project : Design Alternatives"

    Not sure if this all of these are required but I already drafted some Table-based (or Class-based) design (relational or object model) with columns (attributes) list for each table/object.

    Here is the first list that can be used as a start point and discussed/changed/validated/adopted :

    - Patient : Patient-Sid, Hospital-Id, name, Therapist-Id , address, sector, status
    - Therapist : Therapist-Sid, Name, [Cares], [In-dates, Out-dates], [Patients]
    - Visit : Visit-Sid, Patient-Id, Therapist-Id, date, status
    - Action : Action-Sid, Visit-Id, Planned-date, Planned-Care-Id, Planned-status, Planned-begin-time, Planned-End-time, Implementation-Care-Id, Implementation-Status, Implementation-Begin-time, Implementation-End-time
    - Care : Care-Sid, description
    - Route : Route-Sid, description, [sectors]
    - Transport : Transport-Sid, Date, Start-time, End-time, Route-Id, [Patient-Ids]

    Regards,
    Gerard
  15. Graham

    Graham Developer Staff Member

    Gerard,

    You've been posting to the rebol mailing list for about 5 years now.

    If you wanted to learn Rebol I would have thought you would have done so by now.
  16. Gerard

    Gerard New Member

    Just for your information - I found some analysis for a similar old project on which Martin Fowler worked on in 1992, before the advent of the UML.
    His model is a lot more elaborate Health care project.

    The one I proposed here to start with has no accountability part and is different too from what I have to manage here.
    The proposed model and his accompanying doc can be found at : http://rewrite.rickbradley.com/articles/2006/07/06/cosmos-documentation/
    This helpmed me to better describe the parts I am concerned with.

    I plan to post my first trials to get a prototype based Serial-Id Object that can be reused as a start Object (kind of Class) by all the other objects I created requiring a Serial-id generator.
    This will be the first point about which I would like to get some discussions - is this the better way to proceed and if not what are the alternatives that could be used instead.

    In general the problem of Serial-id generation was solved - before the advent of OO - by getting an external storage container for the many Serial-id counts, like some environment variables in a file.
    Then when some new id was required that could start after the last generated number, al was needed was to retrieve the last value stored for this id and add one to the count then storing back this new value toi the container.
    I then tried to get this functionality using objects and in-memory storage. It will then be necessary to store all of this when the program will be stopped so as to be able to keep and restore the serial-ids already generated.

    I'll post my first version of this experiments today so we'll have something to discuss about if someone needs to do.
    But don't wait. Try your foryour own solution. It doesn't matter if it si done using only functions without using Objects.
    I simply choosed this way to learn about objects and how I could manage them using the REBOL way.

    Regards
    Gerard

    PS. In fact I didn't looked at the best way to attach some scripts contents here for sharing.
    Graham, did you plan some preferred mechanism to do so ?
  17. Gerard

    Gerard New Member

    Hi Graham,

    Since 2000 in fact I tried to get in touch with REBOL for many times but my bad Health never helped me since the medication (Lithium) my employer forced me to take until 2006
    was not appropriate and it kept me drowsily 20 hours a day while my reasoning and memory took a bad time too. I was simply no more able to leanr anything even if I wanted to do so.

    Nevertheless, sinc then I got many personal and family problems and then I think I am dolid enough to get back. In fact if I am able to require some help for precise points and give back to
    others too in the process, this is for me a good sign that I'm now able to accept the challenge.

    Don't be fooled by my too long learning time - I heard a lot in the past about many people that also got good intentions but left without being able to cope with the specific knowledge REBOL requires.
    I thought I summarized these facts in my previous post.

    Also know I'm of the perfectionnist kind of people. I dislike to have doint things when I know I didn't do them the right way in the first time. So I'm asking a lot before trying them myself.
    For sure I could simply continue to program using the functional paradigm REBOL offers but then may be I will miss a lot of what REBOL has to offer to support me becoming a better programmer.

    And to finish with - without having to find myself some additional justification - I never got a formal CS curriculum before getting to REBOL. However this tool-kit and the many concepts required to get
    the full use of the many tools REBOL offers require such a knowledge I also have to acquire before I can use them to their maximum. So much to read and learn in parallel that I had some difficulty
    to keep all of this stuff together.

    But now I have got sufficiently to express myself what is missing and what I now catched on sufficiently to begin with some serious but small project.

    Please don't forget that if my questions and the exchange of information that I hope should follow the examples I plan to use to start with permit to put together some new concise and additional material
    that was missing in some way before, I will have got all my own objectives - the last one is sharing my knoledge with others so they could had a better start-up than I did.

    Regards,
    Gerard
  18. Graham

    Graham Developer Staff Member

    To my mind, learning is by doing. You can read as much as you like but that's only book knowledge.

    So, starting a real project as you are now is the real first step to learning how to program in Rebol.

    as an alternative for a serial id, I would consider using a UUID generator.
  19. Gerard

    Gerard New Member

    Graham,

    I agree entirely your POV as I always recommended my own students to DO rather than only READ or speak about what they learn, and this is the reason I submit this project for helping others to start. As far as I know I'm now able to do it by myself, event if it will never be as good as it could be without comments and suggestions from others.

    Even your suggestion to use a UUID generator intrigues me sinc I never heard this term before. So this is the sort of thing I would never knew if you didn't suggest it to me. No problem if I have to read about it before trying it, it's a normal learning process. the important thing is that may be in the end I will use this UUID generator instead of creating my own serial-id generator.

    In any case, it was fun to me to recreate this part, using REBOL.

    In ANOTHER order of idea, if someone is interested in going after what a FSM is, how it works and how it is somehow related to Regular expressions, all driving to a better knowledge of the PARSE Grammars as used by REBOL, let me suggest the marvelous first chapter written about Automata, in the MIT books trilogy by Brian Harvey, a famous teacher using both Scheme (a Lisp variant) and Logo. This book called Computer Science Logo Style Volume 3 - Beyound programming can be found at :
    http://www.eecs.berkeley.edu/~bh/v3-toc2.html

    Hope this will be of interest to any person needing more formal stuff about parsing, especially well explained in an informal and clear style. I now have to adapt his fsm program to REBOL to test my deep understanding of his work.

    Regards
    Gerard
  20. YueM

    YueM New Member

    henrik, gerard, thanks for the link for the various documentation, they are great.

    gerard, the reason I was starting with vid, is that I believe that a good gui is a good selling point for a language. that's how VB became so popular, and that's why java failed when it started, even now , quite a lot of people still dislike swing.

    actually you seem to know more about Rebol than you sound, at least to me who is a complete beginner, and you seem to have thought a lot about the language. those things you are trying to do are going to help the documentation for sure.

    I believe you should publish your thoughts on alt me as well, there are a lot of knowlegeable and active people there, who have the depth of knowledge to help. the reality is not many of those knowledgeable people are on this site. apart from Henrik and Graham who are active on the rebol front. and where do you plan to publish your docs ?

Share This Page