Org-watchdoc

org-watchdoc.el — Watchdog for exported Org-mode trees

EXPORT_OPTIONS: prop:nil
wdoc_1992rwM: /home/tj/git/org-watchdoc/README.md /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org gfm
wdoc_1992G_r: /home/tj/gitclone/worg/org-contrib/org-watchdoc.org /home/tj/git/org-watchdoc/export-templates/org-watchdoc-worg.org org
wdoc_1992gas: /home/tj/git/org-watchdoc/targets/org-watchdoc.html /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org html
wdoc_1992tky: /home/tj/git/org-watchdoc/targets/org-watchdoc.txt /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org ascii
wdoc_1992fuB: /home/tj/git/org-watchdoc/targets/org-watchdoc.tex /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org latex

Copyright (C) from 2014 Thorsten Jolitz Author: Thorsten Jolitz <tjolitz at gmail dot com> Keywords: org-mode, exporter, propagate changes, documentation

MetaData

copyright: Thorsten Jolitz
copyright-years: 2014+
version: 1.0
licence: GPL 3 or later (free software)
licence-url: http://www.gnu.org/licenses/
part-of-emacs: no
git-repo: https://github.com/tj64/org-watchdoc.git
git-clone: git://github.com/tj64/org-watchdoc.git
author: Thorsten Jolitz
author_email: tjolitz AT gmail DOT com

Commentary

This library implements functionality for keeping exported files associated with Org subtrees up-to-date.

Its principal use case is writing the comment-section of Emacs Lisp (or other) source-code files only once (and in full Org-mode using outorg.el), export it as README documentation from the outorg-edit-buffer to html, ascii, latex/pdf, markdown-github-flavor or whatever, and keep the exported doc files automatically up-to-date when the original comment-section of the source-buffer is edited explicitly with outorg (via M-x outorg-edit-comments-and-propagate-changes).

org-watchdoc is just a little toolbox that can be used independently from outorg too. All its functions are commands, so its functionality is available for interactive use too.

Installation

Put this line in your init file

(require 'org-watchdoc)

and make sure Emacs can find the file org-watchdoc.el.

To take real advantage of org-watchdoc, outshine.el and outorg.el (and maybe navi-mode.el) should be installed and source-code buffers should be structured with outshine headers (outcommented Org-mode headers), taking care that the whole comment-section is one single outline tree that is the first headline in the source-code file. Use org-watchdoc.el itself as an example for this kind of file structuring.

Usage

Commands

Since org-watchdoc is a toolbox and not a mode, no menu or keymap is specified. However, its commands can be used interactively:

M-x org-watchdoc-	action
add-target	add target-combination to watchlist
remove-target	remove target-combination from watchlist
propagate-changes	if md5 changed reexport all combinations
set-md5	set org-watchdoc-md5 to current md5

Interactive Use

In interactive use, this would be the typical order of actions:

Export first buffer tree to desired doc files (e.g. README-GH.md or README-WORG.html). Optional, since adding non-exiting target-files in step 2 will cause the exporter to write them the when exiting the edit-buffer.
Add targets with point on first buffer headline.

Targets are combinations of files the exporter writes to, export-template files to be inserted before the exporter does its work, and backends the exporter should export to, e.g.
```
"/home/me/proj/README-GH.md /home/me/proj/gh-tmpl.org gfm"
"/home/me/proj/README-WORG.html /home/me/proj/worg-tmpl.org html"
```
The three elements of such a combination are prompted from the user.
Save and set md5 variable.
Edit the (narrowed) first buffer tree and save
Propagate changes.

Since md5 has changed due to the edits, all registered target combinations are automatically re-exported.

Use with Outorg

Assuming outshine and outorg are installed and active, do once:

Edit as Org

In the outorg-edit-buffer do steps 1 and 2 described above for direct interactive use.

M-x outorg-edit-comments-and-propagate-changes

Then whenever you want to edit the source-buffer's comment-section and propagate the changes to the watched doc files, do:

M-x outorg-edit-comments-and-propagate-changes

instead of the usual

M-x outorg-edit-comment-as-org

This will

Offer the first buffer tree for editing in the outorg-edit-buffer
Reset `org-watchdoc-md5' immediately after edit-buffer setup
Check if buffer md5 has changed when editing is quitted. If so, propagate the changes to the doc files registered in the subtrees watchlist.

Keybindings in Outshine

Here are the keybindings I added to outshine.el:

;; edit comment-section with `outorg' and propagate changes

;; best used with prefix-key 'C-c' 
(define-key map "`" 'outorg-edit-comments-and-propagate-changes)

;; best used with prefix-key 'M-#'
(define-key map "\M-+" 'outorg-edit-comments-and-propagate-changes)
(define-key map "+" 'outorg-edit-comments-and-propagate-changes)

So just like editing e.g. an Emacs Lisp buffer or subtree (with outshine activated) in full Org-mode only involves pressing M-# M-# once to start editing, and then M-# to exit the edit-buffer, edting the comment-section of such a source-buffer and propagating the changes to several export-targets only involves pressing M-# M-+ once to start editing, and then M-# to exit the edit buffer (when M-# was set as outline-minor-mode prefix).

ChangeLog

date	author(s)	version
<2014-04-09 Wed>	Thorsten Jolitz	0.9