#+TITLE: Outshine

#+PROPERTY: logging nil

Outshine attempts to bring the look and feel of Org Mode to the world outside of the Org major-mode.  It's an extension of ~outline-minor-mode~ that should act as a replacement of Outline Mode.  Just change all your calls to ~outline-minor-mode~ into ~outshine-mode~.

* Installation

** MELPA

Simply install the =outshine= package from MELPA.

** Quelpa

Installing directly with [[https://framagit.org/steckerhalter/quelpa][Quelpa]] into your Emacs config is also very easy:

1.  Install [[https://framagit.org/steckerhalter/quelpa-use-package#installation][quelpa-use-package]] (which can be installed directly from MELPA).
2.  Add this form to your init file:

#+BEGIN_SRC emacs-lisp
  (use-package outshine
    :quelpa (outshine :fetcher github :repo "alphapapa/outshine"))
#+END_SRC

After installation, upgrading can be done through =quelpa=, e.g. with @@html:<kbd>@@C-u M-x quelpa RET outshine RET@@html:</kbd>@@.

** Manual

Manual installation is not recommended because it's difficult to keep up with changes.  If you want to do this, you'll have to install the elisp files and dependencies manually.

* Usage

** Keymap prefix

To enable the keybindings, you must set the variable ~outline-minor-mode-prefix~ (note the variable name carefully) /before/ loading Outshine, e.g.:

#+BEGIN_SRC elisp
  (defvar outline-minor-mode-prefix "\M-#")
#+END_SRC

** Activation

Activate ~outshine-mode~ in buffers in which you want to use it.  You may add it to major mode hooks like so:

#+BEGIN_SRC elisp
  (add-hook 'emacs-lisp-mode-hook 'outshine-mode)
#+END_SRC

** Commands

The extensions to ~outline-minor-mode~ aim to make its use similar to Org.  Given a correctly structured ~outshine~ buffer, outline navigation, structure editing, and visibility cycling with ~outshine~ should make an Org user feel right at home.

Try @@html:<kbd>@@C-h m@@html:</kbd>@@ (~describe-mode~) and @@html:<kbd>@@C-h b@@html:</kbd>@@ (~describe-bindings~) in an ~outshine~ buffer to see the available functions and their keybindings.

** Speed commands

The very useful Org speed commands are available in ~outshine~.  To activate them, customize the variable ~outshine-use-speed-commands~.  Call ~outshine-speed-command-help~ to get an overview of the commands and keybindings.

** Terminal support

Emacs running on a terminal may have issues with =M-up= and =M-down=
bindings.  There used to be a hack in Outshine itself to get those to
work, which was removed in
[[https://github.com/alphapapa/outshine/commit/210cc88bf9ee2fca2a283e4de89d4abe849d706b]].

#+begin_src emacs-lisp
  (define-key input-decode-map "\e\eOA" [(meta up)])
  (define-key input-decode-map "\e\eOB" [(meta down)])
#+end_src

If you experience issues with Emacs not recognizing these bindings when running in a terminal, adding these two lines to your =init.el= may help.  You may need to adapt the escape sequences depending on the emulator you use.

** Misc

+  ~imenu~ is supported with the command ~outshine-imenu~.
+  Show the number of hidden lines in folded headlines with the command ~outshine-show-hidden-lines-cookies~.
+  ~latex-mode~ commands:
     -  ~outshine-latex-insert-header~
     -  ~outshine-latex-insert-headers-in-buffer~
     -  ~outshine-TeX-command-region-on-subtree~.

* Changelog

** 3.1-pre

*Added*
+ Add ~outshine-define-key~ macro for defining conditional key bindings (e.g. on headlines). Improves on previous ~outshine-define-key-with-fallback~ macro by interning a named function and matching the function signature of ~define-key~.
+ Bind @@html:<kbd>@@ <backtab> @@html:</kbd>@@ to ~outshine-cycle-buffer~ on headlines

*Fixed*
+ More fully override Imenu configuration when using ~outshine-imenu~.  ([[https://github.com/alphapapa/outshine/pull/93][#93]].  Thanks to [[https://github.com/dankessler][Dan Kessler]].)

*Deprecated*
+ Declare ~outshine-define-key-with-fallback~ as obsolete, use ~outshine-define-key~ instead

** 3.0 and earlier

| 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 |

* Credits

Outshine was originally authored by [[https://github.com/tj64][Thorsten Jolitz]], based on ~outline-magic~ by Carsten Dominik (the creator of Org Mode) and ~out-xtra~ by Per Abrahamsen.  Maintainership was transferred to [[https://github.com/alphapapa][Adam Porter]] in 2017.  It was refactored to a minor mode and released as 3.0 by [[https://github.com/thblt][Thibault Polge]] in 2018.

* License

GPLv2+