Update.
[elisp/gnus.git-] / README-offline.en
1 1) What's "gnus-offline (Gnus Offline Backend Utility)" ?
2 =========================================================
3
4 This program is a utility for Semi-gnus that handles messages
5 (i.e. mail and news) in the "offline" state in a more simple way.
6
7 It is basically designed for "gnus-agent". (See info about gnus-agent.)
8
9 You can also use it with a function "nnspool"(*1) (which needs an
10 external program such as "gnspool"(*2) ), or with "miee.el"(*3) for
11 posting and/or sending messages.
12
13      (*1) See info about nnspool.
14      (*2) gnspool comes with a newsreader "gn".
15      (*3) The latest version of miee.el (or MIEE) is available at
16           http://www.shiojiri.ne.jp/%7Et-ichi/meadow.html
17
18 You can handle messages in the offline state without "gnus-offline",
19 but "gnus-offline" provides a simple way for setup and operation.
20
21 **Features**
22
23 o Simple configuration -- An "INTERACTIVE" configuration to set
24          the variables.
25
26 o Simple operation -- Type "g" in the *Group* buffer, and gnus-offline 
27          will:
28            o Dial (*)
29            o Send mails & post news articles
30            o Fetch new mails & articles
31            o Hang up (*)
32
33       (*) For dialing and hanging up, external softwares are needed.
34           But you can do without ones if you connect and disconnect
35           manually.
36
37 This document is written mainly for the case using "gnus-agent" with
38 gnus-offline.el bundled in T-gnus 6.10.056 or later, and Semi-gnus
39 6.10.1 or later. (*)
40
41       (*) T-gnus is based on the latest test version of Gnus. It is
42           called Pterodactyl Gnus or pGnus.
43           Most versions of Semi-gnus other than T-gnus are based on
44           Gnus version 5.6.xx.
45           There are a lot of changes between Gnus 5.6.xx and pGnus.
46           This document will refer to the differences caused by the
47           changes when it is important.
48
49 2) Installation
50 ===============
51
52 As you are reading this document, this version of Semi-gnus includes
53 gnus-offline. Installation is simple. "make install" will
54 automatically install "gnus-offline".
55
56 If the Semi-gnus comes without gnus-offline, or you want to install
57 the latest version of gnus-offline, you may manually byte-compile
58 "gnus-offline.el" and "gnus-ofsetup.el". Make sure they are in one of
59 the `load-path' directories. 
60
61 3) How to use
62 =============
63
64 o First, you must do a general setup for Semi-gnus (See info about the 
65  setup).
66
67 o Add the following code to ~/.emacs
68
69         (load "gnus-ofsetup")
70         (gnus-setup-for-offline)
71         (load gnus-offline-setting-file)
72
73 o Add the following code to ~/.gnus
74
75         (gnus-agentize)
76
77 o Restart Emacs. gnus-ofsetup.el will ask you some questions and
78  create ~/.gnus-offline.el. (*)
79
80       (*) If you don't know how to answer some questions, typing "TAB"
81           key may show you the possible answers. See the next section
82           which explains the user options.
83           You will also be asked whether to save the POP password in
84           ~/.newsrc.eld or not. Answer it carefully. See section 6)
85           for details.
86
87 o At the first time, you must start Gnus in the "online" state and
88  decide which groups to subscribe (See info about subscribing).
89
90 o Add the following code to ~/.gnus
91
92         (gnus-agent-toggle-plugged nil)
93
94 That's all. Restart Gnus and try typing "g" in the *Group* buffer.
95
96 ***Note***
97
98 Most versions of Semi-gnus have pop3-fma.el to operate multiple POP
99 accounts. T-gnus 6.10.56 or later does not because it can handle
100 multiple POP accounts itself.
101
102 <<<<<ATTENTION!!>>>>>
103 T-gnus 6.10.56 or later doesn't contain "pop3-fma.el". If you are
104 updating to T-gnus 6.10.56 or later, remove the setting for
105 pop3-fma.el (or simply, delete the old ~/.gnus-offline.el).
106
107 [Semi-gnus with pop3-fma.el]
108 o pop3-fma-spool-file-alist 
109 \e$B!!!!!!!!\e(B'(
110         ("po:account1@pop-server1" pass) 
111         ("po:account2@pop-server2" pass) 
112         :
113         :
114         ))
115 o pop3-fma-movemail-type 
116       use movemail.exe ('exe) or pop3.el('lisp) 
117
118 [T-gnus 6.10.56 or later]
119
120 o gnus-offline-mail-source 
121         '(
122         (pop :user "manbou" :server "pop.ceres.dti.ne.jp")
123         (pop :user "imp9397" :server "mvb.biglobe.ne.jp")
124         :
125         :
126         ) 
127
128
129 4) User customizable variables in gnus-offline
130 ==============================================
131
132 o gnus-offline-dialup-program  
133     Program name to dialup.
134
135 o gnus-offline-dialup-program-arguments
136     List of dialup program arguments.
137
138 o gnus-offline-hangup-program
139     Program name to hangup.
140
141 o gnus-offline-hangup-program-arguments
142     List of hangup program arguments.
143
144 o gnus-offline-mail-spool-directory
145     Spool directory for sending mail.
146     This variable is available only using MIEE.
147
148 o gnus-offline-news-spool-directory
149     Spool directory for sending news.
150     This variable is available only using MIEE.
151
152 o gnus-offline-mail-treat-environ
153     If t , gnus-offline sends mail to spool first.
154     If nil , gnus-offline sends mail immediately.
155
156 o gnus-offline-articles-to-fetch
157     Article type you want to fetch.
158
159        'both ... Fetch both Mail/News.
160        'Mail ... Fetch only Mail.
161        'News ... Fetch only News.
162
163     Default value is both.
164
165 o gnus-offline-load-hook
166     Hook before gnus-offline load.
167
168 o gnus-offline-before-online-hook
169     Hook before all online jobs.
170
171 o gnus-offline-after-online-hook
172     Hook after all online jobs.
173
174 o gnus-offline-interval-time
175     Interval time to do all online jobs.(minutes)
176
177 o gnus-offline-MTA-type
178     MTA type to sending mail.
179
180    'smtp     ... Use smtp.el.
181    'sendmail ... Use sendmail.el.
182
183 o gnus-offline-drafts-queue-type
184    Message queue type when spooling message.
185    
186    'miee  ... Use miee.el.
187    'agent ... Use gnus-agent.el.
188
189 o gnus-offline-after-empting-spool-hook
190    Hook before empting spool.
191
192 o gnus-offline-before-empting-spool-hook
193    Hook after emoting spool.
194
195 o gnus-offline-dialup-function
196    Function to dialup.
197
198 o gnus-offline-hangup-function
199    Function to hangup.
200
201 o gnus-offline-pop-password-file 
202    File name to save username , mailserver and password.
203
204 o gnus-offline-pop-password-decoding-function 
205    Function to decode password.
206
207 5) Commands in gnus-offline
208 ===========================
209
210 o M-x gnus-offline-toggle-plugged
211    Toggle offline/online state.
212
213 o M-x gnus-offline-toggle-auto-hangup
214    Change current state to offline.
215
216 o M-x gnus-offline-toggle-on/off-send-mail
217    Toggle method to sending mail.
218
219 o M-x gnus-offline-toggle-articles-to-fetch
220    Toggle articles you want to fetch.
221
222 o M-x gnus-offline-toggle-movemail-program
223    Toggle movemail program.
224
225 o M-x gnus-offline-set-interval-time
226    Set interval time(minute) to fetch article.
227
228 o M-x gnus-offline-agent-expire
229    Expire articles.
230
231 6) [!!!IMPORTANT!!!] About the pop password
232 ===========================================
233
234 <<<<<ATTENTION!!>>>>>
235 T-gnus 6.10.56 or later doesn't contain "pop3-fma.el". If you are
236 updating to T-gnus 6.10.56 or later, remove the setting for
237 pop3-fma.el (or simply, delete the old ~/.gnus-offline.el).
238
239 Under Semi-gnus with pop3-fma.el, you must enter the password for the
240 pop server every time you accesses the server. (We recommend you do
241 it.)
242
243 If your machine is stand alone, and nobody else uses it, you can save
244 the password in some ways. (But, on your own responsibility!)
245
246 ---
247
248 One way is provided by gnus-ofsetup.el. At the first interactive
249 configuration, it will ask you whether to save the password in
250 ~/.newsrc.eld or not. When you answer "y" to this question, the
251 password will be saved in ~/.newsrc.eld. (*)
252
253        (*) Actually the following will be added to ~/.gnus-offline.el.
254
255            [Semi-gnus with pop3-fma.el]
256
257             (add-hook 'gnus-setup-news-hook 
258              (lambda ()
259               (setq pop3-fma-save-password-information t)
260               (add-to-list 'gnus-variable-list 'pop3-fma-password)))
261
262            [T-gnus 6.10.56 or later]
263
264             (add-hook 'gnus-setup-news-hook 
265              (lambda ()
266               (add-to-list 'gnus-variable-list 'mail-source-password-cache)))
267
268 Answer this question carefully, because the password will NOT be
269 encoded!
270
271 ---
272
273 There is another way. It will not save the password in a file but keep
274 it in the memory as a variable.
275
276 For Semi-gnus with pop3-fma.el, add the following code in
277 ~/.gnus-offline.el.
278
279          (setq pop3-fma-save-password-information t)
280
281 In this way, once you enter the password at the startup of Gnus, it
282 will be kept as a variable `pop3-fma-password' until you quit Gnus.
283
284 Under T-gnus 6.10.56 or later, the password will be kept as a variable
285 `mail-source-password-cache' by default.