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