Create gh-pages for '56f06f8 Update font installation instructions'

Author: Lokaltog

_sources/fontpatching.txt

@@ -7,6 +7,9 @@ Powerline provides a font patcher for custom glyphs like the segment
 dividers (arrows), branch symbol, padlock symbol, etc. The font patcher 
 requires FontForge with Python bindings to work.
 
+You may be able to avoid patching your coding font to use the custom glyphs!  
+See :ref:`font-installation` for instructions.
+
 Check out the `powerline-fonts 
 <https://github.com/Lokaltog/powerline-fonts>`_ repository on GitHub for 
 patched versions of some popular programming fonts.

_sources/overview.txt

@@ -6,6 +6,11 @@ Requirements
 
 Powerline requires Python 2.7 to work.
 
+Powerline uses several special glyphs to get the arrow effect and some 
+custom symbols for developers. This requires that you either have the symbol 
+font or a patched font on your system. See `Font installation`_ for more 
+details.
+
 Vim plugin requirements
 ^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -48,6 +53,61 @@ they provide an easy way of installing and upgrading Powerline:
 
 * `Arch Linux (AUR) <https://aur.archlinux.org/packages/powerline-git/>`_
 
+.. _font-installation:
+
+Font installation
+^^^^^^^^^^^^^^^^^
+
+Linux
+*****
+
+If you're running Linux, you may be able to avoid patching your coding font 
+to get the special glyphs required by Powerline. This works by utilizing 
+fontconfig's fallback font feature, which replaces missing glyphs in a font 
+with another font on your system.
+
+This has been tested and works very well with many different coding fonts, 
+but some fonts may look terrible, in which case you'll have to use a patched 
+font (see :ref:`font-patching` for details).
+
+1. Download the `latest version of PowerlineSymbols 
+   <https://github.com/Lokaltog/powerline/raw/develop/powerline/fontpatcher/PowerlineSymbols.otf>`_.
+2. Move :file:`PowerlineSymbols.otf` to :file:`~/.fonts`.
+3. Run ``fc-cache -vf ~/.fonts`` to update your font cache.
+4. Edit your fontconfig file, located in either :file:`~/.fonts.conf` or 
+   :file:`~/.config/fontconfig/fonts.conf`, depending on your fontconfig 
+   version.  If your fontconfig file is empty, add the entire code block 
+   below. If you already have a custom font configuration, only add the 
+   ``<alias>`` block to your font configuration:
+
+   .. code-block:: xml
+
+      <?xml version="1.0"?>
+      <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+
+      <fontconfig>
+          <alias>
+              <family>monospace</family>
+              <prefer>
+                  <family>PowerlineSymbols</family>
+                  <family>YOUR MONOSPACE FONT HERE</family>
+              </prefer>
+          </alias>
+      </fontconfig>
+
+   Remember to replace ``YOUR MONOSPACE FONT HERE`` with your preferred 
+   coding font.
+5. Configure your terminal emulator or gvim to use the ``monospace`` font.
+6. If you still don't see the arrow symbols, please close all instances of 
+   your terminal emulator or gvim. You may also have to restart X for the 
+   changes to take effect.
+
+OS X and Windows
+****************
+
+You'll have to use a patched font to use the Powerline symbols. See 
+:ref:`font-patching` for details on font patching and pre-patched fonts.
+
 Usage
 -----
 

fontpatching.html

@@ -55,6 +55,8 @@ <h3>Navigation</h3>
 <p>Powerline provides a font patcher for custom glyphs like the segment
 dividers (arrows), branch symbol, padlock symbol, etc. The font patcher
 requires FontForge with Python bindings to work.</p>
+<p>You may be able to avoid patching your coding font to use the custom glyphs!
+See <a class="reference internal" href="overview.html#font-installation"><em>Font installation</em></a> for instructions.</p>
 <p>Check out the <a class="reference external" href="https://github.com/Lokaltog/powerline-fonts">powerline-fonts</a> repository on GitHub for
 patched versions of some popular programming fonts.</p>
 <div class="admonition warning">

index.html

@@ -63,6 +63,7 @@ <h1>Powerline<a class="headerlink" href="#powerline" title="Permalink to this he
 <li class="toctree-l2"><a class="reference internal" href="overview.html#installation">Installation</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="overview.html#installing-with-pip">Installing with <tt class="docutils literal"><span class="pre">pip</span></tt></a></li>
 <li class="toctree-l3"><a class="reference internal" href="overview.html#distribution-specific-packages">Distribution-specific packages</a></li>
+<li class="toctree-l3"><a class="reference internal" href="overview.html#font-installation">Font installation</a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="overview.html#usage">Usage</a><ul>

objects.inv

@@ -55,6 +55,10 @@ <h1>Overview<a class="headerlink" href="#overview" title="Permalink to this head
 <div class="section" id="requirements">
 <h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
 <p>Powerline requires Python 2.7 to work.</p>
+<p>Powerline uses several special glyphs to get the arrow effect and some
+custom symbols for developers. This requires that you either have the symbol
+font or a patched font on your system. See <a class="reference internal" href="#id1">Font installation</a> for more
+details.</p>
 <div class="section" id="vim-plugin-requirements">
 <h3>Vim plugin requirements<a class="headerlink" href="#vim-plugin-requirements" title="Permalink to this headline">¶</a></h3>
 <p>The vim plugin requires a vim version with Python 2.7 support compiled in.
@@ -96,6 +100,60 @@ <h3>Distribution-specific packages<a class="headerlink" href="#distribution-spec
 <li><a class="reference external" href="https://aur.archlinux.org/packages/powerline-git/">Arch Linux (AUR)</a></li>
 </ul>
 </div>
+<div class="section" id="font-installation">
+<span id="id1"></span><h3>Font installation<a class="headerlink" href="#font-installation" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="linux">
+<h4>Linux<a class="headerlink" href="#linux" title="Permalink to this headline">¶</a></h4>
+<p>If you&#8217;re running Linux, you may be able to avoid patching your coding font
+to get the special glyphs required by Powerline. This works by utilizing
+fontconfig&#8217;s fallback font feature, which replaces missing glyphs in a font
+with another font on your system.</p>
+<p>This has been tested and works very well with many different coding fonts,
+but some fonts may look terrible, in which case you&#8217;ll have to use a patched
+font (see <a class="reference internal" href="fontpatching.html#font-patching"><em>Font patching</em></a> for details).</p>
+<ol class="arabic">
+<li><p class="first">Download the <a class="reference external" href="https://github.com/Lokaltog/powerline/raw/develop/powerline/fontpatcher/PowerlineSymbols.otf">latest version of PowerlineSymbols</a>.</p>
+</li>
+<li><p class="first">Move <tt class="file docutils literal"><span class="pre">PowerlineSymbols.otf</span></tt> to <tt class="file docutils literal"><span class="pre">~/.fonts</span></tt>.</p>
+</li>
+<li><p class="first">Run <tt class="docutils literal"><span class="pre">fc-cache</span> <span class="pre">-vf</span> <span class="pre">~/.fonts</span></tt> to update your font cache.</p>
+</li>
+<li><p class="first">Edit your fontconfig file, located in either <tt class="file docutils literal"><span class="pre">~/.fonts.conf</span></tt> or
+<tt class="file docutils literal"><span class="pre">~/.config/fontconfig/fonts.conf</span></tt>, depending on your fontconfig
+version.  If your fontconfig file is empty, add the entire code block
+below. If you already have a custom font configuration, only add the
+<tt class="docutils literal"><span class="pre">&lt;alias&gt;</span></tt> block to your font configuration:</p>
+<div class="highlight-xml"><div class="highlight"><pre><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>
+<span class="cp">&lt;!DOCTYPE fontconfig SYSTEM &quot;fonts.dtd&quot;&gt;</span>
+
+<span class="nt">&lt;fontconfig&gt;</span>
+    <span class="nt">&lt;alias&gt;</span>
+        <span class="nt">&lt;family&gt;</span>monospace<span class="nt">&lt;/family&gt;</span>
+        <span class="nt">&lt;prefer&gt;</span>
+            <span class="nt">&lt;family&gt;</span>PowerlineSymbols<span class="nt">&lt;/family&gt;</span>
+            <span class="nt">&lt;family&gt;</span>YOUR MONOSPACE FONT HERE<span class="nt">&lt;/family&gt;</span>
+        <span class="nt">&lt;/prefer&gt;</span>
+    <span class="nt">&lt;/alias&gt;</span>
+<span class="nt">&lt;/fontconfig&gt;</span>
+</pre></div>
+</div>
+<p>Remember to replace <tt class="docutils literal"><span class="pre">YOUR</span> <span class="pre">MONOSPACE</span> <span class="pre">FONT</span> <span class="pre">HERE</span></tt> with your preferred
+coding font.</p>
+</li>
+<li><p class="first">Configure your terminal emulator or gvim to use the <tt class="docutils literal"><span class="pre">monospace</span></tt> font.</p>
+</li>
+<li><p class="first">If you still don&#8217;t see the arrow symbols, please close all instances of
+your terminal emulator or gvim. You may also have to restart X for the
+changes to take effect.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="os-x-and-windows">
+<h4>OS X and Windows<a class="headerlink" href="#os-x-and-windows" title="Permalink to this headline">¶</a></h4>
+<p>You&#8217;ll have to use a patched font to use the Powerline symbols. See
+<a class="reference internal" href="fontpatching.html#font-patching"><em>Font patching</em></a> for details on font patching and pre-patched fonts.</p>
+</div>
+</div>
 </div>
 <div class="section" id="usage">
 <h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
@@ -174,6 +232,11 @@ <h3><a href="index.html">Table Of Contents</a></h3>
 <li><a class="reference internal" href="#installation">Installation</a><ul>
 <li><a class="reference internal" href="#installing-with-pip">Installing with <tt class="docutils literal"><span class="pre">pip</span></tt></a></li>
 <li><a class="reference internal" href="#distribution-specific-packages">Distribution-specific packages</a></li>
+<li><a class="reference internal" href="#font-installation">Font installation</a><ul>
+<li><a class="reference internal" href="#linux">Linux</a></li>
+<li><a class="reference internal" href="#os-x-and-windows">OS X and Windows</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li><a class="reference internal" href="#usage">Usage</a><ul>