archematics/README.md

76 lines
3.6 KiB
Markdown
Raw Permalink Normal View History

2023-08-28 05:11:26 +00:00
# archematics
Browser plugin to uncover lost mathematical treasures on the web.
More details on its features and operation can be found in the
[options page](etc/options.html).
### Installing archematics
Currently archematics may only be installed as a "development" plugin;
although it is fully implemented and uses only well-known standard
packages, publication policies of the various browsers will require some
changes before it can receive approval as a plugin that can be installed
normally. (For example, Firefox requires that all files in a plugin be
under 4MB, but one of the packages this depends on is only distributed with
files larger than that.) Therefore, to install it, you must:
First, create a distribution directory by either
* the build process below, in which case you are looking for the subdirectory
named "archematics" of the top-level directory of the repository, or
* or, if you have a link to a zip file of a distribution directory (perhaps
one was given to you), download the zip file and unzip it into the directory
of your choice.
How you then install archematics as a development plugin depends on the
browser:
* **Firefox:** open a new tab and enter "about:debugging" in the URL bar.
Then click the "This Firefox" entry in the left column. Near the top right
you will see a "Load Temporary Add-on" button. Click this button and
navigate to the "manifest.json" file in your distribution directory in the
resulting file browser. Select that file and the plugin will load. Then
select the "Add-ons and Themes" item in the main Firefox menu and make sure
the archematics plugin is enabled, and on its preferences tab the parts
of it you want to use are activated. Then you can navigate to a web page
where it applies. You will have to give it permission to run on that
domain (using the "puzzle-piece" plug-in icon at the top right), and then
reload the page and you should see it take effect.
Note in Firefox, each time you quit and restart the browser you will need
to reinstall the extension if you want to use it (since it is only loaded
as a development extension).
* **Chrome:** open a new tab and enter "chrome://extensions" in the URL bar.
In the top right-hand corner, enable "Developer mode". Then click on the
"Load unpacked" button at the top left. Navigate to the distribution
directory in the resulting file browser, and click on Select. Once the
extension is loaded, click on the "Details" button. About halfway down the
page under "Site access" you can give archematics permission to work
with the sites you want; and most of the way down the page click on\
"Extension options" to make sure the features you want are enabled.
In Chrome, the extension should remain installed for future browsing
sessions as well, even when you stop and restart the browser.
* **Edge:** open a new tab and enter "edge://extensions" in the URL bar.
On the left side near the bottom, activate "Developer Mode." Click on the
"Load unpacked" button, and proceed as for Chrome.
* For other browsers, check the browser's documentation for how to load a
tempory or unpacked extension; we'd be happy to include the procedures
here if you let us know what worked for you. You can contact the
developers by email at
glen at archematics dot app
Enjoy seeing math treasures on the web in a whole old-that-is-new-again way!
### Building archematics
1) Install node v20 or later and pnpm v8.11 or later in your build environment
2) Clone the repository https://code.studioinfinity.org/glen/archematics.git
and enter its top-level directory
3) Execute `pnpm install`
4) Execute `pnpm build`