705292ea203fed9d692eec71369afd42964264b7
[worg.git] / org-tutorials / org-outside-org.org
1 #+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
2 #+STARTUP:    align fold nodlcheck oddeven lognotestate
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
5 #+TITLE:      Org-mode outside Org-mode
6 #+AUTHOR:     Thorsten Jolitz, François Pinard
7 #+EMAIL:      tjolitz at gmail dot com
8 #+DATE        <2013-03-12 Di>
9 #+LANGUAGE:   en
10 #+PRIORITIES: A C B
11 #+CATEGORY:   worg
12
13 [[file:index.org][{Back to Worg's index}]]
14
15 * Introduction
16   :PROPERTIES:
17   :CUSTOM_ID: introduction
18   :END:
19
20   Once one gets used to Org-mode, it's hard to live without it. Even its most
21   basic feature, the hierarchical tree-like structuring of files, can be
22   missed badly when editing files in other GNU Emacs major-modes, not to
23   mention the convenient navigation, structure-editing and visibility-cycling
24   functionality Org-mode offers for these tree-like structures.
25
26   One especially important case where Org-mode users might miss Org-mode
27   functionality is their =.emacs= configuration file. These Emacs Lisp files
28   might become huge, for example [[http://www.mygooglest.com/fni/dot-emacs.html][Fabrice Niessen's .emacs]] has some 9720 lines,
29   and structuring them only using Emacs Lisp comments (=;=) easily becomes a
30   creative nightmare (many approaches for structuring a .emacs file can be
31   found on [[http://www.dotemacs.de/index.html][the very unofficial dotemacs home]] page). 
32
33   Another typical case where Org-mode's editing facilities are missing is
34   writing the comment-header sections of Emacs Lisp source code files. These
35   sections often contain extensive explanations of the development-history,
36   installation-process and usage of the library, but are just that - Emacs
37   Lisp comment-sections. Sometimes even the comment-strings of important and
38   complex Emacs Lisp functions contain long and complicated text parts that
39   are not easy to edit as comments. 
40
41   Last not least, anybody who has used =C-c C-j (org-goto)= for looking up a
42   different location in the current org-file, keeping current visibility,
43   might have wondered if a kind of 'remote-buffer-control' via a temporary
44   indirect buffer might not be a generally useful idea.
45
46 * Org-mode everywhere
47   :PROPERTIES:
48   :CUSTOM_ID: org-mode-everywhere
49   :END:
50 ** File Structuring
51    :PROPERTIES:
52    :CUSTOM_ID: file-structuring
53    :END:
54 *** Orgstruct 
55     :PROPERTIES:
56     :CUSTOM_ID: orgstruct-minor-mode
57     :END:
58
59    One possibility to enjoy Org-mode's structure-editing and list-formatting
60    facilities outside Org-mode buffers is /Orgstruct minor mode/. Let's cite
61    from the [[http://orgmode.org/manual/Orgstruct-mode.html][Org-mode manual]]:
62
63 #+begin_example
64     If you like the intuitive way the Org mode structure editing and list
65     formatting works, you might want to use these commands in other modes like
66     Text mode or Mail mode as well. The minor mode orgstruct-mode makes this
67     possible. [...]
68
69     When this mode is active and the cursor is on a line that looks to Org like a
70     headline or the first line of a list item, most structure editing commands
71     will work, even if the same keys normally have different functionality in
72     the major mode you are using. If the cursor is not in one of those special
73     lines, Orgstruct mode lurks silently in the shadows. When you use
74     orgstruct++-mode, Org will also export indentation and autofill settings
75     into that mode, and detect item context after the first line of an item.
76 #+end_example
77
78 *orgstruct* currently does NOT work with /outorg/ and /navi-mode/ (see below for
79 a description of these libraries). To make both libraries work with
80 orgstruct-buffers just like with outshine-buffers, it would be necessary to:
81
82  1. Structure the file with outshine-style headings (e.g. =;; * Header=)
83  2. Make Orgstruct calculate and set file-local variable =outline-regexp= the
84     way /outshine/ does.
85  3. Make Orgstruct calculate and set file-local variable =outline-level= the
86     way /outshine/ does.
87  4. Make Orgstruct calculate and set file-local variable
88     =outline-promotion-headings= the way /outshine/ does. 
89
90 Then, maybe after a few minor tweaks in the libraries themselves, /outorg/ and
91 /navi-mode/ wouldn't care if they deal with an orgstruct-buffer or an
92 outshine-buffer.
93
94 *** Outline with Outshine 
95     :PROPERTIES:
96     :CUSTOM_ID: outline-with-outshine
97     :END:
98
99 **** History and Credits
100     :PROPERTIES:
101     :CUSTOM_ID: history-and-credits
102     :END:
103
104 *outshine* is a merge and extension of older extensions for
105 /outline-minor-mode/. More exactly, /outshine/ developed out of the now
106 obsolete =outxxtra.el=, /Thorsten Jolitz's/ modified extension of /Per
107 Abrahamsen's/ =out-xtra.el=. With the blessing of it's (well-known) author
108 /Carsten Dominik/, /Thorsten Jolitz/ could merge the (slightly modified)
109 =outline-magic.el= with =outxxtra.el= and extend them into the new
110 =outshine.el= library. Thus, if you use outline with outshine, you don't need
111 outline-magic and out-xtra anymore. However, outshine does not make either of
112 these two libraries obsolete, since it has a more specialized approach and
113 might not be able to replace them in all cases.
114
115 So what is /outshine/? It's an extension library for outline-minor-mode that
116 gives buffers in different major-modes the 'look-and-feel' of Org-mode buffers
117 and enables the use of /outorg/ and /navi-mode/ on them.
118
119 To sum it up in one sentence:
120
121 #+begin_verse
122  Outline with Outshine outshines Outline
123 #+end_verse
124
125 **** Installation
126      :PROPERTIES:
127      :CUSTOM_ID: outshine-installation
128      :END:
129
130 Download =outshine.el= (or clone the github-repo) and copy it to a location
131 where Emacs can find it:
132
133 | https://github.com/tj64/outshine           |
134 | git clone git@github.com:tj64/outshine.git |
135
136 Use this in your '.emacs' to get started:
137
138 #+begin_src emacs-lisp
139 (require 'outshine)
140 (add-hook 'outline-minor-mode-hook 'outshine-hook-function)
141 #+end_src
142
143 Download [[https://raw.github.com/andreas-marschke/dotfiles/master/elisp/outline-mode-easy-bindings.el][outline-mode-easy-bindings.el]] and put it in a place where Emacs can
144 find it. `outshine' loads this library if it is able to successfully require
145 it. The functions and keybindings (for 'M -<<arrow-key>>' navigation and
146 visibility cycling) defined there are so convenient that I put the following
147 code into my Emacs init file to have the same functionality/keybindings
148 available in Org-mode too:
149
150 #+begin_src emacs-lisp
151 (when (require 'outline-mode-easy-bindings nil 'NOERROR)
152   (add-hook 'org-mode-hook
153             (lambda ()
154               ;; Redefine arrow keys, since promoting/demoting and moving
155               ;; subtrees up and down are less frequent tasks then
156               ;; navigation and visibility cycling
157                 (org-defkey org-mode-map
158                             (kbd "M-<left>") 'outline-hide-more)
159                 (org-defkey org-mode-map
160                             (kbd "M-<right>") 'outline-show-more)
161                 (org-defkey org-mode-map
162                             (kbd "M-<up>") 'outline-previous-visible-heading)
163                 (org-defkey org-mode-map
164                             (kbd "M-<down>") 'outline-next-visible-heading))
165             'append))
166 #+end_src
167
168 Add this if you (e.g.) always want outline/outshine for emacs-lisp buffers
169 (recommended):
170
171 #+begin_src emacs-lisp
172 (add-hook 'emacs-lisp-mode-hook 'outline-minor-mode)  
173 #+end_src
174
175 If you want a different prefix key for outline-minor-mode, insert first
176 (e.g.):
177
178 #+begin_src emacs-lisp
179  (defvar outline-minor-mode-prefix "\C-c") 
180 #+end_src
181
182 or whatever you like best to replace the (quite unusable) original prefix
183 "\C-c @". The prefix can only be changed before outline (minor) mode is
184 loaded.
185
186 **** Outshine's fundamental idea
187      :PROPERTIES:
188      :CUSTOM_ID: fundamental-idea
189      :END:
190
191 /outshine/ is based on a very simple but powerfull idea, that enables its use
192 in any Emacs major-mode (in theory at least):
193
194 #+begin_verse
195 Outshine headlines are Org-mode headlines out-commented with =comment-region=
196 #+end_verse
197
198 Thus, the file at hand must be outline-structured 'the outshine way', i.e.
199 with the headlines being proper Org-mode headlines, marked and outcommented
200 with =comment-region=. As an example, to generate a 3rd level
201 outshine-headline in an Emacs Lisp file, write down
202
203 : ,-----------------------
204 : | *** Third Level Header 
205 : `-----------------------
206
207 mark the header line, and apply =comment-region= on it:
208
209 : ,-----------------------
210 : | ;; *** Third Level Header 
211 : `-----------------------
212
213 In a LaTeX file, an adecuate header will look like this:
214
215 : ,-----------------------
216 : | % *** Third Level Header 
217 : `-----------------------
218
219 and in a PicoLisp file like this (always depending of the major-mode specific
220 values of =comment-start=, =comment-end=, =comment-add= and
221 =comment-padding=):
222
223 : ,-----------------------
224 : | ## *** Third Level Header 
225 : `-----------------------
226
227 =outshine.el=, =outorg.el= and =navi-mode.el= are all examples of how to
228 structure emacs-lisp source files with outshine-style headlines. 
229
230 **** Fontification, Navigation and Structure Editing
231      :PROPERTIES:
232      :CUSTOM_ID: fontification-navigation-and-structure-editing
233      :END:
234
235 After structuring a source code file the 'outshine-way' and loading
236 outline-minor-mode with outshine-extensions, the file will have a very
237 Org-mode like 'look-and-feel'. The headlines (up to level 8) are fontified the
238 same way Org-mode headlines are fontified, and the very specific navigation
239 and structure editing commands of outline-minor-mode as well as their more
240 general Org-mode style counterparts are available:
241
242 =outline-minor-mode= Minor Mode Bindings:
243
244 | key       | binding                          |
245 |-----------+----------------------------------|
246 | C-c       | PrefixCommand                    |
247 | <M-down>  | outline-next-visible-heading     |
248 | <M-left>  | outline-hide-more                |
249 | <M-right> | outline-show-more                |
250 | <M-up>    | outline-previous-visible-heading |
251 | <tab>     | outshine-cycle-subtree           |
252 | <backtab> | outshine-cycle-buffer            |
253 | C-c C-a   | show-all                         |
254 | C-c C-b   | outline-backward-same-level      |
255 | C-c C-c   | hide-entry                       |
256 | C-c C-d   | hide-subtree                     |
257 | C-c C-e   | show-entry                       |
258 | C-c C-f   | outline-forward-same-level       |
259 | C-c TAB   | show-children                    |
260 | C-c C-k   | show-branches                    |
261 | C-c C-l   | hide-leaves                      |
262 | C-c RET   | outline-insert-heading           |
263 | C-c C-n   | outline-next-visible-heading     |
264 | C-c C-o   | outline-hide-other               |
265 | C-c C-p   | outline-previous-visible-heading |
266 | C-c C-q   | outline-hide-sublevels           |
267 | C-c C-s   | show-subtree                     |
268 | C-c C-t   | hide-body                        |
269 | C-c C-u   | outline-up-heading               |
270 | C-c C-v   | outline-move-subtree-down        |
271 | C-c C-^   | outline-move-subtree-up          |
272 | C-c '     | outorg-edit-as-org               |
273 | C-c @     | outline-mark-subtree             |
274 | C-c I     | outline-previous-visible-heading |
275 | C-c J     | outline-hide-more                |
276 | C-c K     | outline-next-visible-heading     |
277 | C-c L     | outline-show-more                |
278 | C-c C-<   | outline-promote                  |
279 | C-c C->   | outline-demote                   |
280
281 ** Subtree and Comment Editing
282    :PROPERTIES:
283    :CUSTOM_ID: comment-editing
284    :END:
285 *** Introduction
286     :PROPERTIES:
287     :CUSTOM_ID: comment-editing-introduction
288     :END:
289
290     Once a (outshine) source code buffer looks and behaves like an Org-mode
291     buffer, it would be nice to have the full editing power of Org-mode
292     available when editing the (comment) text parts or overall structure of
293     the buffer.
294
295     Think "reverse Org-Babel": editing of comment-sections or entire subtrees
296     from source code files in temporary Org-mode buffers instead of editing of
297     Org-mode source-blocks in temporary source-code buffers.
298
299     There are two new libraries available for editing with Org-mode in other
300     major-modes, /outorg/ and /poporg/. Although developed independently with
301     very different implementations, both libraries complement each other very
302     well in their functionality. 
303
304 *** Outorg
305     :PROPERTIES:
306     :CUSTOM_ID: outorg
307     :END:
308
309 **** Introduction and Installation
310     :PROPERTIES:
311     :CUSTOM_ID: outorg-introduction-and-installation
312     :END:
313
314 *outorg* is a library written by /Thorsten Jolitz/ on top of his /outshine/
315 library. Thus, /outorg/ needs /outshine/, and files that are structured with
316 outshine-style headers, otherwise it won't work. 
317
318 You can download the file (or clone the github-repo) here:
319
320 | https://github.com/tj64/outorg           |
321 | git clone git@github.com:tj64/outorg.git |
322
323 /outorg/ requires Org-mode too, thus should be loaded after Org-mode. Insert
324
325 #+begin_src emacs-lisp
326  (require 'outorg)
327 #+end_src
328
329 in your .emacs and you are done. 
330
331 **** Usage
332      :PROPERTIES:
333      :CUSTOM_ID: outorg-usage
334      :END:
335
336 /outorg's/ main command is
337
338 :  ,---------------------------
339 :  | C-c ' (outorg-edit-as-org)
340 :  `---------------------------
341
342 used in source-code buffers where `outline-minor-mode' is activated with
343 `outshine' extensions. The Org-mode edit-buffer popped up by this command
344 has `outorg-edit-minor-mode' activated, a minor-mode with only 2 commands:
345
346 : ,----------------------------------------
347 : | M-# (outorg-copy-edits-and-exit)
348 : | C-x C-s (outorg-save-edits-to-tmp-file)
349 : `----------------------------------------
350
351 If you want to insert Org-mode source-code or example blocks in
352 comment-sections, simply outcomment them in the outorg-edit buffer before
353 calling `outorg-copy-edits-and-exit'.
354
355 If you want to insert Org-mode source-code or example blocks in
356 comment-sections, simply outcomment them in the outorg-edit buffer before
357 calling `outorg-copy-edits-and-exit'.
358
359 Thus, with point inside a subtree or on a subtree header, pressing =C-c '
360 (outorg-edit-as-org)= will open this subtree in a temporary Org-mode edit
361 buffer, with all out-commented parts in the original buffer uncommented, and
362 all source code parts enclosed in Org-mode source blocks. 
363
364 When =outorg-edit-as-org= is called with a prefix =C-u=, the whole source-code
365 buffer will be transformed into Org-mode and offered for editing in a
366 temporary Org-mode buffer, all headlines folded except the subtree where point
367 was in.
368
369 If the original-buffer was read-only, the user is asked if he wants to make it
370 writable for the Org-mode editing. If he answers yes, the buffer can be
371 edited, but will be set back to read-only again after editing is finished.
372
373 To avoid accidental loss of edits, the temporary outorg-edit-buffer is backed
374 up in the OS =/tmp= directory. During editing, the outorg-edit-buffer can be
375 saved as usual with =save-buffer= via  =C-x C-s=. Even when killed by
376 accident, that last state of the outorg-edit-buffer will be saved and can be
377 recovered. 
378
379 When done with editing in Org-mode, =M-# (Meta-key and #)= is used to call
380 =outorg-copy-edits-and-exit=, a command that orderly exits the edit-buffer by
381 converting the (modified) comment-sections back to comments and extracting the
382 source-code parts out of the Org-mode source-code blocks.
383
384 Please note: /outorg/ is line-based, it only works with 'one-line' comments,
385 i.e. with comment-sections like those produced by `comment-region' (a command
386 that comments or uncomments each line in the region). Those special multi-line
387 comments found in many programming languages are not recognized and lead to
388 undefined behaviour.
389
390 **** Outorg vs Poporg
391      :PROPERTIES:
392      :CUSTOM_ID: outorg-vs-poporg
393      :END:
394
395 /outorg/ works on subtrees (or whole buffers). 
396
397 One advantage of this is that there is always a complete subtree (-hierarchy)
398 in the outorg-edit-buffer, thus not only the Orgmode editing functionality can
399 be applied, but also its export facilities. As an example, in order to produce
400 the nice README.txt files for the github-repos of /outshine/, /outorg/ and
401 /navi-mode/, I simply called =outorg-edit-as-org= on the first
402 1st-level-headline of the source-code files (the file header comment-sections)
403 and exported the subtree to ASCII.
404
405 One disadvantage of this is that comment-strings of (e.g. emacs-lips)
406 functions cannot be edited comfortably, since after transformation of the
407 source-code buffer they end up inside Org-mode source-code blocks - as
408 comment-strings, just like before. 
409
410 Enters /poporg/. It will be described in much detail in the next section, but
411 it can already be mentioned here that it does exactly what /outorg/ cannot do
412 well - Org-mode editing of atomic, isolated comment-strings, no matter where
413 they are found in the source code buffer. And it is, in contrast to /outorg/,
414 completely independent from outline structuring with e.g. /outshine/ or
415 /orgstruct/. 
416
417 *** Poporg
418     :PROPERTIES:
419     :CUSTOM_ID: poporg
420     :END:
421
422 [NOTE: This section of the tutorial is copied from
423 https://github.com/pinard/poporg, where you can find the =poporg.el= file too,
424 and only slightly modified]
425
426 **** Introduction
427      :PROPERTIES:
428      :CUSTOM_ID: poporg-introcuction
429      :END:
430
431 *poporg* is a small Emacs Lisp project written by /François Pinard/, to help
432 editing program string or comments using Org mode.
433
434 Literate programming with Org is often presented as mixing programs snippets
435 within an Org document, with tools to extract pure programs out of the Org
436 files. I (/François/) would prefer it the other way around: mixing
437 documentation snippets within program source code, with tools to extract pure
438 Org documentation from the source files.
439
440 Emacs does not nicely handle multiple major modes in a single buffer.
441 So far, many solutions have been implemented, all yielding some level
442 of happiness, but none are perfect.  The *poporg* approach avoids the
443 problem by extracting the block comment or the string, from a buffer
444 using a major programming mode, into a separate buffer to be edited in
445 Org mode, but containing only that block comment or that string.  Once
446 the edit is completed, the modified comment or string gets
447 re-integrated in the buffer containing the program, replacing the
448 original contents.
449
450 **** Installation
451      :PROPERTIES:
452      :CUSTOM_ID: poporg-installation
453      :END:
454
455 To install *poporg*, move files =poporg.el= and =rebox.el= at a place
456 where Emacs will find them.  You might byte-compile the files if you
457 want.
458
459 To use *poporg*, you need to pick some unused keybinding and add a few
460 lines to your =~/.emacs= file.  For one, I picked =C-c e o= and added
461 these lines:
462
463 #+BEGIN_SRC emacs-lisp
464 (autoload 'poporg-dwim "poporg" nil t)
465 (global-set-key "\C-ceo" 'poporg-dwim)
466 #+END_SRC
467
468 Another possibility would be to use 
469
470 #+BEGIN_SRC emacs-lisp
471 (global-set-key "\C-c `" 'poporg-dwim)
472 #+END_SRC
473
474 i.e. =C-c and backquote=, just to harmonize a bit the keybindings for
475 /outorg/ and /poporg/, but note that this keybinding is already in use in
476 Org-mode too. 
477
478 **** Usage
479      :PROPERTIES:
480      :CUSTOM_ID: poporg-usage
481      :END:
482
483 While editing a buffer containing a program, you may edit a comment
484 block or a string (often a doc-string) in Org mode by placing the
485 cursor within or nearby that comment or string, and calling
486 =poporg-dwim= using your selected keybinding.  This pops another buffer
487 in Org Mode (hence the project name), containing the comment or
488 string.  Once your edition is done, right in the popped up editing
489 buffer, call =poporg-dwim= again to complete the edition, or merely kill
490 that buffer to abandon the edition.
491
492 More precisely, if the cursor is within a comment block or a string,
493 this is what gets edited.  If the cursor is not within a comment block
494 or a string, a comment or string following the cursor gets selected
495 instead.  Otherwise, this is the comment or string which precedes the
496 cursor which is selected for edition.  Python mode receives a special
497 treatment: if the cursor is within a string, it is assumed to be a
498 sextuple-quoted string (that is, a triple double-quoted one), and this
499 is what the tool selects.
500
501 While the comment or string is being copied in the editing buffer and
502 until the edition is completed, the original comment or string in the
503 original buffer is greyed out and protected against accidental
504 modification.  Calling =poporg-dwim= again from within a greyed out
505 region recovers the editing buffer, it does not create a new
506 one.  *poporg* asks for confirmation when the user attempts to kill an
507 editing buffer which has modifications.  *poporg* also prevents the
508 original buffer from being killed while there are pending *poporg*
509 edits, the user should either complete or abandon all those edits
510 before killing the original buffer.
511
512 Functions added to =poporg-edit-hook= are run once the *poporg* editing buffer
513 has been set up with its contents, with the common prefix already removed,
514 these functions may further modify the buffer contents. Functions added to
515 =poporg-edit-exit-hook= are run when *poporg* is about to reinstate the common
516 prefix and move back the editing buffer contents into the original programming
517 buffer, these functions may alter the contents as needed. (I (/François/) did
518 not need these hooks, so let's talk if you need them to be defined
519 differenty!)
520
521 **** Known bugs
522      :PROPERTIES:
523      :CUSTOM_ID: poporg-known-bugs
524      :END:
525
526 The following list is organized in decreasing order of approximative
527 or subjective priority.  You may also check if there are any [[https://github.com/pinard/poporg/issues][issues on
528 GitHub]].
529 - If the cursor is located immediately before the opening delimiter of
530   a string before =poporg-dwim=, some extraneous text to edit may be
531   collected from before the cursor.
532 - The protective measures against losing a pending edition do not work
533   when the user plainly exits Emacs.
534 - If characters are added immediately before or immediately after the
535   region being edited, while the edition is pending, the characters
536   after the region are preserved when the user completes its *poporg*
537   edition, but the characters before the region are lost, while they
538   should have been preserved.
539 - Even if a region being edited is /intangible/ (meaning that the cursor
540   cannot be pushed into it), it is not /read-only/ and could have its
541   contents deleted by editing from either end of the region.  I
542   suspect (without being sure) that this bug, and the preceding one,
543   come from the fact overlays and text-properties do not behave the
544   same.
545 - Ideally, the region being edited should be /read-only/ but not
546   /intangible/, in that the cursor could be moved into it, from where a
547   =poporg-dwim= command would popup the associated edit buffer.  This
548   would be particularly useful when a user has many pending *poporg*
549   edits.
550 - It has been suggested, and rightly so, that =C-c C-c= would be a nice
551   keybinding for completing a *poporg* edit.  The problem with this is
552   that the edit buffer uses Org mode, where =C-c C-c= is overcrowded
553   with many functionnalities already; some care would be needed to
554   make sure this command, used with another intent, does not
555   unexpectedly close the edition.
556
557 **** Caveats
558      :PROPERTIES:
559      :CUSTOM_ID: poporg-caveats
560      :END:
561
562 - I (/François/) do not much like that *poporg* depends on Rebox, which is a
563   complex piece of code compared to the reminder of *poporg*. For comments,
564   Rebox studies the file contents to guess comment delimiters and box styles,
565   while for strings, *poporg* rather relies the syntax analysis previously
566   made by the programming major mode, and expressed through faces. These
567   approaches are too different, maybe both are wrong anyway. Moreover, the
568   faces approach easily fools *poporg* when a comment or string does not use a
569   uniform face. One advantage of using Rebox might be that it brings *poporg*
570   closer to the capability of editing Org mode comments for a wider variety of
571   boxing patterns.
572
573 - Once the string and comment is back into the programming buffer, we
574   loose Org mode highlighting and presentation details, which is
575   unfortunate.  Multiple editing modes in Emacs are not able to
576   highlight sections of a file according to the intended mode for each
577   section: there is a single mode for the whole buffer in fact.  Org
578   mode, on the other hand, has the virtue of correctly highlighting
579   the code snippets it contains, so surely, there is a way to do
580   things as they should, that might be understood and recycled, I'm
581   not sure.
582
583 - *poporg* should ideally be accompanied by a set of conventions and
584   some tools for proper extraction of an Org file out of program
585   sources.  One is already provided for Python, it would be nice to
586   also have some support for other languages.
587
588 **** History
589      :PROPERTIES:
590      :CUSTOM_ID: poporg-history
591      :END:
592
593 *poporg* recycles a few ideas from two previous Emacs projects:
594
595 - my (/François/) PO mode ([[http://git.savannah.gnu.org/cgit/gettext.git/tree/gettext-tools/misc/po-mode.el][source]] and [[http://www.gnu.org/software/gettext/manual/html_node/PO-Mode.html][documentation]]), for the idea of using
596   separate buffers for edition. For PO files, the need is quite clear:
597   =msgstr= strings use escaping which is easy to get wrong, so the idea of a
598   separate buffer is a way to remove that concern from the user, PO mode
599   unquotes before presenting the string to the user, and requotes it once the
600   editing is completed. This was also solving the problem that =msgid= and
601   =msgstr= fields, and the reminder of the PO file, could be using different
602   character sets.
603
604 - my (/François/) Rebox tool ([[https://github.com/pinard/Pymacs/blob/master/contrib/rebox/rebox.el][source]] and [[https://github.com/pinard/Pymacs/blob/master/contrib/rebox/README][documentation]]), for finding the
605   boundaries of block comments. Originally in Emacs Lisp, this tool has later
606   rewritten in Python at the time I was developing Pymacs, with a few minor
607   improvements while doing so. Le Wang, starting from my old Emacs Lisp, wrote
608   a /much/ enhanced version ([[https://github.com/lewang/rebox2/blob/master/rebox2.el][source]] and [[http://youtube.googleapis.com/v/53YeTdVtDkU][video]]). For *poporg*, however, the
609   needs are modest, so it includes the old Emacs Lisp version. See the very
610   last section of the Rebox documentation for more historial context.
611
612 **** Other tools
613      :PROPERTIES:
614      :CUSTOM_ID: poporg-other-tools
615      :END:
616
617 Major programming modes show comments and strings in full, and when
618 these comments or strings are written using Org, with all parts of a
619 link visible, it may be disruptive to those sensible to line width
620 limits.  The nice [[https://github.com/seanohalpin/org-link-minor-mode][org-link-minor-mode]] tool takes good care of this, by
621 hiding the usually invisible parts of an Org link in other modes.
622
623 Org comes with many tools for spreading Org over other major modes,
624 among which the following minor modes which may be /added/ to other
625 major modes:
626
627   | Command            |
628   |--------------------|
629   | *orgstruct-mode*   |
630   | *orgstruct++-mode* |
631   | *orgtbl-mode*      |
632
633 Org also has the following globally available commands:
634
635   | Command                    | Usual keybinding |
636   |----------------------------+------------------|
637   | *org-store-link*           | =C-c l=          |
638   | *org-insert-link-global*   | =C-c L=          |
639   | *org open-at-point-global* | =C-c O=          |
640   |----------------------------+------------------|
641
642 **** Python
643      :PROPERTIES:
644      :CUSTOM_ID: poporg-python
645      :END:
646
647 ***** PEP8 validation
648       :PROPERTIES:
649       :CUSTOM_ID: poporg-pep8-validation
650       :END:
651
652 The width of Org links often triggers the line length limit check of
653 the *pep8* program, which gets annoying when one uses *flymake* to get
654 real-time feedback while writing.  To silence these, I took advantage
655 of this [[https://gist.github.com/florentx/5024445/177f224f90d176365a2ecac2844875212d15c7ed][nice workaround]], installing a *pep8* replacement program, and
656 managed so *flymake* uses that replacement program instead of *pep8*.
657
658 ***** Extractor for Python
659       :PROPERTIES:
660       :CUSTOM_ID: poporg-python-extractor
661       :END:
662
663 The =extradoc.py= tool in this *poporg* project has the purpose of
664 extracting and processing the Org contents of a set of Python sources.
665 I used the =.py= suffix just in case there could be other =extradoc.LANG=
666 tools for similarly handling sources in other languages.  This
667 =extradoc.py= tool presumes that all Org text is made up by
668 concatenating the content of all sextuple-quoted strings (I mean
669 triple double-quoted strings).  Moreover, prefixed strings are not
670 recognized.  Here is its own documentation:
671
672 #+BEGIN_EXAMPLE
673 Extract documentation from one or more Python sources.
674 Documentation lies in all unprefixed, sextuple-quoted strings.
675
676 Usage: extradoc.py [OPTION]... [SOURCE]...
677
678 Options:
679   -c PREFIX     Common prefix for all output files.
680   -s            Split output in directory PREFIX, obey #+FILE directives.
681   -h            Produce an HTML file, either PREFIX.html or PREFIX/NAME.html.
682   -o            Produce an Org file, either PREFIX.org or PREFIX/NAME.org.
683   -p            Produce a PDF file, either PREFIX.pdf or PREFIX/NAME.pdf.
684   -t            Produce a translation file, name will be PREFIX.pot.
685   -v            Be verbose and repeat all of Emacs output.
686   -D SYM        Define SYMbol as being True
687   -D SYM=EXPR   Define SYMbol with the value of EXPR.
688   -I TAGS       Only include sections having one of TAGS in their header.
689   -X TAGS       Exclude sections having one of TAGS in their header.
690
691 If no SOURCE are given, the program reads and process standard input.
692 Option -c is mandatory.  If -h or -p are used and -o is not, file PREFIX.org
693 should not pre-exist, as the program internally writes it and then deletes it.
694
695 Some non-standard Org directives are recognized:
696   #+FILE: NAME.org   Switch output to NAME.org, also requires -s.
697   #+IF EXPR          Produce following lines only if EXPR is true, else skip.
698   #+ELIF EXPR        Expected meaning within an #+IF block.
699   #+ELSE             Expected meaning within an #+IF block.
700   #+ENDIF            Expected meaning to end an #+IF block.
701
702 EXPRs above are Python expressions, eval context comes from -D options.
703 TAGS represents a comma-separated list of Org tags.  To get through, a line
704 should go through the #+IF system, not be within an excluded section, and if
705 any included sections is specified, then either be part of one of them or
706 within the introduction (that is, before the first header).
707 #+END_EXAMPLE
708
709 ** Remote Buffer Control
710    :PROPERTIES:
711    :CUSTOM_ID: remote-buffer-control
712    :END:
713
714 While visibility-cycling and outline-navigation commands make it very
715 convenient to work even with big Org-mode or outshine buffers, it can't be
716 denied that an indirect read-only buffer with one-key command-bindings,
717 exclusively for navigation and high-level structure editing of the associated
718 original-buffer, can be even more convenient. 
719
720 Enters /navi-mode/, a major-mode by /Thorsten Jolitz/ derived from and
721 inspired by /occur-mode/ (and, to a certain extend, the =org-goto= command).
722 Just like /outorg/, /navi-mode/ depends on /outshine/ and works only with
723 source-code files structured with 'outshine-style' outline-headers. It does
724 work with org-mode files too, though. 
725
726 A /navi-buffer/ is a kind of "remote-control" for its associated
727 /original-buffer/. It offers a vast amount of views on the /original-buffer/
728 via predefined occur-searches that combine headlines and
729 (programming-language specific) keywords. It further allows many frequent
730 actions on the subtree at point to be triggered directly from the
731 /navi-buffer/, without (visibly) switching to the /original-buffer/ where the
732 actions take place. 
733
734 A special feature of /navi-mode/ is its customizability. It predefines all
735 ASCII printing characters as keybindings for the =navi-generic-command=, and
736 users can therefore map their user-defined regexp-searches (customizable
737 variable =navi-keywords=) to any of the many free one-key bindings (in
738 customizable variable =navi-key-mappings=). These customizations are made by
739 programming-language, thus the Emacs community could work out default
740 'alists' for many languages that then may be used and modified by the users. 
741
742 /navi-mode's/ author /Thorsten Jolitz/ already worked out two configurations,
743 one for Emacs Lisp and the other for PicoLisp. You could use them as
744 inspiration for a configuration of your favorite programming language - and
745 send these 'alists' to him so that he can include them in the library. The
746 more predefined sets of keyword searches there are, the easier to use
747 /navi-mode/ with many languages.
748
749 *** Navi-mode
750     :PROPERTIES:
751     :CUSTOM_ID: navi-mode
752     :END:
753
754 **** About navi-mode
755      :PROPERTIES:
756      :CUSTOM_ID: about-navi-mode
757      :END:
758
759 This file implements extensions for occur-mode. You can think of a navi-buffer
760 as a kind of 'remote-control' for an (adecuately) outline-structured
761 original-buffer. It enables quick navigation and basic structure editing in
762 the original-buffer without (necessarily) leaving the navi-buffer. When
763 switching to the original-buffer and coming back after some modifications, the
764 navi-buffer is always reverted (thus up-to-date).
765
766 Besides the fundamental outline-heading-searches (8 outline-levels) and the 5
767 basic keyword-searches (:FUN, :VAR, :DB, :OBJ and :ALL), all languages can
768 have their own set of searches and keybindings (see =navi-key-mappings= and
769 =navi-keywords=). Heading-searches and keyword-searches can be combined,
770 offering a vast amount of possible 'views' at the original-buffer.
771
772 **** Installation
773
774 Download (or clone the github-repos of) the three required libraries
775
776 | `navi-mode.el' | https://github.com/tj64/navi           |
777 |                | git clone git@github.com:tj64/navi.git |
778 | `outshine.el'  | https://github.com/tj64/outshine       |
779 | `outorg.el'    | https://github.com/tj64/outorg         |
780
781 and put them in a place where Emacs can find them (on the Emacs 'load-path').
782 Follow the installation instructions in =outshine.el= and =outorg.el=.
783
784 Install =navi-mode.el= by adding
785
786 #+begin_src emacs-lisp
787  (require 'navi-mode)
788 #+end_src
789
790 to your .emacs file. 
791
792
793 **** Usage
794      :PROPERTIES:
795      :CUSTOM_ID: navi-mode-usage
796      :END:
797
798 For /navi-mode/ to work, the original-buffer must be outline-structured 'the
799 outshine way', i.e. with the headlines being proper Org-mode headlines, marked
800 and outcommented with /comment-region/. 
801
802 The second assumption is that /outline-minor-mode/ is activated in the
803 original-buffer and /outshine.el/ loaded like described in its installation
804 instructions.
805
806 When these pre-conditions are fullfilled (/outorg.el/ must be loaded too), you
807 can use =M-s n (navi-search-and-switch)= to open a /navi-buffer/ and
808 immediately switch to it. The new navi-buffer will show the first-level
809 headings of the /original-buffer/, with point at the first entry.
810
811 You can then:
812
813  - Show headlines (up-to) different levels:
814
815 | key     | command            | function-name        |
816 |---------+--------------------+----------------------|
817 | 1 ... 8 | show levels 1 to 8 | navi-generic-command |
818
819  - Navigate up and down in the search results shown in the navi-buffer:
820
821 | key | command   | function-name       |
822 |-----+-----------+---------------------|
823 | p   | previous  | occur-prev          |
824 | n   | next      | occur-next          |
825 | DEL | down page | scroll-down-command |
826 | SPC | up page   | scroll-up-command   |
827
828  - Revert the navi-buffer (seldom necessary), show help for the user-defined
829    keyword-searches, and quit the navi-buffer and switch-back to the
830    original-buffer:
831
832 | key | command                   | function-name        |
833 |-----+---------------------------+----------------------|
834 | g   | revert buffer             | navi-revert-function |
835 | h   | show help                 | navi-show-help       |
836 | q   | quit navi-mode and switch | navi-quit-and-switch |
837
838  - Switch to the original-buffer and back to the navi-buffer, display an
839    occurence in the original-buffer or go to the occurence:
840
841 | key     | command                | function-name                     |
842 |---------+------------------------+-----------------------------------|
843 | M-s n   | launch navi-buffer     | navi-search-and-switch            |
844 | M-s s   | switch to other buffer | navi-switch-to-twin-buffer        |
845 | M-s M-s |                        |                                   |
846 | s       |                        |                                   |
847 | d       | display occurrence     | occur-mode-display-occurrence     |
848 | o       | goto occurrence        | navi-goto-occurrence-other-window |
849
850  - Structure editing on subtrees and visibility cycling
851
852 | key       | command                        | function-name          |
853 |-----------+--------------------------------+------------------------|
854 | TAB       | cycle subtrees                 | navi-cycle-subtree     |
855 | <backtab> | cycle buffer                   | navi-cycle-buffer      |
856 | +         | Demote Subtree                 | navi-demote-subtree    |
857 | -         | promote subtree                | navi-promote-subtree   |
858 | \^        | move up subtree (same level)   | navi-move-up-subtree   |
859 | <         | move down subtree (same level) | navi-move-down-subtree |
860
861  - Miscancellous actions on subtrees
862
863 | key | command                    | function-name                     |
864 |-----+----------------------------+-----------------------------------|
865 | m   | mark subtree               | navi-mark-subtree-and-switch      |
866 | c   | copy subtree               | navi-copy-subtree-to-register-s   |
867 | k   | kill subtree               | navi-kill-subtree                 |
868 | y   | yank killed/copied subtree | navi-yank-subtree-from-register-s |
869 | u   | undo last change           | navi-undo                         |
870 | r   | narrow to subtree          | navi-narrow-to-subtree            |
871 | w   | widen                      | navi-widen                        |
872 | l   | query-replace              | navi-query-replace                |
873 | i   | isearch                    | navi-isearch                      |
874 | e   | edit as org (outorg)       | navi-edit-as-org                  |
875
876  - Furthermore, there are five (semantically) predefined keyword-searches:
877
878 | key | keyword-symbol | searches for               |
879 |-----+----------------+----------------------------|
880 | f   | :FUN           | functions, macros etc.     |
881 | v   | :VAR           | vars, consts, customs etc. |
882 | x   | :OBJ           | OOP (classes, methods etc) |
883 | b   | :DB            | DB (store and select)      |
884 | a   | :ALL           | all                        |
885
886
887  - And (potentially) many more user-defined keyword-searches
888 (example Emacs Lisp):
889
890 | key | keyword-symbol | searches for |
891 |-----+----------------+--------------|
892 | F   | :defun         | (defun       |
893 | V   | :defvar        | (defvar      |
894 | C   | :defconst      | (defconst    |
895 | G   | :defgroup      | (defgroup    |
896 | U   | :defcustom     | (defcustom   |
897 | A   | :defadvice     | (defadvice   |
898 | M   | :defmacro      | (defmacro    |
899 | E   | :defface       | (defface     |
900 | S   | :defstruct     | (defstruct   |
901 | L   | :defclass      | (defclass    |
902
903  - Headline-searches and keyword-searches can be combined, e.g.
904
905 : ,------
906 : | C-2 f 
907 : `------
908
909 in a /navi-buffer/ associated to an Emacs Lisp source file shows all headlines
910 up-to level 2 as well as all function, macro and advice definitions in the
911 original-buffer,
912
913 : ,------
914 : | C-5 a 
915 : `------
916
917 shows all headlines up-to level 5 as well as all functions, variables,
918 classes, methods, objects, and database-related definitions. The exact meaning
919 of the standard keyword-searches 'f' and 'a' must be defined with a regexp in
920 the customizable variable `navi-keywords' (just like the user-defined
921 keyword-searches).
922
923 * Screencasts 
924   :PROPERTIES:
925   :CUSTOM_ID: screencasts
926   :END:
927
928 There are some screencasts on Youtube that show the libraries mentioned in
929 this article in action:
930
931 | topic                          | url                            |
932 |--------------------------------+--------------------------------|
933 | <30>                           | <30>                           |
934 | Modern conventions for Emacs Lisp files | https://www.youtube.com/watch?v=nqE6YxlY0rw |
935 | Exploring Bernt Hansen's Org-mode tutorial with 'navi-mode' | https://www.youtube.com/watch?v=nqE6YxlY0rw |
936 | Exploring my dot emacs file with 'navi-mode' | https://www.youtube.com/watch?v=nqE6YxlY0rw |
937 | Exploring a PicoLisp source file with GNU Emacs navi-mode | https://www.youtube.com/watch?v=MYJvQ-5dvK8 |
938
939 'Modern conventions for Emacs Lisp files' is probably the video you should
940 watch first, it explores 'navi-mode.el' itself as an Emacs Lisp library
941 structured the 'outshine way', and shows the use of outline-minor-mode,
942 outorg, poporg and navi-mode on such a file. And is has the best background
943 music.