[elpa] master d923d2e 06/10: Various updates to documentation

[Ian Dunn]

branch: master
commit d923d2edbeccdb785e905e4e522ac1493da06dea
Author: Ian Dunn <address@hidden>
Commit: Ian Dunn <address@hidden>

    Various updates to documentation
---
 .gitignore        |   3 +-
 hook-helpers.info | 283 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 hook-helpers.org  |  48 ++++++++-
 3 files changed, 328 insertions(+), 6 deletions(-)

diff --git a/.gitignore b/.gitignore
index 1af0c54..bf6ec2f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 *.elc
-hook-helpers.html
\ No newline at end of file
+hook-helpers.html
+hook-helpers.texi
\ No newline at end of file
diff --git a/hook-helpers.info b/hook-helpers.info
new file mode 100644
index 0000000..5cf10ce
--- /dev/null
+++ b/hook-helpers.info
@@ -0,0 +1,283 @@
+This is hook-helpers.info, produced by makeinfo version 6.5 from
+hook-helpers.texi.
+
+INFO-DIR-SECTION Emacs
+START-INFO-DIR-ENTRY
+* Hook Helpers: (hook-helpers). Anonymous, modifiable hook functions.
+END-INFO-DIR-ENTRY
+
+
+File: hook-helpers.info,  Node: Top,  Next: Copying,  Up: (dir)
+
+Hook Helpers
+************
+
+* Menu:
+
+* Copying::
+* Introduction::
+* Installation::
+* Examples::
+* In-Depth Usage::
+* Changelog::
+
+— The Detailed Node Listing —
+
+In-Depth Usage
+
+* Adding and Removing Helpers::
+* Seeing all the Available Helpers::
+
+Changelog
+
+* 1.1.1: 111.
+* 1.1: 11.
+* 1.0: 10.
+
+
+
+File: hook-helpers.info,  Node: Copying,  Next: Introduction,  Prev: Top,  Up: 
Top
+
+Copying
+*******
+
+Copyright (C) 2016-2018 Free Software Foundation, Inc.
+
+     This program is free software: you can redistribute it and/or
+     modify 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/>.
+
+
+File: hook-helpers.info,  Node: Introduction,  Next: Installation,  Prev: 
Copying,  Up: Top
+
+Introduction
+************
+
+Savannah Project (https://savannah.nongnu.org/projects/hook-helpers-el/)
+
+   Often times, I see people define a function to be used once in a
+hook.  If they don’t do this, then it will be an anonymous function.  If
+the anonymous function is modified, then the function can’t be removed.
+With a function outside of the ‘add-hook’ call, it looks messy.
+
+   Hook Helpers are a solution to this.  A “hook helper” is an
+anonymous, modifiable function created for the sole purpose of being
+attached to a hook.  This combines the two commonly used methods
+mentioned above.  The functions don’t exist, so they don’t get in the
+way of ‘C-h f’, but they can be removed or modified as needed.
+
+
+File: hook-helpers.info,  Node: Installation,  Next: Examples,  Prev: 
Introduction,  Up: Top
+
+Installation
+************
+
+Hook Helpers requires Emacs 25.1 or later.
+
+   The easiest way to install hook helpers is using GNU ELPA:
+
+     M-x package-install RET hook-helpers RET
+
+   No more setup is required to start using hook helpers.
+
+   You can also clone from the git repo:
+
+     git clone https://git.savannah.gnu.org/git/hook-helpers-el hook-helpers
+     make -C hook-helpers compile autoloads
+
+   Then you’ll need to add the following to your .emacs file (or
+equivalent):
+
+     (add-to-list 'load-path "/path/to/hook-helpers")
+     (load "/path/to/hook-helpers/hook-helpers-autoloads.el")
+
+
+File: hook-helpers.info,  Node: Examples,  Next: In-Depth Usage,  Prev: 
Installation,  Up: Top
+
+Examples
+********
+
+Let’s look at some examples.
+
+   Without using a hook helper, one must do the following:
+
+     (defun my/after-init-hook ()
+       (set-scroll-bar-mode nil))
+     (add-hook 'after-init-hook 'my/after-init-hook)
+
+   If you forget the ‘add-hook’ call, then this doesn’t do any good.
+Alternatively, you can use a lambda function:
+
+     (add-hook 'after-init-hook (lambda () (set-scroll-bar-mode nil)))
+
+   But then if you want to modify the function, it’s permanently stuck
+on the after-init-hook variable, and you have to deal with it.  It’s not
+a problem for after-init-hook, which is used once, but would be a
+problem for a mode hook, like text-mode-hook.
+
+   With a hook helper, this is reduced to the following:
+
+     (define-hook-helper after-init ()
+       (set-scroll-bar-mode nil))
+
+   Which handles everything for you.
+
+
+File: hook-helpers.info,  Node: In-Depth Usage,  Next: Changelog,  Prev: 
Examples,  Up: Top
+
+In-Depth Usage
+**************
+
+There are two macros in hook helpers: ‘define-hook-helper’ and
+‘create-hook-helper’.
+
+   The former is a basic case; it creates and adds a helper for a single
+hook.  Most hooks have the -hook suffix, so we take advantage of that
+here for a little less typing.  In order to add a helper to a
+non-standard hook, use the ‘:suffix’ argument:
+
+     (define-hook-helper my ()
+       :suffix function
+       :append t
+       (message "Hello!"))
+
+   We also introduce the ‘:append’ keyword above, which does exactly
+what it sounds like.
+
+   There’s one more keyword for ‘define-hook-helper’: ‘:name’.  This
+specifies an additional name for the new helper.  Without this, its
+helper ID is just the name of the hook; with a ‘:name’, its ID is
+HOOK-NAME/NAME.
+
+   The work horse of hook helpers is ‘create-hook-helper’.  This is the
+generic case, capable of adding itself to any number of hooks:
+
+     (create-hook-helper new-helper ()
+       :hooks (hook-1-hook
+               (hook-2-hook . t)
+               hook-3-function)
+       (message "Look at all that we can do!"))
+
+   This creates a new hook helper called “new-helper”, and adds it to
+‘hook-1-hook’, ‘hook-2-hook’, and ‘hook-3-function’, appending to the
+latter.
+
+   The ‘:hooks’ keyword can have the following form:
+
+   • A single hook
+   • A cons cell (HOOK .  APPEND)
+   • A list containing a mixture of the above two forms
+
+   This is called a “hook spec”.
+
+* Menu:
+
+* Adding and Removing Helpers::
+* Seeing all the Available Helpers::
+
+
+File: hook-helpers.info,  Node: Adding and Removing Helpers,  Next: Seeing all 
the Available Helpers,  Up: In-Depth Usage
+
+Adding and Removing Helpers
+===========================
+
+To add or remove helpers, the functions add-hook-helper and
+remove-hook-helper are provided.
+
+     (add-hook-helper 'test-helper '(hook-the-first hook-the-second))
+     (remove-hook-helper 'test-helper 'hook-the-second)
+
+   As you can see, each of them takes the same arguments: a symbol
+denoting the helper to add or remove, and a quoted hook spec.
+
+   Any hook helper created using ‘define-hook-helper’ can be removed as
+well:
+
+     (define-hook-helper my ()
+       :name ours
+       (message "Hello!"))
+
+     (remove-hook-helper 'my-hook/ours 'my-hook)
+
+
+File: hook-helpers.info,  Node: Seeing all the Available Helpers,  Prev: 
Adding and Removing Helpers,  Up: In-Depth Usage
+
+Seeing all the Available Helpers
+================================
+
+Seeing lambda functions in your hooks can be confusing.  While we don’t
+have a solution for that, we do have ‘describe-hook-helpers’, an
+interactive function that creates a pretty buffer containing all the
+defined hook helpers, grouped by the hooks to which they are attached.
+
+
+File: hook-helpers.info,  Node: Changelog,  Prev: In-Depth Usage,  Up: Top
+
+Changelog
+*********
+
+* Menu:
+
+* 1.1.1: 111.
+* 1.1: 11.
+* 1.0: 10.
+
+
+File: hook-helpers.info,  Node: 111,  Next: 11,  Up: Changelog
+
+1.1.1
+=====
+
+   • Fixed some usage warnings
+   • Added more examples of removing hook helpers
+   • Added documentation about installing from GNU ELPA
+   • Added changelog section to the documentation
+
+
+File: hook-helpers.info,  Node: 11,  Next: 10,  Prev: 111,  Up: Changelog
+
+1.1
+===
+
+   • Updated to new design
+
+
+File: hook-helpers.info,  Node: 10,  Prev: 11,  Up: Changelog
+
+1.0
+===
+
+   • Initial release
+
+
+
+Tag Table:
+Node: Top219
+Node: Copying585
+Node: Introduction1411
+Node: Installation2236
+Node: Examples2934
+Node: In-Depth Usage3890
+Node: Adding and Removing Helpers5572
+Node: Seeing all the Available Helpers6315
+Node: Changelog6791
+Node: 1116936
+Node: 117211
+Node: 107327
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End:
diff --git a/hook-helpers.org b/hook-helpers.org
index 4a72ce1..1f5090e 100644
--- a/hook-helpers.org
+++ b/hook-helpers.org
@@ -1,10 +1,20 @@
 #+TITLE: Hook Helpers
 #+AUTHOR: Ian Dunn
 #+EMAIL: address@hidden
+#+DATE: {{{modification-time}}}
+
+#+STARTUP: overview
+#+STARTUP: indent
+#+TODO: FIXME | FIXED
+#+OPTIONS: toc:2 num:nil timestamp:nil \n:nil |:t ':t email:t
+#+OPTIONS: *:t <:t d:nil todo:nil pri:nil tags:not-in-toc -:nil
+
+#+TEXINFO_DIR_CATEGORY: Emacs
+#+TEXINFO_DIR_TITLE: Hook Helpers: (hook-helpers)
+#+TEXINFO_DIR_DESC: Anonymous, modifiable hook functions
 
 * Copying
-Copyright (C) 2016 Ian Dunn
-Copyright (C) 2017 Free Software Foundation, Inc.
+Copyright (C) 2016-2018 Free Software Foundation, Inc.
 
 #+BEGIN_QUOTE
 This program is free software: you can redistribute it and/or modify
@@ -39,15 +49,22 @@ modified as needed.
 
 Hook Helpers requires Emacs 25.1 or later.
 
-To install hook helpers, you can clone from the git repo:
+The easiest way to install hook helpers is using GNU ELPA:
+
+#+begin_example
+M-x package-install RET hook-helpers RET
+#+end_example
+
+No more setup is required to start using hook helpers.
+
+You can also clone from the git repo:
 
 #+BEGIN_SRC shell
 git clone https://git.savannah.gnu.org/git/hook-helpers-el hook-helpers
 make -C hook-helpers compile autoloads
 #+END_SRC
 
-After that, setup is easy.  Just add the following to your .emacs file (or
-equivalent):
+Then you'll need to add the following to your .emacs file (or equivalent):
 
 #+BEGIN_SRC emacs-lisp
 (add-to-list 'load-path "/path/to/hook-helpers")
@@ -142,9 +159,30 @@ are provided.
 As you can see, each of them takes the same arguments: a symbol denoting the
 helper to add or remove, and a quoted hook spec.
 
+Any hook helper created using ~define-hook-helper~ can be removed as well:
+
+#+begin_src emacs-lisp
+(define-hook-helper my ()
+  :name ours
+  (message "Hello!"))
+
+(remove-hook-helper 'my-hook/ours 'my-hook)
+#+end_src
+
 ** Seeing all the Available Helpers
 
 Seeing lambda functions in your hooks can be confusing.  While we don't have a
 solution for that, we do have ~describe-hook-helpers~, an interactive function
 that creates a pretty buffer containing all the defined hook helpers, grouped 
by
 the hooks to which they are attached.
+
+* Changelog
+** 1.1.1
+- Fixed some usage warnings
+- Added more examples of removing hook helpers
+- Added documentation about installing from GNU ELPA
+- Added changelog section to the documentation
+** 1.1
+- Updated to new design
+** 1.0
+- Initial release