All the sources required to tangle code and craete html docs
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
elisp
org-templates
style
.gitignore
README.org
VERSION
license.org
make-clean.mk
makefile

README.org

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