Skip to main content

Workflow abstraction

Starting point​

We start with a collection of markdown files containing terms and definitions. We want to create a “specification” from these markdownfiles. This is going to be an index.html file.

User Entry Point is a Command Line Menu:

  ,---.                  .   .        --.--
  `---.,---.,---.,---.   |   |,---.     |
      ||   ||---'|    ---|   ||   |---  |
  `---'|---'`---'`---'   `---'|---'     `
       |                      |


  Please choose one of the following options:

    [0] Add content
    [1] Render specification
    [2] Export to PDF
    [3] Collect external references (cache, faster)
    [4] Collect external references (no cache, slower)
    [5] Add, remove or view xref source
    [6] Configure
    [7] Open documentation website
    [8] Freeze specification
    [Q] Quit

    An xref is a reference to another repository.

    Enter your choice:

End result​

The end result is an index.html file that is “self containing”, in this case meaning that it has all the styling (CSS) and behaviour (JS) and data (a JS variable) inside.

Menu option [0] Add content​

Shows simple instructions on how to add content.

Steps: |

– BEGIN –
– 1 –

create-term-index.js​

Read all the user-created term files (markdown).

Make an ordered list (JSON) of all the names of the terms files (“term index”).

↓
– 2 –

insert-term-index.js​

  • Use content of specs.json (the user config file )
  • Insert term index in this content
  • Create a specs-generated.json (system config file) from this content.
↓
– 3 –

create-versions-index.js​

Create a directory with a version index (if it does not exist yet).

This page lists all available snapshots of this Spec-Up-T specification

#version #snapshot

↓
– 4 –

prepare-tref.js​

Prepare the markdown files that contain '[[tref]]'s as a definition. A '[[tref]]' is a term defined in another (“remote” or “external”) specification. The definition (already locally stored in local JSON) is inserted in the file.

The definition is prepended by an html comment stating that everything below is inserted and can safely be removed.

↓
– 5 –

fix-markdown-files.js​

Fix the markdown in the term files.

One blank line between paragraphs, prepend ~ to lines, etc

↓
– 6 –

index.js​

Create a <script> object that contains external data. A local copy of external data are inserted in the index.html

– END –

Creates a snapshot of the current index.html and places it in the version index.

#version #snapshot