How to get feedback/comments on documentation pages

I've been using GitHub pages and "Jekyll" to build a couple of websites, including the one for the C++ validation used by Revolt:

At the bottom there's an "edit this page" button, which takes you to the GitHub page editing. (It tells you that you need to fork the repository to propose changes if you're not a member of the repo.)

The Needful documentation also demonstrates testing the code to make sure it works. On each commit, Python scripts extract the C code portions and read some labels on it saying what expected error messages are--or if things are supposed to be successful that there is no error. In the case of Needful it's tested on several platforms and under several language standards... Revolt should be easier (I hope).

Anyway, the static site build is a moment in time we can check a current executable as having the behavior shown in the examples. I think we can clone this approach and begin a serious effort at help documentation, NOW.

Jekyll is Markdown-based, and there's something called "front matter" that lets you establish some boilerplate YAML which is structured data you can use to organize the static site build. So if the help page is for a native, we can put the native spec in the front matter...and even use Revolt itself to analyze that spec.

It's Time For It, My Mind Isn't Indexing It All Any More

Let me give you an example. DELTA-TIME had stopped working, it was written like this:

/delta-time: func [
    "Returns the time it takes to evaluate the block"
    block [block!]  ; callsite FENCE! evaluates to BLOCK!, wrapped
][
    let results: reduce reduce [  ; word lookups first, run fetched
        lift now:precise/
        elide/ (as group! block)
        lift now:precise/
    ]
    return difference results.2 results.1
]

It's written like this because it is trying not to mix paying for word/chain lookups with running the code.

e.g. let's say your code you're timing is delta-time [1 + 2]. The first thing that happens is it does a set of things it doesn't time, that's turning now:precise/ into a specialized ACTION!...

>> now:precise/
== \~&[frame! [
    year: ~null~  ; hole
    month: ~null~  ; hole
    day: ~null~  ; hole
    time: ~null~  ; hole
    zone: ~null~  ; hole
    date: ~null~  ; hole
    weekday: ~null~  ; hole
    yearday: ~null~  ; hole
    utc: ~null~  ; hole
    local: ~null~  ; hole
]]~\  ; antiform (action!)

You can't store that in a block, but it auto-decays to a plain FRAME!. The same happens to ELIDE. So without having any of this count in the timing, we get:

let results: reduce [
    &[frame! ["now" ...]]
    &[frame! ["elide" ...]] (1 + 2)
    &[frame! ["now" ...]]
]]~

No lookups required here (outside of any lookups you were trying to time) and the REDUCE just stays inside the native. FRAME! evaluates by calling the function.

But it didn't work, because REDUCE rejected the VOID! produced by ELIDE instead of erasing it.

Having not done anything with the language since May, I completely forgot why REDUCE doesn't just erase VOID!

The rationale is actually found in a post in Archive:

And there's a post which presents the "correct" alternative of using JOIN BLOCK!, so as to keep the "religion" of N-expressions in, N-values-out for REDUCE:

Plus a related question about whether predicates should run on VOID! in REDUCE (also moved to Archive):

But the behavior and examples should be on the REDUCE documentation page. It's fine to link to the forum for those who want to read the deep reasons of "why" but people who want vanishing in REDUCE need to be told that it doesn't do that and they need JOIN.

This Should Happen Before Going Further

It's time, and the AI are here to get the job done. I can ask them to follow the pattern used for Needful.

The test suite has atrophied in a big way and I've been on the fence about where I should try to fix the tests vs. where I should accept that there are large parts of the system that I don't really care to fix, because those are no longer important features. Or they are experiments that pushed the system in ways that it no longer makes sense to push it... when the "big" discoveries about binding and isotopes are the real focus of the efforts now.

1 Like