Chaos overhaul

doc/onboarding.md

@@ -9,15 +9,16 @@ Unless otherwise specified, all commands we ask you to run are supposed to be
 run in a Terminal emulator using a shell like Bash or Zsh (on Linux and macOS)
 or in Git Bash (on Windows). Anything you have to fill in with the proper
 information for your setup (as opposed to execute verbatim as shown) is
-enclosed in brackets `[]`.
+enclosed in brackets `[]`. MacOS specific instructions appear at the end of
+steps where they apply, preceded by "_Mac_:"
 
 ## Accounts, etc.
 
-(Steps 2 and 3 only apply to the members of the Numberscope project at the CU
-Boulder Experimental Mathematics Lab.)
-
-1. If you don't have an account, sign up for [GitHub](https://github.com).
-2. Make sure you've been added to the Numberscope GitHub organization.
+1. If you are planning to contribute code and don't have a GitHub account,
+   [sign up for one](https://github.com).
+2. For members of the Numberscope project at the CU Boulder Experimental
+   Mathematics Lab only: Make sure you've been added to the Numberscope GitHub
+   organization.
 
 ## Setting up your computer for development
 
@@ -31,55 +32,103 @@ Boulder Experimental Mathematics Lab.)
     - TypeScript Vue Plugin (Volar)
     - Vue Language Features (Volar)
 
-    For more info on extensions, see:
-    https://code.visualstudio.com/docs/editor/extension-marketplace.
+    For more info on extensions, see the Visual Studio
+    [extension marketplace](https://code.visualstudio.com/docs/editor/extension-marketplace).
 
 2. If you don't have [Git](https://git-scm.com/) installed, install it. We use
-   Git to keep track of the different versions of our code.
+   Git to keep track of the different versions of our code. _Mac_: The easiest
+   way to install Git is to install the Mac "developer tools." You can do so
+   by opening Settings > General > Software Update and then (in a terminal, as
+   mentioned above) executing `xcode-select --install`. Then follow the
+   prompts in the Software Update window; your computer may need to restart
+   for the changes to take effect.
 3. If you don't have [NodeJS](https://nodejs.org/en/) installed, install it.
    NodeJS allows you to run JavaScript outside of a web browser. We use it in
-   our front end code base.
+   our front end code base. _Mac_: You can obtain Node by first installing the
+   "node version manager" via:
+
+    ```
+    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
+    ```
+
+    [Note that you may need to change the `v0.40.2` portion of the above URL
+    to the latest version of nvm; it was current at the time of this writing,
+    but you can always find the latest release on its
+    [GitHub page](https://github.com/nvm-sh/nvm/releases).] Now either log out
+    and log back in for the nvm installation to take effect, or instead just
+    execute `. ~/.nvm/nvm.sh`. Finally, to install Node, choose the version of
+    Node you want (latest was 23 at the time of this writing, but you can
+    always look up the
+    [available releases](https://nodejs.org/en/about/previous-releases)). Then
+    execute the command `nvm install [DESIRED_VERSION]`, e.g.,
+    `nvm install 23`.
+
 4. Make sure you have [Make](https://linuxhandbook.com/using-make/) installed.
-   There's a guide for Linux on that page; or you can try these other links
-   for
-   [Windows](https://stackoverflow.com/questions/32127524/how-to-install-and-use-make-in-windows)
-   or [MacOS](https://stackoverflow.com/questions/1469994/using-make-on-os-x).
-5. If you don't have [Python 3](https://www.python.org/) installed, install
-   it. We use Python in frontscope for our documentation site.
-6. Make sure you have a `venv` module by running the following command:
-    ```sh
-    python3 -m venv -h
+   There's a guide for Linux on that page; or you can try this link for
+   [Windows](https://stackoverflow.com/questions/32127524/how-to-install-and-use-make-in-windows).
+   _Mac_: Unfortunately, the version of `make` that Apple includes with its
+   developer tools is too outdated to work with frontscope. Therefore, you
+   must compile and install a more recent version of `make`. One relatively
+   simple way to do this is to install the "Homebrew" package management
+   system for MacOS, via
+
+    ```
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
     ```
-    You should see help for the `venv` module. If you don't you might have to
-    install the module separately. How you do this depends on your system and
-    might require some googling. We use `venv` for a "virtual environment". In
-    this context, a virtual environment is an empty box, a clean slate, for
-    all of our Python dependencies. It makes it so that we can use the exact
-    dependencies we list in `requirements.txt`. All of the dependencies in
-    `requirements.txt` are installed into a subdirectory in the `.venv`
-    directory. Once you activate a virtual environment, all of the Python
-    commands you run are run using the dependencies in the virutal
-    environment, and not the dependencies you installed elsewhere on your
-    computer.
-7. Somewhere on your computer, make a directory where you can keep Numberscope
+
+    (Note this command will require administrator access to execute.) When
+    that completes, it will print out some commands that you should execute to
+    finish providing access to Homebrew. Once those are done, you can install
+    the current version of `make` with the command `brew install make`. When
+    it's done, it will print a message about what you need to do to use it as
+    "make"; you don't need to worry about this, as frontscope already uses it
+    as "gmake".
+
+5. _Mac_ (only): The version of the Gnu "bash" command interpreter installed
+   in MacOS is also too outdated to work with frontscope. As a result, you
+   must install a current version. If you installed Homebrew in the previous
+   step, you can perform this installation with `brew install bash`.
+
+6. If you don't have [Python 3](https://www.python.org/) installed, install
+   it. We use Python in frontscope for our documentation site.
+
+7. Make sure you have a `venv` module by running the following command:
+   `python3 -m venv -h`. You should see help for the `venv` module. If you
+   don't you might have to install the module separately. How you do this
+   depends on your system and might require some web searching. We use `venv`
+   for a "virtual environment". In this context, a virtual environment is an
+   empty box, a clean slate, for all of our Python dependencies. It allows us
+   to use the exact dependencies we list in `requirements.txt`. All of the
+   dependencies in `requirements.txt` are installed into a subdirectory in the
+   `.venv` directory. Once you activate a virtual environment, all of the
+   Python commands you run use the dependencies in the virutal environment,
+   and not the dependencies installed elsewhere on your computer.
+
+8. Somewhere on your computer, make a directory where you can keep Numberscope
    code. I like to put a directory called `Code` in my home directory. You can
    call this whatever you want.
-8. Clone the official github repository:
+
+9. Clone the official github repository:
+
     ```sh
     cd [/path/to/your/code/directory]
     git clone https://github.com/numberscope/frontscope.git
     ```
+
     If you have trouble, read
     [this doc](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
-    or ping someone for help.
-9. If you plan to submit new code to become part of Numberscope at some time
-   in the future, _you must_ also "fork" (make your own copy of) the
-   repository:
+    or ask someone for help.
+
+10. If you plan to submit new code to become part of Numberscope at some time
+    in the future, _you must_ also "fork" (make your own copy of) the
+    repository:
+
     - Go to https://github.com/numberscope/frontscope.
     - Click the "Fork" button (in the upper right as of this writing) and then
       follow the instructions GitHub provides. You need to create the fork on
       your GitHub account.
-10. If you are going to submit new code, you will also need to run the
+
+11. If you are going to submit new code, you will also need to run the
     standard tests of the system with your changes in place, and likely add
     new tests for your changes. Running tests requires that you have
     [Docker](https://www.docker.com/) installed on your system. There are many
@@ -88,24 +137,27 @@ Boulder Experimental Mathematics Lab.)
     [Ubuntu Linux](https://linuxconfig.org/quick-docker-installation-on-ubuntu-24-04),
     and
     [Mac OS](https://thesecmaster.com/blog/installing-docker-desktop-on-macos).
-11. Go to the newly cloned `frontscope` directory and install the
+
+12. Go to the newly cloned `frontscope` directory and install the
     dependencies:
+
     ```sh
     cd frontscope
     npm install
     ```
+
     You need NodeJS installed to do this.
-12. Run the development server (this runs a local copy of Numberscope on your
-    computer so you can interact with the webpage):
-    ```sh
-    npm run dev
-    ```
-    This should print a link that you can open in the browser. Open it and see
-    if Numberscope seems to be working.
-13. If you plan on contributing code to Numberscope, _you must_ work in your
+
+13. Run the development server (this runs a local copy of Numberscope on your
+    computer so you can interact with the webpage): `npm run dev`. This should
+    print a link that you can open in the browser. Open it and see if
+    Numberscope seems to be working.
+
+14. If you plan on contributing code to Numberscope, _you must_ work in your
     fork on a dedicated feature branch. To learn how to create a branch, see
     [this doc](working-with-git-and-github.md#create-a-branch).
-14. Finally, before you start changing code, please read
+
+15. Finally, before you start changing code, please read
     [our docs on submitting a pull request](../CONTRIBUTING.md#submit-a-pull-request).
 
 See [the doc on running from source](./running-from-source.md) for more

doc/running-from-source.md

@@ -11,6 +11,11 @@
     install the venv module with a command like `apt install python3.11-venv`
     (you may have to replace the "3.11" with the version that is currently
     running in your installation).
+
+    If you are working under MacOS and would like more detail on how to set up
+    all of these tools, take a look at the Mac notes in the
+    [onboarding](onboarding.md) page.
+
 2.  In addition, if you want to build the documentation website for the
     `frontscope` system, you will need the [d2](https://d2lang.com) diagram
     generation software installed on your system. This step is not necessary

doc/visualizer-in-depth.md

@@ -494,6 +494,24 @@ browser, often with the JavaScript `Event` structure as shown.
 !}
 ```
 
+### Display a simple informational popup
+
+As a convenience and to prevent code duplication among Visualizers derived
+from P5Visualizer, the base P5Visualizer class provides a simple informational
+popup/tooltip facility, via the following instance method:
+
+`this.simplePopup('Display me', [atX, atY])`
+
+-   Shows the popup with the given text ('Display me' in this example) at the
+    given X and Y coordinates (here `atX` and `atY`). If the text to display
+    is empty (the default), hides the popup instead; thus, you can simply call
+    `this.simplePopup()` to hide the popup. The popup starts invisible and
+    will not be displayed unless/until there is a call to this method with a
+    non-empty first argument.
+
+The popup is styled to coordinate with the overall frontscope visual design;
+there is not currently any mechanism to alter its styling.
+
 ### How to report errors
 
 There are three ways to let people interacting with a visualizer know that

etc/Makefile

@@ -1,7 +1,7 @@
 .RECIPEPREFIX = |
 .PHONY: FORCE playreport phony typecheck vueserve docserve preview prettiest
 
-SHELL = /bin/bash
+SHELL = bash
 
 sources != shopt -s globstar && echo src/** index.html
 docs != shopt -s globstar &&\

package.json

@@ -9,7 +9,7 @@
         "help:dev-1": "echo Compiles frontscope and starts a server running it.",
         "help:dev-2": "echo Note the server will hot-reload the code from any",
         "help:dev-3": "echo source files as they change, to ease development.",
-        "dev": "make -f etc/Makefile vueserve",
+        "dev": "gmake -f etc/Makefile vueserve",
         "help:dev:workbench": "run-s -s help:dev:workbench-*",
         "help:dev:workbench-1": "echo Compiles frontscope and starts a server running it in workbench mode,",
         "help:dev:workbench-2": "echo \"with the visualizers in the 'visualizers-workbench' directory loaded.\"",
@@ -19,7 +19,7 @@
         "help:doc:serve-1": "echo \"This is like the 'dev' script, but for the\"",
         "help:doc:serve-2": "echo embedded documentation rather than the",
         "help:doc:serve-3": "echo Numberscope interface itself.",
-        "doc:serve": "make -f etc/Makefile docserve",
+        "doc:serve": "gmake -f etc/Makefile docserve",
         "help:doc:serve:workbench": "run-s -s help:doc:serve:workbench-*",
         "help:doc:serve:workbench-1": "echo \"This is like the 'dev:workbench' script, but\"",
         "help:doc:serve:workbench-2": "echo for the embedded documentation rather than the",
@@ -29,20 +29,20 @@
         "help:build:1": "echo Compiles frontscope and minifies the result,",
         "help:build:2": "echo producing a bundle ready for installation",
         "help:build:3": "echo on a server.",
-        "build": "make -f etc/Makefile",
+        "build": "gmake -f etc/Makefile",
         "help:preview": "run-s -s help:preview:*",
         "help:preview:1": "echo Runs build and then serves the resulting site",
         "help:preview:2": "echo \"(the contents of the 'dist/' directory) \"",
         "help:preview:3": "echo for you to browse. This script differs from",
         "help:preview:4": "echo \"'dev' in that there isn't any hot module\"",
         "help:preview:5": "echo reload. It is what runs in production.",
-        "preview": "make -f etc/Makefile preview",
+        "preview": "gmake -f etc/Makefile preview",
         "help:preview:cmd": "echo Previews w/o rebuild; needed for e2e tests.",
         "preview:cmd": "vite --config etc/vite.config.ts preview",
         "help:test:unit": "echo Typechecks and runs unit tests.",
-        "test:unit": "sh -xc 'make -f etc/Makefile testunit \"cl_args=$*\"' phony",
+        "test:unit": "sh -xc 'gmake -f etc/Makefile testunit \"cl_args=$*\"' phony",
         "help:test:e2e": "echo Runs end-to-end in-browser tests via Docker.",
-        "test:e2e": "sh -xc 'make -f etc/Makefile e2e/certificate \"cl_args=$*\"' phony",
+        "test:e2e": "sh -xc 'gmake -f etc/Makefile e2e/certificate \"cl_args=$*\"' phony",
         "help:test:e2e:cmd": "run-s -s help:test:e2e:cmd-*",
         "help:test:e2e:cmd-1": "echo Runs end-to-end tests directly.",
         "help:test:e2e:cmd-2": "echo However, note that it does not rebuild",
@@ -52,13 +52,13 @@
         "help:test:e2e:cmd-6": "echo use by other scripts.",
         "test:e2e:cmd": "playwright test -c e2e/playwright.config.ts",
         "help:test:e2e:report": "echo Runs e2e and opens report in browser",
-        "test:e2e:report": "sh -xc 'make -f etc/Makefile playreport \"cl_args=$*\"' phony",
+        "test:e2e:report": "sh -xc 'gmake -f etc/Makefile playreport \"cl_args=$*\"' phony",
         "help:test:e2e:ui": "echo Runs interactive end-to-end tests directly.",
         "test:e2e:ui": "npm run build && npm run test:e2e:cmd -- --ui",
         "help:typecheck": "run-s -s help:typecheck:*",
         "help:typecheck:1": "echo Checks for TypeScript errors in both .vue",
         "help:typecheck:2": "echo and .ts files.",
-        "typecheck": "make -f etc/Makefile typecheck",
+        "typecheck": "gmake -f etc/Makefile typecheck",
         "help:lint": "run-s -s help:lintx:*",
         "help:lintx:01": "echo If you would like to format your code before",
         "help:lintx:02": "echo you make a commit with git -- which has hooks",
@@ -74,13 +74,13 @@
         "help:lintx:12": "echo commit, presuming the standard git hooks that",
         "help:lintx:13": "echo this project sets up are in place, the commit",
         "help:lintx:14": "echo will be rejected.",
-        "lint": "make -f etc/Makefile prettiest 'flags=-l --write'",
+        "lint": "gmake -f etc/Makefile prettiest 'flags=-l --write'",
         "help:lint:check": "run-s -s help:lint:check-*",
         "help:lint:check-1": "echo \"This is like the 'lint' script, but it\"",
         "help:lint:check-2": "echo only shows what changes would be made and",
         "help:lint:check-3": "echo reports any unresolved problems; it does",
         "help:lint:check-4": "echo not modify any of your source files.",
-        "lint:check": "make -f etc/Makefile prettiest flags=-s",
+        "lint:check": "gmake -f etc/Makefile prettiest flags=-s",
         "//only lifecycle scripts below here": "echo",
         "prepare": "husky",
         "postinstall": "git config --local include.path ../.gitconfig && python3 -m venv .venv && cd tools && node pyrun.mjs python -m pip install -U pip && node pyrun.mjs pip install -r requirements.txt"