is a minimal literate programming boilerplate
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:
- All source code and documentation are contained in a README.md text file, which is written using 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 as example.
- Source code is generated running
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
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. It is recommended if you have Node.js installed, in particular you can use triple backticks and highlight your code.
Add the row below in your markdown file to get a badge
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.
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
cat <<README > README.md
using the following template
<!-- TODO: edit name and description --> # name > description [![KLP](https://fibo.github.io/svg/klp-badge.svg)](https://fibo.github.io/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.
cat <<MAKEFILE > Makefile .PHONY: $TARGET $TARGET: grep ' ' README.md | sed -e 's/ //' > $TARGET MAKEFILE
unset TARGET }
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
- grep and sed: used for extracting code from README.md
- cat: used to generate Makefile and README.md.
- git: optionally used for installation
Follows a list of examples embracing KLP method:
- fibo’s home initializer script