spacemacs/layers/rebox/README.org

#+TITLE: Rebox layer

* Table of Contents                                         :TOC_4_gh:noexport:
 - [[#description][Description]]
   - [[#features][Features]]
 - [[#install][Install]]
   - [[#layer][Layer]]
   - [[#configuration][Configuration]]
     - [[#styles-cycling][Styles cycling]]
     - [[#text-mode][Text mode]]
 - [[#style-templates][Style Templates]]
   - [[#standard-packaged-templates][Standard packaged templates]]
     - [[#comments][Comments]]
     - [[#text-mode][Text Mode]]
     - [[#c-mode][C Mode]]
   - [[#additional-templates][Additional Templates]]
 - [[#key-bindings][Key bindings]]

* Description
This layer adds support for [[https://github.com/lewang/rebox2][rebox2]] package which is a minor-mode allowing
to easily add ASCII text boxes to a buffer.

A nice video demonstration by the package author can be found [[https://www.youtube.com/watch?v=53YeTdVtDkU][here]].

** Features
- Auto-wrap correctly in comments,
- Auto-fill correctly in comments,
- Boxes auto-adapt as text is inserted or deleted,
- ~S-return~ to continue a comment on the next line,
- Kill/yank within the box,
- Apparently works well with ancient ~filladpt-mode~ (see authors video).

* Install
** Layer
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =rebox= to the existing =dotspacemacs-configuration-layers= list in this
file.

** Configuration
*** Styles cycling
Box styles are identified by numbers, it is possible to cycle through a list
of styles using ~SPC i b n~. This list can be customized by setting the variable
=rebox-style-loop=.

#+BEGIN_SRC emacs-lisp
(setq rebox-style-loop '(71 72 73))
#+END_SRC

*** Text mode
As text mode usage could surprise some users (e.g., when they enter M-q to fill
a paragraph) =rebox= is not enabled by default in =text-mode=. To enable it you
need to set the layer variable =rebox-enable-in-text-mode= to =t=.

#+begin_src emacs-lisp
(setq-default dotspacemacs-configuration-layers '(
    (rebox :variables rebox-enable-in-text-mode t)))
#+end_src

* Style Templates
** Standard packaged templates
*** Comments
These templates are single line comments styles. A =#= is used here for
illustration; however, it will work equally well if the comment character is
different (e.g., lisp's =;= comment character).

#+begin_src sh
  #box-style 10

  # box style 11

  # box style 12 #
  # ------------ #

  # ------------ #
  # box style 13 #
  # ------------ #

  # box style 14 #
  ################

  ################
  # box style 15 #
  ################

  #,----
  #| box style 16
  #`----

  #,-------------
  #| box style 17
  #`-------------

  ##box style 20

  ## box style 21

  ## box style 22 ##
  ## ------------ ##

  ## ------------ ##
  ## box style 23 ##
  ## ------------ ##

  ## box style 24 ##
  ##################

  ##################
  ## box style 25 ##
  ##################

  ##,----
  ##| box style 26
  ##`----

  ##,-------------
  ##| box style 27
  ##`-------------

  ###box style 30

  # and so on repeating up to styles 5x which have 5 leading comment characters
#+end_src

*** Text Mode
#+begin_src text
  box style 111

  | box style 112 |
  +---------------+

  +---------------+
  | box style 113 |
  +---------------+

  | box style 114 |
  *===============*

  *===============*
  | box style 115 |
  *===============*

  -------------
  box style 116
  -------------

  | box style 121 |

  | box style 122 |
  `---------------'

  .---------------.
  | box style 123 |
  `---------------'

  | box style 124 |
  \===============/

  /===============\
  | box style 125 |
  \===============/

  ,----
  | box style 126
  `----

  ,--------------
  | box style 127
  `--------------

  ,----
  | box style 136
  `----

  ,--------------
  | box style 137
  `--------------

  | box style 141

  ** box style 142 *
  ******************

  ******************
  ** box style 143 *
  ******************

  X box style 144 X
  XXXXXXXXXXXXXXXXX

  XXXXXXXXXXXXXXXXX
  X box style 145 X
  XXXXXXXXXXXXXXXXX
#+end_src

*** C Mode
*Note* this mode is disabled for now due to bugs in rebox.

#+begin_src c
  /* box style 111 */

  /* box style 112 */
  /* ------------- */

  /* ------------- */
  /* box style 113 */
  /* ------------- */

  /* box style 114 */
  /* ============= */

  /* ============= */
  /* box style 115 */
  /* ============= */

  /*
     box style 221
   */

  /*          .
   | box style 222 |
   `--------------*/

  /*--------------.
  | box style 223 |
  `--------------*/

  /*              \
  | box style 224 |
  \==============*/

  /*==============\
  | box style 225 |
  \==============*/

  /*
   | box style 231
   */

  /*
   | box style 232 |
   *---------------*/

  /*---------------*
   | box style 233 |
   *---------------*/

  /* box style 234 */
  /*---------------*/

  /*---------------*/
  /* box style 235 */
  /*---------------*/

  /*
   * box style 241
   */

  /*               *
   * box style 242 *
   *****************/

  /*****************
   * box style 243 *
   *****************/

  /* box style 244 */
  /*****************/

  /*****************/
  /* box style 245 */
  /*****************/

  /****************//**
   * box style 246
   ********************/
#+end_src

** Additional Templates
These templates are added by the Spacemacs layer.

#+begin_src sh
  #
  # box style 71
  #

  # ------------
  # box style 72
  # ------------

  # ============
  # box style 73
  # ============

  #--------------
  # box style 74
  #--------------

  #--------------+
  # box style 75
  #--------------+

  #==============
  # box style 76
  #==============

  ##
  ## box style 81
  ##

  ## ------------
  ## box style 82
  ## ------------

  ## ============
  ## box style 83
  ## ============

  ##--------------
  ## box style 84
  ##--------------

  ##--------------+
  ## box style 85
  ##--------------+

  ##==============
  ## box style 86
  ##==============
#+end_src

* Key bindings
*Note:* Use a numerical prefix argument to choose a specific style for instance
~86 SPC i b b~ to use the style 86 above.

| Keybinding                 | Command                                                           |
|----------------------------+-------------------------------------------------------------------|
| ~SPC i b >~                | Move box to the right (point must be around left side of the box) |
| ~SPC i b <~                | Move box to the left (point must be around left side of the box)  |
| ~SPC i b b~                | Draw next box defined in =rebox-style-loop=                       |
| ~SPC i b B~                | Draw previous box defined in =rebox-style-loop=                   |
| ~SPC i b c~                | Center box (point must be around left side of the box)                                                       |
| ~S-return~                 | rebox-indent-new-line                                             |