Making it easier for new users

A lot of the discussion on the "Try REBOL 3" blog was a bit off topic. Somehow a thread got started about the problems new users face and how certain simple actions are done. For example, how do you translate a character into its numeric representation?

Many of the questions were answered quite well by other users... but it does raise two questions in my mind:

would there be some value in a translation glossary?
do we need a "starter-kit" that includes helper functions?

Translation glossary

On the first, I'm thinking along these lines: a bunch of us in the community could build a web page on the wiki with a glossary such as:

In Perl	In REBOL	Description
chr(integer);	to char! integer	convert an integer to its character representation
ord(char);	to integer! char	convert a character to its numeric representation
localtime(time());	now	get the client system's current time and date
$value[5]+1900;	value/year	for a date value, return the year integer
etc	etc	etc

Starter kit?

For the starter-kit, we could provide a module of common functions to do things that users have done other ways in other languages. I've been reluctant to do that in the past, because it allows users to avoid learning the best way to do such things.

But, for example, consider the substr function that is used to copy part of a string.

In REBOL we do this with:

str: copy/part start end

where start and end are the series indexed to the range over which the copy should occur (but end can be an integer length as well.) What's important here is that you can see that this is a copy, and you can use copy various ways.

A user familiar with substr from some other language would want to write:

str = substr(fullstr, index, length);

Of course, the user may not consider where the index came from or how the length was determined. For example, the index is quite often the result of a search:

str: copy/part find fullstr "xyz" 10

or, using the substr function:

str = substr(fullstr, strpos(fullstr, "xyz"), 10);

So, that's what's really going on most of the time. Examples shown in manuals of:

str = substr("abcde", 3, 2);

never actually happen in real code. Most of the time, you need to call other functions to get the required arguments.

Hmmm....

Well... now that I've written this example... perhaps it's better just to add that to the glossary table. It's probably better that users truly learn what a series is, and not use index numbers everywhere.

Please share your thoughts on this topic. And, if you know of a web page that already includes this information, post it, and we can add it to the main docs page.

28 Comments

Updated 14-Nov-2024 - Copyright Carl Sassenrath - WWW.REBOL.COM - Edit - Blogger Source Code