kiss-literate-programming

is a minimal literate programming boilerplate

KLP

Description

Merge two beautiful concepts: the KISS principle and the Literate programming approach.

The kiss-literate-programming (from now on, KLP) is defined by the following rules:

KLP is agnostic about:

Most of all: KLP does not need an implementation like the one provided here, you can just edit Makefile and README.md by hand! Of course you can also use klp command, see installation instructions

Usage

Suppose you want to create a shell command, for instance hello-world.sh. I suppose you version it using a git repository inside an hello-world folder.

mkdir hello-world
cd hello-world
klp hello-world.sh

Now you have a README.md you can edit to add documentation and code. See this README.md itself as example.

Annotated source

Start a klp function

klp() {

which expects one parameter, otherwise prints its usage

	if [ -z "$1" ]
	then
		cat <<-MESSAGE
		# KISS Literate programming
		##
		# Installation instructions, source and license available here:
		# http://g14n.info/kiss-literate-programming
		##
		USAGE: klp foo
		MESSAGE

		return 1
	fi

	TARGET=$1

Check if README.md and Makefile already exist, do not overwrite them.

	if [ -e Makefile ]
	then
		echo Makefile already exists
		return 1
	fi

	if [ -e README.md ]
	then
		echo README.md already exists
		return 1
	fi

Generate README.md

	cat <<README > README.md

using the following template

<!-- TODO: edit name and description -->
# name

> description 

[![KLP](https://img.shields.io/badge/kiss-literate-orange.svg)](http://g14n.info/kiss-literate-programming)

## Installation

<!-- TODO: installation instructions here -->

## Usage


## Annotated source

Documentation here

    your code here

more documentation
more documentation

```
example code
```

    more code
    more code more code
    more code more code more code

more documentation

## License

<!-- TODO: license here -->

Remember to change name, description and so on. Please keep the kiss-literate badge to support the project.

README

Generate Makefile

	cat <<MAKEFILE > Makefile
.PHONY: $TARGET

$TARGET:
	grep '    ' README.md | sed -e 's/    //' > $TARGET
MAKEFILE

Clean up

	unset TARGET
}

Installation

Instructions borrowed from git-aware-prompt.

mkdir -p ~/.bash
cd ~/.bash
git clone git://github.com/fibo/kiss-literate-programming.git

If you prefer, you can just copy the klp.sh somewhere.

Edit your ~/.bash_profile or ~/.profile and add the following

source ~/.bash/kiss-literate-programming/klp.sh

Requirements

License

MIT