docstrip

docstrip

Docstrip is a tool for creating packages and their documentation in an elegant, literate programming scheme.

The syntax is sort of similar to the TeX docstrip utility, by which all comments are can be removed. Markdown and Javascript files are generated with shared or respectively designated comments. Every non-commented line or block is implicitly javascript.

Basic Usage and File Structure

Basic usage involves a source file and the docstrip script file. This package, for example, places the docstrip (docstrip.js) and source (index.js) files within the /docstrip subdirectory, and the destination file is aimed at the top level (which happens to also be named docstrip).

Project
 |__ docstrip
 |    |__ docstrip.js
 |    |__ source.js
 |__ output.js
 |__ output.md

Concurrent File Structures

Removable comments not only facilitates the organization of file type-specific content, but it also allows for the possibility of protected (or disappearing) comments. This means a project could be built in a private local directory, then stripped to a more navigable (and publishable) version of the project.

Project
 |__ Private
 |    |__ docstrip.js
 |    |__ source.js
 |__ Public
      |__ output.js
      |__ output.md

Source File

Single Lines

A line beginning with // such as ...

// my comment here

will be rendered in place in both markdown and javascript destinations.

A line beginning with //. will render to javascript only.

//. my javascript comment here

A line beginning with //m such as ...

//m my markdown here

will be rendered to markdown only, and excluded in any javascript destination.

White-space-only lines are always removed. This means your source can make use of white space for legibility, while the output file(s) -- the code ultimately used -- is reduced (though not minimized).

Blocks

Lines between the delimeters ///. and //./ will render to javascript only.

///.

let self = 1;

function me(x) {
  return x * self;
}

//./

Lines between the delimeters ///m and //m/ will render to markdown only.

///m

## foo

Here is some markdown stuff.

//m/

docstrip script

Put the necessary lines from the following all in one file, then nodee <that file>.

var ds = require('docstrip');

It might eventually be useful/necessary to have some sort of package options protocol, and at that point surely the distinction of .javascript/.markdown/etc. functionality will be essential. For now it may be a little tedious, but you can of course wrap these with your own conveninece functions, which is sort of the aim anyway.

render markdown

ds.markdown("../original/index.js", "../new/README.md");

render javascript

ds.javascript("../original/index.js", "../new/index.js");