You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
259 lines
11 KiB
259 lines
11 KiB
#+PROPERTY: logging nil |
|
|
|
* Tasks |
|
|
|
** TODO Enable and test with lexical-binding |
|
|
|
** TODO Use/integrate/rewrite [[id:a240e86a-b615-4672-a45b-2a8502d8997c][old commentary]] |
|
|
|
** TODO Rewrite readme |
|
|
|
* Reference |
|
|
|
** Old commentary |
|
:PROPERTIES: |
|
:ID: a240e86a-b615-4672-a45b-2a8502d8997c |
|
:END: |
|
|
|
Parts of the old commentary removed from =outshine.el=. |
|
|
|
#+BEGIN_SRC elisp |
|
;; Outshine attempts to bring the look & feel of Org-mode to the (GNU |
|
;; Emacs) world outside of the Org major-mode. It is an extension of |
|
;; `outline-minor-mode' (Org-mode itself derives from outline-mode), |
|
;; that should act as a silent replacement of Outline. Just change |
|
;; all your calls to `outline-minor-mode' into `outshine-mode'. |
|
|
|
;; Outshine is major-mode agnostic. At least in theory, it should work |
|
;; out-of-the-box with all major-modes, even those not yet written, as |
|
;; long as these modes have comment syntax defined. In real life there |
|
;; are some major-modes where outshine just works, others that need |
|
;; some minor tweaks to make outshine work, and a few that need |
|
;; special handling. |
|
|
|
;; An outshine file is structured just like an org file, only that the |
|
;; headlines are outcommented with the current major-mode's comment |
|
;; syntax. We call these outcommented org headers 'outshine |
|
;; headers'. The different headline levels are fontified like in |
|
;; Org-mode, and many of the outline-navigation, visibility cycling |
|
;; and structure editing commands known from Org-mode work in outshine |
|
;; too. An Org-mode user will feel right at home in an outshine |
|
;; buffer, the look&feel should be pretty similar, only the |
|
;; keybindings differ. Since outshine extends a minor-mode it has to |
|
;; avoid conflicts with major-mode keymaps by using a rather unusual |
|
;; prefix that is still easy to type (M-#). But the Org-mode |
|
;; speed-commands have been ported to outshine too, and they use |
|
;; exactly the same (one-key) bindings like in Org-mode. |
|
|
|
;; There is a distinction between the library 'outshine.el' and the |
|
;; 'Outshine Project' (or 'Outshine Suite') which contains 3 |
|
;; libraries: |
|
|
|
;; - outshine.el :: The core library. To use it, simply call |
|
;; `outshine-mode' instead of `outline-minor-mode'. |
|
|
|
;; - outorg.el :: Major-mode for toggling between the |
|
;; programming-mode view and the org-mode view of |
|
;; outshine buffers, i.e. buffers structured with |
|
;; outshine headers that have outline-minor-mode with |
|
;; outshine extensions activated. |
|
|
|
;; - navi-mode.el :: Occur-based major-mode for super-fast |
|
;; buffer-navigation and buffer-remote-control with |
|
;; one-key-bindings from an associated read-only |
|
;; *Navi* buffer. Navi-mode allows to have the |
|
;; (outshine- or org-) buffer overview side by side |
|
;; with the buffer details, and it gives many |
|
;; different kinds of overviews (these views are |
|
;; actually customizable). With point in the *Navi* |
|
;; overview buffer, many actions in the associated |
|
;; original (outshine- or org-) buffer can be |
|
;; triggered without leaving the *Navi* buffer. |
|
|
|
|
|
;; Note that there is a fourth library 'poporg.el' from François |
|
;; Pinard, which allows to edit function docstrings in temporary |
|
;; Org-mode buffers and thus nicely complements 'outorg.el'. |
|
|
|
;; Together these libraries enable a lightweight kind of 'literate |
|
;; programming' that turns the usual implementation of the concept |
|
;; upside-down: instead of using a text-mode as default and taking |
|
;; extra action to edit and execute source-code, with Outshine the |
|
;; programming-mode is the default mode and the text-mode |
|
;; (i.e. Org-mode) only called when needed. This is much simpler, it |
|
;; treats Org-mode and Programming-mode simply as two different views |
|
;; on the same (outshine) file while making it easy to switch between |
|
;; these views. |
|
|
|
;;;;; History and Credits |
|
|
|
;; The outshine.el library merges, modifies and extends two existing |
|
;; extension-libraries for `outline' (minor) mode: `outline-magic' (by |
|
;; Carsten Dominik) and `out-xtra' (by Per Abrahamsen). It offers all the |
|
;; functionality of `outline-magic' (with some tiny changes and fixes) |
|
;; and parts of the functionality of `out-xtra', together with many new |
|
;; features and ideas. |
|
|
|
;; See `outline-magic.el' (https://github.com/tj64/outline-magic) for |
|
;; detailled instructions on the usage of the additional outline |
|
;; functions introduced by `outline-magic'. |
|
|
|
;; Furthermore, `outshine.el' includes some functions and keybindings |
|
;; from `outline-mode-easy-bindings' |
|
;; (http://emacswiki.org/emacs/OutlineMinorMode). Unfortunately, no |
|
;; author is given for that library, so I cannot credit the person who |
|
;; wrote it. |
|
|
|
;;;;; Installation |
|
|
|
;; There are three ways to get outshine.el (and the other Outshine |
|
;; libraries): |
|
|
|
;; 1. Clone the git repo or fork them on github |
|
;; (https://github.com/alphapapa/outshine) |
|
|
|
;; 2. Use the package manager to install them (from MELPA). |
|
|
|
;; 3. Simply download the raw .el files from github and copy them to |
|
;; a location where Emacs can find them. This is not really |
|
;; recommended, since easy updating is not possible this way. |
|
|
|
;; Note that since version 2.0, outshine.el depends on outorg.el and |
|
;; navi-mode.el depends on both, outshine.el and outorg.el. So the order |
|
;; of installation should be |
|
|
|
;; 1. outorg |
|
;; 2. outshine |
|
;; 3. navi-mode (optional) |
|
|
|
;; To get started, simply start Outshine with `M-x outshine-mode RET' |
|
|
|
;; Add this to your init file if you always want outshine for emacs-lisp |
|
;; buffers (recommended): |
|
|
|
;; : #+begin_src emacs-lisp |
|
;; : (add-hook 'emacs-lisp-mode-hook 'outshine-mode) |
|
;; : #+end_src |
|
|
|
;; It makes sense to add 'outline-minor-mode' to the hooks of other |
|
;; major-modes too, e.g. |
|
|
|
;; : #+begin_src emacs-lisp |
|
;; : (add-hook 'LaTeX-mode-hook 'outshine-mode) |
|
;; : (add-hook 'picolisp-mode-hook 'outshine-mode) |
|
;; : (add-hook 'clojure-mode-hook 'outshine-mode) |
|
;; : (add-hook 'ess-mode-hook 'outshine-mode) |
|
;; : (add-hook 'ledger-mode-hook 'outshine-mode) |
|
;; : (add-hook 'message-mode-hook 'outshine-mode) |
|
;; : #+end_src |
|
|
|
;; or whatever your favorite Emacs modes are. Then you can structure and |
|
;; handle all your source-files just like Org files, allowing for a |
|
;; uniform approach to file structuring independent from the (text or |
|
;; programming) mode. |
|
|
|
;; Outline(-minor)-mode comes with a rather unusable prefix key |
|
;; out-of-the-box. You need to set the outshine prefix (M-#) in your init |
|
;; file before (!) outline-mode is loaded to enable the outshine |
|
;; keybindings: |
|
|
|
;; : #+begin_src emacs-lisp |
|
;; : (defvar outline-minor-mode-prefix "\M-#") |
|
;; : #+end_src |
|
|
|
;;;;; Usage |
|
|
|
;;;;;; Basic Usage |
|
|
|
;; The outshine.el extensions to outline-minor-mode aim to make its |
|
;; use more similar to Org-mode. Given a correctly structured outshine |
|
;; buffer, outline-navigation, structure-editing and visibility |
|
;; cycling with outshine should make an Org-mode user feel right at |
|
;; home. |
|
|
|
;; Try C-h m (describe-mode) and C-h b (describe-bindings) in an |
|
;; outshine buffer to find out more about the available functions and |
|
;; their keybindings. |
|
|
|
;; The very useful Org speed-commands have been ported to outshine, |
|
;; here a quote from the |
|
;; [[http://orgmode.org/manual/Speed-keys.html][Org-mode manual]] that |
|
;; describes what they do: |
|
|
|
;; #+BEGIN_QUOTE |
|
;; Single keys can be made to execute commands when the cursor is at |
|
;; the beginning of a headline, i.e., before the first star. |
|
;; #+END_QUOTE |
|
|
|
;; To activate speed-keys, put this in your init-file: |
|
|
|
;; : #+BEGIN_SRC emacs-lisp |
|
;; : (setq outshine-use-speed-commands t) |
|
;; : #+END_SRC |
|
|
|
;; Call `outshine-speed-command-help' to get an overview over the |
|
;; available functionality and the keybindings. |
|
|
|
;; Note that outshine works with 'imenu' (`outshine-imenu') and has |
|
;; extra functionality to show the number of hidden lines in folded |
|
;; headlines (`outshine-show-hidden-lines-cookies'). There are a few |
|
;; utility commands for latex-mode too |
|
;; (`outshine-latex-insert-header', |
|
;; `outshine-latex-insert-headers-in-buffer' and |
|
;; `outshine-TeX-command-region-on-subtree') |
|
|
|
;;;;;; Extended Usage (outshine-use-outorg) |
|
|
|
;; Outshine's basic usage is mostly based on its own implementation, |
|
;; i.e. code from existing extensions to outline-minor-mode, new code |
|
;; written for outshine, as well as code ported from Org-mode to |
|
;; outshine. |
|
|
|
;; Its extended use aims to make outshine headers more 'intelligent', |
|
;; i.e. make them know about TODO items, tags, properties, dates and |
|
;; times. This is done via the `outshine-use-outorg' function that |
|
;; uses outorg to first convert an outshine buffer/subtree to |
|
;; org-mode, then call an Org function on it, and finally convert the |
|
;; edited buffer/subtree back to outshine. The outshine-use-outorg |
|
;; concept turns outshine into a kind of org-minor-mode without |
|
;; actually reimplementing Org functionality, just by reusing it with |
|
;; the help of outorg. |
|
|
|
;; This is still work in progress. Not all Org commands make sense in |
|
;; an outshine buffer. Not all work out-of-the-box. Since there are |
|
;; many Org commands, it will take some time to check them one-by-one |
|
;; and filter out those that make sense with outshine (and fix them if |
|
;; neccessary). |
|
|
|
;;;;; Emacs Version |
|
|
|
;; Outshine works with GNU Emacs 24 or later. No attempts of testing |
|
;; with older versions or other types of Emacs have been made (yet). |
|
|
|
;;;; ChangeLog |
|
|
|
;; | date | author(s) | version | |
|
;; |-----------------+------------------------+---------| |
|
;; | <2018-12-30 Su> | Thibault Polge | 3.0 | |
|
;; | <2018-10-24 We> | (Various contributors) | 2.1 | |
|
;; | <2014-09-20 Sa> | Thorsten Jolitz | 2.0 | |
|
;; | <2013-05-03 Fr> | Thorsten Jolitz | 1.0 | |
|
;; | <2013-02-20 Mi> | Thorsten Jolitz | 0.9 | |
|
#+END_SRC |
|
|
|
** Old readme metadata |
|
|
|
#+BEGIN_SRC org |
|
:copyright: Thorsten_Jolitz |
|
:copyright-from: 2013+ |
|
:version: 3.0 |
|
:licence: GPL 2 or later (free software) |
|
:licence-url: http://www.gnu.org/licenses/ |
|
:part-of-emacs: no |
|
:authors: Thorsten_Jolitz Carsten_Dominik Per_Abrahamsen |
|
:credits: Fabrice_Niessen Alexander_Vorobiev Jonas_Bernoulli |
|
:inspiration: outline-magic outxxtra out-xtra |
|
:keywords: emacs outlines file_structuring |
|
:git-repo: https://github.com/alphapapa/outshine.git |
|
:git-clone: git://github.com/alphapapa/outshine.git |
|
#+END_SRC
|
|
|