mweave

mweave

mweave is a literate programming experiment I started by in 2012. I liked Donald Knuth's ideas about literate programming but didn't enjoy the implementations. This incarnation of my experiment (2018) I am looking at literate programming from the perspective of a writing tool for creative projects in interactive fiction and electronic literature.

mweave experiment history

mweave started 2012

This project started out as an experiment to write a document generator written for NodeJS's in JavaScript. While I thought of it as "literate programming" what I implemented was really just an inside out document generator. Code blocks that were preceeded by a link were scraped and written to a file indicated by the targetted link. I did not use the concepts of "tangle" and "weave" individually and I didn't support the arbitrary ordering of code blocks or macros.

My bootstrap was written in Bash, it processed the README.md file using vi, sed, to generate a mw-bootstrap.js and then that processed a file, mw.md to implement mw.js and npm to assemble dependencies. In the end my initial experiment failed because I failed to use mw.js on a regular basis. It wasn't compelling. The version number at npmjs.org shows 0.0.2. I've since flagged it as deprecated. I am no longer developing a NodeJS based implementation.

If you're looking for something practicle two interesting projects capture what I was thinking about. They are Jupyter Notebooks and R Notebooks. Both have grown out of the Open Science and Open Data communities. Very cool stuff.

mweave in January, 2018

Today I find myself working in a Research Library and literate programming is again calling to me. This experiment builds on the 2012 ideas but now is implemented in Golang. We'll see if this moves beyond a toy program in the coming years. RSD, 2018-01-05

The experiment

Can _mweave_ be a useful tool for writing interactive fiction?  

mweave is a Golang package and command line program. It provides both "tangle" and "weave" functions. The mweave command line program integrates macro support by pre-processing the text through shorthand a very simple label expander. An mweave file is a UTF-8 plain text file with an extension of ".mweave" or ".mw". Documentation is rendered to Markdown file(s) and source to the specified source code files. Like the original project mweave is still one command but the explicit options of -weave or -tangle are now included so you can generate both markdown and source code files.

At it's core mweave is a pre-processor that looks for mweave directives. Unlike the 2012 version mweave directives are embedded as an HTML/XML style comments.

Hello World

As an example you can render a helloworld python script from helloworld.mweave using -tangle and render a helloworld Markdown page by using -weave. Processing that markdown using a Markdown process like mkpage would give you the final helloworld page.

Here is the example mweave file--

    # Hello World!

    This is an example of an embedded document to be extracted by 
    [mweave](https://github.com/rsdoiel/mweave).
    <!--mweave:source "helloworld.py" 0 -->
    ```python
        #!/usr/bin/env python3
        print("Hello World!")
    ```
    <!--mweave:end -->

Here are the commands to render helloworld.md and helloworld.py from our helloworld.mweave source.

    mweave -weave -i helloworld.mweave -o helloworld.md
    mweave -tangle -i hellowolrd.meave

Notice that tangle ignores the output file name. That is beceause the source files are set in the mweave begin directive.

How it works

mweave reads in the entire source document and runs through the shorthand macro expander. It then splits the document into plain text sections and source sections. Source sections start with mweave:source and end with a mweave:end HTML style comment. mweave:source takes two required parameters, the filename (string) and an order value (an integer). The ordering value is used by tangle to order blocks of texts associated with the filename.

Before parsing into source and plain text blocks the shorthand macro processor runs over the code and the resulting text is then parsed into source and plain text. See shorthand for details about shorthand.

This 2nd mweave experiment is still rediculiously simple like 2012. v0.1.0 was I implemented in less than a day so I could experiment again with literate programming using the HTML comment indicator for flag source files to output. v0.1.1 integrated a macro system was another day (though the macro engine already existed). I am trying to sort out how simple a tool I can write and still support literate programming. My hypothis is that if the tool is simple enough I might actually use it and find it more useful and interesting to maintain.

Requirements

• Golang version 1.9.2 or better

Installation

mweave is "go get"-able.

    go get -u github.com/rsodiel/mweave/...