[elpa] externals/bug-hunter 91e1fea 50/95: Better Readme

[Stefan Monnier]

branch: externals/bug-hunter
commit 91e1fea0809ac8b633779319d34a28be7bec9565
Author: Artur Malabarba <bruce.connor.am@gmail.com>
Commit: Artur Malabarba <bruce.connor.am@gmail.com>

    Better Readme
---
 README.md      |  26 -------------------
 README.org     |  54 +++++++++++++++++++++++++++++++++++++++
 bug-hunter.el  |  78 ++++++++++++++++++++++++++++++++++-----------------------
 cl-example.png | Bin 0 -> 13527 bytes
 4 files changed, 101 insertions(+), 57 deletions(-)

diff --git a/README.md b/README.md
deleted file mode 100644
index 6adb3a3..0000000
--- a/README.md
+++ /dev/null
@@ -1,26 +0,0 @@
-##  ![hunter](hunter.png) Bug Hunter 
[![travis](https://secure.travis-ci.org/Bruce-Connor/elisp-bug-hunter.png?branch=master)](https://travis-ci.org/Bruce-Connor/elisp-bug-hunter?branch%3Dmaster)
-
-`bug-hunter` is an Emacs library that finds the source of a bug inside any 
given `.el` file. 
-
-## Usage Examples
-
-1. If your Emacs init file signals an error during startup, but you
-   don’t know why, simply issue
-
-        M-x bug-hunter-init-file RET RET
-
-   and `bug-hunter` will find it for you.
-
-2. If Emacs starts up without errors but something is not working as
-   it should, invoke the same command, but give it in an assertion:
-
-         M-x bug-hunter-init-file RET (when issue-detected t) RET
-
-
-3. You can also use `bug-hunter-file` to hunt in other files, or even
-   `bug-hunter-hunt` to search in a list of expressions.
-
-## Installation
-
-1. Open the `bug-hunter.el` file.
-2. Issue  `M-x package-install-from-buffer`.
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..7485af3
--- /dev/null
+++ b/README.org
@@ -0,0 +1,54 @@
+#+OPTIONS: toc:nil num:nil
+#+TITLE: [[file:hunter.png]] Bug Hunter 
[[https://travis-ci.org/Bruce-Connor/elisp-bug-hunter?branch%3Dmaster][https://secure.travis-ci.org/Bruce-Connor/elisp-bug-hunter.png?branch=master]]
+
+~bug-hunter~ is an Emacs library that finds the source of an error or
+unexpected behavior inside an elisp configuration file (tipically
+~init.el~ or ~.emacs~).
+
+* Usage Examples
+
+If your Emacs init file signals an error during startup, but you don’t
+know why, simply issue
+#+BEGIN_SRC text
+M-x bug-hunter-init-file RET RET
+#+END_SRC
+and ~bug-hunter~ will find it for you.
+
+If Emacs starts up without errors but something is not working as it
+should, invoke the same command, but give it in an assertion.
+Essentially, if you can write a snippet that detects the issue and
+returns non-nil, just provide this snippet as the assertion and the
+Bug Hunter will do a bisection search for you.
+
+For example, let’s say there’s something in your init file that’s
+loading the ~cl~ library, and you don’t want that. You /know/ you’re
+not loading it yourself, but how can you figure out which external
+package is responsible for this outrage?
+
+#+BEGIN_SRC text
+M-x bug-hunter-init-file RET (featurep 'cl) RET
+#+END_SRC
+
+*That’s it!* You’ll be given a nice buffer reporting the results:
+
+[[file:cl-example.png]]
+- Are you getting obscure errors when trying to open /“.tex”/
+  files? Don’t despair! Just use ~(find-file "dummy.tex")~ as the
+  assertion.
+- Did ~ox-html~ stop working due to some arcane misconfiguration? Just
+  write an assertion that does an export and checks the result.
+- Does some random command suddenly bind itself to ~C-j~ and you can’t
+  figure out why? ~(eq (key-binding "\n") 'unwanted-command)~ is the
+  assertion for you!
+
+Finally, you can also use ~bug-hunter-file~ to hunt in other files.
+
+* Installation
+# It is part of Emacs and is available trough 
[[https://elpa.gnu.org/packages/bug-hunter.html][GNU Elpa]]. To install, issue 
+
+# #+BEGIN_SRC text
+# M-x package-install RET bug-hunter
+# #+END_SRC
+Bug Hunter will be on Gelpa shortly. For now, do the following:
+1. Open the `bug-hunter.el` file.
+2. Issue  `M-x package-install-from-buffer`.
diff --git a/bug-hunter.el b/bug-hunter.el
index b9964c2..c48d705 100644
--- a/bug-hunter.el
+++ b/bug-hunter.el
@@ -12,49 +12,65 @@
 ;; it under the terms of the GNU General Public License as published by
 ;; the Free Software Foundation, either version 3 of the License, or
 ;; (at your option) any later version.
-
+;;
 ;; This program is distributed in the hope that it will be useful,
 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ;; GNU General Public License for more details.
-
+;;
 ;; You should have received a copy of the GNU General Public License
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ;;; Commentary:
-;; `bug-hunter' is an Emacs library that finds the source of a bug inside
-;; any given `.el' file.
-;;
-;;
+;; `bug-hunter' is an Emacs library that finds the source of an error or
+;; unexpected behavior inside an elisp configuration file (tipically
+;; `init.el' or `.emacs').
+;; 
+;; 
 ;; Usage Examples
 ;; ==============
-;;
-;;   1. If your Emacs init file signals an error during startup, but you
-;;      don’t know why, simply issue
-;;      ,----
-;;      | M-x bug-hunter-init-file RET RET
-;;      `----
-;;      and `bug-hunter' will find it for you.
-;;
-;;   2. If Emacs starts up without errors but something is not working as
-;;      it should, invoke the same command, but give it in an assertion:
-;;      ,----
-;;      | M-x bug-hunter-init-file RET (when issue-detected t) RET
-;;      `----
-;;
-;;   3. You can also use `bug-hunter-file' to hunt in other files, or even
-;;      `bug-hunter-hunt' to search in a list of expressions.
-;;
-;;
-;; Installation
-;; ============
-;;
-;;   It is part of Emacs and is available trough GNU Elpa. To install,
-;;   issue
-;;
+;; 
+;;   If your Emacs init file signals an error during startup, but you don’t
+;;   know why, simply issue
 ;;   ,----
-;;   | M-x package-install RET bug-hunter
+;;   | M-x bug-hunter-init-file RET RET
 ;;   `----
+;;   and `bug-hunter' will find it for you.
+;; 
+;;   If Emacs starts up without errors but something is not working as it
+;;   should, invoke the same command, but give it in an assertion.
+;;   Essentially, if you can write a snippet that detects the issue and
+;;   returns non-nil, just provide this snippet as the assertion and the
+;;   Bug Hunter will do a bisection search for you.
+;; 
+;;   For example, let’s say there’s something in your init file that’s
+;;   loading the `cl' library, and you don’t want that. You /know/ you’re
+;;   not loading it yourself, but how can you figure out which external
+;;   package is responsible for this outrage?
+;; 
+;;   ,----
+;;   | M-x bug-hunter-init-file RET (featurep 'cl) RET
+;;   `----
+;; 
+;;   *That’s it!* You’ll be given a nice buffer reporting the results:
+;; 
+;;   - Are you getting obscure errors when trying to open /“.tex”/ files?
+;;     Don’t despair! Just use `(find-file "dummy.tex")' as the assertion.
+;;   - Did `ox-html' stop working due to some arcane misconfiguration? Just
+;;     write an assertion that does an export and checks the result.
+;;   - Does some random command suddenly bind itself to `C-j' and you can’t
+;;     figure out why? `(eq (key-binding "\n") 'unwanted-command)' is the
+;;     assertion for you!
+;; 
+;;   Finally, you can also use `bug-hunter-file' to hunt in other files.
+;; 
+
+;; Installation
+;; ============
+;; 
+;;   Bug Hunter will be on Gelpa shortly. For now, do the following:
+;;   1. Open the `bug-hunter.el` file.
+;;   2. Issue `M-x package-install-from-buffer`.
 
 
 ;;; Code:
diff --git a/cl-example.png b/cl-example.png
new file mode 100644
index 0000000..51ea8e6
Binary files /dev/null and b/cl-example.png differ