Skip to content

source_code

Ben Garrett edited this page Jul 12, 2019 · 3 revisions

RetroTxt - Source code

RetroTxt employs an open sourced license with the complete source code available on GitHub. This page instructs on how to use the source in both Chromium based and Firefox web browsers.

Visual Studio Code is used to create RetroTxt, and so it has some .vscode conveniences included in the package such as workspace settings and extension recommendations.

There are also Node.js with NPM dependencies for the programming and build tools.

The source code is linted with ESLint and stylised using Prettier, an opinionated formatter.

Download

Download the RetroTxt source code onto your local computer.

Either by using this GitHub link and decompress the saved RetroTxt-master.zip.

Or run the following Git command in a terminal.

git clone https://github.com/bengarrett/RetroTxt.git

Install programming and build tools with NPM

cd RetroTxt
npm install

If the installation of the tools is successful, this command should return the web-ext version number.

npm run version

NPM tools usage

Create distribution packages in the \web-ext-artifacts\ subdirectory for both Chromium and Firefox Gecko platforms.

npm run build-chrome
cp manifest_firefox.json manifest.json
npm run build-firefox

Convert and compact a Truetype font into WOFF2 for use by RetroTxt.

Windows users may need to edit package.json and update "scripts": { "font": "woff2_compress.js.cmd" }

npm run font fonts/monafont/mona.ttf mona.woff2

Run RetroTxt in Firefox with automatic extension reloading.

For this to work Firefox needs to be installed on your computer and then RetroTxt on Firefox will reload whenever a change is made to this source code.

cp manifest_firefox.json manifest.json
npm run firefox

Analyse the source code for any errors using Mozilla's web-ext lint tool.

cp manifest_firefox.json manifest.json
npm run lint

Use on Chrome and Chromium

I suggest that you create a new user profile in Chrome to use and edit this WebExtension.

Open a new tab and type in the address of the extension.

  • Chrome/Chromium: chrome://extensions
  • Brave: brave://extensions
  • Edge: edge://extensions
  1. In the Extensions tab, toggle Developer mode
  2. Click the Load unpacked button
  3. Navigate to the local directory containing the RetroTxt source code and select OK

Font options selection

RetroTxt should load. The Options link behind the Details button and allows you to configure RetroTxt styling and behaviour.

Use on Firefox

Firefox is locked down and doesn't permit the loading of extensions outside of the Firefox Add-ons page.

Mozilla's web-ext tool is the easiest method to bypass this with a dedicated web page but requires Node.js.

  1. Install Node.js if needed
  2. cd RetroTxt into the cloned RetroTxt directory
  3. npm install to install web-ext and dependencies
  4. npm run firefox to load RetroTxt in Firefox with automatic extension reloading

web-ext run example

Use on Firefox Developer Edition

  1. Edit web-ext-config.js
  2. Update "run": { "firefox": "firefox" } and change it to "run": { "firefox": "firefoxdeveloperedition" }
  3. Follow the above Use on Firefox instructions

Directory and file structure

These are the root directories and files that comprise of RetroTxt. With critical subdirectories and sub-files also pointed out.

  • .vscode Workspace settings for Visual Studio Code
  • _locales Spelling differences for the UK and US English.
    • /en_US/messages Also include shared variables for remote URLs and BBS software names.
  • assets Images used by the README.md, /html/welcome.html and other resources.
  • css WebExtension cascading style sheets in CSS3 syntax.
    • layout.css Base elements styles.
    • retrotxt.css Fonts, scanlines, and cursor stylings.
    • text_colors.css Text theme combinations.
    • text_ecma_48.css ANSI Select Graphic Rendition function classes.
    • text_colors_4bit.css ANSI Select Graphic Rendition colour classes.
    • text_colors_4bit-ice.css ANSI Select Graphic Rendition iCE Color classes.
    • text_colors_vga.css Standard VGA 16 colours for ANSI colour classes.
    • text_colors_xterm.css xterm 16 colours for ANSI colour classes.
    • text_colors_8bit.css xterm 256 colours for ANSI colour classes.
    • text_colors_bbs.css BBS colours and font styles.
    • text_colors_pcboard.css PCBoard BBS colour classes.
  • fonts Original fonts with their documentation and licences.
  • html WebExtension HTML5 templates for the Options dialogue and the welcome load page.
  • libs JavaScript dependencies that cannot be installed using NPM.
  • md Changes document in GitHub Flavored Markdown and README assets.
  • scripts WebExtension JavaScripts in ES6+ (ES2015) syntax.
    • eventpage.js Background functions and listeners that are completely isolated from all other scripts.
    • functions.js Shared functions accessible to non-isolated scripts.
    • options.js Isolated functions for the Options dialogue template located at /html/options_*.html.
    • parse_ansi.js Functions to handle ANSI and ECMA-48 controls.
    • parse_dos.js Functions to handle text encodings and DOS code pages.
    • retrotxt.js Invokes RetroTxt, handles the browser page display and SAUCE metadata.
    • welcome.js Isolated functions for the welcome load page template located at /html/welcome.html.
  • test
    • /example_files ASCII, BBS and ANSI text test cases for use with files:///
    • index.html Entry point for the QUnit tests.
    • tests-*.js QUnit tests for the /script/*.js functions.
  • .eslintrc.js ESLint configuration file.
  • .eslintignore ESLint ignore file.
  • manifest.json WebExtension manifest file containing read-only metadata and configuration options.
  • package.json NPM configuration file.
  • web-ext-chrome.js web-ext configuration file for packaging a Chrome distribution package using npm run build-chrome.
  • web-ext-config.js web-ext configuration file for packaging a Firefox distribution and all other web-ext commands.
You can’t perform that action at this time.