Org-mode outside Org-mode

outshine is a merge and extension of older extensions for outline-minor-mode. More exactly, outshine developed out of the now obsolete outxxtra.el, Thorsten Jolitz's modified extension of Per Abrahamsen's out-xtra.el. With the blessing of it's (well-known) author Carsten Dominik, Thorsten Jolitz could merge the (slightly modified) outline-magic.el with outxxtra.el and extend them into the new outshine.el library. Thus, if you use outline with outshine, you don't need outline-magic and out-xtra anymore. However, outshine does not make either of these two obsolete libraries, since it has a more specialized approach and might not be able to replace them in all cases.

Furthermore, `outshine.el' includes functions and keybindings from outline-mode-easy-bindings. Unfortunately, no author is given for that library, so I cannot credit the person who wrote it.

So what is outshine? It's an extension library for outline-minor-mode that gives buffers in different major-modes the 'look-and-feel' of Org-mode buffers and enables the use of outorg and navi-mode on them.

To sum it up in one sentence:

Outline with Outshine outshines Outline

Download outshine.el (or clone the github-repo) and copy it to a location where Emacs can find it:

Use this in your '.emacs' to get started:

(require 'outshine)
(add-hook 'outline-minor-mode-hook 'outshine-hook-function)

If you like the functions and keybindings for 'M -' navigation and visibility cycling copied from `outline-mode-easy-bindings', you might want to put the following code into your Emacs init file to have the same functionality/keybindings available in Org-mode too, overriding the less frequently used commands for moving and promoting/demoting subtrees (but clashing with 'org-table' keybindings):

(when (require 'outshine nil 'NOERROR)
  (add-hook 'org-mode-hook
            (lambda ()
              ;; Redefine arrow keys, since promoting/demoting and moving
              ;; subtrees up and down are less frequent tasks then
              ;; navigation and visibility cycling
                (org-defkey org-mode-map
                            (kbd "M-<left>") 'outline-hide-more)
                (org-defkey org-mode-map
                            (kbd "M-<right>") 'outline-show-more)
                (org-defkey org-mode-map
                            (kbd "M-<up>") 'outline-previous-visible-heading)
                (org-defkey org-mode-map
                            (kbd "M-<down>") 'outline-next-visible-heading))
            'append))

Add this if you (e.g.) always want outline/outshine for emacs-lisp buffers (recommended):

(add-hook 'emacs-lisp-mode-hook 'outline-minor-mode)  

If you want a different prefix key for outline-minor-mode, insert first (e.g.):

(defvar outline-minor-mode-prefix "\C-c") 

or whatever you like best to replace the (quite unusable) original prefix "\C-c @". The prefix can only be changed before outline (minor) mode is loaded.

outshine is based on a very simple yet powerful idea, that enables its use in any Emacs major-mode (in theory at least):

Outshine headlines are Org-mode headlines out-commented with comment-region

Thus, the file at hand must be outline-structured 'the outshine way', i.e. with the headlines being proper Org-mode headlines, marked and outcommented with comment-region. As an example, to generate a 3rd level outshine-headline in an Emacs Lisp file, write down

,-----------------------
| *** Third Level Header 
`-----------------------

mark the header line, and apply comment-region on it:

,-----------------------
| ;; *** Third Level Header 
`-----------------------

In a LaTeX file, an adequate header will look like this:

,-----------------------
| % *** Third Level Header 
`-----------------------

and in a PicoLisp file like this (always depending of the major-mode specific values of comment-start, comment-end, comment-add and comment-padding):

,-----------------------
| ## *** Third Level Header 
`-----------------------

outshine.el, outorg.el and navi-mode.el are all examples of how to structure emacs-lisp source files with outshine-style headlines.

After structuring a source code file the 'outshine-way' and loading outline-minor-mode with outshine-extensions, the file will have a very Org-mode like 'look-and-feel'. The headlines (up to level 8) are fontified the same way Org-mode headlines are fontified, and the very specific navigation and structure editing commands of outline-minor-mode as well as their more general Org-mode style counterparts are available:

outline-minor-mode Minor Mode Bindings:

outorg is a library written by Thorsten Jolitz on top of his outshine library. Thus, outorg needs outshine, and files that are structured with outshine-style headers, otherwise it won't work (note that 'oldschool' Emacs Lisp files with headers matched by ^;;;+ are a special case where outorg works too).

You can download the file (or clone the github-repo) here:

outorg requires Org-mode too, thus should be loaded after Org-mode. Insert

(require 'outorg)

in your .emacs and you are done.

outorg's main command is

,---------------------------
| C-c ' (outorg-edit-as-org)
`---------------------------

used in source-code buffers where `outline-minor-mode' is activated with `outshine' extensions. The Org-mode edit-buffer popped up by this command has `outorg-edit-minor-mode' activated, a minor-mode with only 2 commands:

,----------------------------------------
| M-# (outorg-copy-edits-and-exit)
| C-x C-s (outorg-save-edits-to-tmp-file)
`----------------------------------------

If you want to insert Org-mode source-code or example blocks in comment-sections, simply outcomment them in the outorg-edit buffer before calling `outorg-copy-edits-and-exit'.

Thus, with point inside a subtree or on a subtree header, pressing C-c ' (outorg-edit-as-org) will open this subtree in a temporary Org-mode edit buffer, with all out-commented parts in the original buffer uncommented, and all source code parts enclosed in Org-mode source blocks.

When outorg-edit-as-org is called with a prefix C-u, the whole source-code buffer will be transformed into Org-mode and offered for editing in a temporary Org-mode buffer, all headlines folded except the subtree where point was in.

If the original-buffer was read-only, the user is asked if he wants to make it writable for the Org-mode editing. If he answers yes, the buffer can be edited, but will be set back to read-only again after editing is finished.

To avoid accidental loss of edits, the temporary outorg-edit-buffer is backed up in the OS /tmp directory. During editing, the outorg-edit-buffer can be saved as usual with save-buffer via C-x C-s. Even when killed by accident, that last state of the outorg-edit-buffer will be saved and can be recovered.

When done with editing in Org-mode, M-# (Meta-key and #) is used to call outorg-copy-edits-and-exit, a command that orderly exits the edit-buffer by converting the (modified) comment-sections back to comments and extracting the source-code parts out of the Org-mode source-code blocks.

Please note: outorg is line-based, it only works with 'one-line' comments, i.e. with comment-sections like those produced by `comment-region' (a command that comments or uncomments each line in the region). Those special multi-line comments found in many programming languages are not recognized and lead to undefined behaviour.

outorg works on subtrees (or whole buffers).

One advantage of this is that there is always a complete subtree (-hierarchy) in the outorg-edit-buffer, thus not only the Orgmode editing functionality can be applied, but also its export facilities and many other commands that act on headlines or subtrees. As an example, in order to produce the nice README.txt files for the github-repos of outshine, outorg and navi-mode, I simply called outorg-edit-as-org on the first 1st-level-headline of the source-code files (the file header comment-sections) and exported the subtree to ASCII.

One disadvantage of this is that comment-strings of (e.g. emacs-lips) functions cannot be edited comfortably, since after transformation of the source-code buffer they end up inside Org-mode source-code blocks - as comment-strings, just like before.

Enters poporg. It will be described in much detail in the next section, but it can already be mentioned here that it does exactly what outorg cannot do well - Org-mode editing of atomic, isolated comment-strings, no matter where they are found in the source code buffer. And it is, in contrast to outorg, completely independent from outline structuring with e.g. outshine or orgstruct.

poporg is a small Emacs lisp project written by François Pinard to help editing program strings and comments using Org mode (or any other major mode). This can be useful as it is often more convenient to edit large pieces of text, like Emacs lisp or Python docstrings, in an org-mode buffer instead of in a comment or a string.

Emacs does not easily handle multiple major modes in a single buffer. So far many solutions have been implemented, with varying degrees of success, but none is perfect. The poporg approach avoids the problem by extracting the text from the comment or the string from a buffer using a major programming mode, into a separate buffer to be edited in a text mode, but containing only that comment or that string. Once the edit is completed, the modified comment or string gets re-integrated in the buffer containing the program, replacing the original contents.

The main utility of this package is its ability to handle prefixes automatically. For comments, it finds all contiguous nonempty comments on their own line, and strips the common prefix before inserting into the editing buffer (see poporg-comment-skip-regexp). For strings, it checks if there is consistent indentation for the whole string (the opening delimiter of the string can only have whitespace before it), and uses that as the common prefix. For regions, it just uses a naive common prefix. When placing the edited text back in context, it adds the common prefix again, potentially stripping any trailing whitespace (see poporg-delete-trailing-whitespace). It can even adjust the fill column in the editing buffer to account for indentation (see poporg-adjust-fill-column).

To install poporg, move file poporg.el to a place where Emacs will find it. You might byte-compile the file if you want. There are also El-Get and MELPA recipes.

To use poporg, you need to pick some unused keybinding and add a few lines to your ~/.emacs file, such as:

(autoload 'poporg-dwim "poporg" nil t)
(global-set-key (kbd "C-c \"") 'poporg-dwim)

It is important that this be a global keybinding, or at least that the command poporg-dwim be available from both the programming and the text editing buffers.

The command poporg-dwim searches for a nearby comment or string (see poporg-find-string-or-comment) and, upon finding one, it opens an empty buffer in a new window with its contents available for editing. If the region is active then poporg-dwim inserts the region into the buffer instead. The original text is grayed out and set read-only to prevent editing in two places at once. After editing, running poporg-dwim again from the editing buffer kills the editing buffer and inserts the edited text back into its original context.

Hopefully poporg-dwim will do what you expect in most situations. It uses the buffer's syntax table for parsing, so it should adapt well to most modes (including sextuple-quoted strings in Python). If you run poporg-dwim in the vicinity of a grayed-out region that you are editing in another buffer, it pops to that buffer. It has the following caveats:

1. It does not understand empty strings.
2. It cannot deal very well with comments with ending delimiters.

For example, in c-mode, comments start with /* and end with */. This is a problem because poporg needs a common prefix for all lines. In order to make poporg understand these comments, write them on separate lines like this:

/*
 * Comments go here.  Not on a line with the opening delimiter or the
 * closing delimiter.
 */

In this situation poporg will ignore the first and last lines because they are empty except for comment delimiters, and detect the common prefix __ or __*_ for the middle lines, depending on whether the * character is matched by poporg-comment-skip-regexp.

You will probably want to customize poporg-edit-hook, since that is where the major mode of the edit buffer is set. The minor mode poporg-mode is activated in the edit buffer. It has one keybinding by default, which remaps save-buffer (C-x C-s) to poporg-edit-exit. You can add additional keybindings to poporg-mode-map. To save an edit, from the editing buffer run poporg-edit-exit or poporg-dwim; to abort the edit simply kill the buffer.

navi-mode implements extensions for occur-mode. You can think of a navi-buffer as a kind of 'remote-control' for an (adequately) outline-structured original-buffer. It enables quick navigation and basic structure editing in the original-buffer without (necessarily) leaving the navi-buffer. When switching to the original-buffer and coming back after some modifications, the navi-buffer is always reverted (thus up-to-date).

Besides the fundamental outline-heading-searches (8 outline-levels) and the 5 basic keyword-searches (:FUN, :VAR, :DB, :OBJ and :ALL), all languages can have their own set of searches and keybindings (see navi-key-mappings and navi-keywords). Heading-searches and keyword-searches can be combined, offering a vast amount of possible 'views' at the original-buffer.

Download (or clone the github-repos of) the three required libraries

and put them in a place where Emacs can find them (on the Emacs 'load-path'). Follow the installation instructions in outshine.el and outorg.el.

Install navi-mode.el by adding

(require 'navi-mode)

to your .emacs file.

For navi-mode to work, the original-buffer must be outline-structured 'the outshine way', i.e. with the headlines being proper Org-mode headlines, marked and outcommented with comment-region (but oldschool Emacs Lisp headers like ;;; header level 1 work too) .

The second assumption is that outline-minor-mode is activated in the original-buffer and outshine.el loaded like described in its installation instructions (except for Org-mode files).

When these pre-conditions are fulfilled (outorg.el must be loaded too), you can use M-s n (navi-search-and-switch) to open a navi-buffer and immediately switch to it. The new navi-buffer will show the first-level headings of the original-buffer, with point at the first entry.

You can then:

• Show headlines (up-to) different levels:

• Navigate up and down in the search results shown in the navi-buffer:

• Revert the navi-buffer (seldom necessary), show help for the user-defined keyword-searches, and quit the navi-buffer and switch-back to the original-buffer:

• Switch to the original-buffer and back to the navi-buffer, display an occurrence in the original-buffer or go to the occurrence:

• Structure editing on subtrees and visibility cycling

• Miscellaneous actions on subtrees

• Furthermore, there are five (semantically) predefined keyword-searches:

• And (potentially) many more user-defined keyword-searches

(example Emacs Lisp):

• Headline-searches and keyword-searches can be combined, e.g.

,------
| C-2 f 
`------

in a navi-buffer associated to an Emacs Lisp source file shows all headlines up-to level 2 as well as all function, macro and advice definitions in the original-buffer,

,------
| C-5 a 
`------

shows all headlines up-to level 5 as well as all functions, variables, classes, methods, objects, and database-related definitions. The exact meaning of the standard keyword-searches 'f' and 'a' must be defined with a regexp in the customizable variable `navi-keywords' (just like the user-defined keyword-searches).