From: Ken Hornstein <kenh@pobox.com>
Date: Mon, 11 Nov 2013 03:46:49 +0000 (-0500)
Subject: Document things a bit more.
X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/4e6bc7b6d19bd083ee0446a3a7f2968a1b9dba20?hp=e546c4b5abbf2025a5e346887c6b20c1ad99dbe1

Document things a bit more.
---

diff --git a/h/addrsbr.h b/h/addrsbr.h
index 5ca801e6..a753e623 100644
--- a/h/addrsbr.h
+++ b/h/addrsbr.h
@@ -12,19 +12,24 @@
 #define	NETHOST		1
 #define	BADHOST		2
 
+/*
+ * The email structure used by nmh to define an email address
+ */
+
 struct mailname {
-    struct mailname *m_next;
-    char *m_text;
-    char *m_pers;
-    char *m_mbox;
-    char *m_host;
-    char *m_path;
-    int m_type;
-    char m_nohost;
-    char m_bcc;
-    int m_ingrp;
-    char *m_gname;
-    char *m_note;
+    struct mailname *m_next;	/* Linked list linkage; available for */
+				/* application use */
+    char *m_text;		/* Full unparsed text of email address */
+    char *m_pers;		/* display-name in RFC 5322 parlance */
+    char *m_mbox;		/* local-part in RFC 5322 parlance */
+    char *m_host;		/* domain in RFC 5322 parlance */
+    char *m_path;		/* Host routing; should not be used */
+    int m_type;			/* UUCPHOST, LOCALHOST, NETHOST, or BADHOST */
+    char m_nohost;		/* True if no host part available */
+    char m_bcc;			/* Used by post to keep track of bcc's */
+    int m_ingrp;		/* True if email address is in a group */
+    char *m_gname;		/* display-name of group */
+    char *m_note;		/* Note (post-address comment) */
 };
 
 #define	adrformat(m) auxformat ((m), 1)
@@ -34,7 +39,55 @@ struct mailname {
  */
 void mnfree(struct mailname *);
 int ismymbox(struct mailname *);
-char *getname(const char *);
+
+/*
+ * Parse an address header, and return a sequence of email addresses.
+ * This function is the main entry point into the nmh address parser.
+ * It is used in conjunction with getm() to parse an email header.
+ *
+ * Arguments include:
+ *
+ * header	- Pointer to the start of an email header.
+ *
+ * On the first call, header is copied and saved internally.  Each email
+ * address in the header is returned on the first and subsequent calls
+ * to getname().  When there are no more email addresses available in
+ * the header, NULL is returned and the parser's internal state is
+ * reset.
+ */
+
+char *getname(const char *header);
 char *getlocaladdr(void);
 char *auxformat(struct mailname *, int);
-struct mailname *getm(char *, char *, int, int, char *);
+
+/*
+ * Parse an email address into it's components.
+ *
+ * Used in conjunction with getname() to parse a complete email header.
+ *
+ * Arguments include:
+ *
+ * str		- Email address being parsed.
+ * dfhost	- A default host to append to the email address if
+ *		  one is not included.  If NULL, use nmh's idea of
+ *		  localhost().
+ * dftype	- If dfhost is given, use dftype as the email address type
+ *		  if no host is in the email address.
+ * wanthost	- One of AD_HOST or AD_NHST.  If AD_HOST, look up the
+ *		  "official name" of the host.  Well, that's what the
+ *		  documentation says, at least ... support for that
+ *		  functionality was removed when hostable support was
+ *		  removed and the address parser was converted by default
+ *		  to always being in DUMB mode.  So nowadays this only
+ *		  affects where error messages are put if there is no
+ *		  host part (set it to AD_HOST if you want error messages
+ *		  to appear on standard error).
+ * eresult	- Any error string returned by the address parser.  String
+ *		  must contain sufficient room for the error message.
+ *		  (BUFSIZ is used in general by the code).  Can be NULL.
+ *
+ * A pointer to an allocated struct mailname corresponding to the email
+ * address is returned.
+ */
+struct mailname *getm(char *str, char *dfhost, int dftype,
+		      int wanthost, char *eresult);
diff --git a/sbr/encode_rfc2047.c b/sbr/encode_rfc2047.c
index 98d2454a..66c736e8 100644
--- a/sbr/encode_rfc2047.c
+++ b/sbr/encode_rfc2047.c
@@ -419,6 +419,8 @@ field_encode_base64(const char *name, char **value, const char *charset)
 	 * token marker; this makes things work out correctly for the first
 	 * line, which should have a space between the ':' and the start
 	 * of the token.
+	 *
+	 * It's okay if you don't follow all of that.
 	 */
 
 	q += snprintf(q, outlen - (q - output), "?=\n%*s", prefixlen - 1, "");
@@ -435,7 +437,8 @@ field_encode_base64(const char *name, char **value, const char *charset)
     output = mh_xrealloc(output, outlen);
     q = output + curlen;
 
-    q += snprintf(q, outlen - (q - output), " =?%s?B?", charset);
+    q += snprintf(q, outlen - (q - output), "%s=?%s?B?",
+    		  prefixlen ? " " : "", charset);
 
     if (writeBase64raw((unsigned char *) p, strlen(p),
     		       (unsigned char *) q) != OK) {
@@ -519,9 +522,13 @@ unfold_header(char **value, int len)
     *value = str;
 }
 
+/*
+ * Decode a header containing addresses.  This means we have to parse
+ * each address and only encode the display-name or comment field.
+ */
+
 static int
 field_encode_address(const char *name, char **value, int encoding,
 		     const char *charset)
 {
-    return 0;
 }