read at least RFC2045 and RFC2047.
@menu
+* Interface Functions:: An abstraction over the basic functions.
* Basic Functions:: Utility and basic parsing functions.
* Decoding and Viewing:: A framework for decoding and viewing.
+* Standards:: A summary of RFCs and working documents used.
* Index:: Function and variable index.
@end menu
-@node Basic Functions
-@chapter Basic Functions
+@node Interface Functions
+@chapter Interface Functions
+@cindex interface functions
+@cindex mail-parse
-This chapter describes the basic, ground-level functions for parsing and
-handling. Covered here is parsing @code{From} lines, removing comments
-from header lines, decoding encoded words, parsing date headers and so
-on. High-level functionality is dealt with in the next chapter
-(@pxref{Decoding and Viewing}).
-
-@menu
-* mail-parse:: The generalized @sc{mime} and mail interface.
-* rfc2231:: Parsing @code{Content-Type} headers.
-* drums:: Handling mail headers defined by RFC822bis.
-* rfc2047:: En/decoding encoded words in headers.
-* time-date:: Functions for parsing dates and manipulating time.
-* qp:: Quoted-Printable en/decoding.
-* base64:: Base64 en/decoding.
-* mailcap:: How parts are displayed is specified by the @file{.mailcap} file
-@end menu
-
-
-@node mail-parse
-@section mail-parse
-
-It is perhaps misleading to place the @code{mail-parse} library in this
-chapter. It is not a basic low-level library---rather, it is an
-abstraction over the actual low-level libraries that are described in the
-subsequent sections.
+The @code{mail-parse} library is an abstraction over the actual
+low-level libraries that are described in the next chapter.
Standards change, and so programs have to change to fit in the new
mold. For instance, RFC2045 describes a syntax for the
@example
(mail-header-parse-content-type
"image/gif; name=\"b980912.gif\"")
-=> ("image/gif" (name . "b980912.gif"))
+@result{} ("image/gif" (name . "b980912.gif"))
@end example
@item mail-header-parse-content-disposition
@example
(mail-content-type-get
'("image/gif" (name . "b980912.gif")) 'name)
-=> "b980912.gif"
+@result{} "b980912.gif"
@end example
@item mail-header-remove-comments
@example
(mail-header-remove-comments
"Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
-=> "Gnus/5.070027 "
+@result{} "Gnus/5.070027 "
@end example
@item mail-header-remove-whitespace
@example
(mail-header-remove-whitespace
"image/gif; name=\"Name with spaces\"")
-=> "image/gif;name=\"Name with spaces\""
+@result{} "image/gif;name=\"Name with spaces\""
@end example
@item mail-header-get-comment
@example
(mail-header-get-comment
"Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
-=> "Finnish Landrace"
+@result{} "Finnish Landrace"
@end example
@item mail-header-parse-address
@example
(mail-header-parse-address
"Hrvoje Niksic <hniksic@@srce.hr>")
-=> ("hniksic@@srce.hr" . "Hrvoje Niksic")
+@result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
@end example
@item mail-header-parse-addresses
@example
(mail-header-parse-addresses
"Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
-=> (("hniksic@@srce.hr" . "Hrvoje Niksic")
+@result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
("sb@@metis.no" . "Steinar Bang"))
@end example
@example
(mail-encode-encoded-word-string
"This is naïve, baby")
-=> "This is =?iso-8859-1?q?na=EFve,?= baby"
+@result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
@end example
@item mail-decode-encoded-word-region
@example
(mail-decode-encoded-word-string
"This is =?iso-8859-1?q?na=EFve,?= baby")
-=> "This is naïve, baby"
+@result{} "This is naïve, baby"
@end example
@end table
-Currently, @code{mail-parse} is an abstraction over @code{drums},
+Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
@code{rfc2047} and @code{rfc2231}. These are documented in the
subsequent sections.
+
+@node Basic Functions
+@chapter Basic Functions
+
+This chapter describes the basic, ground-level functions for parsing and
+handling. Covered here is parsing @code{From} lines, removing comments
+from header lines, decoding encoded words, parsing date headers and so
+on. High-level functionality is dealt with in the next chapter
+(@pxref{Decoding and Viewing}).
+
+@menu
+* rfc2231:: Parsing @code{Content-Type} headers.
+* ietf-drums:: Handling mail headers defined by RFC822bis.
+* rfc2047:: En/decoding encoded words in headers.
+* time-date:: Functions for parsing dates and manipulating time.
+* qp:: Quoted-Printable en/decoding.
+* base64:: Base64 en/decoding.
+* binhex:: Binhex decoding.
+* uudecode:: Uuencode decoding.
+* rfc1843:: Decoding HZ-encoded text.
+* mailcap:: How parts are displayed is specified by the @file{.mailcap} file
+@end menu
+
+
@node rfc2231
@section rfc2231
title*0*=us-ascii'en'This%20is%20even%20more%20;
title*1*=%2A%2A%2Afun%2A%2A%2A%20;
title*2=\"isn't it!\"")
-=> ("application/x-stuff"
+@result{} ("application/x-stuff"
(title . "This is even more ***fun*** isn't it!"))
@end example
@end table
-@node drums
-@section drums
+@node ietf-drums
+@section ietf-drums
@dfn{drums} is an IETF working group that is working on the replacement
for RFC822.
The functions provided by this library include:
@table @code
-@item drums-remove-comments
-@findex drums-remove-comments
+@item ietf-drums-remove-comments
+@findex ietf-drums-remove-comments
Remove the comments from the argument and return the results.
-@item drums-remove-whitespace
-@findex drums-remove-whitespace
+@item ietf-drums-remove-whitespace
+@findex ietf-drums-remove-whitespace
Remove linear white space from the string and return the results.
Spaces inside quoted strings and comments are left untouched.
-@item drums-get-comment
-@findex drums-get-comment
+@item ietf-drums-get-comment
+@findex ietf-drums-get-comment
Return the last most comment from the string.
-@item drums-parse-address
-@findex drums-parse-address
+@item ietf-drums-parse-address
+@findex ietf-drums-parse-address
Parse an address string and return a list that contains the mailbox and
the plain text name.
-@item drums-parse-addresses
-@findex drums-parse-addresses
+@item ietf-drums-parse-addresses
+@findex ietf-drums-parse-addresses
Parse a string that contains any number of comma-separated addresses and
return a list that contains mailbox/plain text pairs.
-@item drums-parse-date
-@findex drums-parse-date
+@item ietf-drums-parse-date
+@findex ietf-drums-parse-date
Parse a date string and return an Emacs time structure.
-@item drums-narrow-to-header
-@findex drums-narrow-to-header
+@item ietf-drums-narrow-to-header
+@findex ietf-drums-narrow-to-header
Narrow the buffer to the header section of the current buffer.
@end table
and manipulating time. (Not by using tesseracts, though, I'm sorry to
say.)
-These functions converts between five formats: A date string, an Emacs
+These functions convert between five formats: A date string, an Emacs
time structure, a decoded time list, a second number, and a day number.
The functions have quite self-explanatory names, so the following just
@example
(parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
-=> (54 21 12 12 9 1998 6 nil 7200)
+@result{} (54 21 12 12 9 1998 6 nil 7200)
(date-to-time "Sat Sep 12 12:21:54 1998 +0200")
-=> (13818 19266)
+@result{} (13818 19266)
(time-to-seconds '(13818 19266))
-=> 905595714.0
+@result{} 905595714.0
(seconds-to-time 905595714.0)
-=> (13818 19266 0)
+@result{} (13818 19266 0)
(time-to-day '(13818 19266))
-=> 729644
+@result{} 729644
(days-to-time 729644)
-=> (961933 65536)
+@result{} (961933 65536)
(time-since '(13818 19266))
-=> (0 430)
+@result{} (0 430)
(time-less-p '(13818 19266) '(13818 19145))
-=> nil
+@result{} nil
(subtract-time '(13818 19266) '(13818 19145))
-=> (0 121)
+@result{} (0 121)
(days-between "Sat Sep 12 12:21:54 1998 +0200"
"Sat Sep 07 12:21:54 1998 +0200")
-=> 5
+@result{} 5
(date-leap-year-p 2000)
-=> t
+@result{} t
(time-to-day-in-year '(13818 19266))
-=> 255
+@result{} 255
@end example
@node base64
@section base64
+@cindex base64
Base64 is an encoding that encodes three bytes into four characters,
thereby increasing the size by about 33%. The alphabet used for
@end table
+@node binhex
+@section binhex
+@cindex binhex
+@cindex Apple
+@cindex Macintosh
+
+@code{binhex} is an encoding that originated in Macintosh environments.
+The following function is supplied to deal with these:
+
+@table @code
+@item binhex-decode-region
+@findex binhex-decode-region
+Decode the encoded text in the region. If given a third parameter, only
+decode the @code{binhex} header and return the filename.
+
+@end table
+
+
+@node uudecode
+@section uudecode
+@cindex uuencode
+@cindex uudecode
+
+@code{uuencode} is probably still the most popular encoding of binaries
+used on Usenet, although @code{base64} rules the mail world.
+
+The following function is supplied by this package:
+
+@table @code
+@item uudecode-decode-region
+@findex uudecode-decode-region
+Decode the text in the region.
+@end table
+
+
+@node rfc1843
+@section rfc1843
+@cindex rfc1843
+@cindex HZ
+@cindex Chinese
+
+RFC1843 deals with mixing Chinese and ASCII characters in messages. In
+essence, RFC1843 switches between ASCII and Chinese by doing this:
+
+@example
+This sentence is in ASCII.
+The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
+@end example
+
+Simple enough, and widely used in China.
+
+The following functions are available to handle this encoding:
+
+@table @code
+@item rfc1843-decode-region
+Decode HZ-encoded text in the region.
+
+@item rfc1843-decode-string
+Decode a HZ-encoded string and return the result.
+
+@end table
+
+
@node mailcap
@section mailcap
Here's an example file:
@example
-image/*; xv -8 %s
-audio/x-pn-realaudio; rvplayer %s
+image/*; gimp -8 %s
+audio/wav; wavplayer %s
@end example
This says that all image files should be displayed with @samp{xv}, and
@end table
+@node Standards
+@chapter Standards
+
+The Emacs @sc{mime} library implements handling of various elements
+according to a (somewhat) large number of RFCs, drafts and standards
+documents. This chapter lists the relevant ones. They can all be
+fetched from @samp{http://www.stud.ifi.uio.no/~larsi/notes/}.
+
+@table @dfn
+@item RFC822
+@itemx STD11
+Standard for the Format of ARPA Internet Text Messages.
+
+@item RFC1036
+Standard for Interchange of USENET Messages
+
+@item RFC2045
+Format of Internet Message Bodies
+
+@item RFC2046
+Media Types
+
+@item RFC2047
+Message Header Extensions for Non-ASCII Text
+
+@item RFC2048
+Registration Procedures
+
+@item RFC2049
+Conformance Criteria and Examples
+
+@item RFC2231
+MIME Parameter Value and Encoded Word Extensions: Character Sets,
+Languages, and Continuations
+
+@item RFC1843
+HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
+ASCII characters
+
+@item draft-ietf-drums-msg-fmt-05.txt
+Draft for the successor of RFC822
+
+@item RFC1892
+The Multipart/Report Content Type for the Reporting of Mail System
+Administrative Messages
+
+@end table
+
@node Index
@chapter Index
\input texinfo @c -*-texinfo-*-
@setfilename gnus
-@settitle Semi-gnus 6.10.023 Manual
+@settitle Semi-gnus 6.10.024 Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@tex
@titlepage
-@title Semi-gnus 6.10.023 Manual
+@title Semi-gnus 6.10.024 Manual
@author by Lars Magne Ingebrigtsen
@page
API. So Semi-gnus does not discriminate various language communities.
Oh, if you are a Klingon, please wait Unicode Next Generation.
-This manual corresponds to Semi-gnus 6.10.023.
+This manual corresponds to Semi-gnus 6.10.024.
@end ifinfo
gnus-group-clear-data-on-native-groups} command to clear out all data
that you have on your native groups. Use with caution.
+After changing servers, you @strong{must} move the cache hierarchy away,
+since the cached articles will have wrong article numbers, which will
+affect which articles Gnus thinks are read.
+
@node Startup Files
@section Startup Files
@item W d
@kindex W d (Summary)
@findex gnus-article-treat-dumbquotes
-Treat M******** sm*rtq**t*s (@code{gnus-article-treat-dumbquotes}).
+@vindex gnus-article-dumbquotes-map
+@cindex Smartquotes
+@cindex M******** sm*rtq**t*s
+@cindex Latin 1
+Treat M******** sm*rtq**t*s according to
+@code{gnus-article-dumbquotes-map}
+(@code{gnus-article-treat-dumbquotes}).
@item W w
@kindex W w (Summary)
``right'' window configuration, you can set
@code{gnus-always-force-window-configuration} to non-@code{nil}.
+If you're using tree displays (@pxref{Tree Display}), and the tree
+window is displayed vertically next to another window, you may also want
+to fiddle with @code{gnus-tree-minimize-window} to avoid having the
+windows resized.
+
@node Faces and Fonts
@section Faces and Fonts
new group parameter -- `post-to-server' that says to post
using the current server. Also a variable to do the same.
@item
- the slave dribble files should autosave to the slave file names.
+ the slave dribble files should auto-save to the slave file names.
@item
a group parameter that says what articles to display on group entry, based
on article marks.
add a way to select which NoCeM type to apply -- spam, troll, etc.
@item
- nndraft-request-group should tally autosave files.
+ nndraft-request-group should tally auto-save files.
@item
implement nntp-retry-on-break and nntp-command-timeout.
@lisp
(gnus-check-backend-function "request-scan" "nnml:misc")
-=> t
+@result{} t
@end lisp
@item gnus-read-method
There should be no result data from this function.
+@item (nnchoke-request-set-mark GROUP ACTION &optional SERVER)
+
+Set/remove/add marks on articles. Normally Gnus handles the article
+marks (such as read, ticked, expired etc) internally, and store them in
+@code{~/.newsrc.eld}. Some backends (such as IMAP) however carry all
+information about the articles on the server, so Gnus need to propagate
+the mark information to the server.
+
+ACTION is a list of mark setting requests, having this format:
+
+@example
+(RANGE ACTION MARK)
+@end example
+
+Range is a range of articles you wish to update marks on. Action is
+@code{set}, @code{add} or @code{del}, respectively used for removing all
+existing marks and setting them as specified, adding (preserving the
+marks not mentioned) mark and removing (preserving the marks not
+mentioned) marks. Mark is a list of marks; where each mark is a
+symbol. Currently used marks are @code{read}, @code{tick}, @code{reply},
+@code{expire}, @code{killed}, @code{dormant}, @code{save},
+@code{download} and @code{unsend}, but your backend should, if possible,
+not limit itself to theese.
+
+Given contradictory actions, the last action in the list should be the
+effective one. That is, if your action contains a request to add the
+@code{tick} mark on article 1 and, later in the list, a request to
+remove the mark on the same article, the mark should in fact be removed.
+
+An example action list:
+
+@example
+(((5 12 30) 'del '(tick))
+ ((10 . 90) 'add '(read expire))
+ ((92 94) 'del '(read)))
+@end example
+
+The function should return a range of articles it wasn't able to set the
+mark on (currently not used for anything).
+
+There should be no result data from this function.
+
@item (nnchoke-request-update-mark GROUP ARTICLE MARK)
If the user tries to set a mark that the backend doesn't like, this
second is a more complex one:
@example
-("no.group" 5 (1 . 54324))
+("no.group" 5 ((1 . 54324)))
("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
((tick (15 . 19)) (replied 3 6 (19 . 3)))
projects / elisp / gnus.git- / commitdiff