+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:@@C-u M-x quelpa RET outshine RET@@html:@@.

** 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:@@C-h m@@html:@@ (~describe-mode~) and @@html:@@C-h b@@html:@@ (~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:@@ @@html:@@ 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+