org-weave.md

org-weave takes an Org file as an argument and produces, on standard output, source code for typeset documentation.

Currently, the only format supported is gfm (GitHub flavored Markdown).

Usage

org-weave [options] file.org > document

Options:

-E EMACS	Specify the Emacs executable. Default value is 'emacs24-nox'
-O OPTIONS	Specify the options to pass to Emacs. Default value is '-Q –batch'
-q	Enable quick expansion of noweb references
	(see variable org-babel-use-quick-and-dirty-noweb-expansion).
-L ORGDIR	Specify an alternate directory for Org libs.
-f FORMAT	Specify the output format.
	Currently, only 'gfm' (GitHub flavored Mardown) is supported.
-V	Show version and exit

Source code

Shell code

• Initial variables

  DIR=`pwd`
  FILES=""
  ORGDIR="/path/to/alternate/org-mode"
  QUICK_EXPANSION=nil
  EMACS=<<emacs>>
  EMACS_OPTS="-Q --batch"
  FLAVOR=gfm
  VERSION=0.1

  <<emacs>> =

  emacs24-nox

• Help function

  read -d '' help_string <<"EOF"
  Usage: <<usage>>
  
  <<format-options(toptions,fmt="%-15s %s")>>
  EOF
  
  help () {
    echo -ne "$help_string\n"
  }

• Main part

  Let's deal with command line options

  while getopts "hE:O:L:f:qV" option "$@"; do
    case $option in
      h) help && exit 0 ;;
      E) EMACS="$OPTARG" ;;
      O) EMACS_OPTS="$OPTARG" ;;
      q) QUICK_EXPANSION=t ;;
      f) FLAVOR="$OPTARG" ;;
      L) ORGDIR="$OPTARG" ;;
      V) echo "$(basename $0) $VERSION" && exit 0 ;;
    esac
  done ; shift $((OPTIND -1))

  We need a file as an argument

  [ "$1" ] || { help && exit 1; }
  file="$1"

  For now, only gfm is supported

  [ "$FLAVOR" = "gfm" ] || { help && exit 1; }

  Create a temporary file

  out=$(mktemp)

  Now, execute emacs…

  $EMACS ${EMACS_OPTS} --eval "(progn
    <<escape-quotes(elisp-code)>>)"

Elisp code

When ORGDIR actually exists, load Org libraries from this directory. Otherwise, we'll use the ones that ship with Emacs or were installed using package.el

(package-initialize)
(when (file-accessible-directory-p "$ORGDIR")
   (add-to-list 'load-path (expand-file-name "$ORGDIR/lisp/"))
   (add-to-list 'load-path (expand-file-name "$ORGDIR/contrib/lisp/" t)))

Require the necessary libs (only ox-gfm for now)

(require 'ox-gfm)

Set org-babel-use-quick-and-dirty-noweb-expansion to the value of QUICK_EXPANSION

(setq org-babel-use-quick-and-dirty-noweb-expansion ${QUICK_EXPANSION})

Do not require confirmation before evaluating code blocks

(setq org-confirm-babel-evaluate nil)

Open the file within emacs;

(find-file (expand-file-name "$file" "$DIR"))

export it

(princ (org-export-as 'gfm))

Utility functions

<<escape-quotes>> =

(save-match-data
  (replace-regexp-in-string "\"" "\\\\\"" str-val))

Used to escape the quotes within the elisp code before embedding it into the shell code, in order to preserve readability.

<<format-options>> =

(mapconcat 
  (lambda (row)
    (format fmt (car row) (cadr row))) table "\n")

Used to format the options table.