--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Sat May 06 16:53:07 2023 +0000
@@ -0,0 +1,44 @@
+The present code repository contains email software which Mother Mychaela
+developed for her own personal use; it is unlikely to be of interest to other
+people as my tastes in personal technology tend to be very different from the
+rest of the world, but I publish almost all of my software nonetheless, as a
+matter of general principle.
+
+The main program in the present collection is f-demime - it is a de-MIME-ing
+tool.  f-demime processes one or more email messages in UNIX mailbox format
+(each message preceded and delimited by a '^From ' line) and applies the
+following transformations to each message:
+
+1] base64 blobs that aren't text parts are excised from the message; each such
+   blob is decoded and saved into its own file.  These saved attachment files
+   are written into a special directory that must be indicated with
+   FDEMIME_ATT_DIR= environment variable.
+
+2] text/plain parts that are encoded in either base64 or quoted-printable are
+   decoded and written out in a form that (a) losslessly preserves the content
+   of the text part that originally contained non-ASCII characters and/or
+   insanely long lines, but also (b) is more suitable for direct consumption by
+   my wetware, rather than MIME software.  The output form uses backslash
+   escapes to represent non-ASCII characters and machine-inserted line breaks.
+
+3] text/html and other non-plain text parts that are encoded in base64 are
+   losslessly transcoded from base64 to quoted-printable.
+
+The transformations applied by f-demime aren't fully lossless at level of
+overall message lines and octets (one cannot take f-demime output and
+reconstruct a message byte-identical to the original), but they are lossless at
+the level of content which MIME itself promises to preserve.
+
+One important demiming function which f-demime does NOT do is collapsing
+multipart/alternative structures, keeping text/plain and discarding HTML.  The
+rationale for this functional omission is that I will be inserting f-demime
+into my incoming mail handling path, such that every incoming message will
+automatically pass through f-demime before it hits my eyeballs.  Given the
+current state of badness on the Internet, I occasionally receive mails in which
+the HTML part (which would be thrown away in a multipart/alternative collapse)
+contains some valuable or interesting information content that is missing in the
+text/plain version - thus fully automatic collapsing is not a workable approach
+currently.  I plan on implementing another program (resurrecting maltcollapse
+from my previous cdemime attempt circa 2006) to do this multipart/alternative
+collapsing, and then devising a practical way to invoke it once I have
+determined that the HTML part is junk that can be safely thrown away.