True offline reading using slrn and slrnpull ============================================ This README describes how you can use slrn and slrnpull for "true offline reading", i.e. getting only the article headers first and selecting the article bodies you want to download. Support for this is new in slrn 0.9.8.0, so please report any problems you may experience with this feature. Support in slrnpull: -------------------- The group entries in slrnpull.conf now may have a fourth field that indicates if you want to use true offline reading for that group. If you set it to 1, slrnpull will fetch only the headers of the new articles it would otherwise retrieve completely. slrnpull also has two new command-line switch connected with true offline reading: --fetch-score SCORE Tells slrnpull to fetch article bodies if the corresponding header is assigned a score value of at least SCORE, even if true offline reading is used for that group. --marked-bodies Tells slrnpull to fetch only the article bodies that were marked for download within slrn (see next section on how to do that). slrnpull also does this when run without this switch; specifying --marked-bodies simply keeps it from checking for new articles. Note: If you didn't fetch the body of an article and it is no longer available on the server, slrnpull expires it even if it has not reached the age specified in slrnpull.conf. This makes sense, because it's no longer possible to download this article's body anyway. Support in slrn: ---------------- When run in spool mode, slrn will display whether or not the body of an article is present and whether or not you have requested it for download. In header_display_format the new %B escape is used for this. If you don't want to customize header_display_format, you don't need to worry about this. If the body of an article is missing, %B (in the default setting: The sixth column from the left) displays a "H" (for "header only"); if the body is requested for download, it displays a "M" (for "marked"). In a collapsed thread, only some of the articles may be incomplete or marked. In this case, a "h" or "m" is shown ("m" takes precedence, i.e. you'll see it if at least one article body in the thread is marked for download). To mark a body for download, you can use the "request" function (by default bound to 'm'). If the body is already requested, the mark is removed; if the body is already present, this command has no effect. Note that articles that are marked for download cannot be marked read - I expect that you will want to see them again when their body is in place. When applied on a collapsed thread that has some marked articles in it and some that are incomplete, but not yet marked for download, the "request" function will mark all articles in it, rather than toggling the status of each individual article. In this case, you can apply the command a second time to un-mark all articles. If you just want to use the basic true offline functionality, this should be all you need to know. The following sections are for people who want to use advanced functionality and those who want to know what's going on behind the scenes when using this feature. Scoring on the body status: --------------------------- It is possible to score an article depending on whether or not its body is present. To do this, use the new "Has-Body" keyword described in score.txt. Intrinsic functions for true offline reading: --------------------------------------------- Currently, there are two new intrinsic functions connected with this feature: get_body_status and request_body. Both are described in detail in slrnfuns.txt How does the whole thing work? ------------------------------ You may want to read this section if you're a system administrator who wants to set up true offline reading on a multiple-user system or if you're just curious ;-) slrnpull creates a directory for the requests (it is called "requests" and a subdirectory of the slrnpull root directory). In this directory, each user has his own newsrc-style file where the article numbers of the requested bodies are kept. The name of each user's request file is his login name, so there shouldn't be any accidental clashes (at least on Unix-like systems; if no login name can be determined, the file is called "!unknown"). By default, slrn sets these files to mode 0640. This means that your request list cannot be modified by others. Of course, slrnpull needs to be able to read the request files. On multi-user systems, you should run the configure script with --enable-setgid-code to ensure this (see setgid.txt for details). Note that slrnpull does not write to the request files - slrn itself will notice when article bodies have been downloaded and prune the request list accordingly. To keep track of the articles that don't have bodies, slrnpull creates a file called ".headers" in each spool directory that has incomplete articles in it. Make sure that these files do not get deleted or corrupted - if an article is not listed there, slrn won't allow the users to request its body for download; on the other hand, if that file lists a complete article, its body can get requested (and appended) again! Since version 0.9.8.0, slrnpull also creates files called ".servermin" in each spool directory - they only contain the server's low water mark that got reported for that group the last time slrnpull checked for new articles. This information is used to expire articles without body that are no longer available on the server - slrnpull does not connect to the server when run in expiry mode.