summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJeff Bailey <jbailey@gnu.org>1999-10-11 04:31:32 +0000
committerJeff Bailey <jbailey@gnu.org>1999-10-11 04:31:32 +0000
commit9b9fbddceb63fb10af572298fc0404f90384c7de (patch)
tree1e35ffd52567e745510f5f213fd06073a8ce33ae
parentbc54c260dd128f015450fe3a3aa9a9d6dd1877af (diff)
downloadmailutils-9b9fbddceb63fb10af572298fc0404f90384c7de.tar.gz
mailutils-9b9fbddceb63fb10af572298fc0404f90384c7de.tar.bz2
More libsrc/ to lib/ updates. Add doc/, add mailutils.texi, THANKS
-rw-r--r--ChangeLog13
-rw-r--r--Makefile.am2
-rw-r--r--THANKS9
-rw-r--r--configure.in2
-rw-r--r--doc/Makefile.am1
-rw-r--r--doc/mailutils.texi462
-rw-r--r--pop3d/Makefile.am2
7 files changed, 487 insertions, 4 deletions
diff --git a/ChangeLog b/ChangeLog
index 536561241..9214a0071 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,8 +1,19 @@
1999-10-10 Jeff Bailey <jbailey@cr499794-a.crdva1.bc.wave.home.com>
+ * THANKS: New file
+
+ * doc/mailutils.texi: New File
+ Provided by Alain Magloire <alainm@rcsm.ece.mcgill.ca> with some
+ changes so that Makeinfo reports no errors.
+
+ * doc/Makefile.am: New file
+
+ * configure.in: Deal with libsrc to lib rename
+
* pop3d/Makefile.am: Deal with libsrc to lib rename
- * Makefile.am: Deal with libsrc to lib rename
+ * Makefile.am: Deal with libsrc to lib rename.
+ Add reference to doc/ subdirectory.
* libsrc/: Rename to lib/
diff --git a/Makefile.am b/Makefile.am
index d6e480bb7..0eb121652 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,3 +1,3 @@
AUTOMAKE_OPTIONS = gnu 1.4
-SUBDIRS = lib libmailbox mail pop3d
+SUBDIRS = lib libmailbox mail pop3d doc
diff --git a/THANKS b/THANKS
new file mode 100644
index 000000000..96d39c32e
--- /dev/null
+++ b/THANKS
@@ -0,0 +1,9 @@
+GNU mailutils THANKS file
+
+GNU mailutils has originally been written by Jakob Kaivo, Jeff Bailey and
+Sean 'Shaleh' Perry. Many people further contributed to GNU mailutils by
+reporting problems, suggesting various improvements or submitting actual
+code. Here is a list of these people. Help us keep it complete and exempt
+of errors.
+
+Alain Magloire <alainm@rcsm.ece.mcgill.ca> \ No newline at end of file
diff --git a/configure.in b/configure.in
index 2099c6b66..5472654d4 100644
--- a/configure.in
+++ b/configure.in
@@ -52,5 +52,5 @@ AC_SUBST(AUTHLIBS)
dnl Output Makefiles
AC_OUTPUT(Makefile libmailbox/Makefile mail/Makefile pop3d/Makefile
- libsrc/Makefile)
+ lib/Makefile doc/Makefile)
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 000000000..31098482d
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1 @@
+info_TEXINFOS = mailutils.texi
diff --git a/doc/mailutils.texi b/doc/mailutils.texi
new file mode 100644
index 000000000..876790d76
--- /dev/null
+++ b/doc/mailutils.texi
@@ -0,0 +1,462 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename mailutils.info
+@settitle mailutils, Programming Manual
+@c %**end of header
+
+@c This file has the new style title page commands.
+@c Run `makeinfo' rather than `texinfo-format-buffer'.
+
+@c smallbook
+
+@c tex
+@c \overfullrule=0pt
+@c end tex
+
+@include version.texi
+
+@c Combine indices.
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+
+@defcodeindex op
+@syncodeindex op fn
+@syncodeindex vr fn
+
+@ifinfo
+@direntry
+* mailutils: (libmailutils). The GNU mailutils library API.
+@end direntry
+This file documents @sc{mailutils}, library API.
+
+
+Published by the Free Software Foundation,
+59 Temple Place - Suite 330
+Boston, MA 02111-1307, USA
+
+Copyright 1999 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Foundation.
+@end ifinfo
+
+@setchapternewpage off
+
+@titlepage
+@title mailutils, librairy API.
+@subtitle version @value{VERSION}, @value{UPDATED}
+@author Alain Magloire et al.
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1999 Free Software Foundation, Inc.
+
+@sp 2
+Published by the Free Software Foundation, @*
+59 Temple Place - Suite 330, @*
+Boston, MA 02111-1307, USA
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Foundation.
+
+@end titlepage
+@page
+
+
+@node Top, Introduction, (dir), (dir)
+@comment node-name, next, previous, up
+
+@ifinfo
+This document was produced for version @value{VERSION} of @sc{gnu}
+@sc{mailutils}.
+@end ifinfo
+
+@menu
+* Introduction:: GNU @sc{Mailutils} Programmer's manual.
+* Maildrop:: Creating a maildrop.
+* URL:: Unified Ressource Locator.
+* Maildrop Macros:: Maildrop Helper Macros.
+* Mailbox:: Mailbox API.
+* Mailbox Macros:: Mailbox Helper Macros.
+* Headers:: Headers API.
+* Headers Macros:: Header helper Macros.
+* Headers Parsed:: Alternatives for Headers.
+* Headers Regex:: ERE with Headers.
+* Mime:: Mime API.
+* Encoding:: Encoding API.
+* RFC1522:: RFC1522
+* Quoted Printable:: QP Encoding
+* Base64:: B64 Encoding
+* Reporting Bugs:: Reporting Bugs.
+* Acknowledgement:: Thanks and Credits.
+* Concept Index:: Topics in this manual.
+* Index:: All @sc{Mailutils} functions.
+@end menu
+
+@node Introduction, Maildrop, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+@cindex Introduction
+
+@sc{gnu} @sc{Mailutils} offers a general purpose library aimed to provide
+a rich set of functions for accessing different mail formats and maildrops.
+For example writing a simple from command that will list @var{From} and
+@var{Subject} of a folder.
+
+@example
+/* sfrom, Simple From */
+#include <stdio.h>
+#include <unistd.h>
+#include <string.h>
+#include <mailutils.h>
+
+#define MAILDIR "/usr/spool/mail"
+#define DATA_SIZE 4096
+
+int main (int argc, char ** argv)
+@{
+ char buffer[DATA_SIZE];
+ char * data;
+ maildrop_t mdrop;
+ mailbox_t mbox;
+ header_t rfc822;
+ int status, id, msg_no;
+ int size = DATA_SIZE;
+
+ if (argc == 2)
+ strncpy (buffer, argv[1], sizeof(buffer);
+ else
+ @{
+ char * maildir = getenv ("MAILDIR");
+ char * logname = getlogin();
+ snprintf (buffer, sizeof (buffer), "%s/%s",
+ (maildir) ? maildir : MAILDIR,
+ (logname) ? logname : "nobody");
+ @}
+
+ status = maildrop_create (&mdrop, NULL, buffer, 0);
+ if (status != 0)
+ @{
+ fprintf (stderr, "maildrop_create(%s), %s\n",
+ buffer, strerror(status));
+ exit (EXIT_FAILURE);
+ @}
+
+ maildrop_get_mailbox (mdrop, &mbox);
+
+ status = mailbox_open (mbox);
+ if (status != 0)
+ @{
+ fprintf (stderr, "mailbox_open(%s), %s\n",
+ buffer, strerror(status));
+ exit (EXIT_FAILURE);
+ @}
+
+ header_create (HEADER_RFC822 | HEADER_RFC1522, &rfc822);
+
+ data = xmalloc (size);
+
+ mailbox_stat (mbox, &msg_no, NULL);
+
+ for (id = 0; id < msg_no; id++)
+ @{
+ mailbox_get_header_size (mbox, id, &hd_size));
+ if (hd_size > size)
+ @{
+ data = xrealloc (data, hd_size);
+ size = hd_size;
+ @}
+ mailbox_get_header (mbox, id, data, size);
+ header_get_value(rfc822, "From", buffer, sizeof (buffer);
+ printf ("%s \t", buffer);
+ header_get_value(rfc822, "Subject", buffer, sizeof (buffer);
+ printf ("%s\n", buffer);
+ @}
+
+ free (data);
+ header_destroy (rfc822);
+ return maildrop_destroy (mdrop);
+@}
+@end example
+
+@node Maildrop, URL, Introduction, Top
+@comment node-name, next, previous, up
+@chapter Maildrop
+@cindex Maildrop
+
+For sending or receiving mail you must create a maildrop indicating the
+address/folder, this is done by calling @code{maildrop_create} and
+giving it an @var{url}.
+
+@findex maildrop_create
+@findex maildrop_destroy
+@example
+
+int maildrop_create (maildrop_t * @var{mid}, const char * @var{url}
+ char * @var{address}, int @var{flags})
+int maildrop_destroy (maildrop_t * @var{mid})
+
+@end example
+
+@noindent
+@var{mid} will contain maildrop id,
+@var{url} a url object,
+@var{addr} is a string that contains the maildrop address,
+@var{flags} specify execution flags.
+
+@example
+struct _maildrop
+ @{
+ /* PRIVATE */
+ url_t url;
+ mailbox_t mbox;
+
+ /* PUBLIC */
+ int (*_get_mailbox) (maildrop_t, mailbox_t *);
+ int (*_get_url) (maildrop_t, url_t *);
+ @};
+
+typedef struct _maildrop * maildrop_t;
+
+@end example
+
+@node URL, Maildrop Macros, Maildrop, Top
+@comment node-name, next, previous, up
+@subsection URL
+@cindex URL
+
+See rfc2368, rfc2369, rfc2384
+
+@node Maildrop Macros, Mailbox, URL, Top
+@comment node-name, next, previous, up
+@subsection Maildrop Macros
+@cindex Maildrop Macros
+
+The predefined macros --taken directly from @file{mailutils.h}--are:
+@findex maildrop_get_mailbox
+@findex maildrop_get_url
+@example
+
+__inline__ int maildrop_get_mailbox (maildrop_t mdrop, mailbox_t * mbox)
+@{ *mbox = mdrop->mbox; return (*mbox) 0 : EINVAL; @}
+
+__inline__ int maildrop_get_url (maildrop_t mdrop, url_t * url)
+@{ *url = mdrop->url; return (*url) 0 : EINVAL; @}
+
+@end example
+
+@node Mailbox, Mailbox Macros, Maildrop Macros, Top
+@comment node-name, next, previous, up
+@chapter Mailbox
+@cindex Mailbox
+
+Those are different formats to access a folder.
+
+@table @samp
+@item POP3
+Post Office Protocol, Not Implemented.
+@item IMAP
+Not Implemented
+@item QMAIL
+Not Implemented
+@item UNIX
+Sketchy
+@end table
+
+@findex mailbox_create
+@findex mailbox_destroy
+@example
+
+int mailbox_create (mailbox_t * @var{mailbox}, int @var{flags})
+
+int maildrop_destroy (mailbox_t * @var{mailbox})
+
+@end example
+
+All implementation shall provide the minimum set of the API :
+
+@example
+
+struct _mailbox
+ @{
+ /* Private Data */
+ .....
+ /* Public API */
+ int (*_open) (url_t);
+ int (*_close) (mailbox_t);
+ int (*_set_header) (mailbox_t, size_t *, char *, size_t);
+ int (*_get_header) (mailbox_t, size_t, char *, size_t);
+ int (*_get_header_size) (mailbox_t, size_t, size_t *);
+ int (*_delete) (mailbox_t, size_t);
+ int (*_undelete) (mailbox_t, size_t);
+ int (*_set_body) (mailbox_t, size_t, char *, size_t);
+ int (*_get_body) (mailbox_t, size_t, char *, size_t);
+ int (*_get_body_size) (mailbox_t, size_t, size_t *);
+ int (*_set_timeout) (mailbox_t, size_t);
+ int (*_get_timeout) (mailbox_t, size_t *);
+ int (*_send_envelop) (mailbox_t, size_t, size_t);
+ int (*_stat) (mailbox_t, size_t *, size_t *);
+ int (*_update) (mailbox_t);
+ @};
+
+typedef struct _mailbox * mailbox_t;
+@end example
+
+@node Mailbox Macros, Headers, Mailbox, Top
+@comment node-name, next, previous, up
+@subsection Mailbox Macros
+@cindex Mailbox Macros
+
+@findex maildrop_get_header
+@findex maildrop_get_header_size
+@example
+
+__inline__ int mailbox_get_header (mailbox_t mbox, int id, char * hdr, int sz)
+@{ return mbox->_get_header (mbox, id, hdr, sz); @}
+
+__inline__ int mailbox_get_header_size (mailbox_t mbox, int id, int * sz)
+@{ return mbox->_get_header_size (mbox, id, sz); @}
+
+@end example
+
+@node Headers, Headers Macros, Mailbox Macros, Top
+@comment node-name, next, previous, up
+@chapter Headers
+@cindex Headers
+
+So far we plan support for RFC822 and RFC1522;
+
+@example
+int header_create (int flags, header_t * header);
+
+int header_destroy (header_t header);
+
+struct _header
+ @{
+ /* Private */
+ ...
+ /* Public */
+ char * (*_get_value) (header_t, char *);
+ @};
+
+typedef struct _header * header_t;
+@end example
+
+@node Headers Macros, Headers Parsed, Headers, Top
+@comment node-name, next, previous, up
+@subsection Headers Macros
+@cindex Headers Macros
+
+@example
+__inline__ int header_get_value (header_t hdr, char * h, char buf, size_t sz)
+@{ return hdr->_get_value (hdr, h, buf, sz); @}
+@end example
+
+@node Headers Parsed, Headers Regex, Headers Macros, Top
+@comment node-name, next, previous, up
+@subsection Headers Parsed
+@cindex Headers Parsed
+
+Return a hash table, a dictionnary, ???
+
+@node Headers Regex, Mime, Headers Parsed, Top
+@comment node-name, next, previous, up
+@subsection Headers Parsed
+@cindex Headers Parsed
+
+Using regular expression ?
+
+@node Mime, Encoding, Headers Regex, Top
+@comment node-name, next, previous, up
+@chapter Mime
+@cindex Mime
+
+Mime stuff in the Body.
+
+@node Encoding, RFC1522, Mime, Top
+@comment node-name, next, previous, up
+@chapter Encoding
+@cindex Encoding
+
+@node RFC1522, Quoted Printable, Encoding, Top
+@comment node-name, next, previous, up
+@subsection RFC1522
+@cindex RFC1522
+
+@node Quoted Printable, Base64, RFC1522, Top
+@comment node-name, next, previous, up
+@subsection Quoted Printable
+@cindex Quoted Printable
+
+@node Base64, Reporting Bugs, Quoted Printable, Top
+@comment node-name, next, previous, up
+@subsection Base64
+@cindex Base64
+
+@node Reporting Bugs, Acknowledgement, Base64, Top
+@comment node-name, next, previous, up
+@chapter Reporting Bugs
+@cindex Reporting Bugs
+
+Email bug reports to @email{bug-mailutils@@gnu.org}.
+Be sure to include the word ``mailutils'' somewhere in the ``Subject:'' field.
+
+@node Acknowledgement, Concept Index, Reporting Bugs, Top
+@comment node-name, next, previous, up
+@chapter Acknowledgement
+@cindex Acknowledgement
+
+Jakob Kaivo @email{jkaivo@@ndn.net},
+Jeff Bailey @email{jbailey@@gnu.org},
+Sean Perry @email{shaleh@@debian.org},
+
+@page
+@node Concept Index , Index, Acknowledgement, Top
+@comment node-name, next, previous, up
+@unnumbered Concept Index
+
+This is a general index of all issues discussed in this manual
+
+@printindex cp
+@page
+
+@node Index, , Concept Index, Top
+@unnumbered Index
+
+This is an alphabetical list of all @sc{mailutils} functions.
+
+@printindex fn
+
+@contents
+
+@bye
diff --git a/pop3d/Makefile.am b/pop3d/Makefile.am
index cc7e14808..87ed3b2ac 100644
--- a/pop3d/Makefile.am
+++ b/pop3d/Makefile.am
@@ -7,4 +7,4 @@ pop3d_DEPENDENDENCIES = ../libmailbox/libmailbox.la ../lib/libgetopt.la\
pop3d_SOURCES = apop.c auth.c capa.c dele.c extra.c pop3d.c pop3d.h\
list.c noop.c quit.c retr.c rset.c stat.c top.c uidl.c user.c signal.c
-pop3d_LDADD = ../libmailbox/libmailbox.la ../libsrc/libmailutils.a @AUTHLIBS@
+pop3d_LDADD = ../libmailbox/libmailbox.la ../lib/libmailutils.a @AUTHLIBS@

Return to:

Send suggestions and report system problems to the System administrator.