[elpa] externals/gnorb 4d3de61 316/449: Various documentation improvements

[Stefan Monnier]

branch: externals/gnorb
commit 4d3de61e75c24c35f6e8ad8f159dbc6ae64889a3
Author: Eric Abrahamsen <eric@ericabrahamsen.net>
Commit: Eric Abrahamsen <eric@ericabrahamsen.net>

    Various documentation improvements
    
    * gnorb.org: Most notably a new section on "Basic Usage" for email tracking.
    * gnorb.texi:
    * gnorb.info:
---
 gnorb.info | 135 +++++++++++++++++++++++++++++++++++++------------------------
 gnorb.org  |  66 +++++++++++++++++++++---------
 gnorb.texi |  82 +++++++++++++++++++++++++++----------
 3 files changed, 189 insertions(+), 94 deletions(-)

diff --git a/gnorb.info b/gnorb.info
index b6f3fab..52ca072 100644
--- a/gnorb.info
+++ b/gnorb.info
@@ -30,6 +30,7 @@ Gnorb Manual
 
 Email Tracking
 
+* Basic Usage::
 * Email-Related Commands::
 * Trigger Actions::
 * Viewing Tracked Messages in *Summary* Buffers::
@@ -139,18 +140,19 @@ IDs are associated with Org heading ids.  As a 
conversation develops,
 messages are collected on a heading (and/or its children).  You can
 compose new messages directly from the Org heading, and Gnorb will
 automatically associate your sent message with the conversation.  You
-can open temporary Gnus *Summary* buffers holding all the messages
-associated with an Org subtree, and reply from there.  When you receive
-new messages relevant to a conversation, Gnorb will notice them and
-prompt you to associate them with the appropriate Org heading.
-Attachments on incoming messages can be automatically saved as
-attachments on Org headings, using org-attach.
+can open Gnus *Summary* buffers holding all the messages associated with
+an Org subtree, and reply from there – these groups can be made
+persistent, if you like.  When you receive new messages relevant to a
+conversation, Gnorb will notice them and prompt you to associate them
+with the appropriate Org heading.  Attachments on incoming messages can
+be automatically saved as attachments on Org headings, using org-attach.
 
    In general, the goal is to keep track of whole conversations, reduce
 friction when moving between Gnus and Org, and keep you in the Org
 agenda rather than in Gnus.
 * Menu:
 
+* Basic Usage::
 * Email-Related Commands::
 * Trigger Actions::
 * Viewing Tracked Messages in *Summary* Buffers::
@@ -160,9 +162,34 @@ agenda rather than in Gnus.
 * Likely Workflow::
 
 
-File: gnorb.info,  Node: Email-Related Commands,  Next: Trigger Actions,  Up: 
Email Tracking
+File: gnorb.info,  Node: Basic Usage,  Next: Email-Related Commands,  Up: 
Email Tracking
+
+4.1 Basic Usage
+===============
+
+The following sections might be a bit confusing to read if you haven’t
+actually tried using Gnorb.  If you don’t want to dive in all the way
+just yet, you can just dabble your toes.  First set up email tracking as
+specified in *note Setup: Setup, then do the following:
+
+  1. Add “%ug” somewhere appropriate in your ‘gnus-summary-line-format’
+     variable.
+  2. If you don’t use a local archive method, add your sent message
+     groups to ‘gnorb-gnus-sent-groups’ (see the docstring).
+  3. Use Org capture from Gnus summary buffers to create reminders for
+     emails you need to reply to.
+  4. Reply to those emails by pressing “C-c t” on the TODO heading in
+     either the Agenda, or in regular Org files.
+  5. If you ever get confused about what’s associated with an Org
+     heading, press “C-c v” on the heading (works in either the Agenda,
+     or regular Org files).
+
+   That should be enough to get started.
 
-4.1 Email-Related Commands
+
+File: gnorb.info,  Node: Email-Related Commands,  Next: Trigger Actions,  
Prev: Basic Usage,  Up: Email Tracking
+
+4.2 Email-Related Commands
 ==========================
 
 Email tracking starts in one of three ways:
@@ -195,7 +222,7 @@ Email tracking starts in one of three ways:
      ‘gnorb-org-handle-mail’.  It does the same thing as the latter, but
      first exports the body of the subtree as either text or a file,
      then inserts the text into the message body, or attaches the file
-     to the message, depending on what you’ve chosen.
+     to the message, respectively.
   2. ‘gnorb-gnus-incoming-do-todo’ is called on a message in a Gnus
      *Summary* buffer.  You’ll be prompted for an Org heading, taken to
      that heading, and asked to trigger an action on it.
@@ -223,7 +250,7 @@ Email tracking starts in one of three ways:
    Because these three commands all express a similar intent, but are
 called in different modes, it can make sense to give each of them the
 same keybinding in the keymaps for Org mode, Gnus summary mode, and
-Message mode, respectively.
+Message mode.
 
    An additional convenience command is available for use in Gnus
 summary buffers: ‘gnorb-gnus-quick-reply’.  If you don’t want to go
@@ -235,33 +262,35 @@ heading.
 
 File: gnorb.info,  Node: Trigger Actions,  Next: Viewing Tracked Messages in 
*Summary* Buffers,  Prev: Email-Related Commands,  Up: Email Tracking
 
-4.2 Trigger Actions
+4.3 Trigger Actions
 ===================
 
 After calling ‘gnorb-gnus-incoming-do-todo’ on a message, or after
 sending a message associated with an Org heading, you’ll be taken to the
 heading and asked to “trigger an action” on it.  At the moment there are
-four different possibilities: triggering a TODO state-change on the
+six different possibilities: triggering a TODO state-change on the
 heading, taking a note on the heading (both these options will associate
 the message with the heading), associating the message but doing nothing
-else, and lastly, doing nothing at all.
+else, capturing a new Org heading as a sibling to the tracked heading,
+capturing a new Org heading as a child, and lastly, doing nothing at
+all.
 
-   More actions will be added in the future; it’s also possible to
+   More actions may be added in the future; it’s also possible to
 rearrange or delete existing actions, and add your own: see the
 docstring of ‘gnorb-org-trigger-actions’.
 
 
 File: gnorb.info,  Node: Viewing Tracked Messages in *Summary* Buffers,  Next: 
Hinting in Gnus,  Prev: Trigger Actions,  Up: Email Tracking
 
-4.3 Viewing Tracked Messages in *Summary* Buffers
+4.4 Viewing Tracked Messages in *Summary* Buffers
 =================================================
 
-Call ‘gnorb-org-view’ on an Org heading to open an nnir *Summary* buffer
+Call ‘gnorb-org-view’ on an Org heading to open an nnir summary buffer
 showing all the messages associated with that heading and child headings
-(this requires that you’ve added an nngnorb server to your Gnus
-backends).  A minor mode will be in effect, ensuring that any replies
-you send to messages in this buffer will automatically be associated
-with the original Org heading.  You can also invoke
+(this requires you to have added an nngnorb server to your Gnus
+backends).  A minor mode is in effect, ensuring that any replies you
+send to messages in this buffer will automatically be associated with
+the original Org heading.  You can also invoke
 ‘gnorb-summary-disassociate-message’ (“C-c d”) to disassociate the
 message with the Org heading.
 
@@ -281,7 +310,7 @@ linked messages.  This is dog-slow at the moment; it will 
get faster.
 
 File: gnorb.info,  Node: Hinting in Gnus,  Next: Message Attachments,  Prev: 
Viewing Tracked Messages in *Summary* Buffers,  Up: Email Tracking
 
-4.4 Hinting in Gnus
+4.5 Hinting in Gnus
 ===================
 
 When you receive new mails that might be relevant to existing Org TODOs,
@@ -330,18 +359,19 @@ message.
 
 File: gnorb.info,  Node: Registry Usage,  Next: Likely Workflow,  Prev: 
Message Attachments,  Up: Email Tracking
 
-4.6 Registry Usage
+4.7 Registry Usage
 ==================
 
 You can see how many associations you’ve got stored in the registry by
 calling ‘gnorb-report-tracking-usage’.  This will pop up a buffer
-showing how the number of associations, and offering keybindings for
-‘gnorb-flush-dead-associations’, to help Gnorb clean up after itself.
+showing how much of the registry you’re using, and offering keybindings
+for ‘gnorb-flush-dead-associations’, to help Gnorb clean up after
+itself.
 
 
 File: gnorb.info,  Node: Likely Workflow,  Prev: Registry Usage,  Up: Email 
Tracking
 
-4.7 Likely Workflow
+4.8 Likely Workflow
 ===================
 
 You receive an email from Jimmy, who wants to rent a room in your house.
@@ -696,7 +726,7 @@ File: gnorb.info,  Node: Suggested Keybindings,  Prev: Misc 
Gnus,  Up: Top
           (org-defkey org-mode-map (kbd "C-c V") 'gnorb-org-popup-bbdb)
           (setq gnorb-org-agenda-popup-bbdb t)
           (eval-after-load "org-agenda"
-            '(progn (org-defkey org-agenda-mode-map (kbd "H") 
'gnorb-org-handle-mail)
+            '(progn (org-defkey org-agenda-mode-map (kbd "C-c t") 
'gnorb-org-handle-mail)
                     (org-defkey org-agenda-mode-map (kbd "C-c v") 
'gnorb-org-popup-bbdb)
                     (org-defkey org-agenda-mode-map (kbd "V") 
'gnorb-org-view)))))
 
@@ -727,32 +757,33 @@ File: gnorb.info,  Node: Suggested Keybindings,  Prev: 
Misc Gnus,  Up: Top
 
 Tag Table:
 Node: Top194
-Node: Introduction1028
-Node: Installation2137
-Node: Setup2551
-Node: Email Tracking3918
-Node: Email-Related Commands5468
-Node: Trigger Actions8839
-Node: Viewing Tracked Messages in *Summary* Buffers9688
-Node: Hinting in Gnus11184
-Node: Message Attachments12192
-Node: Registry Usage13373
-Node: Likely Workflow13815
-Node: Restoring Window Layout16615
-Node: Recent Mails From BBDB Contacts16979
-Node: BBDB posting styles17975
-Node: BBDB Org tagging18891
-Node: Misc BBDB19637
-Node: Searching for messages from BBDB contacts19850
-Node: Citing BBDB contacts20296
-Node: User Options20617
-Node: Misc Org22156
-Node: Inserting BBDB links22331
-Node: User Optionsx22586
-Node: Misc Gnus25323
-Node: Viewing Org headlines relevant to a message25536
-Node: User Optionsxx25851
-Node: Suggested Keybindings28858
+Node: Introduction1044
+Node: Installation2153
+Node: Setup2567
+Node: Email Tracking3934
+Node: Basic Usage5544
+Node: Email-Related Commands6617
+Node: Trigger Actions10112
+Node: Viewing Tracked Messages in *Summary* Buffers11064
+Node: Hinting in Gnus12551
+Node: Message Attachments13647
+Node: Registry Usage14828
+Node: Likely Workflow15279
+Node: Restoring Window Layout18079
+Node: Recent Mails From BBDB Contacts18443
+Node: BBDB posting styles19439
+Node: BBDB Org tagging20355
+Node: Misc BBDB21101
+Node: Searching for messages from BBDB contacts21314
+Node: Citing BBDB contacts21760
+Node: User Options22081
+Node: Misc Org23620
+Node: Inserting BBDB links23795
+Node: User Optionsx24050
+Node: Misc Gnus26787
+Node: Viewing Org headlines relevant to a message27000
+Node: User Optionsxx27315
+Node: Suggested Keybindings30322
 
 End Tag Table
 
diff --git a/gnorb.org b/gnorb.org
index 12cfb49..58b0365 100644
--- a/gnorb.org
+++ b/gnorb.org
@@ -35,6 +35,9 @@ https://github.com/girzel/gnorb, and put the "gnorb" 
directory on your
 load-path. The Github site is also a good place to report bugs and
 other issues.
 * Setup
+:PROPERTIES:
+:ID:       9da59609-bb3c-4970-88f6-bddca18d2ad4
+:END:
 Loading "gnorb" will make the basic functions available. Using Gnorb
 for email tracking takes a bit more setup, however:
 
@@ -68,16 +71,36 @@ message IDs are associated with Org heading ids. As a 
conversation
 develops, messages are collected on a heading (and/or its children).
 You can compose new messages directly from the Org heading, and Gnorb
 will automatically associate your sent message with the conversation.
-You can open temporary Gnus *Summary* buffers holding all the messages
-associated with an Org subtree, and reply from there. When you receive
-new messages relevant to a conversation, Gnorb will notice them and
-prompt you to associate them with the appropriate Org heading.
-Attachments on incoming messages can be automatically saved as
-attachments on Org headings, using org-attach.
+You can open Gnus *Summary* buffers holding all the messages
+associated with an Org subtree, and reply from there -- these groups
+can be made persistent, if you like. When you receive new messages
+relevant to a conversation, Gnorb will notice them and prompt you to
+associate them with the appropriate Org heading. Attachments on
+incoming messages can be automatically saved as attachments on Org
+headings, using org-attach.
 
 In general, the goal is to keep track of whole conversations, reduce
 friction when moving between Gnus and Org, and keep you in the Org
 agenda rather than in Gnus.
+** Basic Usage
+The following sections might be a bit confusing to read if you haven't
+actually tried using Gnorb. If you don't want to dive in all the way
+just yet, you can just dabble your toes. First set up email tracking
+as specified in [[id:9da59609-bb3c-4970-88f6-bddca18d2ad4][Setup]], then do 
the following:
+
+1. Add "%ug" somewhere appropriate in your `gnus-summary-line-format'
+   variable.
+2. If you don't use a local archive method, add your sent message
+   groups to `gnorb-gnus-sent-groups' (see the docstring).
+3. Use Org capture from Gnus summary buffers to create reminders for
+   emails you need to reply to.
+4. Reply to those emails by pressing "C-c t" on the TODO heading in
+   either the Agenda, or in regular Org files.
+5. If you ever get confused about what's associated with an Org
+   heading, press "C-c v" on the heading (works in either the Agenda,
+   or regular Org files).
+
+That should be enough to get started.
 ** Email-Related Commands
 Email tracking starts in one of three ways:
 
@@ -109,7 +132,7 @@ There are three main email-related commands:
    `gnorb-org-handle-mail'. It does the same thing as the latter, but
    first exports the body of the subtree as either text or a file,
    then inserts the text into the message body, or attaches the file
-   to the message, depending on what you've chosen.
+   to the message, respectively.
 2. `gnorb-gnus-incoming-do-todo' is called on a message in a Gnus
    *Summary* buffer. You'll be prompted for an Org heading, taken to
    that heading, and asked to trigger an action on it.
@@ -137,7 +160,7 @@ There are three main email-related commands:
 Because these three commands all express a similar intent, but are
 called in different modes, it can make sense to give each of them the
 same keybinding in the keymaps for Org mode, Gnus summary mode, and
-Message mode, respectively.
+Message mode.
 
 An additional convenience command is available for use in Gnus summary
 buffers: `gnorb-gnus-quick-reply'. If you don't want to go through the
@@ -149,23 +172,25 @@ heading.
 After calling `gnorb-gnus-incoming-do-todo' on a message, or after
 sending a message associated with an Org heading, you'll be taken to
 the heading and asked to "trigger an action" on it. At the moment
-there are four different possibilities: triggering a TODO state-change
+there are six different possibilities: triggering a TODO state-change
 on the heading, taking a note on the heading (both these options will
 associate the message with the heading), associating the message but
-doing nothing else, and lastly, doing nothing at all.
+doing nothing else, capturing a new Org heading as a sibling to the
+tracked heading, capturing a new Org heading as a child, and lastly,
+doing nothing at all.
 
-More actions will be added in the future; it's also possible to
+More actions may be added in the future; it's also possible to
 rearrange or delete existing actions, and add your own: see the
 docstring of `gnorb-org-trigger-actions'.
 ** Viewing Tracked Messages in *Summary* Buffers
 :PROPERTIES:
 :END:
-Call `gnorb-org-view' on an Org heading to open an nnir *Summary*
-buffer showing all the messages associated with that heading and child
-headings (this requires that you've added an nngnorb server to your
-Gnus backends). A minor mode will be in effect, ensuring that any
-replies you send to messages in this buffer will automatically be
-associated with the original Org heading. You can also invoke
+Call `gnorb-org-view' on an Org heading to open an nnir summary buffer
+showing all the messages associated with that heading and child
+headings (this requires you to have added an nngnorb server to your
+Gnus backends). A minor mode is in effect, ensuring that any replies
+you send to messages in this buffer will automatically be associated
+with the original Org heading. You can also invoke
 `gnorb-summary-disassociate-message' ("C-c d") to disassociate the
 message with the Org heading.
 
@@ -226,8 +251,9 @@ message.
 ** Registry Usage
 You can see how many associations you've got stored in the registry by
 calling `gnorb-report-tracking-usage'. This will pop up a buffer
-showing how the number of associations, and offering keybindings for
-`gnorb-flush-dead-associations', to help Gnorb clean up after itself.
+showing how much of the registry you're using, and offering
+keybindings for `gnorb-flush-dead-associations', to help Gnorb clean
+up after itself.
 ** Likely Workflow
 You receive an email from Jimmy, who wants to rent a room in your
 house. "I'll respond to this later," you think.
@@ -488,7 +514,7 @@ heading to jump to that heading.
        (org-defkey org-mode-map (kbd "C-c V") 'gnorb-org-popup-bbdb)
        (setq gnorb-org-agenda-popup-bbdb t)
        (eval-after-load "org-agenda"
-         '(progn (org-defkey org-agenda-mode-map (kbd "H") 
'gnorb-org-handle-mail)
+         '(progn (org-defkey org-agenda-mode-map (kbd "C-c t") 
'gnorb-org-handle-mail)
                  (org-defkey org-agenda-mode-map (kbd "C-c v") 
'gnorb-org-popup-bbdb)
                  (org-defkey org-agenda-mode-map (kbd "V") 'gnorb-org-view)))))
 
diff --git a/gnorb.texi b/gnorb.texi
index fd468c4..cdd7576 100644
--- a/gnorb.texi
+++ b/gnorb.texi
@@ -42,6 +42,7 @@
 
 Email Tracking
 
+* Basic Usage::
 * Email-Related Commands::
 * Trigger Actions::
 * Viewing Tracked Messages in *Summary* Buffers::
@@ -147,17 +148,19 @@ message IDs are associated with Org heading ids. As a 
conversation
 develops, messages are collected on a heading (and/or its children).
 You can compose new messages directly from the Org heading, and Gnorb
 will automatically associate your sent message with the conversation.
-You can open temporary Gnus *Summary* buffers holding all the messages
-associated with an Org subtree, and reply from there. When you receive
-new messages relevant to a conversation, Gnorb will notice them and
-prompt you to associate them with the appropriate Org heading.
-Attachments on incoming messages can be automatically saved as
-attachments on Org headings, using org-attach.
+You can open Gnus *Summary* buffers holding all the messages
+associated with an Org subtree, and reply from there -- these groups
+can be made persistent, if you like. When you receive new messages
+relevant to a conversation, Gnorb will notice them and prompt you to
+associate them with the appropriate Org heading. Attachments on
+incoming messages can be automatically saved as attachments on Org
+headings, using org-attach.
 
 In general, the goal is to keep track of whole conversations, reduce
 friction when moving between Gnus and Org, and keep you in the Org
 agenda rather than in Gnus.
 @menu
+* Basic Usage::
 * Email-Related Commands::
 * Trigger Actions::
 * Viewing Tracked Messages in *Summary* Buffers::
@@ -167,6 +170,35 @@ agenda rather than in Gnus.
 * Likely Workflow::
 @end menu
 
+@node Basic Usage
+@section Basic Usage
+
+The following sections might be a bit confusing to read if you haven't
+actually tried using Gnorb. If you don't want to dive in all the way
+just yet, you can just dabble your toes. First set up email tracking
+as specified in @ref{Setup,Setup}, then do the following:
+
+@enumerate
+@item
+Add ``%ug'' somewhere appropriate in your `gnus-summary-line-format'
+variable.
+@item
+If you don't use a local archive method, add your sent message
+groups to `gnorb-gnus-sent-groups' (see the docstring).
+@item
+Use Org capture from Gnus summary buffers to create reminders for
+emails you need to reply to.
+@item
+Reply to those emails by pressing ``C-c t'' on the TODO heading in
+either the Agenda, or in regular Org files.
+@item
+If you ever get confused about what's associated with an Org
+heading, press ``C-c v'' on the heading (works in either the Agenda,
+or regular Org files).
+@end enumerate
+
+That should be enough to get started.
+
 @node Email-Related Commands
 @section Email-Related Commands
 
@@ -207,7 +239,7 @@ action on it.
 `gnorb-org-handle-mail'. It does the same thing as the latter, but
 first exports the body of the subtree as either text or a file,
 then inserts the text into the message body, or attaches the file
-to the message, depending on what you've chosen.
+to the message, respectively.
 @item
 `gnorb-gnus-incoming-do-todo' is called on a message in a Gnus
 *Summary* buffer. You'll be prompted for an Org heading, taken to
@@ -238,7 +270,7 @@ sent message for this purpose.
 Because these three commands all express a similar intent, but are
 called in different modes, it can make sense to give each of them the
 same keybinding in the keymaps for Org mode, Gnus summary mode, and
-Message mode, respectively.
+Message mode.
 
 An additional convenience command is available for use in Gnus summary
 buffers: `gnorb-gnus-quick-reply'. If you don't want to go through the
@@ -253,24 +285,26 @@ heading.
 After calling `gnorb-gnus-incoming-do-todo' on a message, or after
 sending a message associated with an Org heading, you'll be taken to
 the heading and asked to ``trigger an action'' on it. At the moment
-there are four different possibilities: triggering a TODO state-change
+there are six different possibilities: triggering a TODO state-change
 on the heading, taking a note on the heading (both these options will
 associate the message with the heading), associating the message but
-doing nothing else, and lastly, doing nothing at all.
+doing nothing else, capturing a new Org heading as a sibling to the
+tracked heading, capturing a new Org heading as a child, and lastly,
+doing nothing at all.
 
-More actions will be added in the future; it's also possible to
+More actions may be added in the future; it's also possible to
 rearrange or delete existing actions, and add your own: see the
 docstring of `gnorb-org-trigger-actions'.
 
 @node Viewing Tracked Messages in *Summary* Buffers
 @section Viewing Tracked Messages in *Summary* Buffers
 
-Call `gnorb-org-view' on an Org heading to open an nnir *Summary*
-buffer showing all the messages associated with that heading and child
-headings (this requires that you've added an nngnorb server to your
-Gnus backends). A minor mode will be in effect, ensuring that any
-replies you send to messages in this buffer will automatically be
-associated with the original Org heading. You can also invoke
+Call `gnorb-org-view' on an Org heading to open an nnir summary buffer
+showing all the messages associated with that heading and child
+headings (this requires you to have added an nngnorb server to your
+Gnus backends). A minor mode is in effect, ensuring that any replies
+you send to messages in this buffer will automatically be associated
+with the original Org heading. You can also invoke
 `gnorb-summary-disassociate-message' (``C-c d'') to disassociate the
 message with the Org heading.
 
@@ -335,8 +369,9 @@ message.
 
 You can see how many associations you've got stored in the registry by
 calling `gnorb-report-tracking-usage'. This will pop up a buffer
-showing how the number of associations, and offering keybindings for
-`gnorb-flush-dead-associations', to help Gnorb clean up after itself.
+showing how much of the registry you're using, and offering
+keybindings for `gnorb-flush-dead-associations', to help Gnorb clean
+up after itself.
 
 @node Likely Workflow
 @section Likely Workflow
@@ -676,7 +711,7 @@ line. Defaults to ``&''.
      (org-defkey org-mode-map (kbd "C-c V") 'gnorb-org-popup-bbdb)
      (setq gnorb-org-agenda-popup-bbdb t)
      (eval-after-load "org-agenda"
-       '(progn (org-defkey org-agenda-mode-map (kbd "H") 
'gnorb-org-handle-mail)
+       '(progn (org-defkey org-agenda-mode-map (kbd "C-c t") 
'gnorb-org-handle-mail)
                (org-defkey org-agenda-mode-map (kbd "C-c v") 
'gnorb-org-popup-bbdb)
                (org-defkey org-agenda-mode-map (kbd "V") 'gnorb-org-view)))))
 
@@ -704,5 +739,8 @@ line. Defaults to ``&''.
      (define-key message-mode-map (kbd "C-c t") 'gnorb-gnus-outgoing-do-todo)))
 @end lisp
 
-@c Emacs 25.0.50.7 (Org mode 8.3beta)
-@bye
\ No newline at end of file
+@bye
+@c Local Variables:
+@c mode: texinfo
+@c TeX-master: t
+@c End: