README for Literate Tools

Introduction

literate-tools provide support for literate programming by:

1. building documentation in html and
2. tangling out code separately from org files.

Please refer to Org Babel for help on writing literate programs in org files.

How to use literate-tools

Example

Let us work with an example to illustrate the use of literate-tools. In this example, the project is named illustrate-literate.

illustrate-literate/
|--- README.org
|--- src
     |--- index.org
     |--- requirements.org
     |--- design.org
     |--- runtime
          |--- index.org
    

Strcuture of the repo

The repository must have a src folder and all the source files (read here as org files) must be under src directory.

Build

Since code is situated within the narrative, one has to build from these documents to generate code and documents for publication. While the code is understood by the compiler, the documents published in html are consumed by humans.

Commonality

Since the above build process is common for every project written in literate style, this commonality is possessed by the literate-tools. The next step is to incorporate literate-tools in the project. This is done by incorporating couple of files - makefile and init.sh.

New Structure

The project has added two files to incorporate literate-tools.

illustrate-literate/
|--- init.sh
|--- makefile
|--- README.org
|--- src
     |--- index.org
     |--- requirements.org
     |--- design.org
     |--- runtime
          |--- index.org
    

init.sh

Since literate-tools is a repository on github, this file facilitates cloning of =literate-tools. Please refer to init.sh that is used by an existing project written in literate style.

#!/bin/bash
if [ -d literate-tools ]; then
    echo "literate-tools already present"
   (cd literate-tools; git pull)
else
   git clone https://github.com/vlead/literate-tools.git
fi

if [ -L tangle-make ]; then
   echo "symlinked makefile already present"
else 
   ln -sf literate-tools/makefile tangle-make
fi
    

makefile

Invoke the literate-build from this makefile. Refer to a sample makefile for reference.

#SHELL := /bin/bash

CODE_DIR=build/code
PWD=$(shell pwd)
LINT_FILE=${PWD}/${CODE_DIR}/lint_output
EXIT_FILE=${PWD}/exit.txt
STATUS=0

all:  build

init: 
       	./init.sh

build: init
       	make -f tangle-make -k all

clean:	
         make -f tangle-make clean
    

Build with default style

Run the following command to build the documentation with the default style.

make -k all
    

Build with readtheorg style

Run the following command to build the documentation with the readtheorg style.

make readtheorg=true -k all
    

Build with labtheme style

Run the following command to build the documentation with the labtheme style. And make sure to include the sitemap.org in all the org files by using #+INCLUDE: <relativepath>/sitemap.org :only-contents t

make labtheme=true -k all
    

Build Directory and .gitignore

The build process generates a build folder containing docs and code directories. This build folder is not version controlled since it is generated. To allow git to ignore generated files, we take rescue in .gitignore by adding the following lines.

build/
elisp/
org-templates/
style/
src/org-templates
src/style
sitemap*
elisp          
literate-tools/
    

Setup Emacs for Incremental Build

1. When tangling inline, using C-v t, indentation maight not be preserved. To ensure indentation is preserved, add the following line to the emacs initialization file. Most probably it will ~/.emacs

   (setq org-src-preserve-indentation t)
       

2. To enable faster build, add the following line to the same initialization file

   (defvar org-babel-use-quick-and-dirty-noweb-expansion t
   "Set to true to use regular expressions to expand noweb references.
   This results in much faster noweb reference expansion but does
   not properly allow code blocks to inherit the \":noweb-ref\"
   header argument from buffer or subtree wide properties.")
       

3. Copy the following files from elisp directory to ~/.emacs.d/custom directory

   cd.el
   dired-operations.el       
   incr-build.el             
   tangle-with-publish-dir.el
       

4. Make the following changes to your .emacs file

   (require 'cl)
   ;;; dired
   ;;; =====
   ;; for changing to the directory of the buffer in shell
   (load "~/.emacs.d/custom/cd")
   (load "~/.emacs.d/custom/dired-operations")
   (load "~/.emacs.d/custom/incr-build")
   (load "~/.emacs.d/custom/tangle-with-publish-dir")
   
   (require 'incr-build)
   (setq dired-dwim-target t)
   (setq dired-copy-preserve-time t)
   (setq dired-recursive-copies 'top)
   
   (define-key dired-mode-map "b" 'browse-url-of-dired-file)
   (load "dired-x")
   (define-key dired-mode-map "z" 'dired-remote-copy)
   (define-key dired-mode-map "r" 'rsync-se-101)
   (define-key dired-mode-map "\C-ca" 'dired-acroread-file)
   (define-key dired-mode-map "\C-cd" 'cd-buffer-dir)
       

Build Incrementally

Incremental copying and tangling of org files to build directory

1. In dired mode use key P to push files code files to build/code directory.

   If you are in dired mode in directory prj/src and mark 
   the files
   prj/src/file1.py and
   prj/src/file2.py
   and then hit P, they get copied to prj/build/code
       

2. Alternatively, from dired mode, use key T to tangle org files and push the tangled code to build/code directory

   If you are in dired mode in directory prj/src and mark
   file1.org and file2.org, and these files tangle out file1.py and file2.py
   then hit T, they get copied to 
   
   They get copied to 
   prj/build/code/file1.py
   prj/build/code/file2.py