X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/485abbbdf8c2ae2a053512b259a59a5c0714fb6d..be54382cca73c2a64f3bd2720a2332649541bbd5:/packages/gnorb/gnorb.info diff --git a/packages/gnorb/gnorb.info b/packages/gnorb/gnorb.info index 08085e10a..52ca07270 100644 --- a/packages/gnorb/gnorb.info +++ b/packages/gnorb/gnorb.info @@ -30,11 +30,13 @@ Gnorb Manual Email Tracking +* Basic Usage:: * Email-Related Commands:: * Trigger Actions:: * Viewing Tracked Messages in *Summary* Buffers:: * Hinting in Gnus:: * Message Attachments:: +* Registry Usage:: * 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 -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:: * Hinting in Gnus:: * Message Attachments:: +* Registry Usage:: * 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: @@ -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 - 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. - 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. @@ -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 - 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. @@ -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 -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.  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 -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 @@ -263,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, @@ -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. - 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.  -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. @@ -309,9 +357,21 @@ attach the files in the heading’s org-attach directory to the outgoing message.  -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. + + +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. @@ -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'’ - 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 “&”.  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" - '(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 @@ -692,31 +757,33 @@ File: gnorb.info, Node: Suggested Keybindings, Prev: Misc Gnus, Up: Top  Tag Table: Node: Top194 -Node: Introduction1009 -Node: Installation2118 -Node: Setup2532 -Node: Email Tracking3899 -Node: Email-Related Commands5430 -Node: Trigger Actions8440 -Node: Viewing Tracked Messages in *Summary* Buffers9289 -Node: Hinting in Gnus10523 -Node: Message Attachments11531 -Node: Likely Workflow12713 -Node: Restoring Window Layout15518 -Node: Recent Mails From BBDB Contacts15882 -Node: BBDB posting styles16878 -Node: BBDB Org tagging17794 -Node: Misc BBDB18540 -Node: Searching for messages from BBDB contacts18753 -Node: Citing BBDB contacts19199 -Node: User Options19520 -Node: Misc Org21059 -Node: Inserting BBDB links21234 -Node: User Optionsx21489 -Node: Misc Gnus24226 -Node: Viewing Org headlines relevant to a message24439 -Node: User Optionsxx24754 -Node: Suggested Keybindings27518 +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