Merge commit 'b67364d4825a9bf0a22261809ee9e9060b268198'

[gnu-emacs-elpa] / packages / gnorb / gnorb.info

diff --git a/packages/gnorb/gnorb.info b/packages/gnorb/gnorb.info
index 08085e10a1b001cb12046d91b24e8344ad4f913a..52ca072707589130758c722fd0033ac614d51fdd 100644 (file)
--- a/packages/gnorb/gnorb.info
+++ b/packages/gnorb/gnorb.info
@@ -30,11 +30,13 @@ Gnorb Manual
 
 Email Tracking
 
 
 Email Tracking
 

+* Basic Usage::

 * Email-Related Commands::
 * Trigger Actions::
 * Viewing Tracked Messages in *Summary* Buffers::
 * Hinting in Gnus::
 * Message Attachments::
 * Email-Related Commands::
 * Trigger Actions::
 * Viewing Tracked Messages in *Summary* Buffers::
 * Hinting in Gnus::
 * Message Attachments::

+* Registry Usage::

 * Likely Workflow::
 
 Misc BBDB
 * Likely Workflow::
 
 Misc BBDB


@@ -138,29 +140,56 @@ 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
 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:
 
 
    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::
 * Hinting in Gnus::
 * Message Attachments::
 * Email-Related Commands::
 * Trigger Actions::
 * Viewing Tracked Messages in *Summary* Buffers::
 * Hinting in Gnus::
 * Message Attachments::

+* Registry Usage::

 * Likely Workflow::
 
 \1f
 * Likely Workflow::
 
 \1f

-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
+\1f
+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:
 ==========================
 
 Email tracking starts in one of three ways:


@@ -178,11 +207,14 @@ Email tracking starts in one of three ways:
   1. ‘gnorb-org-handle-mail’ is called on an Org heading to compose a
      new message.  By default, this will begin a reply to the most
      recent message in the conversation.  If there are no associated
   1. ‘gnorb-org-handle-mail’ is called on an Org heading to compose a
      new message.  By default, this will begin a reply to the most
      recent message in the conversation.  If there are no associated

-     messages to reply to (or you call the function with a double prefix
+     messages to reply to (or you call the function with a single prefix

      arg), Gnorb will look for mailto: or bbdb: links in the heading,
      and compose a new message to them.
 
      arg), Gnorb will look for mailto: or bbdb: links in the heading,
      and compose a new message to them.
 

-     The sent message will be associated with the Org heading, and
+     Calling the function with a double prefix arg will ignore all
+     associated messages and links, and compose a blank message.
+
+     Once sent, the message will be associated with the Org heading, and

      you’ll be brought back to the heading and asked to trigger an
      action on it.
 
      you’ll be brought back to the heading and asked to trigger an
      action on it.
 


@@ -190,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
      ‘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.
   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.


@@ -218,39 +250,54 @@ 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
    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 whole round trip of triggering an action and then starting a
+new reply, call this command on an incoming message to associate it with
+a heading, start a reply, and associate your reply with the same
+heading.

 
 \1f
 File: gnorb.info,  Node: Trigger Actions,  Next: Viewing Tracked Messages in *Summary* Buffers,  Prev: Email-Related Commands,  Up: Email Tracking
 
 
 \1f
 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
 ===================
 
 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
 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’.
 
 \1f
 File: gnorb.info,  Node: Viewing Tracked Messages in *Summary* Buffers,  Next: Hinting in Gnus,  Prev: Trigger Actions,  Up: Email Tracking
 
 rearrange or delete existing actions, and add your own: see the
 docstring of ‘gnorb-org-trigger-actions’.
 
 \1f
 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
-showing all the messages associated with that heading (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 ‘gnorb-summary-disassociate-message’ (“C-c
-d”) to disassociate the message with the Org heading.
+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.
+
+   If you call ‘gnorb-org-view’ with a prefix argument, the search group
+will be made persistent across Gnus sessions.  You can re-run the search
+and update the group contents by hitting “M-g” on the group in the Gnus
+*Group* buffer.

 
    As a bonus, it’s possible to go into Gnus’ *Server* buffer, find the
 line specifying your nngnorb server, and hit “G” (aka
 
    As a bonus, it’s possible to go into Gnus’ *Server* buffer, find the
 line specifying your nngnorb server, and hit “G” (aka


@@ -263,7 +310,7 @@ linked messages.  This is dog-slow at the moment; it will get faster.
 \1f
 File: gnorb.info,  Node: Hinting in Gnus,  Next: Message Attachments,  Prev: Viewing Tracked Messages in *Summary* Buffers,  Up: Email Tracking
 
 \1f
 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,
 ===================
 
 When you receive new mails that might be relevant to existing Org TODOs,


@@ -273,18 +320,19 @@ display a message in the minibuffer when opening potentially relevant
 messages.  You can then use ‘gnorb-gnus-incoming-to-todo’ to trigger an
 action on the relevant TODO.
 
 messages.  You can then use ‘gnorb-gnus-incoming-to-todo’ to trigger an
 action on the relevant TODO.
 

-   This hinting can happen in the Gnus summary buffer as well.  If you
-use the escape indicated by ‘gnorb-gnus-summary-mark-format-letter” as
-part of your ‘gnus-summary-line-format’, articles that are relevant to
-TODOs will be marked with a special character in the Summary buffer, as
-determined by ‘gnorb-gnus-summary-mark’.  By default, the format letter
-is “g” (meaning it is used as “%ug” in the format line), and the mark is
-“¡”.
+   This hinting can happen in the Gnus summary buffer as well. If you
+use the escape indicated by ‘gnorb-gnus-summary-mark-format-letter’ as
+part of your ‘gnus-summary-line-format’, articles that may be relevant
+to TODOs will be marked with a special character in the Summary
+buffer, as determined by ‘gnorb-gnus-summary-mark’. By default, the
+format letter is “g” (meaning it is used as “%ug” in the format line),
+and the mark is “&” for messages that are already tracked, and “¡” for
+messages that may be relevant.

 
 \1f
 
 \1f

-File: gnorb.info,  Node: Message Attachments,  Next: Likely Workflow,  Prev: Hinting in Gnus,  Up: Email Tracking
+File: gnorb.info,  Node: Message Attachments,  Next: Registry Usage,  Prev: Hinting in Gnus,  Up: Email Tracking

 
 

-4.5 Message Attachments
+4.6 Message Attachments

 =======================
 
 Gnorb simplifies the handling of attachments that you receive in emails.
 =======================
 
 Gnorb simplifies the handling of attachments that you receive in emails.


@@ -309,9 +357,21 @@ attach the files in the heading’s org-attach directory to the outgoing
 message.
 
 \1f
 message.
 
 \1f

-File: gnorb.info,  Node: Likely Workflow,  Prev: Message Attachments,  Up: Email Tracking
+File: gnorb.info,  Node: Registry Usage,  Next: Likely Workflow,  Prev: Message Attachments,  Up: Email Tracking
+
+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 much of the registry you’re using, and offering keybindings
+for ‘gnorb-flush-dead-associations’, to help Gnorb clean up after
+itself.
+
+\1f
+File: gnorb.info,  Node: Likely Workflow,  Prev: Registry Usage,  Up: Email Tracking

 
 

-4.6 Likely Workflow
+4.8 Likely Workflow

 ===================
 
 You receive an email from Jimmy, who wants to rent a room in your house.
 ===================
 
 You receive an email from Jimmy, who wants to rent a room in your house.


@@ -635,9 +695,13 @@ File: gnorb.info,  Node: User Optionsxx,  Prev: Viewing Org headlines relevant t
      relevant to Org TODOs.  Defaults to “g”, meaning it should be used
      as “%ug” in the format line.
 ‘`gnorb-gnus-summary-mark'’
      relevant to Org TODOs.  Defaults to “g”, meaning it should be used
      as “%ug” in the format line.
 ‘`gnorb-gnus-summary-mark'’

-     The mark used to indicate relevant messages in the Summary buffer,
-     when ‘gnorb-gnus-summary-mark-format-letter’ is present in the
-     format line.  Defaults to “¡”.
+     The mark used to indicate potentially relevant messages in the
+     Summary buffer, when ‘gnorb-gnus-summary-mark-format-letter’ is
+     present in the format line.  Defaults to “¡”.
+‘`gnorb-gnus-summary-tracked-mark'’
+     The mark used to indicate already-tracked messages in the Summary
+     buffer, when ‘gnorb-gnus-summary-mark-format-letter’ is present in
+     the format line.  Defaults to “&”.

 
 \1f
 File: gnorb.info,  Node: Suggested Keybindings,  Prev: Misc Gnus,  Up: Top
 
 \1f
 File: gnorb.info,  Node: Suggested Keybindings,  Prev: Misc Gnus,  Up: Top


@@ -662,8 +726,9 @@ 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"
           (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)
-                    (org-defkey org-agenda-mode-map (kbd "V") 'gnorb-org-popup-bbdb)))))
+            '(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)))))

 
      (eval-after-load "gnorb-gnus"
        '(progn
 
      (eval-after-load "gnorb-gnus"
        '(progn


@@ -692,31 +757,33 @@ File: gnorb.info,  Node: Suggested Keybindings,  Prev: Misc Gnus,  Up: Top
 \1f
 Tag Table:
 Node: Top\7f194
 \1f
 Tag Table:
 Node: Top\7f194

-Node: Introduction\7f1009
-Node: Installation\7f2118
-Node: Setup\7f2532
-Node: Email Tracking\7f3899
-Node: Email-Related Commands\7f5430
-Node: Trigger Actions\7f8440
-Node: Viewing Tracked Messages in *Summary* Buffers\7f9289
-Node: Hinting in Gnus\7f10523
-Node: Message Attachments\7f11531
-Node: Likely Workflow\7f12713
-Node: Restoring Window Layout\7f15518
-Node: Recent Mails From BBDB Contacts\7f15882
-Node: BBDB posting styles\7f16878
-Node: BBDB Org tagging\7f17794
-Node: Misc BBDB\7f18540
-Node: Searching for messages from BBDB contacts\7f18753
-Node: Citing BBDB contacts\7f19199
-Node: User Options\7f19520
-Node: Misc Org\7f21059
-Node: Inserting BBDB links\7f21234
-Node: User Optionsx\7f21489
-Node: Misc Gnus\7f24226
-Node: Viewing Org headlines relevant to a message\7f24439
-Node: User Optionsxx\7f24754
-Node: Suggested Keybindings\7f27518
+Node: Introduction\7f1044
+Node: Installation\7f2153
+Node: Setup\7f2567
+Node: Email Tracking\7f3934
+Node: Basic Usage\7f5544
+Node: Email-Related Commands\7f6617
+Node: Trigger Actions\7f10112
+Node: Viewing Tracked Messages in *Summary* Buffers\7f11064
+Node: Hinting in Gnus\7f12551
+Node: Message Attachments\7f13647
+Node: Registry Usage\7f14828
+Node: Likely Workflow\7f15279
+Node: Restoring Window Layout\7f18079
+Node: Recent Mails From BBDB Contacts\7f18443
+Node: BBDB posting styles\7f19439
+Node: BBDB Org tagging\7f20355
+Node: Misc BBDB\7f21101
+Node: Searching for messages from BBDB contacts\7f21314
+Node: Citing BBDB contacts\7f21760
+Node: User Options\7f22081
+Node: Misc Org\7f23620
+Node: Inserting BBDB links\7f23795
+Node: User Optionsx\7f24050
+Node: Misc Gnus\7f26787
+Node: Viewing Org headlines relevant to a message\7f27000
+Node: User Optionsxx\7f27315
+Node: Suggested Keybindings\7f30322

 \1f
 End Tag Table
 
 \1f
 End Tag Table