[nongnu] elpa/telephone-line f7014a0cc5 004/195: Add Readme

[ELPA Syncer]

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

    Add Readme
---
 abs.png          | Bin 0 -> 4200 bytes
 cubed.png        | Bin 0 -> 4623 bytes
 gradient.png     | Bin 0 -> 4147 bytes
 readme.org       | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 to_the_right.png | Bin 0 -> 4576 bytes
 5 files changed, 142 insertions(+)

diff --git a/abs.png b/abs.png
new file mode 100644
index 0000000000..0a42ba0e95
Binary files /dev/null and b/abs.png differ
diff --git a/cubed.png b/cubed.png
new file mode 100644
index 0000000000..6d4781f064
Binary files /dev/null and b/cubed.png differ
diff --git a/gradient.png b/gradient.png
new file mode 100644
index 0000000000..9fb64b0361
Binary files /dev/null and b/gradient.png differ
diff --git a/readme.org b/readme.org
new file mode 100644
index 0000000000..a605360787
--- /dev/null
+++ b/readme.org
@@ -0,0 +1,142 @@
+#+Title: Telepone Line
+#+Author: Daniel Bordak
+
+Telephone Line is a new implementation of Powerline with a few new
+features that set it apart from the existing Emacs implementations:
+_easier customization_ and _antialiased separators_.
+
+* Antialiased Separators
+
+First off, this is how they look
+
+[[./abs.png]]
+
+Classic powerline, called "abs" (you'll see why later).
+
+[[./cubed.png]]
+
+Spacemacs' default separator, called "cubed".
+
+[[./gradient.png]]
+
+A gradient separator.
+
+[[./to_the_right.png]]
+
+You can use two right separators instead of a left and right, if you
+want.
+
+Each of these separators is defined programmatically (the existing
+powerline.el does something more along the lines of templating), being
+created from two potentially user-defined functions -- but more on
+that later. For now, just enjoy their
+pixels-wot-have-intermediate-colors
+
+* Easy Customization
+
+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
+        '((evil   . (telephone-line-airline-position-segment))
+          (accent . (telephone-line-major-mode-segment))
+          (nil    . (telephone-line-misc-info-segment))))
+#+end_src
+
+...That's it. That's essentially all there is to creating a theme.
+
+Now, as a caveat, this makes things like the spacemacs theme harder to
+create (it could still be done, maybe with a closure that returns
+left/right alternating separators). However, it addresses most of my
+issues with the existing solutions.
+
+** Separator Customization
+
+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.
+
+* 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.
diff --git a/to_the_right.png b/to_the_right.png
new file mode 100644
index 0000000000..08f03bfc1f
Binary files /dev/null and b/to_the_right.png differ