https://github.com/fibo/kiss-literate-programming
is a minimal literate programming boilerplate
https://github.com/fibo/kiss-literate-programming
literate-programming
Last synced: about 1 year ago
JSON representation
is a minimal literate programming boilerplate
- Host: GitHub
- URL: https://github.com/fibo/kiss-literate-programming
- Owner: fibo
- License: mit
- Created: 2016-01-27T09:07:42.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2022-08-05T08:35:51.000Z (almost 4 years ago)
- Last Synced: 2025-04-15T06:39:29.887Z (over 1 year ago)
- Topics: literate-programming
- Language: Shell
- Homepage: https://fibo.github.io/kiss-literate-programming
- Size: 9.77 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# KISS-Literate-Programming
> is a minimal literate programming boilerplate
[](https://fibo.github.io/kiss-literate-programming)
## Description
Merge two beautiful concepts: the [KISS principle](https://en.wikipedia.org/wiki/KISS_principle) and the [Literate programming approach](https://en.wikipedia.org/wiki/Literate_programming).
The *KISS-Literate-Programming* (from now on, KLP) is defined by the following rules:
* All source code and documentation are contained in a *README.md* text file, which is written using [Markdown syntax](https://daringfireball.net/projects/markdown/syntax).
* Source code rows embedded in *README.md* start with 4 spaces; code examples can use the backtick syntax and are ignored. See the [readme template](#readme-template) as example.
* Source code is generated running `make`.
KLP is agnostic about:
* The programming language chosen.
* Installation instructions.
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](#installation)
## ADDENDUM
This KLP implementation uses bash and rely on GNU make which is available on every OS.
For a more advanced, yet tiny, tool please check out [markdown2code](https://fibo.github.io/markdown2code).
It is recommended if you have Node.js installed, in particular you can use triple backticks and highlight your code.
## Badge
Add the row below in your markdown file to get a badge
```
[](https://fibo.github.io/kiss-literate-programming)
```
## 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](https://raw.githubusercontent.com/fibo/kiss-literate-programming/master/README.md) 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:
# https://fibo.github.io/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.md
# name
> description
[](https://fibo.github.io/kiss-literate-programming)
## Installation
## 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
Remember to change *name*, *description* and so on.
Please keep the *kiss-literate* badge to support the project.
README
Generate *Makefile*
cat < Makefile
.PHONY: $TARGET
$TARGET:
grep ' ' README.md | sed -e 's/ //' > $TARGET
MAKEFILE
Clean up
unset TARGET
}
## Installation
Instructions borrowed from [git-aware-prompt](https://github.com/jimeh/git-aware-prompt#installation).
```
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](https://raw.githubusercontent.com/fibo/kiss-literate-programming/master/klp.sh) somewhere.
Edit your *~/.bash_profile* or *~/.profile* and add the following
```
source ~/.bash/kiss-literate-programming/klp.sh
```
## Requirements
* grep and sed: used for extracting code from *README.md*
* cat: used to generate *Makefile* and *README.md*.
* bash
* make
* git: optionally used for installation
## Examples
Follows a list of examples embracing KLP method:
* [5m](https://fibo.github.io/5m/)
* [aws-lambda-res](https://fibo.github.io/aws-lambda-res/)
* [mdconf-from](https://fibo.github.io/mdconf-from/)
* [numerology](https://fibo.github.io/numerology/)
* [prime-number](https://fibo.github.io/prime-number/)
* [static-props](https://fibo.github.io/static-props/)
* [volatility](https://fibo.github.io/volatility/)
* [y-combinator](https://fibo.github.io/y-combinator/)
* [fibo's home initializer script](https://github.com/fibo/home/blob/gh-pages/README.md#init-home)
## License
[MIT](https://fibo.github.io/mit-license)