updating docs

Author: s-n-g

README.html

@@ -27,7 +27,7 @@
 </header>
 <h1 id="pyradio">PyRadio</h1>
 <p>Command line internet radio player.</p>
-<p>Ben Dowling - <a href="https://github.com/coderholic">https://github.com/coderholic</a></p>
+<p>Ben Dowling - <a target="_blank" href="https://github.com/coderholic">https://github.com/coderholic</a></p>
 <h2 id="table-of-contents">Table of contents <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
 <ul>
 <li><a href="#requirements">Requirements</a></li>
@@ -39,20 +39,22 @@ <h2 id="table-of-contents">Table of contents <span style="padding-left: 10px;"><
 <li><a href="#specifying-stations-encoding">Specifying stations’ encoding</a></li>
 <li><a href="#player-detection-selection">Player detection / selection</a></li>
 <li><a href="#player-default-volume-level">Player default volume level</a></li>
+<li><a href="#search-function">Search function</a></li>
 <li><a href="#pyradio-themes">PyRadio Themes</a></li>
 <li><a href="#session-locking">Session Locking</a></li>
 <li><a href="#update-notification">Update notification</a></li>
 <li><a href="#cleaning-up">Cleaning up</a></li>
 <li><a href="#debug-mode">Debug mode</a></li>
+<li><a href="#reporting-bugs">Reporting bugs</a></li>
 </ul>
 <h2 id="requirements">Requirements <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
 <ul>
 <li>python 2.7+/3.5+</li>
 <li>MPV, MPlayer or VLC installed and in your path.</li>
-<li><a href="http://www.dest-unreach.org/socat/">socat</a> (if you wish to use MPV)</li>
+<li><a target="_blank" href="http://www.dest-unreach.org/socat/">socat</a> (if you wish to use MPV)</li>
 </ul>
 <h2 id="installation">Installation <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
-<p>The best way to install <strong>PyRadio</strong> is via a distribution package, if one exists (e.g. <em>Arch Linux</em> and derivatives can install <a href="https://aur.archlinux.org/packages/pyradio-git/">pyradio-git</a> from AUR).</p>
+<p>The best way to install <strong>PyRadio</strong> is via a distribution package, if one exists (e.g. <em>Arch Linux</em> and derivatives can install <a target="_blank" href="https://aur.archlinux.org/packages/pyradio-git/">pyradio-git</a> from AUR).</p>
 <p>In any other case, and since <strong>PyRadio</strong> is currently not available via pip, you will have to <a href="build.html">build it from source</a>.</p>
 <h2 id="command-line-options">Command line options <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
 <pre>$ pyradio -h
@@ -194,12 +196,12 @@ <h3 id="global-encoding-declaration">Global encoding declaration</h3>
 <p>This would be useful in the case where most of your stations do not use <strong>utf-8</strong>. Instead of editing the playlist and add the encoding to each and every affected station, you just set it globally.</p>
 <h3 id="finding-the-right-encoding">Finding the right encoding</h3>
 <p>A valid encoding list can be found at:</p>
-<p><a href="https://docs.python.org/2.7/library/codecs.html#standard-encodings">https://docs.python.org/2.7/library/codecs.html#standard-encodings</a></p>
+<p><a target="_blank" href="https://docs.python.org/2.7/library/codecs.html#standard-encodings">https://docs.python.org/2.7/library/codecs.html#standard-encodings</a></p>
 <p>replacing <strong>2.7</strong> with specific version: <strong>3.0</strong> up to current python version.</p>
 <h2 id="player-detection-selection">Player detection / selection <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
 <p><strong>PyRadio</strong> is basically built around the existence of a valid media player it can use. Thus, it will auto detect the existence of its supported players upon its execution.</p>
 <p>Currently, it supports MPV, MPlayer and VLC, and it will look for them in that order. If none of them is found, the program will terminate with an error.</p>
-<p>MPV will be used only when the <a href="http://www.dest-unreach.org/socat/">socat</a> multipurpose relay is also installed.</p>
+<p>MPV will be used only when the <a target="_blank" href="http://www.dest-unreach.org/socat/">socat</a> multipurpose relay is also installed.</p>
 <p>Users can alter this default behavior by using the <strong><em>-u</em></strong> command line option. This option will permit the user either to specify the player to use, or change the detection order.</p>
 <p>Example:</p>
 <pre>pyradio -u vlc</pre>
@@ -229,6 +231,12 @@ <h3 id="mplayer">MPlayer</h3>
 [pyradio]
 volstep=1
 volume=28</pre>
+<h2 id="search-function">Search function <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
+<p>On any window presenting a list of items (stations, playlists, themes) a <strong>search function</strong> is available by pressing “<strong>/</strong>”.</p>
+<p>The <em>Search Window</em> supports normal and extend editing and in session history.</p>
+<p>After a search term has been successfully found, next occurrence can be obtained using the “<strong>n</strong>” key and previous occurrence can be obtained using the “<strong>N</strong>” key.</p>
+<p style="margin: 1.5em 4em 0 4em; text-indent: -2.5em;"><strong>Note:</strong> <strong>Python 2</strong> users are confined in typing ASCII characters only.</p>
+<p style="margin: 1.5em 4em 0 4em; text-indent: -2.5em;"><strong>Note:</strong> Currently, the <strong>search function</strong> is available on the stations’ and playlists’ window only.</p>
 <h2 id="pyradio-themes">PyRadio Themes <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
 <p><strong>PyRadio</strong> comes with 6 preconfigured (hard coded) themes:</p>
 <ol type="1">
@@ -239,7 +247,12 @@ <h2 id="pyradio-themes">PyRadio Themes <span style="padding-left: 10px;"><sup st
 <li><strong>white_on_black</strong> or <strong>wob</strong> (256 color b&amp;w theme). A theme for dark terminal background settings.</li>
 <li><strong>black_on_white</strong> or <strong>bow</strong> (256 color b&amp;w theme). A theme for light terminal background settings.</li>
 </ol>
-<p>and three 256-color system themes (these are actual files saved in the <strong>themes</strong> installation directory): 1. <strong>brown_by_sng</strong>, <strong>pink_by_sng</strong> and <strong>purple_by_sng</strong>.</p>
+<p>Furthermore, three 256-color system themes (these are actual files saved in the <strong>themes</strong> installation directory) are also available:</p>
+<ol type="1">
+<li><strong>brown_by_sng</strong></li>
+<li><strong>pink_by_sng</strong></li>
+<li><strong>purple_by_sng</strong></li>
+</ol>
 <p>The visual result of an applied theme greatly depends on the terminal settings (e.g. foreground and background color settings, palette used, number of colors supported, real or pseudo-transparency support, etc.)</p>
 <p>Pressing “<strong>t</strong>” will bring up the <em>Theme selection window</em>, which can be used to activate a theme and set the default one.</p>
 <p style="margin: 1.5em 4em 0 4em; text-indent: -2.5em;"><strong>Note:</strong> Themes that use more colors than those supported by the terminal in use, will not be present in the <em>Theme selection window</em>. Furthermore, if a such at theme is set as default (or requested using the “<strong>-t</strong>” command line option), <strong>PyRadio</strong> will silently fall-back to the “<strong>dark</strong>” theme (or the “<strong>light</strong>” theme, if the terminal supports 8 colors and default theme is set to “<em>light_16_colors</em>”).</p>
@@ -276,6 +289,15 @@ <h2 id="cleaning-up">Cleaning up <span style="padding-left: 10px;"><sup style="f
 $ sudo rm -rf /usr/lib/python3.7/site-packages/pyradio-0.7.7-py3.7.egg</pre>
 <h2 id="debug-mode">Debug mode <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
 <p>Adding the <strong><em>-d</em></strong> option to the command line will instruct <strong>PyRadio</strong> to enter <em>Debug mode</em>, which means that it will print debug messages to a file. This file will always reside in the user’s home directory and will be named <em>pyradio.log</em>.</p>
-<p>In case of a bug or a glitch, please include this file to the issue you will <a href="https://github.com/coderholic/pyradio/issues">open in github</a>.</p>
+<p>In case of a bug or a glitch, please include this file to the issue you will <a target="_blank" href="https://github.com/coderholic/pyradio/issues">open at github</a>.</p>
+<h2 id="reporting-bugs">Reporting bugs <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
+<p>When a bug is found, please do report it by <a target="_blank" href="https://github.com/coderholic/pyradio/issues">opening an issue at github</a>, as already stated above.</p>
+<p>In you report you should, at the very least, state your <strong>pyradio version</strong>, <strong>python version</strong> and <strong>method</strong> of installation (built from source, AUR, snap, whatever).</p>
+<p>It would be really useful to include <strong>~/pyradio.log</strong> in your report.</p>
+<p>To create it, enter the following commands in a terminal:</p>
+<pre>$ rm ~/pyradio.log
+$ pyradio -d</pre>
+<p>Then try to reproduce the bug and exit <strong>pyradio</strong>.</p>
+<p>Finally, include the file produced in your report.</p>
 </body>
 </html>

README.md

@@ -15,11 +15,13 @@ Ben Dowling - [https://github.com/coderholic](https://github.com/coderholic)
 * [Specifying stations' encoding](#specifying-stations-encoding)
 * [Player detection / selection](#player-detection-selection)
 * [Player default volume level](#player-default-volume-level)
+* [Search function](#search-function)
 * [PyRadio Themes](#pyradio-themes)
 * [Session Locking](#session-locking)
 * [Update notification](#update-notification)
 * [Cleaning up](#cleaning-up)
 * [Debug mode](#debug-mode)
+* [Reporting bugs](#reporting-bugs)
 
 ## Requirements
 
@@ -327,6 +329,18 @@ Example:
     volstep=1
     volume=28
 
+## Search function
+
+On any window presenting a list of items (stations, playlists, themes) a **search function** is available by pressing "**/**".
+
+The *Search Window* supports normal and extend editing and in session history.
+
+After a search term has been successfully found, next occurrence can be obtained using the "**n**" key and previous occurrence can be obtained using the "**N**" key.
+
+**Note:** **Python 2** users are confined in typing ASCII characters only.
+
+**Note:** Currently, the **search function** is available on the stations' and playlists' window only.
+
 ## PyRadio Themes
 
 **PyRadio** comes with 6 preconfigured (hard coded) themes:
@@ -338,7 +352,11 @@ Example:
 5. **white_on_black** or **wob** (256 color b&w theme). A theme for dark terminal background settings.
 6. **black_on_white** or **bow** (256 color b&w theme). A theme for light terminal background settings.
 
-and three 256-color system themes (these are actual files saved in the **themes** installation directory): 1. **brown_by_sng**, **pink_by_sng** and **purple_by_sng**.
+Furthermore, three 256-color system themes (these are actual files saved in the **themes** installation directory) are also available:
+
+1. **brown_by_sng**
+2. **pink_by_sng**
+3. **purple_by_sng**
 
 The visual result of an applied theme greatly depends on the terminal settings (e.g. foreground and background color settings, palette used, number of colors supported, real or pseudo-transparency support, etc.)
 
@@ -408,4 +426,21 @@ As we see, previous versions still exist in this system: **0.7.6.2** and **0.7.7
 
 Adding the ***-d*** option to the command line will instruct **PyRadio** to enter *Debug mode*, which means that it will print debug messages to a file. This file will always reside in the user's home directory and will be named *pyradio.log*.
 
-In case of a bug or a glitch, please include this file to the issue you will [open in github](https://github.com/coderholic/pyradio/issues).
+In case of a bug or a glitch, please include this file to the issue you will [open at github](https://github.com/coderholic/pyradio/issues).
+
+## Reporting bugs
+
+When a bug is found, please do report it by [opening an issue at github](https://github.com/coderholic/pyradio/issues), as already stated above.
+
+In you report you should, at the very least, state your **pyradio version**, **python version** and **method** of installation (built from source, AUR, snap, whatever).
+
+It would be really useful to include **~/pyradio.log** in your report.
+
+To create it, enter the following commands in a terminal:
+
+    $ rm ~/pyradio.log
+    $ pyradio -d
+
+Then try to reproduce the bug and exit **pyradio**.
+
+Finally, include the file produced in your report.

build.html

@@ -27,7 +27,7 @@
 </header>
 <h1 id="building-pyradio-from-source">Building PyRadio from source</h1>
 <p>Command line internet radio player.</p>
-<p>Ben Dowling - <a href="https://github.com/coderholic">https://github.com/coderholic</a></p>
+<p>Ben Dowling - <a target="_blank" href="https://github.com/coderholic">https://github.com/coderholic</a></p>
 <h2 id="table-of-contents">Table of contents <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style></h2>
 <ul>
 <li><a href="#building-from-source">Building from source</a>
@@ -61,7 +61,7 @@ <h3 id="linux">Linux</h3>
 <p>Use your distribution method to install <em>python-setuptools</em>, <em>git</em>, <em>sed</em> and any one of <em>MPV</em>, <em>MPlayer</em> and/or <em>VLC</em>.</p>
 <p>When you are done, proceed to “<a href="#performing-the-installation">Performing the installation</a>”.</p>
 <h3 id="macos">macOS</h3>
-<p>Everything you need to install, run and keep <strong>pyradio</strong> up-to-date is available on <a href="https://github.com/Homebrew/homebrew">Homebrew</a>. If you haven’t already downloaded its client, go ahead and do it.</p>
+<p>Everything you need to install, run and keep <strong>pyradio</strong> up-to-date is available on <a target="_blank" href="https://github.com/Homebrew/homebrew">Homebrew</a>. If you haven’t already downloaded its client, go ahead and do it.</p>
 <p>Open a <strong>terminal</strong> and type:</p>
 <pre>/usr/bin/ruby -e &quot;$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)&quot;</pre>
 <p>Then just install <strong>git</strong>:</p>
@@ -74,9 +74,9 @@ <h3 id="macos">macOS</h3>
 <p>2. <strong><em>MPlayer</em></strong></p>
 <pre>brew install mplayer</pre>
 <p>3. <strong><em>VLC</em></strong></p>
-<p>You can get VLC from the official site or from <a href="https://github.com/Homebrew/homebrew">Homebrew</a>.</p>
+<p>You can get VLC from the official site or from <a target="_blank" href="https://github.com/Homebrew/homebrew">Homebrew</a>.</p>
 <p>a. <strong><em>Oficial package</em></strong></p>
-<p>You just go to <a href="http://www.videolan.org/vlc/download-macos.html">videolan.org</a>, download and install the program as you usually do with any other application.</p>
+<p>You just go to <a target="_blank" href="http://www.videolan.org/vlc/download-macos.html">videolan.org</a>, download and install the program as you usually do with any other application.</p>
 <p>Finally, add a symbolic link to the executable as follows:</p>
 <pre>sudo ln -s /Applications/VLC.app/Contents/MacOS/VLC /usr/bin/cvlc</pre>
 <p>b. <strong><em>Homebrew package</em></strong></p>

devel/pre-commit

@@ -34,6 +34,7 @@ do
         -e 's{</</p></li>{</li>{g' \
         -e 's/\.md">/.html">/g' \
         -e '/h1 class="title"/d' \
+        -e 's/<a href="http/<a target="_blank" href="http/g' \
         -e 's{</h2>{ <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></style>&{' ${out}
     rm tmp.md
     git add ${out}