Merge commit 'b45fc3f6c0802be172c4e887d1cea268ce7866e0' from swiper

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

diff --git a/packages/gnorb/gnorb.org b/packages/gnorb/gnorb.org
index e19422d874bb5d1c3433b621f7b300e700be3c80..58b03658a910e4f3672fd8c9d56962379a5084be 100644 (file)
--- a/packages/gnorb/gnorb.org
+++ b/packages/gnorb/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
 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:
 
 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.
 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.
 
 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:
 
 ** Email-Related Commands
 Email tracking starts in one of three ways:
 


@@ -94,11 +117,14 @@ There are three main email-related commands:
 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
 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 arg), Gnorb
+   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.
    will look for mailto: or bbdb: links in the heading, and compose a
    new message to them.

+
+   Calling the function with a double prefix arg will ignore all
+   associated messages and links, and compose a blank message.

    
    

-   The sent message will be associated with the Org heading, and
+   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.
    


@@ -106,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
    `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.


@@ -134,31 +160,45 @@ 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
 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.

 ** 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
 ** 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
+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
 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:
 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 (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.
 
 `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
 `gnus-group-make-nnir-group'). At the query prompt, enter an Org-style
 As a bonus, it's possible to go into Gnus' *Server* buffer, find the
 line specifying your nngnorb server, and hit "G" (aka
 `gnus-group-make-nnir-group'). At the query prompt, enter an Org-style


@@ -179,11 +219,12 @@ 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
 
 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 "¡".
+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.

 ** Message Attachments
 :PROPERTIES:
 :END:
 ** Message Attachments
 :PROPERTIES:
 :END:


@@ -207,6 +248,12 @@ The same process works in reverse: when you send a message from an Org
 heading using `gnorb-org-handle-mail', Gnorb will ask if you want to
 attach the files in the heading's org-attach directory to the outgoing
 message.
 heading using `gnorb-org-handle-mail', Gnorb will ask if you want to
 attach the files in the heading's org-attach directory to the outgoing
 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 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.
 ** 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.


@@ -437,10 +484,14 @@ heading to jump to that heading.
      use as part of your `gnus-summary-line-format', to indicate
      messages which might be relevant to Org TODOs. Defaults to "g",
      meaning it should be used as "%ug" in the format line.
      use as part of your `gnus-summary-line-format', to indicate
      messages which might be 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' :: 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-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 "&".

 * Suggested Keybindings
 :PROPERTIES:
 :ID:       de1b2579-86c2-4bb1-b77e-3467a3d2b3c7
 * Suggested Keybindings
 :PROPERTIES:
 :ID:       de1b2579-86c2-4bb1-b77e-3467a3d2b3c7


@@ -463,8 +514,9 @@ 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"
        (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