love-notes
A literate programming tool (LPT) for javascript embedded into markdown in the style of CWEB and noweb
What?
Literate Programming is a method of writing code (conceived by Donald Knuth) in which the documentation and code live side-by-side in the source document in such a way that the code can be extracted in a compilable format.
Why?
One of the biggest issues we, as a community of developers, face, is the fact that our documentation doesn't generally reflect the state of mind or decision making process that we, as indivduals, went through when attempting to solve a problem. Worse than that, when we go back to document, or modify the code, we rarely remember why we made the decisions in the first place. Providing a few readable sentences providing an insight as to why a specific design choice was made (or as I've found to be much more insightful in communicating with other developers, why other decisions were not made) is incredibly helpful when attempting to re-enter the mindset you (or others) were in when developing said solution.
Further more, prose, as opposed to, say, a block comment, provides a much more expressive canvas to relate the context of the solution. Block comments intrinsically ask us to be as succinct with information as possible thus causing us to be terse with our documentaiton. Using a prose style of writing is open-ended and allows for as much or as little explanation as needed to properly convey the necessary information.
This method also supplies a more readable medium for the consumer (whether that's yourself in a year's time, or another developer digging through your api). As love-notes uses markdown, the final woven documentation is simple plain html, which allows for an endless amount of possibilities when it comes to stylistic presentation of the information.
Finally, and personally, to me, code is art. When working on personal projects, I find that I often have a story to tell with my code, and a lot of what I put into my work gets lost in translation. Using a literate style of programming, I've found that I enjoy relating (to no-one in particular) the life-events, or the work of friend and peers, that inspired me. It's also helped me learn and more information as each project I work on tends to bring with it hours and days of research. As I learn, I write. As I write, I start forming the basic ideas that will, in turn, end up being the project's core.
<pre lang="no-highlight"><code> Create an `index.js` file ```js // file: index.js ``` </code></pre> <pre lang="no-highlight"><code> Create a `math.js` file and add a couple of sections ```js > math.js // composable math functions #sum #other-methods ``` </code></pre> <pre lang="no-highlight"><code> A simple addition method ```js > math.js#sum function sum(a, b) { return a + b } ``` Oh, we're gonna need an exports section! ```js > math.js // section: #exports #exports ``` Whoops. I forgot to add these methods earlier. ```js > math.js#other-methods // section: #other-methods #product #square #cube ``` </code></pre> <pre lang="no-highlight"><code> Let's multiply! ```js > math.js#product function product(a, b) { return a * b } ``` Use `product` to create a `square` function ```js > math.js#product function square(a) { return product(a, a) } ``` Compose `square` and `product` to create a `cube` function ```js > math.js#cube function cube(a) { return product(a, square(a)) } ``` Don't forget to export your functions! ```js > math.js#exports export default = {sum, product, square, cube} ``` And now, let's consume our `math` utility and have `index.js` do some science! ```js > index.js import {cube} from './math' const x = 3 console.log(`${x}^3 = ${cube(x)}`) ``` </code></pre> <pre lang="no-highlight"><code> Insert html directly into the built documentation file and keep the code block as well. ```html <3 <h3>I'm a heading!</h3> ``` Also insert javascript directly into the final output ```js <3 console.log('Oh what tangled webs we weave...') ``` the [weaver-example output](https://github.com/8-uh/love-notes/tree/master/examples/weaver-output/test) demonstrates the woven file created from [test2.md](https://github.com/8-uh/love-notes/blob/master/test/test2.md) ## Installation 1. clone the repo 2. `$ npm install` ## Dev `$ npm run test:watch` will run a 14 point test suite on the library ## Building `$ npm run build` `love-notes` uses rollup to create separate umd and `es` packages in the `dist` directory ## Example `$ npm run example:tangler` or `$ npm run example:weaver` This example reads the `test.md` file found in the `test` directory and creates the properly tangled `index.js` and `math.js` files as indicated in the input markdown. ## Tools ### Syntax Highlighting Most editors also already have the ability to highlight not only the markdown itself, but the code inside of properly formatted code fences. And, with the -very- recent advent of GitHub adopting a [formal spec for `gfm`](https://github.com/blog/2333-a-formal-spec-for-github-flavored-markdown), full support for proper syntax highlighting of `love-notes` in your favorite editor will be available soon. ## TODO - [ ] Add macros for inline-tangling - [ ] Create an example project that tangles, weaves, and transpiles/includes other build technologies - [x] Create Tangler - [x] Create Weaver - [x] Create a proper README - [x] Create a simple tangler example - [x] Create a simple weaver example