Up to Main Index                             Up to Journal for April, 2025

                    JOURNAL FOR SATURDAY 12TH APRIL, 2025
______________________________________________________________________________

SUBJECT: Re-writing the Mere ICE tutorial
   DATE: Sat 12 Apr 18:45:44 BST 2025

> Quick side note: Recent efforts have primarily been focused on job hunting.
> Unfortunately, there is a frustrating lack of responses to my applications.
> No rejections, just silence. I have a short window of four working days
> remaining and haven’t yet secured any interviews. If anyone reading this has
> leads for a 100% remote Senior or Lead Go developer role, particularly
> involving LLMs and AI integration, I'd greatly appreciate a connection.

When I built the Mere Interactive Code Environment, Mere ICE[1], I was quite
pleased with it. It was a valuable learning experience being my first time
working with WebAssembly. I saw Mere ICE as being successful in that it
provided a platform for people to learn about Mere and experiment with my
programming language.

I now have the Mere rewrite, codename Mote, and I am starting to look at Mere
ICE with a more critical eye for a re-release. One of the things I really
wanted to do with the initial version was to have a proper interactive
tutorial. However, I hadn't developed my wasm skills enough at the time. What
I ended up with was the tutorial written in source code comments and the code
could be executed. It worked, but it wasn't a great user experience.

I have started re-writing the tutorial for the Mere rewrite re-release. But
what do I want from the new tutorial? I have a few goals:

  • Tutorial should be proper web pages, not source in the editor.
  • The tutorial should have live editable, executable examples.
  • Allow multiple examples per page.
  • It should look nice and fit the WolfMUD website style.
  • Tutorial and examples must be easy to write and low maintenance.

I've already been building. Here is a sneak peek, a screenshot from a working
page of the new tutorial: ./screenshot1.png

I think I've managed to achieve the easy to write and low maintenance goals as
well. For the screenshot above the HTML behind it is:


    display the values with a temporary debugging printf to try and work out
    where the mistake is.

    <code data-rows="2">
    x = 10.0
    y = 20.0
    p = (y/x) * 100.0
    printf "DEBUG: %g is %g%% of %g." x p y  # Our debugging line
    </code>

    <blockquote class="try">
    We have a bug, 10 should be 50% of 20. In the above code our equation is
    wrong. It should be "(x/y) * 100.0". Try fixing the code and running it
    again.
    </blockquote>
    <blockquote class="tip">
    TIP: It is a good idea to use a marker, such as "DEBUG", when using
    debugging print statements. You can then search for your marker using your
    editor to make sure all of the debugging code is removed once the program
    is working.
    </blockquote>

    Assert The Value Of Variable
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Another debugging technique is to assert what value a variable should be
    set to. Below is the same code from before. This time we assert the
    percentage should be 50.0, however if you run the code the assertion fails
    showing us there is a bug.

    <code data-rows="1">
    x = 10.0
    y = 20.0
    p = (y/x) * 100.0
    assert p 50.0
    println "Okay"
    </code>

    <blockquote class="try">
    As before, correct the equation. The assert should no longer fail and we
    should see "Okay" displayed.
    </blockquote>


I don't think I can make the pages of the tutorial simpler than that. The code
is in <code></code> blocks. There are call-outs for "try this" and "tips"
sections using <blockquote></blockquote>.

Unfortunately, even with includes, there is quite a bit of boiler-plate at the
start of each page. By the way, I am hand-coding everything - no frameworks.

If JavaScript is not enable there is a nice fallback. The only feature missing
is the editable and executable code. Here is a screenshot of the same examples
but with JavaScript disabled: ./screenshot2.png

For the main Mere ICE - the full page editor - I have a version up and running
already. It's a work in progress. I'm not quite ready to showcase it yet as
the design is in a lot of flux and I'm concentrating more on the tutorial.

It's going to take a while to rewrite the current tutorial. This shouldn't be
too bad if I polish the first few pages. Then I can use them as templates for
the rest of the tutorial. I also need to update the new tutorial to include
all of the changes from the Mere re-write.

By the time I'm finished I should end up with a nice little showcase :)

--
Diddymus

  [1] Mere ICE: /annex/mere


  Up to Main Index                             Up to Journal for April, 2025