org-contrib/org-watchdoc.org

   1 #+TITLE: Org-watchdoc
   2 #+DATE: <2014-04-09 Mi>
   3 #+AUTHOR: Thorsten Jolitz
   4 #+DATE: 2014-04-10
   5 #+OPTIONS: H:4 num:nil toc:4 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc prop:t
   6 #+STARTUP: align fold nodlcheck oddeven lognotestate
   7 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   8 #+TAGS: Write(w) Update(u) Fix(f) Check(c)
   9 #+LANGUAGE: en
  10 #+PRIORITIES: A C B
  11 #+CATEGORY: worg
  12
  13 # This file is released by its authors and contributors under the GNU
  14 # Free Documentation license v1.3 or later, code examples are released
  15 # under the GNU General Public License v3 or later.
  16
  17 [[file:index.org][{Back to Worg's index}]]
  18
  19 * org-watchdoc.el --- Watchdog for exported Org-mode trees
  20 :PROPERTIES:
  21 :EXPORT_OPTIONS: prop:nil
  22 :wdoc_1992rwM: /home/tj/git/org-watchdoc/README.md /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org gfm
  23 :wdoc_1992G_r: /home/tj/gitclone/worg/org-contrib/org-watchdoc.org /home/tj/git/org-watchdoc/export-templates/org-watchdoc-worg.org org
  24 :wdoc_1992gas: /home/tj/git/org-watchdoc/targets/org-watchdoc.html /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org html
  25 :wdoc_1992tky: /home/tj/git/org-watchdoc/targets/org-watchdoc.txt /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org ascii
  26 :wdoc_1992fuB: /home/tj/git/org-watchdoc/targets/org-watchdoc.tex /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org latex
  27 :END:
  28
  29 Copyright (C) from 2014 Thorsten Jolitz
  30 Author: Thorsten Jolitz <tjolitz at gmail dot com>
  31 Keywords: org-mode, exporter, propagate changes, documentation
  32
  33 ** MetaData
  34 :PROPERTIES:
  35 :copyright: Thorsten Jolitz
  36 :copyright-years: 2014+
  37 :version:  1.0
  38 :licence:  GPL 3 or later (free software)
  39 :licence-url: http://www.gnu.org/licenses/
  40 :part-of-emacs: no
  41 :git-repo: https://github.com/tj64/org-watchdoc.git
  42 :git-clone: git://github.com/tj64/org-watchdoc.git
  43 :author:   Thorsten Jolitz
  44 :author_email: tjolitz AT gmail DOT com
  45 :END:
  46 ** Commentary
  47
  48 This library implements functionality for keeping exported files
  49 associated with Org subtrees up-to-date.
  50
  51 Its principal use case is writing the comment-section of Emacs
  52 Lisp (or other) source-code files only once (and in full Org-mode
  53 using outorg.el), export it as README documentation from the
  54 *outorg-edit-buffer* to html, ascii, latex/pdf,
  55 markdown-github-flavor or whatever, and keep the exported doc
  56 files automatically up-to-date when the original comment-section
  57 of the source-buffer is edited explicitly with outorg (via M-x
  58 outorg-edit-comments-and-propagate-changes).
  59
  60 org-watchdoc is just a little toolbox that can be used
  61 independently from outorg too. All its functions are commands, so
  62 its functionality is available for interactive use too.
  63 ** Installation
  64
  65 Put this line in your init file
  66
  67 #+BEGIN_SRC 'emacs-lisp
  68   (require 'org-watchdoc)
  69 #+END_SRC
  70
  71 and make sure Emacs can find the file org-watchdoc.el.
  72
  73 To take real advantage of org-watchdoc, outshine.el and outorg.el
  74 (and maybe navi-mode.el) should be installed and source-code
  75 buffers should be structured with outshine headers (outcommented
  76 Org-mode headers), taking care that the whole comment-section is
  77 one single outline tree that is the first headline in the
  78 source-code file. Use org-watchdoc.el itself as an example for
  79 this kind of file structuring.
  80 ** Usage
  81
  82 *** Commands
  83
  84 Since org-watchdoc is a toolbox and not a mode, no menu or keymap
  85 is specified. However, its commands can be used interactively:
  86
  87 | M-x org-watchdoc- | action                                   |
  88 |-------------------+------------------------------------------|
  89 | add-target        | add target-combination to watchlist      |
  90 | remove-target     | remove target-combination from watchlist |
  91 | propagate-changes | if md5 changed reexport all combinations |
  92 | set-md5           | set org-watchdoc-md5 to current md5      |
  93 *** Interactive Use
  94
  95 In interactive use, this would be the typical order of actions:
  96
  97 1. Export first buffer tree to desired doc files (e.g. README-GH.md
  98    or README-WORG.html). Optional, since adding non-exiting
  99    target-files in step 2 will cause the exporter to write them the
 100    when exiting the edit-buffer.
 101
 102 2. Add targets with point on first buffer headline.
 103
 104    Targets are combinations of files the exporter writes to,
 105    export-template files to be inserted before the exporter does
 106    its work, and backends the exporter should export to, e.g.
 107
 108    #+BEGIN_EXAMPLE
 109    "/home/me/proj/README-GH.md /home/me/proj/gh-tmpl.org gfm"
 110    "/home/me/proj/README-WORG.html /home/me/proj/worg-tmpl.org html"
 111    #+END_EXAMPLE
 112
 113    The three elements of such a combination are prompted from
 114    the user.
 115
 116 3. Save and set md5 variable.
 117
 118 4. Edit the (narrowed) first buffer tree and save
 119
 120 5. Propagate changes.
 121
 122    Since md5 has changed due to the edits, all registered target
 123    combinations are automatically re-exported.
 124 *** Use with Outorg
 125
 126 Assuming outshine and outorg are installed and active, do once:
 127
 128 - Edit as Org
 129
 130   In the *outorg-edit-buffer* do steps 1 and 2 described above
 131   for direct interactive use.
 132
 133 #+BEGIN_EXAMPLE
 134 M-x outorg-edit-comments-and-propagate-changes
 135 #+END_EXAMPLE
 136
 137 Then whenever you want to edit the source-buffer's
 138 comment-section and propagate the changes to the watched doc
 139 files, do:
 140
 141 #+BEGIN_EXAMPLE
 142 M-x outorg-edit-comments-and-propagate-changes
 143 #+END_EXAMPLE
 144
 145 instead of the usual
 146
 147 #+BEGIN_EXAMPLE
 148 M-x outorg-edit-comment-as-org
 149 #+END_EXAMPLE
 150
 151 This will
 152
 153 - Offer the first buffer tree for editing in the
 154   *outorg-edit-buffer*
 155
 156 - Reset `org-watchdoc-md5' immediately after edit-buffer setup
 157
 158 - Check if buffer md5 has changed when editing is quitted. If so,
 159   propagate the changes to the doc files registered in the subtrees
 160   watchlist.
 161 *** Keybindings in Outshine
 162
 163 Here are the keybindings I added to outshine.el:
 164
 165 #+BEGIN_EXAMPLE
 166 ;; edit comment-section with `outorg' and propagate changes
 167
 168 ;; best used with prefix-key 'C-c'
 169 (define-key map "`" 'outorg-edit-comments-and-propagate-changes)
 170
 171 ;; best used with prefix-key 'M-#'
 172 (define-key map "\M-+" 'outorg-edit-comments-and-propagate-changes)
 173 (define-key map "+" 'outorg-edit-comments-and-propagate-changes)
 174 #+END_EXAMPLE
 175
 176 So just like editing e.g. an Emacs Lisp buffer or subtree (with
 177 outshine activated) in full Org-mode only involves pressing M-# M-#
 178 once to start editing, and then M-# to exit the edit-buffer, edting
 179 the comment-section of such a source-buffer and propagating the
 180 changes to several export-targets only involves pressing M-# M-+ once
 181 to start editing, and then M-# to exit the edit buffer (when M-# was
 182 set as outline-minor-mode prefix).
 183 *** ChangeLog
 184
 185 | date            | author(s)       | version |
 186 |-----------------+-----------------+---------|
 187 | <2014-04-09 Mi> | Thorsten Jolitz |     0.9 |
 188
 189 # Emacs 24.3.1 (Org mode 8.2.5h)