docs/master: ch03.roff comparison

comparison ch03.roff @ 102:a782488c85f5

More text about attachments mainly, plus some rearrangements.

author	markus schnalke <meillo@marmaro.de>
date	Wed, 20 Jun 2012 17:57:37 +0200
parents	e8e6adb14beb
children	2818ca27d24c

comparison

equal deleted inserted replaced

-:e8e6adb14beb
+:a782488c85f5
 The draft folder facility, together with the
 .Sw -form
 switch, are sufficient.
-.U3 "Inplace Editing
+.U3 "In Place Editing
 .P
 .Pn anno
 had the switches
 .Sw -[no]inplace
 to either annotate the message in place and thus preserve hard links,
 .ig
 .P
-To ease typing, the switches can be abbreviated as much as the remaining
-prefix remains unambiguous.
-If in our example no other switch would start with the letter `t', then
-.Cl "-truncate" ,
-.Cl "-trunc" ,
-.Cl "-tr" ,
-and
-.Cl "-t
-would all be the same.
-As a result, switches can neither be grouped (as in
-.Cl "ls -ltr" )
-nor can switch arguments be appended directly to the switch (as in
-.Cl "sendmail -q30m" ).
-.P
-Many switches have negating counter-parts, which start with `no'.
-For example
-.Cl "-notruncate
-inverts the
-.Cl "-truncate
-switch.
-They exist to undo the effect of default switches in the profile.
-If the user has chosen to change the default behavior of some tool
-by adding a default switch to the profile,
-he can still undo this change in behavior by specifying the inverse
-switch on the command line.
-.P
 In the best case, all switches are unambiguous on the first character,
 or on the three-letter prefix for the `no' variants.
 Reducing switch prefix collisions, shortens the necessary prefix length
 the user must type.
 Having less switches helps best.
 ..
+.\" XXX: whatnow prompt commands
 .H1 "Modernizing
+.P
+The code base of mmh originates from the late Seventies.
+Through the Eighties, extensive work had been done on it.
+In the Nineties, it had been partly reorganized and extended.
+Relicts from each decade have gathered in the code base.
+My goal was to modernize the code base.
+.P
+FIXME functional aspect only here
+.P
+FIXME ref to `code style' for non-functional aspects.
 .H2 "Code Relicts
 .P
-The code base of mmh originates from the late Seventies,
+My position to drop obsolete functionality of mmh to remove old code
-had been extensively
+is much more revolutional than the nmh community likes it.
-worked on in the mid Eighties, and had been partly reorganized and extended
+Without the need to justify my decisions, I was able to quickly
-in the Nineties. Relicts of all those times had gathered in the code base.
-My goal was to remove any ancient code parts. One part of the task was
-converting obsolete code constructs to standard constructs, the other part
-was dropping obsolete functions.
-.P
-As I'm not even thirty years old and have no more than seven years of
-Unix experience, I needed to learn about the history in retrospective.
-Older people likely have used those ancient constructs themselves
-and have suffered from their incompatibilities and have longed for
-standardization. Unfortunately, I have only read that others had done so.
-This put me in a much more difficult positions when working on the old
-code. I needed to recherche what other would have known by heart from
-experience. All my programming experience comes from a time past ANSI C
-and past POSIX. Although I knew about the times before, I took the
-current state implicitly for granted most of the time.
-.P
-Being aware of
-these facts, I rather let people with more historic experience solve the
-task of converting the ancient code constructs to standardized ones.
-Luckily, Lyndon Nerenberg focused on this task at the nmh project.
-He converted large parts of the code to POSIX constructs, removing
-the conditionals compilation for now standardized features.
-I'm thankful for this task being solved. I only pulled the changes into
-mmh.
-.P
-The other task \(en dropping ancient functionality to remove old code \(en
-I did myself, though. My position to strip mmh to the bare minimum of
-frequently used features is much more revolutional than the nmh community
-likes it. Without the need to justify my decisions, I was able to quickly
 remove functionality I considered ancient.
 The need to discuss my decisions with
-peers likely would have slowed this process down. Of course, I researched
+peers likely would have slowed this process down.
-if a particular feature really should be dropped. Having not had any
+Of course, I researched if a particular feature really should be dropped.
+Having not had any
 contact to this feature within my computer life was a first indicator to
 drop it, but I also asked others and searched the literature for modern
-usage of the feature. If it appeared to be truly ancient, I dropped it.
+usage of the feature.
+If it appeared to be truly ancient, I dropped it.
 The reason for dropping is always part of the commit message in the
-version control system. Thus, it is easy for others to check their
+version control system.
+Thus, it is easy for others to check their
 view on the topic with mine and possibly to argue for reinclusion.
 .U3 "MMDF maildrop support
 .P
-I did drop any support for the MMDF maildrop format. This type of format
+I did drop any support for the MMDF maildrop format.
+This type of format
 is conceptionally similar to the mbox format, but uses four bytes with
 value 1 (\fL^A^A^A^A\fP) as message delimiter,
 instead of the string ``\fLFrom\ \fP''.
 Due to the similarity and mbox being the de-facto standard maildrop
 format on Unix, but also due to the larger influence of Sendmail than MMDF,
 the MMDF maildrop format had vanished.
 .P
-The simplifications within the code were only moderate. Switches could
+The simplifications within the code were only moderate.
-be removed from tools like
+Switches could be removed from tools like
 .L packf ,
-which generate packed mailboxes. Only one packed mailbox format remained:
+which generate packed mailboxes.
-mbox.
+Only one packed mailbox format remained: mbox.
 The most important changes affect the equally named mail parsing routine in
 .L sbr/m_getfld.c .
 The direct MMDF code had been removed, but as now only one packed mailbox
 format is left, code structure simplifications are likely possible.
 The reason why they are still outstanding is the heavily optimized code
 of
 .Fu m_getfld() .
 Changes beyond a small local scope \(en
 which restructuring in its core is \(en cause a high risk of damaging
-the intricate workings of the optimized code. This problem is know
+the intricate workings of the optimized code.
-to the developers of nmh, too. They also avoid touching this minefield
+This problem is know to the developers of nmh, too.
-if possible.
+They also avoid touching this minefield if possible.
 .U3 "UUCP Bang Paths
 .P
 More questionably than the former topic is the removal of support for the
-UUCP bang path address style. However, the user may translate the bang
+UUCP bang path address style.
+However, the user may translate the bang
 paths on retrieval to Internet addresses and the other way on posting
-messages. The former can be done my an MDA like procmail; the latter
+messages.
-by a sendmail wrapper. This would ensure that any address handling would
+The former can be done my an MDA like procmail; the latter
-work as expected. However, it might just work well without any
+by a sendmail wrapper.
+This would ensure that any address handling would work as expected.
+However, it might just work well without any
 such modifications, as mmh does not touch addresses much, in general.
 But I can't ensure as I have never used an environment with bang paths.
 Also, the behavior might break at any point in further development.
 .U3 "Hardcopy terminal support
 actually being able to work on it, but I fear my chances are null.
 .P
 The check only prevented a pager to be placed between the outputting
 program (\c
 .Pn mhl )
-and the terminal. This could have been ensured with
+and the terminal.
-the
+This could have been ensured with the
 .Sw -nomoreproc
 at the command line statically, too.
 .U3 "Removed support for header fields
 .P
 The
 .Hd Encrypted
 header field had been introduced by RFC\^822, but already
-marked legacy in RFC 2822. It was superseded by FIXME.
+marked legacy in RFC 2822.
+It was superseded by FIXME.
 Mmh does no more support this header field.
 .P
 Native support for
 .Hd Face
 header fields had been removed, as well.
 The perception of the topic described in the RFCs is clearly visible
 in MH's implementation.
 Thus, MH had all the MIME features but no idea of attachments.
 Today, however, users don't need all the MIME features but they want
 convenient attachment handling.
-In order to solve this problem, in 2002, Jon Steinhart had added an
-attachment system to nmh.
+.U3 "Composing MIME Messages
+.P
+In order to improve the situation on the message composing side,
+Jon Steinhart had added an attachment system to nmh in 2002.
 .Ci 7480dbc14bc90f2d872d434205c0784704213252
-He described his motivation to do so as such:
+In the file
+.Fn docs/README-ATTACHMENTS ,
+he described his motivation to do so as such:
 .QS
 Although nmh contains the necessary functionality for MIME message handing,
 the interface to this functionality is pretty obtuse.
 There's no way that I'm ever going to convince my partner to write
 .Pn mhbuild
 composition files!
 .QE
-With this change, the mind model of attachments entered nmh:
+.LP
+With this change, the mind model of attachments entered nmh.
+In the same document:
 .QS
 These changes simplify the task of managing attachments on draft files.
 They allow attachments to be added, listed, and deleted.
 MIME messages are automatically created when drafts with attachments
 are sent.
 .QE
-Unfortunately, the system had been deactivated by default,
+.LP
-like any new facilities in nmh.
+Unfortunately, the attachment system,
-.\" XXX move this paragraph somewhere else
+like any new facilities in nmh,
-Just to give one example, for me it took one year of using nmh
+was deactive by default.
-before I became aware of the existence of the attachment system.
-One could argue that this fact disqualifies my reading of the
-documentation.
-If I would have installed nmh from source back then, I could agree.
-Yet I had used a prepackaged version and had expected that it would
-just work.
 .P
 During my work in Argentina, I tried to improve the attachment system.
-Because of great opposition in the nmh community, after long discussions,
+But, because of great opposition in the nmh community,
-my patch died as a proposal on the mailing list.
+my patch died as a proposal on the mailing list, after long discussions.
 .[
 nmh-workers attachment proposal
 .]
-In Januar 2012, I applied the patch in an extended form to mmh.
+In Januar 2012, I extended the patch and applied it to mmh.
 .Ci 8ff284ff9167eff8f5349481529332d59ed913b1
-.P
 In mmh, the attachment system is active by default.
-There are no command line switches anymore, but a pre-defined attachment
+Instead of command line switches, the
-header field.
-It is named
-.Hd Attach
-by default, but can be renamed with the
 .Pe Attachment-Header
-profile entry.
+profile entry is used to specify
+the name of the attachment header field.
+It is pre-defined to
+.Hd Attach .
+.P
 To add an attachment to a draft, simply add an attachment header:
 .VS
 To: bob
 Subject: The file you wanted
 Attach: /path/to/the/file-bob-wanted
 --------
 Here it is.
 VE
 The header field can be added to the draft manually in the editor,
-by using the `attach' command at the WhatNow prompt, or with
+or by using the `attach' command at the WhatNow prompt, or
+non-interactively with
 .Pn anno :
 .VS
-anno -append -nodate -component Attach -text /path/to/file
+anno -append -nodate -component Attach -text /path/to/attachment
 VE
-Drafts with attachment headers are converted to MIME automatically
+Drafts with attachment headers are converted to MIME automatically by
-on sending.
+.Pn send .
-The draft stored in the draft folder is always in source form with
+The conversion to MIME is invisible to the user.
+The draft stored in the draft folder is always in source form, with
 attachment headers.
-The convertion to MIME is done invisible to the user.
 If the MIMEification fails, for instance because the file to attach
 is not accessible, the original draft is not changed.
 .P
-Forwarding message is handled by the same attachment system.
+The attachment system handles the forwarding of messages, too.
 If the attachment header value starts with a plus character (`+'),
 like in
 .Cl "Attach: +bob 30 42" ,
 The given messages in the specified folder will be attached.
 This allowed to simplify
 .Pn forw .
 .Ci f41f04cf4ceca7355232cf7413e59afafccc9550
 .P
 Closely related to attachments is non-ASCII text content,
 because it requires MIME too.
-In nmh it the user needed to invoke `mime' at the WhatNow prompt
+In nmh, the user needed to call `mime' at the WhatNow prompt
 to have the draft converted to MIME.
-This was necessary if the draft contained non-ASCII characters.
+This was necessary whenever the draft contained non-ASCII characters.
 If the user did not call `mime', a broken message would be sent.
 Therefore, the
 .Pe automimeproc
 profile entry could be specified to have the `mime' command invoked
-automatically for each message.
+automatically each time.
 Unfortunately, this approach conflicted with with attachment system
 because the draft would already be in MIME format at the time
 when the attachment system wanted to MIMEify it.
-To use the attachment system, the user must not run `mime' at the
+To use nmh's attachment system, `mime' must not be called at the
-WhatNow prompt nor have
+WhatNow prompt and
 .Pe automimeproc
-set in the profile.
+must not be set in the profile.
 But then the case of non-ASCII text without attachment headers was
 not caught.
-All in all a bad solution.
+All in all, the solution was complex and irritating.
-My patch from December 2010 already solved this situation.
+My patch from December 2010 would have simplified the situation.
+.P
 Mmh's current solution is even more elaborate.
 Any necessary MIMEification is done automatically.
 There is no `mime' command at the WhatNow prompt anymore.
-The draft will be converted to MIME when either an attachment header
+The draft will be converted automatically to MIME when either an
-or non-ASCII text is present.
+attachment header or non-ASCII text is present.
 Further more, the special meaning of the hash character (`#')
-at the beginning of the line in the draft message is removed.
+at line beginnings in the draft message is removed.
-The user needs not at all deal about the topic.
+Users need not at all deal with the whole topic.
 .P
-This improvement has a price: The new approach does not directly
+Although the new approach does not anymore support arbitrary MIME
-support arbitrary MIME compositions.
+compositions directly, the full power of
-Nonetheless, the full power of
 .Pn mhbuild
 can still be accessed.
-As long as no attachment headers are included, the user can create a
+Given no attachment headers are included, the user can create
-nonlimited
 .Pn mhbuild
-composition draft like in nmh.
+composition drafts like in nmh.
 Then, at the WhatNow prompt, he needs to invoke
 .Cl "edit mhbuild
 to convert it to MIME.
-Because the resulting draft does only contain ASCII characters
+Because the resulting draft does neither contain non-aASCII characters
-and has no attachment headers, the attachment system will not touch it.
+nor has it attachment headers, the attachment system will not touch it.
 .P
 The approach taken in mmh is taylored towards todays most common case:
 a text part with possibly attachments.
-Still, the full power of
+This case is simplified a lot for users.
+.U3 "MIME Type Guessing
+.P
+The use of
 .Pn mhbuild
-can be accessed with a bit of overhead.
+composition drafts had one notable advantage over attachment headers
+from the programmer's point of view: The user provides the appropriate
-.\" XXX: MIME types
+MIME types for files to include.
-.\" XXX: whatnow prompt commands
+The attachment system needs to find out the correct MIME type itself.
-.\" XXX: anno rework
+This is a difficult task, yet it spares the user irritating work.
+Determining the correct MIME type of content is partly mechanical,
+partly intelligent work.
+Forcing the user to find out the correct MIME type,
+forces him to do partly mechanical work.
+Letting the computer do the work, can lead to bad choices for difficult
+content.
+For mmh, the latter option was chosen.
+.P
+Determining the MIME type by the suffix of the file name is a dumb
+approach, yet it is simple to implement and provides good results
+for the common cases.
+Mmh implements this approach in the
+.Pn print-mimetype
+script.
+Using it is the default choice.
+.P
+A far better but less portable approach is the use of
+.Pn file .
+This standard tool tries to determine the type of files.
+Unfortunately, its capabilities and accuracy varies from system to system.
+Additionally, its output was only intended for human beings,
+but not to be used by programs.
+It varies much.
+Nevertheless, modern versions of GNU
+.Pn file ,
+which is prevalent on the popular GNU/Linux systems,
+provides MIME type output in machine-readable form.
+Although this solution is highly system-dependent,
+it solves the difficult problem well.
+On systems where GNU
+.Pn file ,
+version 5.04 or higher, is available it should be used.
+One needs to specify the following profile entry to do so:
+.VS
+Mime-Type-Query: file -b --mime
+VE
+.LP
+Other versions of
+.Pn file
+might possibly be usable with wrapper scripts to reformat the output.
+The diversity among
+.Pn file
+implementations is great; one needs to check the local variant.
+.P
+If no MIME type can be determined, text content gets sent as
+`text/plain' and anything else under the generic fall-back type
+`application/octet-stream'.
+It is not possible in mmh to override the automatic MIME type guessing
+for a specific file.
+To do so, the user would need to know in advance for which file
+the automatic guessing does fail, or the system would require interaction.
+I consider both cases impractical.
+The existing solution should be sufficient.
+If not, the user may always fall back to
+.Pn mhbuild
+composition drafts and ignore the attachment system.
+.U3 "Storing Attachments
+.P
+FIXME
+.U3 "Showing MIME Messages
+.P
+FIXME
 .H2 "Digital Cryptography
 .P
 Signing and encryption.
-.H2 "Good Defaults
+.H2 "Modern Defaults
+.P
+Just to give one example, for me it took one year of using nmh
+before I became aware of the existence of the attachment system.
+One could argue that this fact disqualifies my reading of the
+documentation.
+If I would have installed nmh from source back then, I could agree.
+Yet I had used a prepackaged version and had expected that it would
+just work.
+.H1 "Code Style
 .P
 foo
-.H1 "Code Style
-.P
-foo
 .H2 "Standard Code
 .P
 POSIX
+.U3 "Converting to Standard Code
+.P
+One part of this task was converting obsolete code constructs
+to standard constructs.
+As I'm not even thirty years old and have no more than seven years of
+Unix experience, I needed to learn about the history in retrospective.
+Older people likely have used those ancient constructs themselves
+and have suffered from their incompatibilities and have longed for
+standardization.
+Unfortunately, I have only read that others had done so.
+This put me in a much more difficult positions when working on the old
+code.
+I needed to recherche what other would have known by heart from
+experience.
+All my programming experience comes from a time past ANSI C
+and past POSIX.
+Although I knew about the times before, I took the
+current state implicitly for granted most of the time.
+.P
+Being aware of
+these facts, I rather let people with more historic experience solve the
+task of converting the ancient code constructs to standardized ones.
+Luckily, Lyndon Nerenberg focused on this task at the nmh project.
+He converted large parts of the code to POSIX constructs, removing
+the conditionals compilation for now standardized features.
+I'm thankful for this task being solved. I only pulled the changes into
+mmh.
 .H2 "Separation
 .U2 "MH Directory Split
 .H2 "Style
 .P
 Code layout, goto, ...
+.P
+anno rework
 .H1 "Concept Exploitation/Homogeneity

Mercurial > docs > master

comparison ch03.roff @ 102:a782488c85f5