Terminology MAP

Site Feedback
1

Hi Hostile Fork,
Ren-C has a lot changes and new features but it is hard to follow what has been changed/created, and the discussion that led to the development of a feature, from start to end.

To help undestand your project, could I ask to add a page or a post where you list all additions like: ANTIFORM, BLANK, ISOTOPES and a brief description. Also, it would be great to have a link to the introductiory post to each feature (like UPARSE) and all the subsequent posts regarding the design. This could be done either via a direct link to the introductory post for the new feature, and also filtering via TAG and DATE using tags like #ANTIFORM #DESIGN

Thank you

2 Likes
2

So I'm aiming at what you suggest--even going as far as to reorganize the posts here "wiki-style" to cull dead-ends, and make start-to-finish design summaries.

For example:

The History of Multi-Return in Ren-C

Doing this maintenance is an ongoing task... and I can't stop working on things to do focus solely on documentation. But if there's something specific you are curious about, I can raise the priority of organizing the information here on that topic better.

Using tagging on the forum more effectively is a good idea. But there are also categories, and there is a Feature Discover one which could be better.

For now...I can give you a couple of quick pointers that should be plenty to occupy you. (You can try Ren-C in the browser at the online ReplPad, but please do not advertise it to the world at large. It is not meant to be published broadly yet.)

Isotopes and Quasiforms/Antiforms are explained reasonably well. READ THIS CAREFULLY:

A Justification of Generalized Isotopes

As for UPARSE, the best place to get a sense of what it can do is probably the tests. Each combinator has its own file:

https://github.com/metaeducation/ren-c/tree/master/tests/parse

It could be made somewhat easier, but understanding is always a fundamentally hard thing.

Regardless of how much work I put into documenting, understanding requires patience... putting in effort... and asking questions when you don't understand.

I think you will find it very worth it. The details are addressing important points... including this one from you (as I've mentioned before) that you brought up in Red Gitter (archive.org link, as I guess Gitter scrapped their history...lovely)

"When code is data and data is code, sometimes you can't distinguish a situation from a value:"

>> a: [b c #[none!]]

>> probe type? probe pick a 3 
none
none!

>> probe type? probe pick a 10
none
none!

"None is returned either as an element picked from a block and when we are out of the boundaries. In any function of this kind, you have to create another one to check if we are in a situation that returns None. It's just a personal thought spoken out instead of remaining in my mind."

Couldn't have said it better myself. And this is why things like antiforms exist, which can't be put in blocks. But then that raises the question of what your options are when you want to put a representation of that state in the block... which is why quasiforms exist.

 >> a: [b c]

 >> pick a 3
 == ~null~  ; anti

 >> append a null
 ** Script Error: append expects [~void~ element? splice?] for its value argument

 >> append a meta null
 == [b c ~null~]

 >> pick a 3
 == ~null~

 >> null? pick a 3
 == ~false~  ; anti

 >> unmeta pick a 3
 == ~null~  ; anti

 >> null? unmeta pick a 3
 == ~true~  ; anti

If you think Rebol-family languages are interesting, I see almost no way to not find Ren-C interesting. But somehow the Red people accomplish it. There's a difference...

"It is difficult to get a man to understand something, when his salary depends on his not understanding it."
-- Upton Sinclair

"Convictions are more dangerous enemies of truth than lies"
--Friedrich Nietzsche.

3

Thank you for the links. Waiting to see other "start-to-finish" containers of design messages for a topic. However a single page in alphabetical order (and eventually sortable by date) of all these messages is needed as index.

Also, it was interesting to see my gitter message from the past with this specific problem. Thank you!

I will study what you already have written to uderstand the whole design choices. Looking forward to see them.

4

I agree with this. Several times now I’ve been thinking of something, only to discover that it’s already been thought of and answered — but not in an obvious place. It feels like Ren-C’s design is slowly becoming more stable, so I feel an index would be really helpful.

1 Like
5

@GiuseppeChillemi Note that it's not actually clear to me what the terms are beyond isotopic ones that you don't know, and a few posts I've linked (or that are easy to find) cover these. :-/

I'm all for better and more organized documentation. But I'm going to insist that it be done on a more "as-needed basis" at this moment in time. I will find a place where what you are curious about in that moment is documented, improve if necessary (or make documentation if none exists), and provide you the link.

I've made a chat channel for this purpose: #usage-chat

Think of it like using an AI search engine vs. a traditional one...which is what the world is going toward anyway.

What I want before going on a documentation binge is to ensure whatever is written is in a verifiable format, where embedded code samples can be checked by CI tests.

A long while ago, I tried to use Trello to document things. It's completely and fully out of date at this point:

Rebol 3 Porting Guide (Ren-C Branch)

HOWEVER I really did like Trello's UI for editing and arrangement, and I think it's a good tool for this kind of "glossary" / "overview".

What I don't like about it is that there's no verification process for making sure any code samples given there are kept working.

So if I was going to invest into that again, I wanted some Rebol code that would scrape and validate it... as well as back it up in a non-proprietary format. (@Brett had some Trello API-using code, and I did do a demo of embedding a card in in the Web Repl at one point...since we're looking for examples of Brett's code to rewrite in Ren-C and add to CI, maybe the Trello lib is a useful candidate.)

6

Responding to your post there:

At least for me, it’s not about ‘finding information I want’. (Generally if I’m looking for something, I have few problems finding it.) The problem is that I don’t know what’s out there in the first place — as they say, I don’t know what I don’t know. An index summarising the advances Ren-C has made would be very helpful in that regard.

7

Yes, thats the idea. The first thing needed is a list of what has been added/changed (in MACRO way, not in details). Then add short description on its side. Having it as a base, you could start adding "chapters".