From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thorsten Jolitz Subject: [ANN] org-watchdoc.el --- Watchdog for exported Org-mode trees Date: Thu, 10 Apr 2014 02:23:58 +0200 Message-ID: <87y4zef2w1.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:39781) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WY2lU-0004v9-2u for emacs-orgmode@gnu.org; Wed, 09 Apr 2014 20:22:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WY2lP-00084Q-Mj for emacs-orgmode@gnu.org; Wed, 09 Apr 2014 20:22:48 -0400 Received: from plane.gmane.org ([80.91.229.3]:34078) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WY2lP-00084K-Bt for emacs-orgmode@gnu.org; Wed, 09 Apr 2014 20:22:43 -0400 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1WY2lM-0001y8-5n for emacs-orgmode@gnu.org; Thu, 10 Apr 2014 02:22:40 +0200 Received: from g231224029.adsl.alicedsl.de ([92.231.224.29]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 10 Apr 2014 02:22:40 +0200 Received: from tjolitz by g231224029.adsl.alicedsl.de with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 10 Apr 2014 02:22:40 +0200 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org Hi List, I wrote a little library that is just a small toolbox, but quite useful in combination with outshine.el and outorg.el. This was mainly inspired by the new announcement of the new ox-gfm.el exporter, because it enables the export of nice looking README.md files for github from Org-mode. org-watchdoc takes care of keeping such exported files in sync with the associated Org file. Its prime use case is the reuse of the comment-section of Emacs Lisp libraries as README file and other types of documentation. I wrote an excessively long comment-section for the small library org-watchdoc.el such that it can serve as a good example for its own usage. The ASCII export of this comment section is attached. Note that I added 5 export targets (md, org, html, ascii and latex). In this case, the .md file is actually used on github, and the .org file on Worg, the others are just examples. When I want to change the comment-section of this library, I do it in full Org-mode with outorg, and org-watchdoc makes sure that all registered targets are reexported when I exit the outorg-edit-buffer. This saves me a lot of work: I write documentation only once, and I edit it in only one place, very comfortably in full Org-mode. But I'm a good citizen and add a README on github, a doc on Worg, maybe a HTML post in a Blog and a LaTeX/PDF doc for download. And I want a very readable ASCII version for the announcement email. With org-watchdoc I only have to add the export targets once as properties to the top-level comment-section tree. Then they will be re-exported and kept in sync automatically everytime I make a change to that comment-section tree. While writing this email I could already use org-watchdoc. I noticed that I had two different version numbers in the docs, 0.9 and 1.0. Since there were 6 files with this mistake (.el, .org, .md, .tex, .html, .txt) I was really happy to just do M-# M-+ in org-watchdoc.el, fix the error in the *outorg-edit-buffer*, and exit with M-#, letting org-watchdoc take care of updating the other 5 files. __________________________ 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 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