From: Ken Hornstein Date: Thu, 13 Mar 2014 19:51:32 +0000 (-0400) Subject: Create new mh-mime man page, with overview of how MIME handling works in nmh. X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/8b645f0ed11c256edd214edc24732a1567742c75?ds=sidebyside Create new mh-mime man page, with overview of how MIME handling works in nmh. --- diff --git a/Makefile.am b/Makefile.am index a73a4215..66ce8ab1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -227,16 +227,16 @@ man_MANS = man/ali.1 man/anno.1 man/ap.8 man/burst.1 man/comp.1 \ man/fmtdump.8 man/fmttest.1 man/fnext.1 man/folder.1 man/folders.1 \ man/forw.1 man/fprev.1 man/inc.1 man/install-mh.1 man/mark.1 \ man/mh-alias.5 man/mh-chart.7 man/mh-draft.5 man/mh-folders.5 \ - man/mh-format.5 man/mh-mail.5 man/mh-profile.5 man/mh_profile.5 \ - man/mh-sequence.5 man/mh-tailor.5 man/mhbuild.1 man/mhfixmsg.1 \ - man/mhl.1 man/mhlist.1 man/mhmail.1 man/mhn.1 man/mhparam.1 \ - man/mhpath.1 man/mhshow.1 man/mhstore.1 man/mkstemp.1 man/msgchk.1 \ - man/msh.1 man/mts.conf.5 man/new.1 man/next.1 man/nmh.7 man/packf.1 \ - man/pick.1 man/post.8 man/prev.1 man/prompter.1 man/rcvdist.1 \ - man/rcvpack.1 man/rcvstore.1 man/rcvtty.1 man/refile.1 \ - man/repl.1 man/rmf.1 man/rmm.1 man/scan.1 man/send.1 \ - man/sendfiles.1 man/show.1 man/slocal.1 man/sortm.1 man/unseen.1 \ - man/whatnow.1 man/whom.1 + man/mh-format.5 man/mh-mail.5 man/mh-mime.7 man/mh-profile.5 \ + man/mh_profile.5 man/mh-sequence.5 man/mh-tailor.5 man/mhbuild.1 \ + man/mhfixmsg.1 man/mhl.1 man/mhlist.1 man/mhmail.1 man/mhn.1 \ + man/mhparam.1 man/mhpath.1 man/mhshow.1 man/mhstore.1 \ + man/mkstemp.1 man/msgchk.1 man/msh.1 man/mts.conf.5 man/new.1 \ + man/next.1 man/nmh.7 man/packf.1 man/pick.1 man/post.8 man/prev.1 \ + man/prompter.1 man/rcvdist.1 man/rcvpack.1 man/rcvstore.1 \ + man/rcvtty.1 man/refile.1 man/repl.1 man/rmf.1 man/rmm.1 \ + man/scan.1 man/send.1 man/sendfiles.1 man/show.1 man/slocal.1 \ + man/sortm.1 man/unseen.1 man/whatnow.1 man/whom.1 ## ## Sources for our man pages @@ -247,14 +247,14 @@ man_SRCS = man/ali.man man/anno.man man/ap.man man/burst.man man/comp.man \ man/folder.man man/folders.man man/forw.man man/fprev.man \ man/inc.man man/install-mh.man man/mark.man man/mh-alias.man \ man/mh-chart-gen.sh man/mh-draft.man man/mh-folders.man \ - man/mh-format.man man/mh-mail.man man/mh-profile.man \ - man/mh_profile.man man/mh-sequence.man man/mh-tailor.man \ - man/mhbuild.man man/mhfixmsg.man man/mhl.man man/mhlist.man \ - man/mhmail.man man/mhn.man man/mhparam.man man/mhpath.man \ - man/mhshow.man man/mhstore.man man/mkstemp.man man/msgchk.man \ - man/msh.man man/mts.conf.man man/new.man man/next.man man/nmh.man \ - man/packf.man man/pick.man man/post.man man/prev.man \ - man/prompter.man man/rcvdist.man man/rcvpack.man \ + man/mh-format.man man/mh-mail.man man/mh-mime.man \ + man/mh-profile.man man/mh_profile.man man/mh-sequence.man \ + man/mh-tailor.man man/mhbuild.man man/mhfixmsg.man man/mhl.man \ + man/mhlist.man man/mhmail.man man/mhn.man man/mhparam.man \ + man/mhpath.man man/mhshow.man man/mhstore.man man/mkstemp.man \ + man/msgchk.man man/msh.man man/mts.conf.man man/new.man \ + man/next.man man/nmh.man man/packf.man man/pick.man man/post.man \ + man/prev.man man/prompter.man man/rcvdist.man man/rcvpack.man \ man/rcvstore.man man/rcvtty.man man/refile.man man/repl.man \ man/rmf.man man/rmm.man man/scan.man man/send.man \ man/sendfiles.man man/show.man man/slocal.man man/sortm.man \ diff --git a/man/mh-chart-gen.sh b/man/mh-chart-gen.sh index e0afd409..c59af2ae 100755 --- a/man/mh-chart-gen.sh +++ b/man/mh-chart-gen.sh @@ -40,5 +40,6 @@ cat <<'EOF' .ad .SH "SEE ALSO" -nmh(7) +.IR nmh (7), +.IR mh\-mime (7) EOF diff --git a/man/mh-mime.man b/man/mh-mime.man new file mode 100644 index 00000000..3a568e52 --- /dev/null +++ b/man/mh-mime.man @@ -0,0 +1,161 @@ +.TH MH\-MIME %manext7% " March 13, 2014" "%nmhversion%" +.\" +.\" %nmhwarning% +.\" +.SH NAME +mh\-mime \- Overview of +.IR nmh (7) +MIME message composition and display +.\" +.SH DESCRIPTION +The acronym MIME stands for Multipurpose Internet Mail Extensions, the +format of Internet messages used to send multi\-media content. +The +.B nmh +command suite has support for the display and composition of MIME messages, but +currently MIME support is not completely integrated into all tools. This +document provides an overview as to which tools support MIME message display, +storage, and composition. +.SS +Local Character Set Conversion +All of the +.B nmh +commands convert non\-native character sets to the local character set, +as specified by the operating system locale settings. The +.IR locale (1) +man page has more details on the environment variables used to set the +local character set. Character set conversion will only take place if +.B nmh +was built with +.IR icov (3) +support. +.PP +Depending on the source and target character set, it may not be possible +to convert all characters to the local character set. In this case a +substitution character will be used for the characters that cannot be +converted. +.SS +Message Display +The default format used by +.B scan +will automatically decode MIME-encoded headers. If you have a custom +scan format, see the examples provided with the +.B nmh +distribution (found in the +.RI \*(lq %etcdir% \*(rq +directory) and the +.IR mh\-format (5) +man page for details on how to make sure your MIME headers are properly +decoded. +.PP +By default, if +.B show +detects that it is reading a MIME message it will invoke +.BR mhshow . +The default behavior of +.B mhshow +is to only display text parts that are not marked as attachments. See the +.IR mhshow (1) +man page for details on how to control what +.B mhshow +will display. +.SS +Message Interrogation and Storage +The +.B mhlist +command will display a listing of the MIME parts contained within a +message. That information can be used in conjuction with the +.B mhstore +command to save individual parts or content types of a message. See +the +.IR mhlist (1) +and +.IR mhstore (1) +man pages for more details on how these commands work. +.SS +Message Composition and Reply +All messages sent by +.B send +will automatically be processed by +.B mhbuild +before being passed to +.B post +for message submission. +.B Mhbuild +will use the locale settings to mark text content with the appropriate +character set and apply any necessary encoding. If you wish to include +text in your message using a character set that does not match your +locale, you will need to specify the character set using a +.B mhbuild +directive; see +.IR mhbuild (1) +for more information. +.PP +For attaching files or composing other non-text content, there are two options: the attach system and +.B mhbuild +directives. +.PP +The attach system is best suited for content where one or more files are +being attached to a message. You can use the attach system by either +using the +.B attach +command at the \*(lqWhat now?\*(rq prompt, or by inserting an \*(lqAttach:\*(rq +header in the message draft containing the name of the file you wish to +attach to the message (it should be noted all that the +.B attach +command does is place an \*(lqAttach\*(rq header in the message draft). +.B Mhbuild +will then automatically include the specified file(s) in the outgoing +message. See the +.IR send (1) +man page for details on how +.B mhbuild +determines the proper content type of attached files. +.PP +The other method of composing MIME messages is to use +.B mhbuild +directives. This allows exact control over the contents and format of +the MIME message, but has a more complicated syntax. The +.IR mhbuild (1) +man page contains details on the directive syntax and examples of directives +for different media types. It is important to note that when using +.B mhbuild +directives the user must run +.B mhbuild +outside of +.B send +to have it process directives; when being run by +.BR send , +.B mhbuild +is configured to not process directives so normal user text is not mistaken +for a directive. When using directives a user typically uses the +.B mime +command at the \*(lqWhat now?\*(rq prompt to process them. +.PP +When replying to messages using +.B repl +the traditional MH method of including the original text in the reply does +not interoperate with MIME messages. As of this writing there is no +native solution for addressing this issue, but the contrib directory +.RI ( %docdir%/contrib ) +contains a Perl program called +.B replyfilter +which will decode text parts and present them in an appropriate manner +to be included in a message reply. See the comments at the top of +.B replyfilter +for instructions on how to configure +.B nmh +to work with it. +.SH "SEE ALSO" +.IR nmh (7), +.IR mhbuild (1), +.IR comp (1), +.IR repl (1), +.IR whatnow (1), +.IR mh\-format (5) +.PP +.I %docdir%/contrib/replyfilter +.SH BUGS +MIME support should be more integrated into all of the +.B nmh +tools than it currently is. diff --git a/man/nmh.man b/man/nmh.man index 304a15cc..b9dadd17 100644 --- a/man/nmh.man +++ b/man/nmh.man @@ -1,4 +1,4 @@ -.TH NMH %manext7% "March 1, 2014" "%nmhversion%" +.TH NMH %manext7% "March 13, 2014" "%nmhversion%" .\" .\" %nmhwarning% .\" @@ -549,7 +549,8 @@ The user's nmh profile .SH "SEE ALSO" .IR install-mh (1), .IR mh-profile (5), -.IR mh-chart (7) +.IR mh-chart (7), +.IR mh-mime (7) .ne 4 .SH BUGS If problems are encountered with an