[nongnu] elpa/telephone-line 4adfbf02bb 092/195: Shorten readme

[ELPA Syncer]

branch: elpa/telephone-line
commit 4adfbf02bb39ed28ebd831cae763ccb89b632b05
Author: Daniel Bordak <dbordak@fastmail.fm>
Commit: Daniel Bordak <dbordak@fastmail.fm>

    Shorten readme
---
 readme.org => configuration.org |  79 +++++++-----------
 readme.org                      | 172 ++++------------------------------------
 2 files changed, 44 insertions(+), 207 deletions(-)

diff --git a/readme.org b/configuration.org
similarity index 79%
copy from readme.org
copy to configuration.org
index 74a9b2bca6..c1ea126e63 100644
--- a/readme.org
+++ b/configuration.org
@@ -1,52 +1,7 @@
-#+Title: Telephone Line
+#+Title: Configuration
 #+Author: Daniel Bordak
 
-[[http://www.gnu.org/licenses/gpl-3.0.txt][file:https://img.shields.io/badge/license-GPL_3-green.svg]]
-[[http://melpa.org/#/telephone-line][file:http://melpa.org/packages/telephone-line-badge.svg]]
-[[http://stable.melpa.org/#/telephone-line][file:http://stable.melpa.org/packages/telephone-line-badge.svg]]
-
-[[./screenshots/abs.png]]
-
-[[./screenshots/cubed.png]]
-
-[[./screenshots/gradient.png]]
-
-[[./screenshots/rainbow.png]]
-
-For more information on how to get those screenshots, check out 
[[./examples.org][the examples]].
-
-* Features
-
-Telephone Line is a new implementation of Powerline for emacs with
-*(optional) baked-in evil support*, *antialiased separators*, and an
-*easy configuration language* which makes it *trivial to write your
-own themes*. Additionally, I *dogfood the hell out of it* so bugfixes
-should come quickly. It's also 
*[[https://www.youtube.com/watch?v=77R1Wp6Y_5Y][named after a song]]* which is 
what I
-always look for in software.
-
-* Installation
-
-The easiest way to install telephone-line is with package.el through
-MELPA. Once you have the package installed, initializing it is the
-usual stuff:
-
-#+begin_src emacs-lisp
-(require 'telephone-line)
-(telephone-line-mode 1)
-#+end_src
-
-If you want to use it with evil, instead you should do this
-
-#+begin_src emacs-lisp
-(require 'telephone-line-config)
-(telephone-line-evil-config)
-#+end_src
-
-This implicitly calls ~(telephone-line-mode 1)~.
-
-If you want to further configure it, read on!
-
-* Configuration
+* Segment overview
 
 Themes are defined by customizing the ~telephone-line-lhs~ and
 ~telephone-line-rhs~ variables, for the left and right parts of the
@@ -66,6 +21,8 @@ of the subsegments ~FlyC- ivy~ and ~U:--- *scratch*~). These
 subsegments are separated by secondary separators, such as the thin
 powerline symbol (it looks like ~>~, but larger).
 
+** Color Symbols
+
 The ~Color Symbol~ determines what face is used for the supersegment.
 By default, the choices are:
 
@@ -77,6 +34,14 @@ By default, the choices are:
 
 You can add more by customizing ~telephone-line-faces~.
 
+Each of these symbols also has a subseparator color associated with
+it, which you can configure by changing
+~telephone-line-subseparator-faces~. By default, ~nil~ uses ~accent~'s
+background color as its subseparator color, and the others use
+~nil~'s. If you ever map a color symbol to itself, this will cause the
+subseparator to have the same foreground as the rest of the text in
+that segment.
+
 ** Diagram
 
 [[./screenshots/diagram-1-cropped.png]]
@@ -119,9 +84,25 @@ Now, before you go copy-pasting the above config, it's 
important to
 know that it requires both evil and erc. If you're not using evil,
 though, the defaults should be fine.
 
-* Advanced Customization
+* Creating New Segments
+
+There are a bunch of different ~defsegment~ functions for creating
+your own segments, but when in doubt, try ~defsegment*~. This is
+kinda... Not well defined at the moment, but I'll try to clear it up.
+
+Here's an example of a static segment:
+
+#+begin_src emacs-lisp
+(telephone-line-defsegment my-meme-segment
+  "Meme")
+#+end_src
+
+This segment can now be added as described above. It will match the
+color of the supersegment, and staticly display "Meme".
+
+The ~defsegment~ functions can also take lists of strings.
 
-** Separators
+* Creating New Separators
 
 I mentioned before that the separators are defined in terms of two
 functions. Here's the way that works:
diff --git a/readme.org b/readme.org
index 74a9b2bca6..70b2cbf852 100644
--- a/readme.org
+++ b/readme.org
@@ -44,166 +44,22 @@ If you want to use it with evil, instead you should do this
 
 This implicitly calls ~(telephone-line-mode 1)~.
 
-If you want to further configure it, read on!
-
 * Configuration
 
-Themes are defined by customizing the ~telephone-line-lhs~ and
-~telephone-line-rhs~ variables, for the left and right parts of the
-mode-line, respectively.
-
-The configuration format for both is an alist containing pairs of the form
-
-#+begin_src emacs-lisp
-(COLOR-SYMBOL . (LIST OF SUBSEGMENT FUNCTIONS))
-#+end_src
-
-Each one of these pairs defines a "supersegment" -- a bunch of
-subsegments using the same face. In the screenshots, you can see the
-minor modes and buffer information are in the same color, though they
-aren't the same segment (i.e. ~FlyC- ivy U:--- *scratch*~ consists
-of the subsegments ~FlyC- ivy~ and ~U:--- *scratch*~). These
-subsegments are separated by secondary separators, such as the thin
-powerline symbol (it looks like ~>~, but larger).
-
-The ~Color Symbol~ determines what face is used for the supersegment.
-By default, the choices are:
-
-#+begin_example
-    nil:    mode-line                                  or mode-line-inactive
-    accent: telephone-line-accent-active               or 
telephone-line-accent-inactive
-    evil:   telephone-line-evil-{insert, normal, etc.} or mode-line-inactive
-#+end_example
+Segments can be added by configuring the ~telephone-line-lhs~ and
+~telephone-line-rhs~ variables. Example configuration demonstrating
+the format can be found in [[./examples.org]], and available segments are
+in [[./telephone-line-segments.el]]. You can also make your own!
 
-You can add more by customizing ~telephone-line-faces~.
+Separators are chosen by configuring
+~telephone-line-primary-left-separator~,
+~telephone-line-primary-right-separator~,
+~telephone-line-secondary-left-separator~, and
+~telephone-line-secondary-right-separator~. Available separators are
+in [[./telephone-line-separators.el]]. You can also make your own!
 
-** Diagram
-
-[[./screenshots/diagram-1-cropped.png]]
-
-This shows how a config maps to the mode-line. Important to note is
-how the accent supersegment has three subsegments, but only one is
-displayed (and there are no subseparators). This is because
-subsegments are dynamic. When a subsegment has no information to
-display, it doesn't need a subseparator (in contrast, primary
-separators are _always_ displayed).
-
-** Example Configuration
-
-The screenshots above aren't the default configuration; it's all
-defined in my dotfiles.
-
-Here's the relevant section:
-
-#+begin_src emacs-lisp
-(setq telephone-line-lhs
-        '((evil   . (telephone-line-evil-tag-segment))
-          (accent . (telephone-line-vc-segment
-                     telephone-line-erc-modified-channels-segment
-                     telephone-line-process-segment))
-          (nil    . (telephone-line-minor-mode-segment
-                     telephone-line-buffer-segment))))
-(setq telephone-line-rhs
-        '((nil    . (telephone-line-misc-info-segment))
-          (accent . (telephone-line-major-mode-segment))
-          (evil   . (telephone-line-airline-position-segment))))
-
-(telephone-line-mode t)
-#+end_src
+You can force the height of the mode-line by setting
+~telephone-line-height~.
 
-...That's it. That's essentially all there is to creating a theme.
-Make sure you initialize it after the configuration, though, or
-else some buffers won't have it enabled.
-
-Now, before you go copy-pasting the above config, it's important to
-know that it requires both evil and erc. If you're not using evil,
-though, the defaults should be fine.
-
-* Advanced Customization
-
-** Separators
-
-I mentioned before that the separators are defined in terms of two
-functions. Here's the way that works:
-
-Imagine the cross-section of the mode-line as a number line, ranging
-from -height/2 to +height/2. The first function is applied across this
-number line to get the shape of the separator. Here's the most famous
-separator, defined as 2*abs(x).
-
-#+BEGIN_EXAMPLE
-    -4 |       *
-    -3 |     *
-    -2 |   *
-    -1 | *
-     0 +
-     1 | *
-     2 |   *
-     3 |     *
-     4 |       *
-#+END_EXAMPLE
-
-There you go: a separator. However, we still need another piece.
-That second function I mentioned determines the fill -- the difference
-between a solid separator and a hollow one.
-
-This isn't the sort of function I'd expect to get much customization
-out of, but there are 3 included ones. The first makes a hollow
-separator, which looks more-or-less like the ASCII art above. The
-second provides a fill:
-
-#+BEGIN_EXAMPLE
-    -4 |       *
-    -3 |     *--
-    -2 |   *----
-    -1 | *------
-     0 +--------
-     1 | *------
-     2 |   *----
-     3 |     *--
-     4 |       *
-#+END_EXAMPLE
-
-The third one is a special thing that ignores the first function
-entirely and just produces the same output regardless of the input.
-It's used to make the gradient separator.
-
-Choice of separator can be customized as well, by changing the values
-of =telephone-line-{primary,secondary}-{left,right}-separator=. This
-should be a function which accepts two faces or colors (if provided
-faces, the built-in separators use the background field) and returns a
-propertized image. The separators can be defined independently of one
-another -- feel free to use a nominally left separator for your rhs,
-or mix two different types of separators.
-
-** Unicode Separators
-
-The function for defining separators takes an optional argument for a
-character to display when in a terminal. For the abs separator, this
-is set to the usual Powerline symbol.
-
-* Separator Types
-
-You probably also noticed from the screenshots that there are in fact
-two types of separator on either side of the mode-line. The way this
-works involves the lhs/rhs alists.
-
-Basically, lists of segment functions associated to a color symbol are
-rendered into a 'supersegment'. Supersegments are separated by primary
-separators. Internally, non-nil segment-functions are rendered into
-'subsegments'. Subsegments are separated by secondary separators.
-
-Primary separators are static -- the customization I showed will
-always produce 4 primary separators. Secondaries depend upon the
-subsegments state, so there could be anywhere from 0-3 in my config.
-
-* Package structure
-
-- telephone-line.el: Stuff for setting up the mode-line
-- telephone-line-separators.el: Separator definitions
-- telephone-line-segments.el: Segment definitions
-- telephone-line-utils.el: Functions strictly for defining new
-  Separators and Segments
-
-If you just want the separators, you can just require that. It does
-depend upon utils, however.
+If you want to further information on configuration or creating your
+own segments/separators, continue on to [[./configuration.org]]!