* [ANN] org-watchdoc.el --- Watchdog for exported Org-mode trees
@ 2014-04-10 0:23 Thorsten Jolitz
0 siblings, 0 replies; 2+ messages in thread
From: Thorsten Jolitz @ 2014-04-10 0:23 UTC (permalink / raw)
To: emacs-orgmode
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
<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
^ permalink raw reply [flat|nested] 2+ messages in thread
* [ANN] org-watchdoc.el --- Watchdog for exported Org-mode trees
@ 2014-04-10 0:28 Thorsten Jolitz
0 siblings, 0 replies; 2+ messages in thread
From: Thorsten Jolitz @ 2014-04-10 0:28 UTC (permalink / raw)
To: help-gnu-emacs
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
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2014-04-10 0:28 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-04-10 0:28 [ANN] org-watchdoc.el --- Watchdog for exported Org-mode trees Thorsten Jolitz
-- strict thread matches above, loose matches on Subject: below --
2014-04-10 0:23 Thorsten Jolitz
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.