Highmark Occam

Highmark support for Occam.

This package augments the HTML created with Highmark with listings for the following languages:

• BNF
• JSON
• Furtle
• Nominal
• Plain Text
• Markdown
• Markdown Style

Additinoally, a pakbage name can be stipulated for Nominal listings and, provided the corresponding custom grammars have been registered, the Nominal listing will be parsed accordingly. The results are listings that are effectively indistinguishable from the pretty printed source in Occam's own IDE.

Contents

• Introduction
• Installation
• Example
• Usage
• Building
• Contact

Introduction

Highmark is a document preparation system inspired by Markdown and TeX. There are several packages in the distribution.

• Highmark-CLI Highmark's CLI tool.
• Highmark Yapp Highmark with Yapp listings.
• Highmark Client Highmark's bundled client for viewing HTML.
• Highmark Occam Highmark support for Occam.
• Highmark Markdown Highmark's Markdown and Markdown Style languages.

Only the CLI tool is needed by end users. All of the other packages are likely only of interest to prospective developers.

Installation

If you would like to contribute or would simply like to have a look at the code, you can clone the repository with Git...

git clone https://github.com/djalbat/highmark-occam.git

...and then install the dependencies with npm from within the project's root directory:

npm install

Example

There is a small development server that can be run from within the project's directory with the following command:

npm start

The example will then be available at the following URL:

http://localhost:8888

The source for the example can be found in the src/example.js file and correspondingsrc/example folder. You are encouraged to try the example whilst reading what follows. You can rebuild it on the fly with the following command:

npm run watch-debug

The development server will reload the page whenever you make changes.

One last thing to bear in mind is that this package is included by way of a relative rather than a package import. If you are importing it into your own application, however, you should use the standard package import.

Usage

To begin with you must render Occam's styles pertaining to its pretty printer:

import { renderOccamStyles } from "highmark-occam";

renderOccamStyles();

...

Next, in order to create a node from some Markdown content, use the tokensFromMarkdown(), markdownNodeFromTokens() and topmostHTMLNodeFromMarkdownNode() utility functions:

import { grammarUtilities } from "highmark-occam";

const { tokensFromMarkdown, markdownNodeFromTokens } = grammarUtilities;

const markdown = `

        ...
        
      `,
      tokens = tokensFromMarkdown(markdown),
      markdownNode = markdownNodeFromTokens(tokens),
      topmostHTMLNode = topmostHTMLNodeFromMarkdownNode(markdownNode);

Then it is just a question of mounting the node:

const body = document.querySelector("body"),
      domElement = body,  ///
      parentDOMElement = domElement,  ///
      siblingDOMElement = null,
      context = {
        tokens
      };

topmostHTMLNode.mount(parentDOMElement, siblingDOMElement, context);

Note the use of the tokens in a context plain old JavaScript object that must be passed to the topmost HTML node's mount() method along with the parent and sibling DOM elements. This is why there are two utility functions to create the node in two stages. By the way, the sibling DOM element, if not null, must be a child of the parent DOM element, in which case the node will be mounted immediately after it.

Lastly, if you plan to use Nominal lisintgs then register the custom grammars beforehand:

"use strict";

import { customGrammarsUtilities } from "../index"; ///

import firstOrderLogicCustomGrammarsJSON from "./customGrammarsJSON/firstOrderLogic";

const { registerCustomGrammarsMap } = customGrammarsUtilities;

const customGrammarsJSONMap = {
  "first-order-logic": firstOrderLogicCustomGrammarsJSON
}

registerCustomGrammarsMap(customGrammarsJSONMap);

You can export the custom grammars directly from Occam's IDE and then paste them into the requisite file:

"use strict";

export default [
  { ... },
  { ... }
];

Registering the custom grammars in this way must be done before any listings are rendered. It is best to Follow the example application and place this code in a preamble.

Building

Automation is done with npm scripts, have a look at the package.json file. The pertinent commands are:

npm run build-debug
npm run watch-debug

Contact

• [email protected]