[ANN] org-watchdoc.el --- Watchdog for exported Org-mode trees

[Thorsten Jolitz]

Hi List, 

I announced this on the Org-mode mailing list, but I want to mention it
here too since it is principally a tool for easy documantation of Emacs
Lisp libraries. 

I won't repeat myself here, so I rather insert the ASCII version of the
comment-section of org-watchdoc.el which is long and hopefully explains
it all: 

                       __________________________

                              ORG-WATCHDOC

                            Thorsten Jolitz
                        tjolitz at gmail dot com
                       __________________________


                            <2014-04-09 Mi>


Table of Contents
_________________

1 org-watchdoc.el --- Watchdog for exported Org-mode trees
.. 1.1 MetaData
.. 1.2 Commentary
.. 1.3 Installation
.. 1.4 Usage
..... 1.4.1 Commands
..... 1.4.2 Interactive Use
..... 1.4.3 Use with Outorg
..... 1.4.4 Keybindings in Outshine
..... 1.4.5 ChangeLog





1 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


1.1 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


1.2 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.


1.3 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.


1.4 Usage
~~~~~~~~~

1.4.1 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      


1.4.2 Interactive Use
---------------------

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

  1. 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.

  2. 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.

  1. Save and set md5 variable.

  2. Edit the (narrowed) first buffer tree and save

  3. Propagate changes.

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


1.4.3 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.


1.4.4 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).


1.4.5 ChangeLog
---------------

   date             author(s)        version 
  -------------------------------------------
   <2014-04-09 Mi>  Thorsten Jolitz      1.0 



                                          Emacs 24.3.1 (Org mode 8.2.5h)



-- 
cheers,
Thorsten