meillo@58: .H0 "Discussion meillo@0: .P meillo@169: This main chapter discusses the practical work accomplished in the meillo@169: mmh project. meillo@217: It is structured along the goals chosen for the project. meillo@217: A selection of the work undertaken meillo@217: is described. meillo@217: .P meillo@217: This discussion compares the present version of mmh with the state of meillo@217: nmh at the time when the mmh project had started, i.e. fall 2011. meillo@217: Recent changes in nmh are seldom part of the discussion. meillo@217: Sometimes they are mentioned in side notes. meillo@187: .P meillo@187: For the reader's convenience, the structure of modern email systems meillo@217: is depicted in the following figure. meillo@187: It illustrates the path a message takes from sender to recipient. meillo@217: meillo@217: .sp 1.5 meillo@187: .KS meillo@187: .in 2c meillo@187: .so input/mail-agents.pic meillo@187: .KE meillo@217: .sp 1.5 meillo@217: meillo@187: .LP meillo@217: The ellipses denote mail agents, i.e. different jobs in email processing. meillo@217: These are: meillo@187: .IP "Mail User Agent (MUA) meillo@217: The only program users directly interact with. meillo@187: It includes functions to compose new mail, display received mail, meillo@187: and to manage the mail storage. meillo@217: It is called a \fImail client\fP as well. meillo@187: .IP "Mail Submission Agent (MSA) meillo@187: A special kind of Mail Transfer Agent, used to submit mail into the meillo@187: mail transport system. meillo@217: Often it is also called an MTA. meillo@187: .IP "Mail Transfer Agent (MTA) meillo@187: A node in the mail transport system. meillo@217: It transfers incoming mail to a transport node nearer to the meillo@217: final destination. meillo@217: An MTA may be the final destination itself. meillo@187: .IP "Mail Delivery Agent (MDA) meillo@217: Delivers mail according to a set of rules. meillo@217: Usually, the messages are stored to disk. meillo@187: .IP "Mail Retrieval Agent (MRA) meillo@217: Initiates the transfer of mail from a remote location to the local machine. meillo@217: (The dashed arrow in the figure represents the pull request.) meillo@217: .LP meillo@217: The dashed boxes represent entities that usually reside on single machines. meillo@217: The box on the lower left represents the sender's system. meillo@187: The box on the upper left represents the first mail transfer node. meillo@187: The box on the upper right represents the transfer node responsible for the meillo@187: destination address. meillo@217: The box on the lower right represents the recipient's system. meillo@187: Often, the boxes above the dotted line are servers on the Internet. meillo@217: Many mail clients, including nmh, include all of the components below meillo@217: the dotted line. meillo@217: This is not the case for mmh; it implements the MUA only. meillo@187: meillo@187: meillo@187: meillo@58: meillo@58: meillo@58: meillo@133: .\" -------------------------------------------------------------- meillo@125: .H1 "Streamlining meillo@58: meillo@0: .P meillo@217: MH once provided a complete email system. meillo@217: The community around nmh tries to keep nmh in similar shape. meillo@178: In fundamental contrast, mmh shall be an MUA only. meillo@87: I believe that the development of all-in-one mail systems is obsolete. meillo@173: Today, email is too complex to be fully covered by a single project. meillo@173: Such a project will not be able to excel in all aspects. meillo@159: Instead, the aspects of email should be covered by multiple projects, meillo@87: which then can be combined to form a complete system. meillo@169: Excellent implementations for the various aspects of email already exist. meillo@217: Just to name three examples: Postfix meillo@217: .[ meillo@217: postfix website meillo@217: .] meillo@217: is a specialized MTA, Procmail meillo@217: .[ meillo@217: procmail website meillo@217: .] meillo@217: is a specialized MDA, and Fetchmail meillo@217: .[ meillo@217: fetchmail website meillo@217: .] meillo@217: is a specialized MRA. meillo@89: I believe that it is best to use such specialized tools instead of meillo@217: providing the same function once more as a side component. meillo@58: .P meillo@169: Doing something well requires focusing on a small set of specific aspects. meillo@217: Under the assumption that development which is focussed on a particular meillo@217: area produces better results there, specialized projects will be superior meillo@87: in their field of focus. meillo@87: Hence, all-in-one mail system projects \(en no matter if monolithic meillo@87: or modular \(en will never be the best choice in any of the fields. meillo@217: Even in providing the most consistent all-in-one system, they are likely meillo@217: to be beaten by projects that focus exclusively on the creation meillo@217: of a homogeneous system by integrating existing mail components. meillo@87: .P meillo@217: Usually, the limiting resource in the community development of meillo@217: free software is man power. meillo@171: .\" XXX FIXME ref! meillo@217: If the development effort is spread over a large development area, meillo@217: it becomes more difficult to compete with the specialists in the meillo@87: various fields. meillo@87: The concrete situation for MH-based mail systems is even tougher, meillo@169: given their small and aged community, concerning both developers and users. meillo@87: .P meillo@87: In consequence, I believe that the available development resources meillo@100: should focus on the point where MH is most unique. meillo@87: This is clearly the user interface \(en the MUA. meillo@125: Peripheral parts should be removed to streamline mmh for the MUA task. meillo@60: meillo@60: meillo@100: .H2 "Mail Transfer Facilities meillo@154: .Id mail-transfer-facilities meillo@60: .P meillo@217: The removal of the mail transfer facilities, effectively dropping the meillo@217: MSA and MRA, had been the first work task in the mmh project. meillo@217: The desire for this change initiated the creation of the mmh project. meillo@60: .P meillo@169: Focusing on one mail agent role only, is motivated by Eric Allman's meillo@105: experience with Sendmail. meillo@217: He identified the limitation of Sendmail meillo@217: .[ meillo@217: sendmail website meillo@217: .] meillo@217: to the MTA task as one reason for its success: meillo@105: .[ [ meillo@105: costales sendmail meillo@105: .], p. xviii] meillo@105: .QS meillo@105: Second, I limited myself to the routing function \(en meillo@110: I wouldn't write user agents or delivery back-ends. meillo@217: This was a departure of the dominant thought of the time, meillo@105: in which routing logic, local delivery, and often the network code meillo@105: were incorporated directly into the user agents. meillo@105: .QE meillo@105: .P meillo@187: In nmh, the MSA is called \fIMessage Transfer Service\fP (MTS). meillo@105: This facility, implemented by the meillo@105: .Pn post meillo@217: command, establishes network connections and spoke SMTP to submit meillo@159: messages to be relayed to the outside world. meillo@217: When email transfer changed, this part needed to be changed as well. meillo@89: Encryption and authentication for network connections meillo@87: needed to be supported, hence TLS and SASL were introduced into nmh. meillo@217: This added complexity without improving the core functions. meillo@217: Furthermore, keeping up with recent developments in the field of meillo@87: mail transfer requires development power and specialists. meillo@217: In mmh, this whole facility was simply cut off meillo@76: .Ci f6aa95b724fd8c791164abe7ee5468bf5c34f226 meillo@76: .Ci fecd5d34f65597a4dfa16aeabea7d74b191532c3 meillo@217: .Ci 156d35f6425bea4c1ed3c4c79783dc613379c65b . meillo@87: Instead, mmh depends on an external MSA. meillo@217: All outgoing mail in mmh goes through the meillo@60: .Pn sendmail meillo@87: command, which almost any MSA provides. meillo@87: If not, a wrapper program can be written. meillo@87: It must read the message from the standard input, extract the meillo@87: recipient addresses from the message header, and hand the message meillo@87: over to the MSA. meillo@217: For example, a wrapper script for qmail meillo@217: .[ meillo@217: qmail website meillo@217: .] meillo@217: would be: meillo@87: .VS meillo@87: #!/bin/sh meillo@138: exec qmail-inject # ignore command line arguments meillo@87: VE meillo@87: The requirement to parse the recipient addresses out of the message header meillo@217: may be removed in the future. meillo@217: Mmh could pass the recipient addresses as command line arguments. meillo@100: This appears to be the better interface. meillo@60: .P meillo@60: To retrieve mail, the meillo@60: .Pn inc meillo@217: command in nmh acts as MRA. meillo@217: It establishes network connections meillo@217: and speaks POP3 to retrieve mail from remote servers. meillo@76: As with mail submission, the network connections required encryption and meillo@217: authentication, thus TLS and SASL were added to nmh. meillo@169: Support for message retrieval through IMAP will soon become necessary meillo@169: additions, too, and likewise for any other changes in mail transfer. meillo@217: But not in mmh because it has dropped the support for retrieving mail meillo@217: from remote locations meillo@217: .Ci ab7b48411962d26439f92f35ed084d3d6275459c . meillo@76: Instead, it depends on an external tool to cover this task. meillo@169: Mmh has two paths for messages to enter mmh's mail storage: meillo@100: (1) Mail can be incorporated with meillo@60: .Pn inc meillo@87: from the system maildrop, or (2) with meillo@60: .Pn rcvstore meillo@87: by reading them, one at a time, from the standard input. meillo@60: .P meillo@217: With the removal of the MSA and MRA, mmh converted from a complete meillo@217: mail system to only an MUA. meillo@60: Now, of course, mmh depends on third-party software. meillo@87: An external MSA is required to transfer mail to the outside world; meillo@60: an external MRA is required to retrieve mail from remote machines. meillo@217: Excellent implementations of such software exist. meillo@217: They likely are superior to the internal versions that were removed. meillo@217: Additionally, the best suiting programs can be chosen freely. meillo@60: .P meillo@217: As it had already been possible to use an external MSA and MRA, meillo@217: why should the internal version not be kept for convenience? meillo@217: .\" XXX commas correct? meillo@217: Transfered to a different area, meillo@217: the question whether there is sense in having a fall-back pager in all meillo@76: the command line tools, for the cases when meillo@60: .Pn more meillo@60: or meillo@60: .Pn less meillo@173: are not available, appears to be ridiculous. meillo@100: Of course, MSAs and MRAs are more complex than text pagers meillo@87: and not necessarily available but still the concept of orthogonal meillo@217: design holds: ``Write programs that do one thing and do it well''. meillo@87: .[ meillo@87: mcilroy unix phil meillo@87: p. 53 meillo@87: .] meillo@87: .[ meillo@87: mcilroy bstj foreword meillo@87: .] meillo@87: Here, this part of the Unix philosophy was applied not only meillo@87: to the programs but to the project itself. meillo@87: In other words: meillo@164: Develop projects that focus on one thing and do it well. meillo@169: Projects which have grown complex should be split, for the same meillo@169: reasons that programs which have grown complex should be split. meillo@100: If it is conceptionally more elegant to have the MSA and MRA as meillo@87: separate projects then they should be separated. meillo@217: In my opinion, this is the case. meillo@217: The RFCs suggest this separation by clearly distinguishing the meillo@217: different mail handling tasks [RFC\|821]. meillo@217: The small interfaces between the mail agents support the meillo@217: separation as well. meillo@76: .P meillo@217: Once, email had been small and simple. meillo@100: At that time, meillo@60: .Pn /bin/mail meillo@169: had covered everything there was to email and still was small and simple. meillo@100: Later, the essential complexity of email increased. meillo@217: (Essential complexity is the complexity defined by the problem itself.\& meillo@217: .[ [ meillo@87: brooks no silver bullet meillo@87: .]]) meillo@217: Consequently, email systems grew. meillo@100: RFCs started to introduce the concept of mail agents to separate the meillo@217: various roles because they became more extensive and because meillo@217: new roles appeared. meillo@217: As mail system implementations grew, parts of them were split off. meillo@169: For instance, a POP server was included in the original MH; meillo@169: it was removed in nmh. meillo@217: Now is the time to go one step further and split off the MSA and MRA, meillo@217: as well. meillo@87: Not only does this decrease the code size of the project, meillo@169: more importantly, it unburdens mmh of the whole field of meillo@217: message transfer, with all its implications for the project. meillo@169: There is no more need for concern with changes in network transfer. meillo@217: This independence is gained by depending on external components meillo@217: that cover the field. meillo@60: .P meillo@217: In general, functionality can be added in three different ways: meillo@171: .LI 1 meillo@217: By implementing the function in the project itself. meillo@171: .LI 2 meillo@217: By depending on a library that provides the function. meillo@171: .LI 3 meillo@217: By depending on a program that provides the function. meillo@171: .LP meillo@159: .\" XXX Rework sentence meillo@169: While implementing the function in the project itself leads to the meillo@169: largest increase in code size and requires the most maintenance meillo@169: and development work, meillo@217: it keeps the project's dependence on other software lowest. meillo@169: Using libraries or external programs requires less maintenance work meillo@217: but introduces dependencies on external projects. meillo@169: Programs have the smallest interfaces and provide the best separation, meillo@87: but possibly limit the information exchange. meillo@169: External libraries are more strongly connected than external programs, meillo@169: thus information can be exchanged in a more flexible manner. meillo@87: Adding code to a project increases maintenance work. meillo@87: .\" XXX ref meillo@217: As implementing complex functions in the project itself adds meillo@217: a lot of code, this should be avoided if possible. meillo@217: Thus, the dependencies only change in their character, meillo@169: not in their existence. meillo@66: In mmh, library dependencies on meillo@66: .Pn libsasl2 meillo@66: and meillo@66: .Pn libcrypto /\c meillo@66: .Pn libssl meillo@159: were traded against program dependencies on an MSA and an MRA. meillo@159: This also meant trading build-time dependencies against run-time meillo@87: dependencies. meillo@169: Besides providing stronger separation and greater flexibility, meillo@169: program dependencies also allowed meillo@66: over 6\|000 lines of code to be removed from mmh. meillo@66: This made mmh's code base about 12\|% smaller. meillo@87: Reducing the project's code size by such an amount without actually meillo@87: losing functionality is a convincing argument. meillo@87: Actually, as external MSAs and MRAs are likely superior to the meillo@87: project's internal versions, the common user even gains functionality. meillo@66: .P meillo@169: Users of MH should not have problems setting up an external MSA and MRA. meillo@60: Also, the popular MSAs and MRAs have large communities and a lot meillo@169: of available documentation. meillo@217: meillo@217: Choices for MSAs range from small forwarders such as meillo@217: .[ meillo@217: ssmtp website meillo@217: .] meillo@217: and, meillo@217: .[ meillo@217: nullmailer website meillo@217: .] meillo@217: over mid-size MTAs including meillo@217: .[ meillo@217: masqmail website meillo@217: .] meillo@217: and, meillo@217: .[ meillo@217: dma dragonfly mail agent website meillo@217: .] meillo@217: up to full-featured MTAs as for instance. meillo@217: .[ meillo@217: postfix website meillo@217: .] meillo@217: MRAs are provided for example by meillo@217: .[ [ meillo@217: fetchmail website meillo@217: .] meillo@217: .[ meillo@217: getmail website meillo@217: .] meillo@217: .[ meillo@217: mpop website meillo@217: .] meillo@217: .[ meillo@217: fdm website meillo@217: .]]. meillo@60: meillo@60: meillo@100: .H2 "Non-MUA Tools meillo@60: .P meillo@217: One goal of mmh is to remove the tools that do not significantly meillo@217: contribute to the MUA's job. meillo@217: Loosely related and rarely used tools distract from a lean appearance, meillo@217: and require maintenance work without adding much to the core task. meillo@217: By removing these tools, mmh became more streamlined and focused. meillo@62: .BU meillo@58: .Pn conflict meillo@87: was removed meillo@76: .Ci 8b235097cbd11d728c07b966cf131aa7133ce5a9 meillo@217: because it is a mail system maintenance tool and not MUA-related. meillo@87: It even checked meillo@58: .Fn /etc/passwd meillo@58: and meillo@58: .Fn /etc/group meillo@87: for consistency, which is completely unrelated to email. meillo@87: A tool like meillo@87: .Pn conflict meillo@87: is surely useful, but it should not be shipped with mmh. meillo@76: .\" XXX historic reasons? meillo@62: .BU meillo@58: .Pn rcvtty meillo@87: was removed meillo@87: .Ci 14767c94b3827be7c867196467ed7aea5f6f49b0 meillo@89: because its use case of writing to the user's terminal meillo@200: on reception of mail is obsolete. meillo@87: If users like to be informed of new mail, the shell's meillo@58: .Ev MAILPATH meillo@87: variable or graphical notifications are technically more appealing. meillo@217: Writing to terminals directly is hardly ever desired today. meillo@169: If, though, one prefers this approach, the standard tool meillo@58: .Pn write meillo@58: can be used in a way similar to: meillo@82: .VS meillo@58: scan -file - | write `id -un` meillo@82: VE meillo@62: .BU meillo@58: .Pn viamail meillo@159: .\" XXX was macht viamail meillo@87: was removed meillo@87: .Ci eda72d6a7a7c20ff123043fb7f19c509ea01f932 meillo@87: when the new attachment system was activated, because meillo@58: .Pn forw meillo@76: could then cover the task itself. meillo@62: The program meillo@58: .Pn sendfiles meillo@62: was rewritten as a shell script wrapper around meillo@58: .Pn forw . meillo@76: .Ci 0e82199cf3c991a173e0ac8aa776efdb3ded61e6 meillo@62: .BU meillo@58: .Pn msgchk meillo@159: .\" XXX was macht msgchk meillo@87: was removed meillo@87: .Ci bb9360ead7eb7a3fedcce2eeedfc660014e41dbe , meillo@87: because it lost its use case when POP support was removed. meillo@76: A call to meillo@58: .Pn msgchk meillo@87: provided hardly more information than: meillo@82: .VS meillo@58: ls -l /var/mail/meillo meillo@82: VE meillo@217: Yet, it distinguished between old and new mail, but meillo@169: these details can be retrieved with meillo@76: .Pn stat (1), meillo@62: too. meillo@100: A small shell script could be written to print the information meillo@76: in a similar way, if truly necessary. meillo@76: As mmh's meillo@76: .Pn inc meillo@87: only incorporates mail from the user's local maildrop, meillo@62: and thus no data transfers over slow networks are involved, meillo@169: there is hardly any need to check for new mail before incorporating it. meillo@62: .BU meillo@58: .Pn msh meillo@87: was removed meillo@76: .Ci 916690191222433a6923a4be54b0d8f6ac01bd02 meillo@87: because the tool was in conflict with the philosophy of MH. meillo@217: It provided an interactive shell to access the features of MH. meillo@217: However, it was not just a shell tailored to the needs of mail handling, meillo@217: but one large program that had several MH tools built in. meillo@217: This conflicted with the major feature of MH of being a tool chest. meillo@76: .Pn msh 's meillo@159: main use case had been accessing Bulletin Boards, which have ceased to meillo@62: be popular. meillo@62: .P meillo@62: Removing meillo@169: .Pn msh meillo@212: together with the truly archaic code relics meillo@58: .Pn vmh meillo@58: and meillo@169: .Pn wmh meillo@62: saved more than 7\|000 lines of C code \(en meillo@66: about 15\|% of the project's original source code amount. meillo@100: Having less code \(en with equal readability, of course \(en meillo@76: for the same functionality is an advantage. meillo@63: Less code means less bugs and less maintenance work. meillo@76: As meillo@63: .Pn rcvtty meillo@63: and meillo@63: .Pn msgchk meillo@87: are assumed to be rarely used and can be implemented in different ways, meillo@87: why should one keep them? meillo@217: Removing them streamlined mmh. meillo@63: .Pn viamail 's meillo@63: use case is now partly obsolete and partly covered by meillo@63: .Pn forw , meillo@217: hence there is no reason to still maintain it. meillo@63: .Pn conflict meillo@76: is not related to the mail client, and meillo@63: .Pn msh meillo@63: conflicts with the basic concept of MH. meillo@169: These two tools might still be useful, but they should not be part of mmh. meillo@63: .P meillo@220: .Id slocal meillo@169: Finally, there is meillo@217: .Pn slocal , meillo@217: which is an MDA and thus not directly MUA-related. meillo@217: It should be removed from mmh because including it conflicts with meillo@178: the idea that mmh is an MUA only. meillo@87: However, meillo@76: .Pn slocal meillo@76: provides rule-based processing of messages, like filing them into meillo@76: different folders, which is otherwise not available in mmh. meillo@87: Although meillo@76: .Pn slocal meillo@169: neither pulls in dependencies, nor does it include a separate meillo@154: technical area (cf. Sec. meillo@154: .Cf mail-transfer-facilities ), meillo@169: it still accounts for about 1\|000 lines of code that need to be maintained. meillo@76: As meillo@76: .Pn slocal meillo@76: is almost self-standing, it should be split off into a separate project. meillo@76: This would cut the strong connection between the MUA mmh and the MDA meillo@76: .Pn slocal . meillo@87: For anyone not using MH, meillo@87: .Pn slocal meillo@87: would become yet another independent MDA, like meillo@87: .I procmail . meillo@100: Then meillo@87: .Pn slocal meillo@217: could be installed without a complete MH system. meillo@76: Likewise, mmh users could decide to use meillo@76: .I procmail meillo@217: without having a second, unused MDA, i.e. meillo@87: .Pn slocal , meillo@76: installed. meillo@100: That appears to be conceptionally the best solution. meillo@76: Yet, meillo@76: .Pn slocal meillo@87: is not split off. meillo@100: I defer the decision over meillo@78: .Pn slocal meillo@169: out of a need for deeper investigation. meillo@217: In the meanwhile, it remains part of mmh meillo@217: as its continued existence is not significant; meillo@100: .Pn slocal meillo@100: is unrelated to the rest of the project. meillo@0: meillo@58: meillo@133: meillo@134: .H2 "Displaying Messages meillo@155: .Id mhshow meillo@131: .P meillo@133: Since the very beginning, already in the first concept paper, meillo@159: .\" XXX ref!!! meillo@58: .Pn show meillo@62: had been MH's message display program. meillo@58: .Pn show meillo@76: mapped message numbers and sequences to files and invoked meillo@58: .Pn mhl meillo@89: to have the files formatted. meillo@173: With MIME, this approach was not sufficient anymore. meillo@217: MIME messages can consist of multiple parts. meillo@217: Some parts, like binary attachments or text content in foreign charsets, meillo@217: are not directly displayable. meillo@58: .Pn show 's meillo@76: understanding of messages and meillo@58: .Pn mhl 's meillo@173: display capabilities could not cope with the task any longer. meillo@62: .P meillo@88: Instead of extending these tools, additional tools were written from meillo@217: scratch and were added to the MH tool chest. meillo@88: Doing so is encouraged by the tool chest approach. meillo@88: Modular design is a great advantage for extending a system, meillo@88: as new tools can be added without interfering with existing ones. meillo@62: First, the new MIME features were added in form of the single program meillo@58: .Pn mhn . meillo@58: The command meillo@82: .Cl "mhn -show 42 meillo@217: had then shown the message number meillo@217: .Fn 42 , meillo@217: interpreting MIME. meillo@58: With the 1.0 release of nmh in February 1999, Richard Coleman finished meillo@58: the split of meillo@58: .Pn mhn meillo@88: into a set of specialized tools, which together covered the meillo@88: multiple aspects of MIME. meillo@88: One of them was meillo@69: .Pn mhshow , meillo@88: which replaced meillo@88: .Cl "mhn -show" . meillo@88: It was capable of displaying MIME messages appropriately. meillo@62: .P meillo@88: From then on, two message display tools were part of nmh, meillo@76: .Pn show meillo@76: and meillo@76: .Pn mhshow . meillo@88: To ease the life of users, meillo@69: .Pn show meillo@69: was extended to automatically hand the job over to meillo@69: .Pn mhshow meillo@69: if displaying the message would be beyond meillo@69: .Pn show 's meillo@69: abilities. meillo@88: In consequence, the user would simply invoke meillo@69: .Pn show meillo@69: (possibly through meillo@69: .Pn next meillo@69: or meillo@69: .Pn prev ) meillo@69: and get the message printed with either meillo@69: .Pn show meillo@69: or meillo@69: .Pn mhshow , meillo@69: whatever was more appropriate. meillo@69: .P meillo@217: Having two similar tools for basically the same task is redundancy. meillo@217: Usually, users do not distinguish between meillo@88: .Pn show meillo@88: and meillo@88: .Pn mhshow meillo@88: in their daily mail reading. meillo@217: Having two separate display programs was therefore unnecessary meillo@88: from a user's point of view. meillo@88: Besides, the development of both programs needed to be in sync, meillo@76: to ensure that the programs behaved in a similar way, meillo@76: because they were used like a single tool. meillo@76: Different behavior would have surprised the user. meillo@69: .P meillo@69: Today, non-MIME messages are rather seen to be a special case of meillo@100: MIME messages, although it is the other way round. meillo@69: As meillo@69: .Pn mhshow meillo@217: already had been able to display non-MIME messages, it appeared natural meillo@69: to drop meillo@69: .Pn show meillo@69: in favor of using meillo@69: .Pn mhshow meillo@217: exclusively meillo@217: .Ci 4c1efddfd499300c7e74263e57d8aa137e84c853 . meillo@88: Removing meillo@88: .Pn show meillo@217: is no loss in function, because meillo@88: .Pn mhshow meillo@88: covers it completely. meillo@217: Yet, the old behavior of meillo@88: .Pn show meillo@88: can still be emulated with the simple command line: meillo@88: .VS meillo@88: mhl `mhpath c` meillo@88: VE meillo@88: .P meillo@76: For convenience, meillo@76: .Pn mhshow meillo@88: was renamed to meillo@88: .Pn show meillo@88: after meillo@88: .Pn show meillo@88: was gone. meillo@88: It is clear that such a rename may confuse future developers when meillo@88: trying to understand the history. meillo@88: Nevertheless, I consider the convenience on the user's side, meillo@217: to outweigh the inconvenience for understanding the evolution meillo@217: of the tools. meillo@69: .P meillo@88: To prepare for the transition, meillo@69: .Pn mhshow meillo@69: was reworked to behave more like meillo@69: .Pn show meillo@217: first (cf. Sec. meillo@217: .Cf mhshow ). meillo@164: .\" XXX code commits? meillo@88: Once the tools behaved more alike, the replacing appeared to be meillo@88: even more natural. meillo@88: Today, mmh's new meillo@69: .Pn show meillo@217: has become the one single message display program once again, meillo@159: with the difference meillo@88: that today it handles MIME messages as well as non-MIME messages. meillo@217: The outcomes of the transition are one program less to maintain, meillo@88: no second display program for users to deal with, meillo@88: and less system complexity. meillo@69: .P meillo@88: Still, removing the old meillo@69: .Pn show meillo@88: hurts in one regard: It had been such a simple program. meillo@159: Its lean elegance is missing from the new meillo@159: .Pn show , meillo@159: .\" XXX meillo@159: however there is no alternative; meillo@159: supporting MIME demands higher essential complexity. meillo@58: meillo@134: .ig meillo@134: XXX meillo@134: Consider including text on scan listings here meillo@58: meillo@134: Scan listings shall not contain body content. Hence, removed this feature. meillo@134: Scan listings shall operator on message headers and non-message information meillo@134: only. Displaying the beginning of the body complicates everything too much. meillo@134: That's no surprise, because it's something completely different. If you meillo@134: want to examine the body, then use show(1)/mhshow(1). meillo@134: Changed the default scan formats accordingly. meillo@134: .Ci 70b2643e0da8485174480c644ad9785c84f5bff4 meillo@134: .. meillo@131: meillo@131: meillo@131: meillo@133: meillo@100: .H2 "Configure Options meillo@58: .P meillo@76: Customization is a double-edged sword. meillo@76: It allows better suiting setups, but not for free. meillo@76: There is the cost of code complexity to be able to customize. meillo@76: There is the cost of less tested setups, because there are meillo@171: more possible setups and especially corner cases. meillo@159: Additionally, there is the cost of choice itself. meillo@76: The code complexity directly affects the developers. meillo@173: Less tested code affects both users and developers. meillo@217: The problem of choice affects the users, for once by having to choose meillo@159: but also by more complex interfaces that require more documentation. meillo@159: Whenever options add few advantages but increase the complexity of the meillo@159: system, they should be considered for removal. meillo@72: I have reduced the number of project-specific configure options from meillo@217: 15 to 3. meillo@74: meillo@76: .U3 "Mail Transfer Facilities meillo@74: .P meillo@217: With the removal of the mail transfer facilities 5 configure meillo@85: options vanished: meillo@85: .P meillo@85: The switches meillo@85: .Sw --with-tls meillo@85: and meillo@85: .Sw --with-cyrus-sasl meillo@89: had activated the support for transfer encryption and authentication. meillo@159: .\" XXX cf meillo@159: .\" XXX gruende kurz wiederholen meillo@217: They are not needed anymore. meillo@85: .Ci fecd5d34f65597a4dfa16aeabea7d74b191532c3 meillo@85: .Ci 156d35f6425bea4c1ed3c4c79783dc613379c65b meillo@85: .P meillo@159: .\" XXX cf meillo@159: .\" XXX ``For the same reason ...'' meillo@85: The configure switch meillo@85: .Sw --enable-pop meillo@85: activated the message retrieval facility. meillo@217: Whereas the code area that had been conditionally compiled in meillo@217: for TLS and SASL support was small, meillo@217: the conditionally compiled code area for POP support was much larger. meillo@217: The code base had only changed slightly on toggling TLS or SASL meillo@217: support but it had changed much on toggling POP support. meillo@85: The changes in the code base could hardly be overviewed. meillo@159: By having POP support togglable, a second code base had been created, meillo@85: one that needed to be tested. meillo@85: This situation is basically similar for the conditional TLS and SASL meillo@85: code, but there the changes are minor and can yet be overviewed. meillo@85: Still, conditional compilation of a code base creates variations meillo@85: of the original program. meillo@85: More variations require more testing and maintenance work. meillo@85: .P meillo@85: Two other options only specified default configuration values: meillo@100: .Sw --with-mts meillo@217: defined the default transport service meillo@217: .Ci f6aa95b724fd8c791164abe7ee5468bf5c34f226 . meillo@85: With meillo@100: .Sw --with-smtpservers meillo@217: default SMTP servers could be specified meillo@217: .Ci 128545e06224233b7e91fc4c83f8830252fe16c9 . meillo@164: Both of them became irrelevant when the SMTP transport service was removed. meillo@164: .\" XXX code ref meillo@164: In mmh, all messages are handed over to meillo@164: .Pn sendmail meillo@164: for transportation. meillo@164: meillo@72: meillo@74: .U3 "Backup Prefix meillo@74: .P meillo@76: The backup prefix is the string that was prepended to message meillo@76: filenames to tag them as deleted. meillo@173: By default it had been the comma character (`\fL,\fP'). meillo@159: .\" XXX Zeitlich ordnen meillo@78: In July 2000, Kimmo Suominen introduced meillo@78: the configure option meillo@78: .Sw --with-hash-backup meillo@173: to change the default to the hash character `\f(CW#\fP'. meillo@217: This choice was probably personal preference, but, meillo@217: being related or not, words that start with the hash character meillo@78: introduce a comment in the Unix shell. meillo@72: Thus, the command line meillo@72: .Cl "rm #13 #15 meillo@72: calls meillo@72: .Pn rm meillo@217: without arguments because the first hash character starts a comment meillo@72: that reaches until the end of the line. meillo@72: To delete the backup files, meillo@72: .Cl "rm ./#13 ./#15" meillo@72: needs to be used. meillo@217: Thus, using the hash as backup prefix may be seen as a precaution meillo@217: against backup loss. meillo@78: .P meillo@159: First, I removed the configure option but added the profile entry meillo@217: .Pe Backup-Prefix , meillo@217: which allowed to specify an arbitrary string as backup prefix meillo@217: .Ci 6c40d481d661d532dd527eaf34cebb6d3f8ed086 . meillo@76: This change did not remove the choice but moved it to a location where meillo@217: it suited better, in my eyes. meillo@76: .P meillo@217: Eventually however, the new trash folder concept meillo@154: (cf. Sec. meillo@154: .Cf trash-folder ) meillo@164: removed the need for the backup prefix completely. meillo@78: .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173 meillo@133: .Ci ca0b3e830b86700d9e5e31b1784de2bdcaf58fc5 meillo@133: meillo@76: meillo@76: .U3 "Editor and Pager meillo@74: .P meillo@74: The two configure options meillo@74: .CW --with-editor=EDITOR meillo@74: .CW --with-pager=PAGER meillo@74: were used to specify the default editor and pager at configure time. meillo@109: Doing so at configure time made sense in the eighties, meillo@76: when the set of available editors and pagers varied much across meillo@76: different systems. meillo@89: Today, the situation is more homogeneous. meillo@74: The programs meillo@74: .Pn vi meillo@74: and meillo@74: .Pn more meillo@76: can be expected to be available on every Unix system, meillo@74: as they are specified by POSIX since two decades. meillo@74: (The specifications for meillo@74: .Pn vi meillo@74: and meillo@74: .Pn more meillo@74: appeared in meillo@74: .[ meillo@74: posix 1987 meillo@74: .] meillo@74: and, meillo@74: .[ meillo@74: posix 1992 meillo@74: .] meillo@74: respectively.) meillo@217: As a first step, these two tools were hard-coded as defaults meillo@217: .Ci 5d43a99db70c12a673028c7758c20cbe3e13ef5f . meillo@74: Not changed were the meillo@74: .Pe editor meillo@74: and meillo@74: .Pe moreproc meillo@76: profile entries, which allowed the user to override the system defaults. meillo@217: Later, the concept was reworked again to respect the standard meillo@217: environment variables meillo@74: .Ev VISUAL meillo@74: and meillo@74: .Ev PAGER meillo@76: if they are set. meillo@74: Today, mmh determines the editor to use in the following order, meillo@217: taking the first available and non-empty item meillo@217: .Ci f85f4b7ae62e3d05a945dcd46ead51f0a2a89a9b : meillo@171: .LI 1 meillo@74: Environment variable meillo@74: .Ev MMHEDITOR meillo@171: .LI 2 meillo@74: Profile entry meillo@74: .Pe Editor meillo@171: .LI 3 meillo@74: Environment variable meillo@74: .Ev VISUAL meillo@171: .LI 4 meillo@74: Environment variable meillo@74: .Ev EDITOR meillo@171: .LI 5 meillo@74: Command meillo@74: .Pn vi . meillo@171: .LP meillo@217: The pager to use is determined in a similar order meillo@217: .Ci 0c4214ea2aec6497d0d67b436bbee9bc1d225f1e : meillo@171: .LI 1 meillo@74: Environment variable meillo@74: .Ev MMHPAGER meillo@171: .LI 2 meillo@74: Profile entry meillo@74: .Pe Pager meillo@74: (replaces meillo@74: .Pe moreproc ) meillo@171: .LI 3 meillo@74: Environment variable meillo@74: .Ev PAGER meillo@171: .LI 4 meillo@74: Command meillo@74: .Pn more . meillo@171: .LP meillo@76: By respecting the meillo@74: .Ev VISUAL /\c meillo@74: .Ev EDITOR meillo@74: and meillo@74: .Ev PAGER meillo@76: environment variables, meillo@217: the new behavior complies with the common style on Unix systems. meillo@217: It is more uniform and clearer for users. meillo@72: meillo@72: meillo@76: .U3 "ndbm meillo@72: .P meillo@74: .Pn slocal meillo@217: used to depend on the database library meillo@217: .I ndbm . meillo@217: The database is used to store the meillo@217: .Hd Message-ID meillo@217: header field values of all messages delivered. meillo@217: This enabled meillo@74: .Pn slocal meillo@74: to suppress delivering the same message to the same user twice. meillo@217: This features was enabled by the meillo@74: .Sw -suppressdup meillo@217: switch. meillo@74: .P meillo@217: As a variety of versions of the database library exist, meillo@78: .[ meillo@78: wolter unix incompat notes dbm meillo@78: .] meillo@217: complicated autoconf code was needed to detect them correctly. meillo@181: Furthermore, the configure switches meillo@74: .Sw --with-ndbm=ARG meillo@74: and meillo@74: .Sw --with-ndbmheader=ARG meillo@74: were added to help with difficult setups that would meillo@217: not be detected automatically or not correctly. meillo@74: .P meillo@74: By removing the suppress duplicates feature of meillo@74: .Pn slocal , meillo@74: the dependency on meillo@74: .I ndbm meillo@217: vanished and 120 lines of complex autoconf code could be saved meillo@217: .Ci ecd6d6a20cb7a1507e3a20d6c4cb3a1cf14c6bbf . meillo@217: The change removed functionality but that is considered minor to the meillo@217: improvement of dropping the dependency and the complex autoconf code. meillo@159: .\" XXX argument: slocal ist sowieso nicht teil vom mmh kern meillo@72: meillo@217: .U3 "MH-E Support meillo@72: .P meillo@74: The configure option meillo@74: .Sw --disable-mhe meillo@217: was removed when the MH-E support was reworked. meillo@217: MH-E is the Emacs front-end to MH. meillo@217: .[ meillo@217: mh-e emacs website meillo@217: .] meillo@76: It requires MH to provide minor additional functions. meillo@76: The meillo@76: .Sw --disable-mhe meillo@217: configure option had switched off these extensions. meillo@217: After removing the support for old versions of MH-E, meillo@74: only the meillo@74: .Sw -build meillo@76: switches of meillo@74: .Pn forw meillo@74: and meillo@74: .Pn repl meillo@217: are left to be MH-E extensions. meillo@76: They are now always built in because they add little code and complexity. meillo@76: In consequence, the meillo@74: .Sw --disable-mhe meillo@76: configure option was removed meillo@217: .Ci a7ce7b4a580d77b6c2c4d980812beb589aa4c643 . meillo@217: Dropping the option also removed a variant of the code base meillo@217: that would have needed to be tested. meillo@217: This change was undertaken in January 2012 in nmh and meillo@217: thereafter merged into mmh. meillo@217: meillo@72: meillo@74: .U3 "Masquerading meillo@72: .P meillo@74: The configure option meillo@74: .Sw --enable-masquerade meillo@76: could take up to three arguments: meillo@217: .Ar draft_from , meillo@217: .Ar mmailid , meillo@217: and meillo@217: .Ar username_extension . meillo@74: They activated different types of address masquerading. meillo@74: All of them were implemented in the SMTP-speaking meillo@74: .Pn post meillo@217: command. meillo@76: Address masquerading is an MTA's task and mmh does not cover meillo@76: this field anymore. meillo@76: Hence, true masquerading needs to be implemented in the external MTA. meillo@74: .P meillo@74: The meillo@74: .I mmailid meillo@74: masquerading type is the oldest one of the three and the only one meillo@74: available in the original MH. meillo@74: It provided a meillo@74: .I username meillo@74: to meillo@74: .I fakeusername meillo@217: mapping, based on the meillo@217: .Fn passwd 's meillo@217: GECOS field. meillo@217: Nmh's man page meillo@181: .Mp mh-tailor (5) meillo@74: described the use case as being the following: meillo@98: .QS meillo@74: This is useful if you want the messages you send to always meillo@74: appear to come from the name of an MTA alias rather than your meillo@74: actual account name. For instance, many organizations set up meillo@74: `First.Last' sendmail aliases for all users. If this is meillo@74: the case, the GECOS field for each user should look like: meillo@74: ``First [Middle] Last '' meillo@98: .QE meillo@74: .P meillo@74: As mmh sends outgoing mail via the local MTA only, meillo@76: the best location to do such global rewrites is there. meillo@74: Besides, the MTA is conceptionally the right location because it meillo@74: does the reverse mapping for incoming mail (aliasing), too. meillo@181: Furthermore, masquerading set up there is readily available for all meillo@74: mail software on the system. meillo@76: Hence, mmailid masquerading was removed. meillo@74: .Ci 0836c8000ccb34b59410ef1c15b1b7feac70ce5f meillo@74: .P meillo@74: The meillo@74: .I username_extension meillo@76: masquerading type did not replace the username but would append a suffix, meillo@76: specified by the meillo@74: .Ev USERNAME_EXTENSION meillo@76: environment variable, to it. meillo@76: This provided support for the meillo@74: .I user-extension meillo@217: feature of qmail meillo@217: .[ [ meillo@217: sill qmail handbook meillo@217: .], p. 141] meillo@217: and the similar meillo@74: .I "plussed user meillo@217: processing of Sendmail. meillo@217: .[ [ meillo@217: sendmail costales meillo@217: .], p. 476] meillo@217: The decision to remove this username_extension masquerading meillo@217: was motivated by the fact that meillo@74: .Pn spost meillo@217: had not supported it yet. meillo@217: Username extensions can be used in mmh, but less convenient. meillo@159: .\" XXX covered by next paragraph meillo@76: .\" XXX format file %(getenv USERNAME_EXTENSION) meillo@217: .Ci 2abae0bfd0ad5bf898461e50aa4b466d641f23d9 meillo@74: .P meillo@74: The meillo@74: .I draft_from meillo@74: masquerading type instructed meillo@74: .Pn post meillo@84: to use the value of the meillo@84: .Hd From meillo@84: header field as SMTP envelope sender. meillo@76: Sender addresses could be replaced completely. meillo@76: Mmh offers a kind of masquerading similar in effect, but meillo@74: with technical differences. meillo@76: As mmh does not transfer messages itself, the local MTA has final control meillo@217: over the sender's address. meillo@217: Any masquerading mmh introduces may be reverted by the MTA. meillo@76: In times of pedantic spam checking, an MTA will take care to use meillo@76: sensible envelope sender addresses to keep its own reputation up. meillo@84: Nonetheless, the MUA can set the meillo@84: .Hd From meillo@217: header field and thereby propose a sender address to the MTA. meillo@74: The MTA may then decide to take that one or generate the canonical sender meillo@74: address for use as envelope sender address. meillo@217: .Ci b14ea6073f77b4359aaf3fddd0e105989db9 meillo@74: .P meillo@74: In mmh, the MTA will always extract the recipient and sender from the meillo@84: message header (\c meillo@74: .Pn sendmail 's meillo@74: .Sw -t meillo@74: switch). meillo@84: The meillo@84: .Hd From meillo@84: header field of the draft may be set arbitrary by the user. meillo@74: If it is missing, the canonical sender address will be generated by the MTA. meillo@74: meillo@74: .U3 "Remaining Options meillo@74: .P meillo@74: Two configure options remain in mmh. meillo@74: One is the locking method to use: meillo@74: .Sw --with-locking=[dot|fcntl|flock|lockf] . meillo@217: The idea of removing all methods except the portable meillo@217: .I "dot locking meillo@76: and having that one as the default is appealing, but this change meillo@76: requires deeper technical investigation into the topic. meillo@76: The other option, meillo@74: .Sw --enable-debug , meillo@217: compiles the programs with debugging symbols. meillo@74: This option is likely to stay. meillo@72: meillo@72: meillo@58: meillo@63: meillo@100: .H2 "Command Line Switches meillo@58: .P meillo@217: The command line switches of MH tools follow a style similar to meillo@217: the X Window System style. meillo@171: .\" XXX ref meillo@217: The switches consist of a single dash (`\fL-\fP') followed by a word. meillo@217: For example meillo@217: .Cl -truncate . meillo@212: To ease typing, the word can be abbreviated, given the remaining meillo@217: prefix is unambiguous. meillo@212: If no other switch starts with the letter `t', then any of meillo@212: .Cl "-truncate" , meillo@212: .Cl "-trunc" , meillo@212: .Cl "-tr" , meillo@212: and meillo@212: .Cl "-t meillo@212: is equal. meillo@212: As a result, switches can neither be grouped (as in meillo@212: .Cl "ls -ltr" ) meillo@212: nor can switch arguments be appended directly to the switch (as in meillo@212: .Cl "sendmail -q30m" ). meillo@212: Many switches have negating counter-parts, which start with `no'. meillo@212: For example meillo@212: .Cl "-notruncate meillo@212: inverts the meillo@212: .Cl "-truncate meillo@212: switch. meillo@212: They exist to override the effect of default switches in the profile. meillo@93: Every program in mmh has two generic switches: meillo@93: .Sw -help , meillo@93: to print a short message on how to use the program, and meillo@159: .Sw -Version meillo@164: (with capital `V'), to tell what version of mmh the program belongs to. meillo@93: .P meillo@93: Switches change the behavior of programs. meillo@93: Programs that do one thing in one way require no switches. meillo@93: In most cases, doing something in exactly one way is too limiting. meillo@217: If one task should be accomplished in various ways, meillo@217: switches are a good approach to alter the behavior of a program. meillo@93: Changing the behavior of programs provides flexibility and customization meillo@217: to users, but at the same time it complicates the code, meillo@217: the documentation, and the usage of the program. meillo@97: .\" XXX: Ref meillo@93: Therefore, the number of switches should be kept small. meillo@217: A small set of well-chosen switches is best. meillo@217: Usually, the number of switches increases over time. meillo@93: Already in 1985, Rose and Romine have identified this as a major meillo@93: problem of MH: meillo@93: .[ [ meillo@93: rose romine real work meillo@93: .], p. 12] meillo@98: .QS meillo@93: A complaint often heard about systems which undergo substantial development meillo@93: by many people over a number of years, is that more and more options are meillo@93: introduced which add little to the functionality but greatly increase the meillo@93: amount of information a user needs to know in order to get useful work done. meillo@93: This is usually referred to as creeping featurism. meillo@93: .QP meillo@93: Unfortunately MH, having undergone six years of off-and-on development by meillo@93: ten or so well-meaning programmers (the present authors included), meillo@93: suffers mightily from this. meillo@98: .QE meillo@93: .P meillo@217: Being reluctant to adding new switches (or \fIoptions\fP, meillo@217: as Rose and Romine call them) is one part of a counter-action, meillo@97: the other part is removing hardly used switches. meillo@217: Nmh's tools have lots of switches already implemented. meillo@217: Hence, cleaning up by removing some of them was the more important part meillo@97: of the counter-action. meillo@93: Removing existing functionality is always difficult because it meillo@93: breaks programs that use these functions. meillo@93: Also, for every obsolete feature, there'll always be someone who still meillo@93: uses it and thus opposes its removal. meillo@93: This puts the developer into the position, meillo@93: where sensible improvements to style are regarded as destructive acts. meillo@97: Yet, living with the featurism is far worse, in my eyes, because meillo@97: future needs will demand adding further features, meillo@93: worsening the situation more and more. meillo@93: Rose and Romine added in a footnote, meillo@93: ``[...] meillo@93: .Pn send meillo@217: will no doubt acquire an endless number of switches in the years to come'' meillo@217: .[ [ meillo@217: rose romine real work meillo@217: .], p. 12]. meillo@97: Although clearly humorous, the comment points to the nature of the problem. meillo@97: Refusing to add any new switches would encounter the problem at its root, meillo@97: but this is not practical. meillo@97: New needs will require new switches and it would be unwise to block meillo@97: them strictly. meillo@97: Nevertheless, removing obsolete switches still is an effective approach meillo@97: to deal with the problem. meillo@97: Working on an experimental branch without an established user base, meillo@97: eased my work because I did not offend users when I removed existing meillo@110: functions. meillo@93: .P meillo@93: Rose and Romine counted 24 visible and 9 more hidden switches for meillo@93: .Pn send . meillo@97: In nmh, they increased up to 32 visible and 12 hidden ones. meillo@182: At the time of writing, no more than 4 visible switches and 1 hidden switch meillo@97: have remained in mmh's meillo@97: .Pn send . meillo@217: These numbers include the two generic switches, meillo@182: .Sw -help meillo@182: and meillo@183: .Sw -Version . meillo@217: .P meillo@183: Hidden switches are ones not documented. meillo@183: In mmh, 12 tools have hidden switches. meillo@183: 9 of them are meillo@183: .Sw -debug meillo@183: switches, the other 6 provide special interfaces for internal use. meillo@93: .P meillo@217: The following figure displays the number of switches for each of the tools meillo@159: that is available in both nmh and mmh. meillo@100: The tools are sorted by the number of switches they had in nmh. meillo@217: Both visible and hidden switches were counted, meillo@97: but not the generic help and version switches. meillo@93: Whereas in the beginning of the project, the average tool had 11 switches, meillo@93: now it has no more than 5 \(en only half as many. meillo@93: If the `no' switches and similar inverse variant are folded onto meillo@100: their counter-parts, the average tool had 8 switches in pre-mmh times and meillo@100: has 4 now. meillo@93: The total number of functional switches in mmh dropped from 465 meillo@182: to 233. meillo@58: meillo@93: .KS meillo@93: .in 1c meillo@93: .so input/switches.grap meillo@93: .KE meillo@58: meillo@93: .P meillo@93: A part of the switches vanished after functions were removed. meillo@93: This was the case for network mail transfer, for instance. meillo@97: Sometimes, however, the work flow was the other way: meillo@97: I looked through the meillo@97: .Mp mh-chart (7) meillo@97: man page to identify the tools with apparently too many switches. meillo@217: Then I considered the benefit of each switch by examining meillo@217: the tool's man page and source code, aided by literature research meillo@217: and testing. meillo@97: meillo@58: meillo@93: .U3 "Draft Folder Facility meillo@93: .P meillo@100: A change early in the project was the complete transition from meillo@217: the single draft message to the draft folder facility meillo@217: .Ci 337338b404931f06f0db2119c9e145e8ca5a9860 . meillo@164: .\" XXX ref to section ... meillo@109: The draft folder facility was introduced in the mid-eighties, when meillo@100: Rose and Romine called it a ``relatively new feature''. meillo@93: .[ meillo@93: rose romine real work meillo@93: .] meillo@217: Since then, the facility was included, inactive by default. meillo@217: By making it permanently active and by related rework of the tools, the meillo@93: .Sw -[no]draftfolder , meillo@93: and meillo@93: .Sw -draftmessage meillo@217: switches could be removed from meillo@93: .Pn comp , meillo@93: .Pn repl , meillo@93: .Pn forw , meillo@93: .Pn dist , meillo@93: .Pn whatnow , meillo@93: and meillo@217: .Pn send meillo@217: .Ci 337338b404931f06f0db2119c9e145e8ca5a9860 . meillo@217: The only flexibility lost with this change is having multiple meillo@97: draft folders within one profile. meillo@97: I consider this a theoretical problem only. meillo@159: At the same time, the meillo@93: .Sw -draft meillo@93: switch of meillo@93: .Pn anno , meillo@93: .Pn refile , meillo@93: and meillo@93: .Pn send meillo@93: was removed. meillo@159: The special treatment of \fIthe\fP draft message became irrelevant after meillo@217: the rework of the draft system meillo@159: (cf. Sec. meillo@217: .Cf draft-folder ). meillo@164: Furthermore, meillo@95: .Pn comp meillo@164: no longer needs a meillo@95: .Sw -file meillo@164: switch as the draft folder facility together with the meillo@95: .Sw -form meillo@164: switch are sufficient. meillo@93: meillo@95: meillo@102: .U3 "In Place Editing meillo@93: .P meillo@93: .Pn anno meillo@93: had the switches meillo@93: .Sw -[no]inplace meillo@100: to either annotate the message in place and thus preserve hard links, meillo@217: or annotate a copy to replace the original message. meillo@217: The latter approach broke hard links. meillo@97: Following the assumption that linked messages should truly be the meillo@217: same message and annotating it should not break the link, the meillo@93: .Sw -[no]inplace meillo@93: switches were removed and the previous default meillo@93: .Sw -inplace meillo@217: was made the definitive behavior meillo@217: .Ci c8195849d2e366c569271abb0f5f60f4ebf0b4d0 . meillo@93: The meillo@93: .Sw -[no]inplace meillo@93: switches of meillo@93: .Pn repl , meillo@93: .Pn forw , meillo@93: and meillo@93: .Pn dist meillo@217: could be removed, as well, as they were simply passed through to meillo@93: .Pn anno . meillo@93: .P meillo@93: .Pn burst meillo@93: also had meillo@93: .Sw -[no]inplace meillo@217: switches, but with a different meaning. meillo@95: With meillo@95: .Sw -inplace , meillo@95: the digest had been replaced by the table of contents (i.e. the meillo@110: introduction text) and the burst messages were placed right meillo@95: after this message, renumbering all following messages. meillo@95: Also, any trailing text of the digest was lost, though, meillo@95: in practice, it usually consists of an end-of-digest marker only. meillo@217: Nonetheless, this behavior appeared less elegant than the meillo@95: .Sw -noinplace meillo@95: behavior, which already had been the default. meillo@95: Nmh's meillo@95: .Mp burst (1) meillo@95: man page reads: meillo@98: .QS meillo@164: If meillo@164: .Sw -noinplace meillo@164: is given, each digest is preserved, no table meillo@93: of contents is produced, and the messages contained within meillo@93: the digest are placed at the end of the folder. Other messages meillo@93: are not tampered with in any way. meillo@98: .QE meillo@95: .LP meillo@93: The decision to drop the meillo@93: .Sw -inplace meillo@95: behavior was supported by the code complexity and the possible data loss meillo@95: it caused. meillo@93: .Sw -noinplace meillo@95: was chosen to be the definitive behavior. meillo@97: .Ci 68a686adeb39223a5e1ad35e4a24890ec053679d meillo@93: meillo@95: meillo@95: .U3 "Forms and Format Strings meillo@93: .P meillo@95: Historically, the tools that had meillo@95: .Sw -form meillo@95: switches to supply a form file had meillo@95: .Sw -format meillo@95: switches as well to supply the contents of a form file as a string meillo@95: on the command line directly. meillo@95: In consequence, the following two lines equaled: meillo@95: .VS meillo@95: scan -form scan.mailx meillo@217: scan -format "`cat /path/to/scan.mailx`" meillo@95: VE meillo@95: The meillo@95: .Sw -format meillo@95: switches were dropped in favor for extending the meillo@95: .Sw -form meillo@217: switches meillo@217: .Ci f51956be123db66b00138f80464d06f030dbb88d . meillo@217: If their argument starts with an equal sign (`\fL=\fP'), meillo@95: then the rest of the argument is taken as a format string, meillo@95: otherwise the arguments is treated as the name of a format file. meillo@95: Thus, now the following two lines equal: meillo@95: .VS meillo@95: scan -form scan.mailx meillo@217: scan -form "=`cat /path/to/scan.mailx`" meillo@95: VE meillo@95: This rework removed the prefix collision between meillo@95: .Sw -form meillo@95: and meillo@95: .Sw -format . meillo@217: Typing `\fL-fo\fP' is sufficient to specify form file or format string. meillo@95: .P meillo@95: The different meaning of meillo@95: .Sw -format meillo@95: for meillo@217: .Pn forw meillo@217: and meillo@95: .Pn repl meillo@95: was removed in mmh. meillo@95: .Pn forw meillo@95: was completely switched to MIME-type forwarding, thus removing the meillo@217: .Sw -[no]format meillo@217: .Ci 6e271608b7b9c23771523f88d23a4d3593010cf1 . meillo@95: For meillo@95: .Pn repl , meillo@95: the meillo@95: .Sw -[no]format meillo@95: switches were reworked to meillo@95: .Sw -[no]filter meillo@217: switches meillo@217: .Ci 67411b1f95d6ec987b4c732459e1ba8a8ac192c6 . meillo@95: The meillo@95: .Sw -format meillo@95: switches of meillo@95: .Pn send meillo@95: and meillo@95: .Pn post , meillo@217: which had a third meaning, were removed likewise meillo@217: .Ci f3cb7cde0e6f10451b6848678d95860d512224b9 . meillo@95: Eventually, the ambiguity of the meillo@95: .Sw -format meillo@217: switches is resolved by not having such switches anymore in mmh. meillo@95: meillo@95: meillo@95: .U3 "MIME Tools meillo@95: .P meillo@217: The MIME tools, which once were part of meillo@100: .Pn mhn meillo@164: (whatever that stood for), meillo@95: had several switches that added little practical value to the programs. meillo@95: The meillo@95: .Sw -[no]realsize meillo@95: switches of meillo@95: .Pn mhbuild meillo@95: and meillo@95: .Pn mhlist meillo@217: were removed meillo@217: .Ci 8d8f1c3abc586c005c904e52c4adbfe694d2201c . meillo@217: Real size calculations are done always now because nmh's meillo@159: .Mp mhbuild (1) meillo@217: man page states that meillo@217: ``This provides an accurate count at the expense of a small delay'' meillo@217: with the small delay not being noticable on modern systems. meillo@95: .P meillo@95: The meillo@95: .Sw -[no]check meillo@95: switches were removed together with the support for meillo@95: .Hd Content-MD5 meillo@217: header fields [RFC\|1864] meillo@154: (cf. Sec. meillo@154: .Cf content-md5 ) meillo@217: .Ci 31dc797eb5178970d68962ca8939da3fd9a8efda . meillo@95: .P meillo@95: The meillo@95: .Sw -[no]ebcdicsafe meillo@95: and meillo@95: .Sw -[no]rfc934mode meillo@95: switches of meillo@95: .Pn mhbuild meillo@217: were removed because they are considered obsolete meillo@97: .Ci 01a3480928da485b4d6109d36d751dfa71799d58 meillo@217: .Ci 3363e2624dce0eb8164cf8b3f1ab385c8ff72e88 . meillo@95: .P meillo@95: Content caching of external MIME parts, activated with the meillo@95: .Sw -rcache meillo@95: and meillo@95: .Sw -wcache meillo@217: switches was completely removed meillo@217: .Ci d1fefd9f614e4dc3cda16da6c69133c1b2005269 . meillo@97: External MIME parts are rare today, having a caching facility meillo@159: for them appears to be unnecessary. meillo@95: .P meillo@95: In pre-MIME times, meillo@95: .Pn mhl meillo@95: had covered many tasks that are part of MIME handling today. meillo@95: Therefore, meillo@95: .Pn mhl meillo@95: could be simplified to a large extend, reducing the number of its meillo@217: switches from 21 to 6 meillo@97: .Ci 350ad6d3542a07639213cf2a4fe524e829c1e7b6 meillo@217: .Ci 0e46503be3c855bddaeae3843e1b659279c35d70 . meillo@95: meillo@95: meillo@95: meillo@95: meillo@95: .U3 "Header Printing meillo@95: .P meillo@95: .Pn folder 's meillo@95: data output is self-explaining enough that meillo@159: displaying the header line makes little sense. meillo@95: Hence, the meillo@95: .Sw -[no]header meillo@217: switch was removed and headers are never printed meillo@217: .Ci 601cc73d1fa05ce96faa728f036d6c51b91701c7 . meillo@95: .P meillo@95: In meillo@95: .Pn mhlist , meillo@95: the meillo@95: .Sw -[no]header meillo@217: switches were removed, as well meillo@217: .Ci b24f96523aaf60e44e04a3ffb1d22e69a13a602f . meillo@217: In this case, the headers are printed always because the output meillo@217: is not self-explaining. meillo@95: .P meillo@95: .Pn scan meillo@95: also had meillo@95: .Sw -[no]header meillo@95: switches. meillo@217: Printing this header had been sensible until the introduction of meillo@217: format strings made it impossible to display column headings. meillo@95: Only the folder name and the current date remained to be printed. meillo@217: As this information can be perfectly generated with meillo@95: .Pn folder meillo@95: and meillo@95: .Pn date , meillo@217: the switches were removed meillo@217: .Ci c477dc5d1d03fa6d9a8ab3dd3508c63cbddc044e . meillo@95: .P meillo@95: By removing all meillo@95: .Sw -header meillo@95: switches, the collision with meillo@95: .Sw -help meillo@95: on the first two letters was resolved. meillo@95: Currently, meillo@95: .Sw -h meillo@95: evaluates to meillo@95: .Sw -help meillo@95: for all tools of mmh. meillo@95: meillo@95: meillo@139: .U3 "Suppressing Edits or the Invocation of the WhatNow Shell meillo@95: .P meillo@95: The meillo@95: .Sw -noedit meillo@100: switch of meillo@95: .Pn comp , meillo@95: .Pn repl , meillo@95: .Pn forw , meillo@95: .Pn dist , meillo@95: and meillo@95: .Pn whatnow meillo@217: was removed and replaced by specifying meillo@95: .Sw -editor meillo@217: with an empty argument meillo@217: .Ci 75fca31a5b9d5c1a99c74ab14c94438d8852fba9 . meillo@95: (Specifying meillo@159: .Cl "-editor /bin/true meillo@217: is nearly the same. It differs only in setting the previous editor.) meillo@95: .P meillo@95: The more important change is the removal of the meillo@95: .Sw -nowhatnowproc meillo@217: switch meillo@217: .Ci ee4f43cf2ef0084ec698e4e87159a94c01940622 . meillo@217: This switch had once introduced an awkward behavior, meillo@217: as explained in nmh's man page for meillo@95: .Mp comp (1): meillo@98: .QS meillo@164: The meillo@164: .Sw -editor meillo@164: .Ar editor meillo@164: switch indicates the editor to use for meillo@164: the initial edit. Upon exiting from the editor, meillo@164: .Pn comp meillo@164: will invoke the meillo@164: .Pn whatnow meillo@164: program. See meillo@164: .Mp whatnow (1) meillo@164: for a discussion of available options. meillo@164: The invocation of this program can be meillo@164: inhibited by using the meillo@164: .Sw -nowhatnowproc meillo@164: switch. (In truth of fact, it is the meillo@164: .Pn whatnow meillo@164: program which starts the initial edit. meillo@164: Hence, meillo@164: .Sw -nowhatnowproc meillo@164: will prevent any edit from occurring.) meillo@98: .QE meillo@95: .P meillo@95: Effectively, the meillo@95: .Sw -nowhatnowproc meillo@217: switch caused only only a draft message to be created. meillo@95: As meillo@159: .Cl "-whatnowproc /bin/true meillo@217: does the same, the meillo@95: .Sw -nowhatnowproc meillo@95: switch was removed for being redundant. meillo@95: meillo@95: meillo@95: meillo@95: .U3 "Various meillo@95: .BU meillo@139: With the removal of MMDF maildrop format support, meillo@139: .Pn packf meillo@139: and meillo@139: .Pn rcvpack meillo@139: no longer needed their meillo@139: .Sw -mbox meillo@139: and meillo@139: .Sw -mmdf meillo@139: switches. meillo@217: The behavior of meillo@139: .Sw -mbox meillo@217: is the sole behavior now meillo@217: .Ci 3916ab66ad5d183705ac12357621ea8661afd3c0 . meillo@171: Further rework in both tools made the meillo@139: .Sw -file meillo@217: switch unnecessary meillo@217: .Ci ca1023716d4c2ab890696f3e41fa0d94267a940e . meillo@139: meillo@139: .BU meillo@217: Mmh's tools do no longer clear the screen (\c meillo@139: .Pn scan 's meillo@139: and meillo@139: .Pn mhl 's meillo@139: .Sw -[no]clear meillo@139: switches meillo@139: .Ci e57b17343dcb3ff373ef4dd089fbe778f0c7c270 meillo@139: .Ci 943765e7ac5693ae177fd8d2b5a2440e53ce816e ). meillo@217: Neither does meillo@139: .Pn mhl meillo@139: ring the bell (\c meillo@139: .Sw -[no]bell meillo@139: .Ci e11983f44e59d8de236affa5b0d0d3067c192e24 ) meillo@217: nor does it page the output itself (\c meillo@139: .Sw -length meillo@139: .Ci 5b9d883db0318ed2b84bb82dee880d7381f99188 ). meillo@159: .\" XXX Ref meillo@139: Generally, the pager to use is no longer specified with the meillo@139: .Sw -[no]moreproc meillo@139: command line switches for meillo@139: .Pn mhl meillo@139: and meillo@139: .Pn show /\c meillo@217: .Pn mhshow meillo@217: .Ci 39e87a75b5c2d3572ec72e717720b44af291e88a . meillo@139: meillo@139: .BU meillo@96: In order to avoid prefix collisions among switch names, the meillo@95: .Sw -version meillo@95: switch was renamed to meillo@95: .Sw -Version meillo@217: (with capital `V') meillo@217: .Ci 32b2354dbaf4bf934936eb5b102a4a3d2fdd209a . meillo@95: Every program has the meillo@95: .Sw -version meillo@95: switch but its first three letters collided with the meillo@95: .Sw -verbose meillo@95: switch, present in many programs. meillo@95: The rename solved this problem once for all. meillo@95: Although this rename breaks a basic interface, having the meillo@95: .Sw -V meillo@95: abbreviation to display the version information, isn't all too bad. meillo@139: meillo@95: .BU meillo@95: .Sw -[no]preserve meillo@95: of meillo@95: .Pn refile meillo@168: was removed meillo@168: .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173 meillo@168: because what use was it anyway? meillo@168: Quoting nmh's man page meillo@165: .Mp refile (1): meillo@98: .QS meillo@95: Normally when a message is refiled, for each destination meillo@95: folder it is assigned the number which is one above the current meillo@95: highest message number in that folder. Use of the meillo@164: .Sw -preserv meillo@164: [sic!] switch will override this message renaming, and try meillo@95: to preserve the number of the message. If a conflict for a meillo@164: particular folder occurs when using the meillo@164: .Sw -preserve meillo@164: switch, then meillo@164: .Pn refile meillo@164: will use the next available message number which meillo@95: is above the message number you wish to preserve. meillo@98: .QE meillo@139: meillo@95: .BU meillo@95: The removal of the meillo@95: .Sw -[no]reverse meillo@95: switches of meillo@95: .Pn scan meillo@97: .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173 meillo@217: is a bug fix. meillo@217: This is supported by the comments meillo@95: ``\-[no]reverse under #ifdef BERK (I really HATE this)'' meillo@95: by Rose and meillo@95: ``Lists messages in reverse order with the `\-reverse' switch. meillo@217: This should be considered a bug'' by Romine in the changelogs. meillo@217: The question remains why neither Rose nor Romine have fixed this meillo@217: bug in the eighties when they wrote these comments. meillo@93: meillo@93: meillo@93: meillo@102: meillo@102: meillo@95: meillo@95: meillo@133: .\" -------------------------------------------------------------- meillo@74: .H1 "Modernizing meillo@102: .P meillo@164: In the more than thirty years of MH's existence, its code base was meillo@159: increasingly extended. meillo@118: New features entered the project and became alternatives to the meillo@118: existing behavior. meillo@217: Relics from several decades have gathered in the code base meillo@118: but seldom obsolete features were dropped. meillo@118: This section describes the removing of old code meillo@118: and the modernizing of the default setup. meillo@118: It focuses on the functional aspect only; meillo@154: the non-functional aspects of code style are discussed in Sec. meillo@154: .Cf code-style . meillo@58: meillo@58: meillo@212: .H2 "Code Relics meillo@0: .P meillo@217: My position regarding the removal of obsolete code meillo@159: is much more revolutional than the nmh community appreciates. meillo@217: Working on an experimental version, I was able to quickly drop meillo@217: functionality that I considered ancient. meillo@104: The need for consensus with peers would have slowed this process down. meillo@104: Without the need to justify my decisions, I was able to rush forward. meillo@217: .P meillo@110: In December 2011, Paul Vixie motivated the nmh developers to just meillo@104: do the work: meillo@104: .[ meillo@104: paul vixie edginess nmh-workers meillo@104: .] meillo@104: .QS meillo@104: let's stop walking on egg shells with this code base. there's no need to meillo@104: discuss whether to keep using vfork, just note in [sic!] passing, [...] meillo@104: we don't need a separate branch for removing vmh meillo@104: or ridding ourselves of #ifdef's or removing posix replacement functions meillo@164: or depending on pure ansi/posix ``libc''. meillo@104: .QP meillo@164: these things should each be a day or two of work and the ``main branch'' meillo@104: should just be modern. [...] meillo@104: let's push forward, aggressively. meillo@104: .QE meillo@104: .LP meillo@104: I did so already in the months before. meillo@104: I pushed forward. meillo@159: .\" XXX semicolon ? meillo@104: I simply dropped the cruft. meillo@104: .P meillo@104: The decision to drop a feature was based on literature research and meillo@159: careful thinking, but whether having had contact with this particular meillo@104: feature within my own computer life served as a rule of thumb. meillo@159: I explained my reasons in the commit messages meillo@109: in the version control system. meillo@104: Hence, others can comprehend my view and argue for undoing the change meillo@104: if I have missed an important aspect. meillo@109: I was quick in dropping parts. meillo@179: I rather include falsely dropped parts again, than going at a slower pace. meillo@179: Mmh is experimental work; it requires tough decisions. meillo@159: .\" XXX ``exp. work'' schon oft gesagt meillo@12: meillo@102: meillo@217: .U3 "Process Forking meillo@12: .P meillo@109: Being a tool chest, MH creates many processes. meillo@104: In earlier times meillo@104: .Fu fork() meillo@104: had been an expensive system call, because the process's image needed meillo@159: to be completely duplicated at once. meillo@200: This expensive work was especially unnecessary in the commonly occurring meillo@159: case wherein the image is replaced by a call to meillo@104: .Fu exec() meillo@104: right after having forked the child process. meillo@104: The meillo@104: .Fu vfork() meillo@104: system call was invented to speed up this particular case. meillo@104: It completely omits the duplication of the image. meillo@104: On old systems this resulted in significant speed ups. meillo@104: Therefore MH used meillo@104: .Fu vfork() meillo@104: whenever possible. meillo@12: .P meillo@104: Modern memory management units support copy-on-write semantics, which make meillo@104: .Fu fork() meillo@104: almost as fast as meillo@104: .Fu vfork() . meillo@104: The man page of meillo@104: .Mp vfork (2) meillo@104: in FreeBSD 8.0 states: meillo@104: .QS meillo@104: This system call will be eliminated when proper system sharing mechanisms meillo@104: are implemented. Users should not depend on the memory sharing semantics meillo@104: of vfork() as it will, in that case, be made synonymous to fork(2). meillo@104: .QE meillo@104: .LP meillo@104: Vixie supports the removal with the note that ``the last meillo@104: system on which fork was so slow that an mh user would notice it, was meillo@104: Eunice. that was 1987''. meillo@104: .[ meillo@104: nmh-workers vixie edginess meillo@104: .] meillo@104: I replaced all calls to meillo@104: .Fu vfork() meillo@104: with calls to meillo@217: .Fu fork() meillo@217: .Ci 40821f5c1316e9205a08375e7075909cc9968e7d . meillo@104: .P meillo@104: Related to the costs of meillo@104: .Fu fork() meillo@104: is the probability of its success. meillo@109: In the eighties, on heavy loaded systems, calls to meillo@104: .Fu fork() meillo@104: were prone to failure. meillo@104: Hence, many of the meillo@104: .Fu fork() meillo@104: calls in the code were wrapped into loops to retry the meillo@104: .Fu fork() meillo@217: several times, to increase the chances to succeed eventually. meillo@109: On modern systems, a failing meillo@104: .Fu fork() meillo@109: call is unusual. meillo@104: Hence, in the rare case when meillo@104: .Fu fork() meillo@217: fails, mmh programs simply abort meillo@217: .Ci 5fbf37ee68e018998ada61eeab73e035b26834b6 . meillo@12: meillo@12: meillo@109: .U3 "Header Fields meillo@104: .BU meillo@84: The meillo@84: .Hd Encrypted meillo@104: header field was introduced by RFC\|822, meillo@109: but already marked as legacy in RFC\|2822. meillo@109: Today, OpenPGP provides the basis for standardized exchange of encrypted meillo@104: messages [RFC\|4880, RFC\|3156]. meillo@109: Hence, the support for meillo@104: .Hd Encrypted meillo@217: header fields is removed in mmh meillo@217: .Ci 064527f7b57ab050e5af13e15ad99aeeab125857 . meillo@104: .BU meillo@159: The native support for meillo@84: .Hd Face meillo@217: header fields has been removed, as well meillo@217: .Ci 8e5be81f784682822f5e868c1bf3c8624682bd23 . meillo@104: This feature is similar to the meillo@84: .Hd X-Face meillo@84: header field in its intent, meillo@21: but takes a different approach to store the image. meillo@84: Instead of encoding the image data directly into the header field, meillo@109: it contains the hostname and UDP port where the image meillo@109: date can be retrieved. meillo@159: There is even a third Face system, meillo@109: which is the successor of meillo@109: .Hd X-Face , meillo@109: although it re-uses the meillo@104: .Hd Face meillo@217: header field name. meillo@109: It was invented in 2005 and supports colored PNG images. meillo@104: None of the Face systems described here is popular today. meillo@104: Hence, mmh has no direct support for them. meillo@104: .BU meillo@154: .Id content-md5 meillo@104: The meillo@104: .Hd Content-MD5 meillo@104: header field was introduced by RFC\|1864. meillo@104: It provides detection of data corruption during the transfer. meillo@104: But it can not ensure verbatim end-to-end delivery of the contents meillo@104: [RFC\|1864]. meillo@104: The proper approach to verify content integrity in an meillo@166: end-to-end relationship is the use of digital signatures. meillo@104: .\" XXX (RFCs FIXME). meillo@104: On the other hand, transfer protocols should detect corruption during meillo@109: the transmission. meillo@109: The TCP includes a checksum field therefore. meillo@104: These two approaches in combinations render the meillo@104: .Hd Content-MD5 meillo@104: header field superfluous. meillo@109: Not a single one out of 4\|200 messages from two decades meillo@217: in the nmh-workers mailing list archive meillo@217: .[ meillo@217: nmh-workers mailing list archive website meillo@217: .] meillo@217: contains a meillo@104: .Hd Content-MD5 meillo@104: header field. meillo@104: Neither did any of the 60\|000 messages in my personal mail storage. meillo@217: Removing the support for this header field meillo@217: .Ci 31dc797eb5178970d68962ca8939da3fd9a8efda , meillo@104: removed the last place where MD5 computation was needed. meillo@104: Hence, the MD5 code could be removed as well. meillo@104: Over 500 lines of code vanished by this one change. meillo@104: meillo@104: meillo@104: .U3 "MMDF maildrop support meillo@21: .P meillo@217: This type of maildrop format is conceptionally similar to the mbox format, meillo@139: but uses a different message delimiter (`\fL\\1\\1\\1\\1\fP', meillo@139: commonly written as `\fL^A^A^A^A\fP', instead of `\fLFrom\0\fP'). meillo@104: Mbox is the de-facto standard maildrop format on Unix, meillo@159: whereas the MMDF maildrop format is now forgotten. meillo@217: Mbox remains as the only packed mailbox format, supported in mmh. meillo@104: .P meillo@109: The simplifications within the code were moderate. meillo@109: Mainly, the reading and writing of MMDF mailbox files was removed. meillo@109: But also, switches of meillo@109: .Pn packf meillo@104: and meillo@109: .Pn rcvpack meillo@217: could be removed meillo@217: .Ci 3916ab66ad5d183705ac12357621ea8661afd3c0 . meillo@109: In the message parsing function meillo@109: .Fn sbr/m_getfld.c , meillo@217: knowledge of MMDF packed mail boxes was removed meillo@217: .Ci 684ec30d81e1223a282764452f4902ed4ad1c754 . meillo@109: Further code structure simplifications may be possible there, meillo@109: because only one single packed mailbox format is left to be supported. meillo@104: I have not worked on them yet because meillo@104: .Fu m_getfld() meillo@104: is heavily optimized and thus dangerous to touch. meillo@104: The risk of damaging the intricate workings of the optimized code is meillo@104: too high. meillo@104: meillo@12: meillo@101: .U3 "Prompter's Control Keys meillo@20: .P meillo@20: The program meillo@20: .Pn prompter meillo@104: queries the user to fill in a message form. meillo@217: When used as meillo@104: .Cl "comp -editor prompter" , meillo@20: the resulting behavior is similar to meillo@20: .Pn mailx . meillo@51: Apparently, meillo@20: .Pn prompter meillo@173: had not been touched lately. meillo@104: Otherwise it's hardly explainable why it meillo@20: still offered the switches meillo@84: .Sw -erase meillo@84: .Ar chr meillo@20: and meillo@84: .Sw -kill meillo@84: .Ar chr meillo@20: to name the characters for command line editing. meillo@21: The times when this had been necessary are long time gone. meillo@20: Today these things work out-of-the-box, and if not, are configured meillo@20: with the standard tool meillo@20: .Pn stty . meillo@104: The switches are removed now meillo@104: .Ci 0bd9750710cdbab80cfb4036dd87af20afe1552f . meillo@20: meillo@104: meillo@109: .U3 "Hardcopy Terminal Support meillo@21: .P meillo@109: More of a funny anecdote is a check for being connected to a meillo@109: hardcopy terminal. meillo@159: It remained in the code until spring 2012, when I finally removed it meillo@104: .Ci b7764c4a6b71d37918a97594d866258f154017ca . meillo@21: .P meillo@109: The check only prevented a pager to be placed between the printing meillo@104: program (\c meillo@104: .Pn mhl ) meillo@104: and the terminal. meillo@109: In nmh, this could have been ensured statically with the meillo@104: .Sw -nomoreproc meillo@109: at the command line, too. meillo@121: In mmh, setting the profile entry meillo@104: .Pe Pager meillo@104: or the environment variable meillo@104: .Ev PAGER meillo@104: to meillo@109: .Pn cat meillo@159: is sufficient. meillo@104: meillo@104: meillo@21: meillo@12: meillo@58: .H2 "Attachments meillo@22: .P meillo@101: The mind model of email attachments is unrelated to MIME. meillo@217: Although the MIME RFCs [RFC\|2045\(en2049] define the technical meillo@217: requirements for having attachments, they do not mention the term. meillo@101: Instead of attachments, MIME talks about ``multi-part message bodies'' meillo@101: [RFC\|2045], a more general concept. meillo@101: Multi-part messages are messages meillo@101: ``in which one or more different meillo@101: sets of data are combined in a single body'' meillo@101: [RFC\|2046]. meillo@101: MIME keeps its descriptions generic; meillo@101: it does not imply specific usage models. meillo@217: Today, one usage model is prevalent: attachments. meillo@101: The idea is having a main text document with files of arbitrary kind meillo@101: attached to it. meillo@101: In MIME terms, this is a multi-part message having a text part first meillo@110: and parts of arbitrary type following. meillo@101: .P meillo@101: MH's MIME support is a direct implementation of the RFCs. meillo@101: The perception of the topic described in the RFCs is clearly visible meillo@101: in MH's implementation. meillo@159: .\" XXX rewrite ``no idea''. meillo@159: As a result, meillo@159: MH had all the MIME features but no idea of attachments. meillo@173: But users do not need all the MIME features, meillo@109: they want convenient attachment handling. meillo@109: meillo@102: meillo@102: .U3 "Composing MIME Messages meillo@102: .P meillo@102: In order to improve the situation on the message composing side, meillo@217: Jon Steinhart had added an attachment system to nmh in 2002 meillo@217: .Ci 7480dbc14bc90f2d872d434205c0784704213252 . meillo@102: In the file meillo@102: .Fn docs/README-ATTACHMENTS , meillo@217: he described his motivation to do so: meillo@101: .QS meillo@159: Although nmh contains the necessary functionality for MIME message meillo@159: handing [sic!], the interface to this functionality is pretty obtuse. meillo@101: There's no way that I'm ever going to convince my partner to write meillo@101: .Pn mhbuild meillo@101: composition files! meillo@101: .QE meillo@102: .LP meillo@102: With this change, the mind model of attachments entered nmh. meillo@102: In the same document: meillo@101: .QS meillo@101: These changes simplify the task of managing attachments on draft files. meillo@101: They allow attachments to be added, listed, and deleted. meillo@101: MIME messages are automatically created when drafts with attachments meillo@101: are sent. meillo@101: .QE meillo@102: .LP meillo@217: Unfortunately, the attachment system, like every new facilities in nmh, meillo@110: was inactive by default. meillo@101: .P meillo@217: During my time in Argentina, I tried to improve the attachment system. meillo@217: But, after long discussions my patch died as a proposal on the meillo@217: mailing list because of great opposition in the nmh community. meillo@101: .[ meillo@101: nmh-workers attachment proposal meillo@101: .] meillo@217: In January 2012, I extended the patch and applied it to mmh meillo@217: .Ci 8ff284ff9167eff8f5349481529332d59ed913b1 . meillo@102: In mmh, the attachment system is active by default. meillo@102: Instead of command line switches, the meillo@102: .Pe Attachment-Header meillo@102: profile entry is used to specify meillo@102: the name of the attachment header field. meillo@102: It is pre-defined to meillo@102: .Hd Attach . meillo@101: .P meillo@159: To add an attachment to a draft, a header line needs to be added: meillo@101: .VS meillo@101: To: bob meillo@101: Subject: The file you wanted meillo@101: Attach: /path/to/the/file-bob-wanted meillo@101: -------- meillo@101: Here it is. meillo@101: VE meillo@101: The header field can be added to the draft manually in the editor, meillo@102: or by using the `attach' command at the WhatNow prompt, or meillo@102: non-interactively with meillo@101: .Pn anno : meillo@101: .VS meillo@102: anno -append -nodate -component Attach -text /path/to/attachment meillo@101: VE meillo@102: Drafts with attachment headers are converted to MIME automatically by meillo@102: .Pn send . meillo@102: The conversion to MIME is invisible to the user. meillo@159: The draft stored in the draft folder is always in source form with meillo@101: attachment headers. meillo@179: If the MIMEification fails (e.g. because the file to attach meillo@179: is not accessible) the original draft is not changed. meillo@101: .P meillo@102: The attachment system handles the forwarding of messages, too. meillo@173: If the attachment header value starts with a plus character (`\fL+\fP'), meillo@101: like in meillo@101: .Cl "Attach: +bob 30 42" , meillo@159: the given messages in the specified folder will be attached. meillo@101: This allowed to simplify meillo@217: .Pn forw meillo@217: .Ci f41f04cf4ceca7355232cf7413e59afafccc9550 . meillo@101: .P meillo@101: Closely related to attachments is non-ASCII text content, meillo@217: because it requires MIME as well. meillo@102: In nmh, the user needed to call `mime' at the WhatNow prompt meillo@101: to have the draft converted to MIME. meillo@102: This was necessary whenever the draft contained non-ASCII characters. meillo@101: If the user did not call `mime', a broken message would be sent. meillo@101: Therefore, the meillo@101: .Pe automimeproc meillo@101: profile entry could be specified to have the `mime' command invoked meillo@102: automatically each time. meillo@179: Unfortunately, this approach conflicted with the attachment system meillo@101: because the draft would already be in MIME format at the time meillo@101: when the attachment system wanted to MIMEify it. meillo@102: To use nmh's attachment system, `mime' must not be called at the meillo@102: WhatNow prompt and meillo@101: .Pe automimeproc meillo@102: must not be set in the profile. meillo@101: But then the case of non-ASCII text without attachment headers was meillo@101: not caught. meillo@102: All in all, the solution was complex and irritating. meillo@168: My patch from December 2010 meillo@168: .[ meillo@168: nmh-workers attachment proposal meillo@168: .] meillo@168: would have simplified the situation. meillo@102: .P meillo@101: Mmh's current solution is even more elaborate. meillo@101: Any necessary MIMEification is done automatically. meillo@101: There is no `mime' command at the WhatNow prompt anymore. meillo@102: The draft will be converted automatically to MIME when either an meillo@102: attachment header or non-ASCII text is present. meillo@173: Furthermore, the hash character (`\fL#\fP') is not special any more meillo@159: at line beginnings in the draft message. meillo@159: .\" XXX REF ? meillo@159: Users need not concern themselves with the whole topic at all. meillo@101: .P meillo@102: Although the new approach does not anymore support arbitrary MIME meillo@102: compositions directly, the full power of meillo@101: .Pn mhbuild meillo@101: can still be accessed. meillo@217: Given no attachment headers are included, users can create meillo@101: .Pn mhbuild meillo@102: composition drafts like in nmh. meillo@217: Then, at the WhatNow prompt, they can invoke meillo@101: .Cl "edit mhbuild meillo@217: to convert the draft to MIME. meillo@217: Because the resulting draft neither contains non-ASCII characters meillo@102: nor has it attachment headers, the attachment system will not touch it. meillo@101: .P meillo@159: The approach taken in mmh is tailored towards today's most common case: meillo@159: a text part, possibly with attachments. meillo@159: This case was simplified. meillo@102: meillo@112: meillo@102: .U3 "MIME Type Guessing meillo@102: .P meillo@159: From the programmer's point of view, the use of meillo@101: .Pn mhbuild meillo@159: composition drafts had one notable advantage over attachment headers: meillo@159: The user provides the appropriate MIME types for files to include. meillo@217: The new attachment system needs to find out the correct MIME type itself. meillo@217: This is a difficult task. meillo@102: Determining the correct MIME type of content is partly mechanical, meillo@102: partly intelligent work. meillo@102: Forcing the user to find out the correct MIME type, meillo@102: forces him to do partly mechanical work. meillo@179: Letting the computer do the work can lead to bad choices for difficult meillo@102: content. meillo@217: For mmh, the latter option was chosen to spare the user the work meillo@217: .Ci 3baec236a39c5c89a9bda8dbd988d643a21decc6 . meillo@102: .P meillo@102: Determining the MIME type by the suffix of the file name is a dumb meillo@102: approach, yet it is simple to implement and provides good results meillo@102: for the common cases. meillo@217: If no MIME type can be determined, text content is sent as `text/plain', meillo@217: anything else under the generic fall-back type `application/octet-stream'. meillo@102: Mmh implements this approach in the meillo@102: .Pn print-mimetype meillo@217: script meillo@217: .Ci 4b5944268ea0da7bb30598a27857304758ea9b44 . meillo@102: .P meillo@112: A far better, though less portable, approach is the use of meillo@102: .Pn file . meillo@102: This standard tool tries to determine the type of files. meillo@102: Unfortunately, its capabilities and accuracy varies from system to system. meillo@102: Additionally, its output was only intended for human beings, meillo@102: but not to be used by programs. meillo@102: Nevertheless, modern versions of GNU meillo@102: .Pn file , meillo@217: which are prevalent on the popular GNU/Linux systems, meillo@159: provide MIME type output in machine-readable form. meillo@217: Although this solution is system-dependent, meillo@102: it solves the difficult problem well. meillo@102: On systems where GNU meillo@102: .Pn file , meillo@102: version 5.04 or higher, is available it should be used. meillo@102: One needs to specify the following profile entry to do so: meillo@102: .VS meillo@102: Mime-Type-Query: file -b --mime meillo@102: VE meillo@102: .LP meillo@102: Other versions of meillo@102: .Pn file meillo@217: might possibly be usable with wrapper scripts that reformat the output. meillo@102: The diversity among meillo@102: .Pn file meillo@102: implementations is great; one needs to check the local variant. meillo@102: .P meillo@102: It is not possible in mmh to override the automatic MIME type guessing meillo@102: for a specific file. meillo@159: To do so, either the user would need to know in advance for which file meillo@217: the automatic guessing fails or the system would require interaction. meillo@102: I consider both cases impractical. meillo@102: The existing solution should be sufficient. meillo@102: If not, the user may always fall back to meillo@102: .Pn mhbuild meillo@217: composition drafts and bypass the attachment system. meillo@101: meillo@102: meillo@102: .U3 "Storing Attachments meillo@102: .P meillo@169: Extracting MIME parts of a message and storing them to disk is performed by meillo@108: .Pn mhstore . meillo@108: The program has two operation modes, meillo@108: .Sw -auto meillo@108: and meillo@108: .Sw -noauto . meillo@108: With the former one, each part is stored under the filename given in the meillo@108: MIME part's meta information, if available. meillo@108: This naming information is usually available for modern attachments. meillo@108: If no filename is available, this MIME part is stored as if meillo@108: .Sw -noauto meillo@108: would have been specified. meillo@108: In the meillo@108: .Sw -noauto meillo@108: mode, the parts are processed according to rules, defined by meillo@108: .Pe mhstore-store-* meillo@108: profile entries. meillo@108: These rules define generic filename templates for storing meillo@108: or commands to post-process the contents in arbitrary ways. meillo@108: If no matching rule is available the part is stored under a generic meillo@108: filename, built from message number, MIME part number, and MIME type. meillo@108: .P meillo@108: The meillo@108: .Sw -noauto meillo@108: mode had been the default in nmh because it was considered safe, meillo@108: in contrast to the meillo@108: .Sw -auto meillo@108: mode. meillo@108: In mmh, meillo@108: .Sw -auto meillo@108: is not dangerous anymore. meillo@108: Two changes were necessary: meillo@171: .LI 1 meillo@108: Any directory path is removed from the proposed filename. meillo@108: Thus, the files are always stored in the expected directory. meillo@108: .Ci 41b6eadbcecf63c9a66aa5e582011987494abefb meillo@171: .LI 2 meillo@108: Tar files are not extracted automatically any more. meillo@108: Thus, the rest of the file system will not be touched. meillo@108: .Ci 94c80042eae3383c812d9552089953f9846b1bb6 meillo@217: .P meillo@217: In mmh, the result of meillo@108: .Cl "mhstore -auto meillo@110: can be foreseen from the output of meillo@108: .Cl "mhlist -verbose" . meillo@217: Although the meillo@108: .Sw -noauto meillo@217: mode is considered to be more powerful, it is less convenient and meillo@108: .Sw -auto meillo@217: is safe now. meillo@217: Additionally, storing attachments under their original name meillo@217: is intuitive. meillo@108: Hence, meillo@108: .Sw -auto meillo@217: serves better as the default option meillo@217: .Ci 3410b680416c49a7617491af38bc1929855a331d . meillo@108: .P meillo@108: Files are stored into the directory given by the meillo@108: .Pe Nmh-Storage meillo@108: profile entry, if set, or meillo@108: into the current working directory, otherwise. meillo@108: Storing to different directories is only possible with meillo@108: .Pe mhstore-store-* meillo@108: profile entries. meillo@108: .P meillo@217: Still existing files get overwritten silently in both modes. meillo@108: This can be considered a bug. meillo@108: Yet, each other behavior has its draw-backs, too. meillo@108: Refusing to replace files requires adding a meillo@108: .Sw -force meillo@217: switch. meillo@108: Users will likely need to invoke meillo@108: .Pn mhstore meillo@108: a second time with meillo@159: .Sw -force . meillo@159: Eventually, only the user can decide in the specific case. meillo@108: This requires interaction, which I like to avoid if possible. meillo@108: Appending a unique suffix to the filename is another bad option. meillo@108: For now, the behavior remains as it is. meillo@108: .P meillo@108: In mmh, only MIME parts of type message are special in meillo@108: .Pn mhstore 's meillo@108: .Sw -auto meillo@108: mode. meillo@108: Instead of storing message/rfc822 parts as files to disk, meillo@108: they are stored as messages into the current mail folder. meillo@159: The same applies to message/partial, although the parts are meillo@159: automatically reassembled beforehand. meillo@159: MIME parts of type message/external-body are not automatically retrieved meillo@159: anymore. meillo@159: Instead, information on how to retrieve them is output. meillo@217: Not supporting this rare case saved nearly one thousand lines of code meillo@217: .Ci 55e1d8c654ee0f7c45b9361ce34617983b454c32 . meillo@108: .\" XXX mention somewhere else too: (The profile entry `nmh-access-ftp' meillo@108: .\" and sbr/ruserpass.c for reading ~/.netrc are gone now.) meillo@217: The MIME type `application/octet-stream; type=tar' is not special anymore. meillo@217: The automatically extracting of such MIME parts had been the meillo@217: dangerous part of the meillo@108: .Sw -auto meillo@217: mode meillo@217: .Ci 94c80042eae3383c812d9552089953f9846b1bb6 . meillo@108: meillo@102: meillo@102: meillo@102: .U3 "Showing MIME Messages meillo@102: .P meillo@114: The program meillo@114: .Pn mhshow meillo@217: was written to display MIME messages. meillo@114: It implemented the conceptional view of the MIME RFCs. meillo@114: Nmh's meillo@114: .Pn mhshow meillo@217: handles each MIME part independently, presenting them separately meillo@114: to the user. meillo@114: This does not match today's understanding of email attachments, meillo@114: where displaying a message is seen to be a single, integrated operation. meillo@114: Today, email messages are expected to consist of a main text part meillo@114: plus possibly attachments. meillo@217: They are no more seen to be arbitrary MIME hierarchies with meillo@114: information on how to display the individual parts. meillo@114: I adjusted meillo@114: .Pn mhshow 's meillo@114: behavior to the modern view on the topic. meillo@114: .P meillo@217: (One should note that this section completely ignores the original meillo@114: .Pn show meillo@114: program, because it was not capable to display MIME messages meillo@114: and is no longer part of mmh. meillo@179: .\" XXX ref to other section meillo@114: Although meillo@114: .Pn mhshow meillo@114: was renamed to meillo@114: .Pn show meillo@114: in mmh, this section uses the name meillo@114: .Pn mhshow , meillo@217: in order to avoid confusion.) meillo@114: .P meillo@114: In mmh, the basic idea is that meillo@114: .Pn mhshow meillo@114: should display a message in one single pager session. meillo@114: Therefore, meillo@114: .Pn mhshow meillo@114: invokes a pager session for all its output, meillo@217: whenever it prints to a terminal meillo@217: .Ci a4197ea6ffc5c1550e8b52d5a654bcaaaee04a4e . meillo@114: In consequence, meillo@114: .Pn mhl meillo@217: does no more invoke a pager meillo@217: .Ci 0e46503be3c855bddaeae3843e1b659279c35d70 . meillo@114: With meillo@114: .Pn mhshow meillo@114: replacing the original meillo@114: .Pn show , meillo@217: the output of meillo@114: .Pn mhl meillo@217: no longer goes to the terminal directly, but through meillo@114: .Pn mhshow . meillo@114: Hence, meillo@114: .Pn mhl meillo@114: does not need to invoke a pager. meillo@114: The one and only job of meillo@114: .Pn mhl meillo@114: is to format messages or parts of them. meillo@114: The only place in mmh, where a pager is invoked is meillo@114: .Pn mhshow . meillo@114: .P meillo@217: In the intended setup, only text content is be displayed, meillo@217: in a single pager session. meillo@217: Non-text content needs to be converted to text by appropriate meillo@217: .Pe mhshow-show-* meillo@217: profile entries before, if this is possible and wanted. meillo@217: A common example for this are PDF files. meillo@217: .ig \"XXX meillo@114: .Pe mhshow-show-* meillo@114: profile entries can be used to display MIME parts in a specific way. meillo@114: to display them in the terminal. meillo@217: .. meillo@217: In mmh, MIME parts are always displayed serially. meillo@114: The request to display the MIME type `multipart/parallel' in parallel meillo@114: is ignored. meillo@217: It is simply treated as `multipart/mixed' meillo@217: .Ci d0581ba306a7299113a346f9b4c46ce97bc4cef6 . meillo@217: This was already possible to requested with the, now removed, meillo@114: .Sw -serialonly meillo@114: switch of meillo@114: .Pn mhshow . meillo@179: As MIME parts are always processed exclusively, i.e. serially, meillo@217: the `\fL%e\fP' escape in meillo@114: .Pe mhshow-show-* meillo@217: profile entries became useless and was thus removed meillo@217: .Ci a20d405db09b7ccca74d3e8c57550883da49e1ae . meillo@114: .P meillo@114: Other kinds of attachments are ignored. meillo@114: With meillo@114: .Pe mhshow-show-* meillo@114: profile entries for them, they can be displayed serially along meillo@114: the message. meillo@114: For parallel display, the attachments need to be stored to disk first. meillo@114: .P meillo@114: To display text content in foreign charsets, they need to be converted meillo@114: to the native charset. meillo@114: Therefore, meillo@114: .Pe mhshow-charset-* meillo@217: profile entries were needed. meillo@169: In mmh, the conversion is performed automatically by piping the meillo@169: text through the meillo@114: .Pn iconv meillo@217: command, if necessary meillo@217: .Ci 2433122c20baccb10b70b49c04c6b0497b5b3b60 . meillo@114: Custom meillo@114: .Pe mhshow-show-* meillo@114: rules for textual content might need a meillo@114: .Cl "iconv -f %c %f | meillo@114: prefix to have the text converted to the native charset. meillo@114: .P meillo@121: Although the conversion of foreign charsets to the native one meillo@114: has improved, it is not consistent enough. meillo@114: Further work needs to be done and meillo@114: the basic concepts in this field need to be re-thought. meillo@114: Though, the default setup of mmh displays message in foreign charsets meillo@114: correctly without the need to configure anything. meillo@114: meillo@114: meillo@114: .ig meillo@114: meillo@114: .P meillo@114: mhshow/mhstore: Removed support for retrieving message/external-body parts. meillo@173: These tools will not download the contents automatically anymore. Instead, meillo@114: they print the information needed to get the contents. If someone should meillo@114: really receive one of those rare message/external-body messages, he can meillo@114: do the job manually. We save nearly a thousand lines of code. That's worth meillo@114: it! meillo@114: (The profile entry `nmh-access-ftp' and sbr/ruserpass.c for reading meillo@114: ~/.netrc are gone now.) meillo@114: .Ci 55e1d8c654ee0f7c45b9361ce34617983b454c32 meillo@114: meillo@114: .. meillo@102: meillo@58: meillo@58: meillo@166: .H2 "Signing and Encrypting meillo@22: .P meillo@166: Nmh offers no direct support for digital signatures and message encryption. meillo@157: This functionality needed to be added through third-party software. meillo@217: In mmh, the functionality is included because it meillo@217: is a part of modern email and is likely wanted by users of mmh. meillo@217: A fresh mmh installation supports signing and encrypting meillo@157: out-of-the-box. meillo@157: Therefore, Neil Rickert's meillo@157: .Pn mhsign meillo@157: and meillo@157: .Pn mhpgp meillo@157: scripts meillo@157: .[ meillo@157: neil rickert mhsign mhpgp meillo@157: .] meillo@217: were included meillo@177: .Ci f45cdc98117a84f071759462c7ae212f4bc5ab2e meillo@177: .Ci 58cf09aa36e9f7f352a127158bbf1c5678bc6ed8 . meillo@177: The scripts fit well because they are lightweight and meillo@177: similar of style to the existing tools. meillo@217: Additionally, no licensing difficulties appeared meillo@157: as they are part of the public domain. meillo@112: .P meillo@157: .Pn mhsign meillo@157: handles the signing and encrypting part. meillo@157: It comprises about 250 lines of shell code and interfaces between meillo@217: .Pn gnupg " meillo@217: .[ meillo@217: gnupg website meillo@217: .] meillo@217: and the MH system. meillo@177: It was meant to be invoked manually at the WhatNow prompt, but in mmh, meillo@157: .Pn send meillo@177: invokes meillo@217: .Pn mhsign meillo@177: automatically meillo@177: .Ci c7b5e1df086bcc37ff40163ee67571f076cf6683 . meillo@177: Special header fields were introduced to request this action. meillo@157: If a draft contains the meillo@157: .Hd Sign meillo@157: header field, meillo@157: .Pn send meillo@177: will initiate the signing. meillo@217: The signing key is either chosen automatically or it is specified by the meillo@157: .Pe Pgpkey meillo@157: profile entry. meillo@157: .Pn send meillo@217: always create signatures using the PGP/MIME standard [RFC\|4880], meillo@217: but by invoking meillo@217: .Pn mhsign meillo@217: manually, old-style non-MIME signatures can be created as well. meillo@177: To encrypt an outgoing message, the draft needs to contain an meillo@157: .Hd Enc meillo@157: header field. meillo@177: Public keys of all recipients are searched for in the gnupg keyring and meillo@177: in a file called meillo@177: .Fn pgpkeys , meillo@177: which contains exceptions and overrides. meillo@157: Unless public keys are found for all recipients, meillo@177: .Pn mhsign meillo@177: will refuse to encrypt it. meillo@157: Currently, messages with hidden (BCC) recipients can not be encrypted. meillo@171: This work is pending because it requires a structurally more complex meillo@171: approach. meillo@157: .P meillo@177: .Pn mhpgp meillo@177: is the companion to meillo@177: .Pn mhsign . meillo@177: It verifies signatures and decrypts messages. meillo@217: Encrypted messages can be either temporarily decrypted and displayed meillo@177: or permanently decrypted and stored into the current folder. meillo@177: Currently, meillo@177: .Pn mhpgp meillo@177: needs to be invoked manually. meillo@177: The integration into meillo@177: .Pn show meillo@177: and meillo@177: .Pn mhstore meillo@217: to verify signatures and decrypt messages as needed meillo@217: is planned but not yet realized. meillo@177: .P meillo@217: Both scripts were written for nmh. meillo@217: Hence they needed to be adjust meillo@177: according to the differences between nmh and mmh. meillo@177: For instance, they use the backup prefix no longer. meillo@181: Furthermore, compatibility support for old PGP features was dropped. meillo@177: .P meillo@157: The integrated message signing and encrypting support is one of the meillo@157: most recent features in mmh. meillo@217: It has not had the time to mature. meillo@177: User feedback and personal experience need to be accumulated to meillo@177: direct the further development of the facility. meillo@217: Already it seems to be worthwhile to consider adding meillo@157: .Sw -[no]sign meillo@157: and meillo@157: .Sw -[no]enc meillo@157: switches to meillo@157: .Pn send , meillo@177: to be able to override the corresponding header fields. meillo@177: A profile entry: meillo@157: .VS meillo@157: send: -sign meillo@157: VE meillo@177: would then activate signing for all outgoing messages. meillo@177: With the present approach, a meillo@177: .Hd Send meillo@177: header component needs to be added to each draft template meillo@177: to achieve the same result. meillo@177: Adding the switches would ease the work greatly and keep the meillo@177: template files clean. meillo@157: meillo@58: meillo@58: meillo@102: meillo@133: .H2 "Draft and Trash Folder meillo@131: .P meillo@58: meillo@131: .U3 "Draft Folder meillo@154: .Id draft-folder meillo@131: .P meillo@131: In the beginning, MH had the concept of a draft message. meillo@217: This was a file named meillo@131: .Fn draft meillo@217: in the MH directory, which was treated special. meillo@131: On composing a message, this draft file was used. meillo@131: When starting to compose another message before the former one was sent, meillo@131: the user had to decide among: meillo@171: .LI 1 meillo@168: Using the old draft to finish and send it before starting with a new one. meillo@171: .LI 2 meillo@168: Discarding the old draft and replacing it with a new one. meillo@171: .LI 3 meillo@168: Preserving the old draft by refiling it to a folder. meillo@171: .LP meillo@217: Working on multiple drafts was only possible in alternation. meillo@217: For that, the current draft needed to be refiled to a folder and meillo@168: another one re-used for editing. meillo@131: Working on multiple drafts at the same time was impossible. meillo@131: The usual approach of switching to a different MH context did not meillo@168: help anything. meillo@131: .P meillo@131: The draft folder facility exists to meillo@131: allow true parallel editing of drafts, in a straight forward way. meillo@131: It was introduced by Marshall T. Rose, already in 1984. meillo@131: Similar to other new features, the draft folder was inactive by default. meillo@131: Even in nmh, the highly useful draft folder was not available meillo@131: out-of-the-box. meillo@131: At least, Richard Coleman added the man page meillo@131: .Mp mh-draft (5) meillo@131: to better document the feature. meillo@131: .P meillo@131: Not using the draft folder facility has the single advantage of having meillo@131: the draft file at a static location. meillo@131: This is simple in simple cases but the concept does not scale for more meillo@131: complex cases. meillo@217: The concept of the draft message is too limited for the problem meillo@217: it tries to solve. meillo@131: Therefore the draft folder was introduced. meillo@131: It is the more powerful and more natural concept. meillo@131: The draft folder is a folder like any other folder in MH. meillo@131: Its messages can be listed like any other messages. meillo@131: A draft message is no longer a special case. meillo@131: Tools do not need special switches to work on the draft message. meillo@171: Hence corner cases were removed. meillo@131: .P meillo@131: The trivial part of the work was activating the draft folder with a meillo@131: default name. meillo@131: I chose the name meillo@217: .Fn +drafts , meillo@131: for obvious reasons. meillo@131: In consequence, the command line switches meillo@131: .Sw -draftfolder meillo@131: and meillo@131: .Sw -draftmessage meillo@131: could be removed. meillo@131: More difficult but also more improving was updating the tools to the meillo@131: new concept. meillo@131: For nearly three decades, the tools needed to support two draft handling meillo@131: approaches. meillo@217: By fully switching to the draft folder, the tools could be meillo@217: simplified by dropping the awkward draft message handling code. meillo@131: .Sw -draft meillo@131: switches were removed because operating on a draft message is no longer meillo@131: special. meillo@131: It became indistinguishable to operating on any other message. meillo@168: .Ci 337338b404931f06f0db2119c9e145e8ca5a9860 meillo@168: .P meillo@168: There is no more need to query the user for draft handling meillo@168: .Ci 2d48b455c303a807041c35e4248955f8bec59eeb . meillo@131: It is always possible to add another new draft. meillo@131: Refiling drafts is without difference to refiling other messages. meillo@168: All of these special cases are gone. meillo@131: Yet, one draft-related switch remained. meillo@131: .Pn comp meillo@131: still has meillo@131: .Sw -[no]use meillo@131: for switching between two modes: meillo@171: .LI 1 meillo@217: Modifying an existing draft, with meillo@217: .Sw -use . meillo@171: .LI 2 meillo@217: Composing a new draft, possibly taking some existing message as template, meillo@217: with meillo@217: .Sw -nouse , meillo@217: the default. meillo@171: .LP meillo@131: In either case, the behavior of meillo@131: .Pn comp meillo@131: is deterministic. meillo@131: .P meillo@131: .Pn send meillo@131: now operates on the current message in the draft folder by default. meillo@131: As message and folder can both be overridden by specifying them on meillo@131: the command line, it is possible to send any message in the mail storage meillo@131: by simply specifying its number and folder. meillo@131: In contrast to the other tools, meillo@131: .Pn send meillo@131: takes the draft folder as its default folder. meillo@131: .P meillo@131: Dropping the draft message concept in favor for the draft folder concept, meillo@217: replaced special cases with regular cases. meillo@131: This simplified the source code of the tools, as well as the concepts. meillo@131: In mmh, draft management does not break with the MH concepts meillo@131: but applies them. meillo@133: .Cl "scan +drafts" , meillo@133: for instance, is a truly natural request. meillo@217: .P meillo@169: Most of the work was already performed by Rose in the eighties. meillo@133: The original improvement of mmh is dropping the old draft message approach meillo@217: and thus simplifying the tools, the documentation, meillo@217: and the system as a whole. meillo@131: Although my part in the draft handling improvement was small, meillo@217: it was important. meillo@131: meillo@131: meillo@131: .U3 "Trash Folder meillo@154: .Id trash-folder meillo@131: .P meillo@131: Similar to the situation for drafts is the situation for removed messages. meillo@131: Historically, a message was ``deleted'' by prepending a specific meillo@173: \fIbackup prefix\fP, usually the comma character, meillo@173: to the file name. meillo@164: The specific file would then be ignored by MH because only files with meillo@164: names consisting of digits only are treated as messages. meillo@131: Although files remained in the file system, meillo@168: the messages were no longer visible in MH. meillo@168: To truly delete them, a maintenance job was needed. meillo@168: Usually a cron job was installed to delete them after a grace time. meillo@131: For instance: meillo@131: .VS meillo@131: find $HOME/Mail -type f -name ',*' -ctime +7 -delete meillo@131: VE meillo@168: In such a setup, the original message could be restored meillo@131: within the grace time interval by stripping the meillo@217: backup prefix from the file name \(en usually but not always. meillo@168: If the last message of a folder with six messages (\fL1-6\fP) was removed, meillo@131: message meillo@131: .Fn 6 , meillo@168: became file meillo@131: .Fn ,6 . meillo@168: If then a new message entered the same folder, it would be named with meillo@168: the number one above the highest existing message number. meillo@168: In this case the message would be named meillo@217: .Fn 6 , meillo@217: reusing the number. meillo@168: If this new message would be removed as well, meillo@217: then the backup of the former message becomes overwritten. meillo@168: Hence, the ability to restore removed messages did not only depend on meillo@181: the sweeping cron job but also on the removing of further messages. meillo@131: It is undesirable to have such obscure and complex mechanisms. meillo@168: The user should be given a small set of clear assertions, such as meillo@131: ``Removed files are restorable within a seven-day grace time.'' meillo@131: With the addition ``... unless a message with the same name in the meillo@131: same folder is removed before.'' the statement becomes complex. meillo@217: A user will hardly be able to keep track of all removals to know meillo@131: if the assertion still holds true for a specific file. meillo@164: In practice, the real mechanism is unclear to the user. meillo@131: .P meillo@217: Furthermore, the backup files were scattered within the whole mail storage. meillo@217: This complicated managing them. meillo@217: It was possible with the help of meillo@131: .Pn find , meillo@217: but everything is more convenient meillo@217: if the deleted messages are collected in one place. meillo@131: .P meillo@131: The profile entry meillo@131: .Pe rmmproc meillo@131: (previously named meillo@131: .Pe Delete-Prog ) meillo@131: was introduced very early to improve the situation. meillo@164: It could be set to any command, which would be executed to remove meillo@131: the specified messages. meillo@217: This had overridden the default action, described above. meillo@217: Refiling the to-be-removed files to a trash folder was the usual example. meillo@131: Nmh's man page meillo@131: .Mp rmm (1) meillo@131: proposes to set the meillo@131: .Pe rmmproc meillo@131: to meillo@131: .Cl "refile +d meillo@217: to move messages to the trash folder meillo@217: .Fn +d meillo@131: instead of renaming them with the backup prefix. meillo@217: The man page additionally proposes the expunge command meillo@131: .Cl "rm `mhpath +d all` meillo@168: to empty the trash folder. meillo@131: .P meillo@217: Removing messages in such a way has advantages: meillo@217: .LI 1 meillo@131: The mail storage is prevented from being cluttered with removed messages meillo@131: because they are all collected in one place. meillo@131: Existing and removed messages are thus separated more strictly. meillo@217: .LI 2 meillo@131: No backup files are silently overwritten. meillo@217: .LI 3 meillo@217: Most important, however, removed messages are kept in the MH domain. meillo@131: Messages in the trash folder can be listed like those in any other folder. meillo@131: Deleted messages can be displayed like any other messages. meillo@169: .Pn refile meillo@169: can restore deleted messages. meillo@131: All operations on deleted files are still covered by the MH tools. meillo@131: The trash folder is just like any other folder in the mail storage. meillo@131: .P meillo@131: Similar to the draft folder case, I dropped the old backup prefix approach meillo@131: in favor for replacing it by the better suiting trash folder system. meillo@131: Hence, meillo@131: .Pn rmm meillo@131: calls meillo@131: .Pn refile meillo@131: to move the to-be-removed message to the trash folder, meillo@131: .Fn +trash meillo@131: by default. meillo@164: To sweep it clean, the user can use meillo@131: .Cl "rmm -unlink +trash a" , meillo@131: where the meillo@131: .Sw -unlink meillo@131: switch causes the files to be unlinked. meillo@168: .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173 meillo@168: .Ci ca0b3e830b86700d9e5e31b1784de2bdcaf58fc5 meillo@131: .P meillo@217: Dropping the legacy approach and converting to the new approach meillo@217: completely, simplified the code base. meillo@131: The relationship between meillo@131: .Pn rmm meillo@131: and meillo@131: .Pn refile meillo@131: was inverted. meillo@131: In mmh, meillo@131: .Pn rmm meillo@131: invokes meillo@217: .Pn refile . meillo@217: That used to be the other way round. meillo@131: Yet, the relationship is simpler now. meillo@164: Loops, like described in nmh's man page for meillo@131: .Mp refile (1), meillo@164: can no longer occur: meillo@131: .QS meillo@131: Since meillo@131: .Pn refile meillo@131: uses your meillo@131: .Pe rmmproc meillo@131: to delete the message, the meillo@131: .Pe rmmproc meillo@131: must NOT call meillo@131: .Pn refile meillo@131: without specifying meillo@131: .Sw -normmproc meillo@131: or you will create an infinite loop. meillo@131: .QE meillo@131: .LP meillo@131: .Pn rmm meillo@131: either unlinks a message with meillo@131: .Fu unlink() meillo@131: or invokes meillo@131: .Pn refile meillo@131: to move it to the trash folder. meillo@131: .Pn refile meillo@131: does not invoke any tools. meillo@131: .P meillo@136: By generalizing the message removal in the way that it became covered meillo@136: by the MH concepts made the whole system more powerful. meillo@131: meillo@131: meillo@131: meillo@131: meillo@131: meillo@133: .H2 "Modern Defaults meillo@133: .P meillo@133: Nmh has a bunch of convenience-improving features inactive by default, meillo@217: although one can expect every new user to want them active. meillo@133: The reason they are inactive by default is the wish to stay compatible meillo@133: with old versions. meillo@217: But what are old versions? meillo@136: Still, the highly useful draft folder facility has not been activated meillo@136: by default although it was introduced over twenty-five years ago. meillo@133: .[ meillo@133: rose romine real work meillo@133: .] meillo@136: The community seems not to care. meillo@217: .P meillo@217: In nmh, new users are required to first build up meillo@217: a profile before they can access the modern features. meillo@136: Without an extensive profile, the setup is hardly usable meillo@133: for modern emailing. meillo@133: The point is not the customization of the setup, meillo@136: but the need to activate generally useful facilities. meillo@217: Yet, the real problem lies less in enabling the features, meillo@217: as this is straight forward as soon as one knows what he wants. meillo@168: The real problem is that new users need deep insight into the project meillo@217: to discover the available but inactive features. meillo@133: To give an example, I needed one year of using nmh meillo@133: before I became aware of the existence of the attachment system. meillo@133: One could argue that this fact disqualifies my reading of the meillo@133: documentation. meillo@133: If I would have installed nmh from source back then, I could agree. meillo@217: Yet, I had used a pre-packaged version and had expected that it would meillo@133: just work. meillo@133: Nevertheless, I had been convinced by the concepts of MH already meillo@133: and I am a software developer, meillo@133: still I required a lot of time to discover the cool features. meillo@133: How can we expect users to be even more advanced than me, meillo@217: just to enable them to use MH in a convenient and modern way? meillo@133: Unless they are strongly convinced of the concepts, they will fail. meillo@133: I have seen friends of me giving up disappointed meillo@133: before they truly used the system, meillo@133: although they had been motivated in the beginning. meillo@217: New users suffer hard enough to get used to the tool chest approach, meillo@179: we developers should spare them further inconveniences. meillo@133: .P meillo@136: Maintaining compatibility for its own sake is bad, meillo@217: because the code base will collect more and more compatibility code. meillo@200: Sticking to the compatibility code means remaining limited; meillo@168: whereas adjusting to the changes renders the compatibility unnecessary. meillo@217: Keeping unused alternatives in the code for longer than a short meillo@217: grace time is a bad choice as they likely meillo@217: gather bugs by not being constantly tested. meillo@136: Also, the increased code size and the greater number of conditions meillo@136: increase the maintenance costs. meillo@133: If any MH implementation would be the back-end of widespread meillo@133: email clients with large user bases, compatibility would be more meillo@133: important. meillo@133: Yet, it appears as if this is not the case. meillo@133: Hence, compatibility is hardly important for technical reasons. meillo@217: Its importance originates from personal reasons rather. meillo@133: Nmh's user base is small and old. meillo@217: Changing the interfaces causes inconvenience to long-term users of MH. meillo@217: It forces them to change their many years old MH configurations. meillo@168: I do understand this aspect, but by sticking to the old users, meillo@217: new users are kept from entering the world of MH. meillo@217: But the future lies in new users. meillo@168: In consequence, mmh invites new users by providing a convenient meillo@168: and modern setup, readily usable out-of-the-box. meillo@133: .P meillo@136: In mmh, all modern features are active by default and many previous meillo@217: approaches are removed or only accessible in a manual way. meillo@136: New default features include: meillo@133: .BU meillo@133: The attachment system (\c meillo@217: .Hd Attach ) meillo@217: .Ci 8ff284ff9167eff8f5349481529332d59ed913b1 . meillo@133: .BU meillo@133: The draft folder facility (\c meillo@217: .Fn +drafts ) meillo@217: .Ci 337338b404931f06f0db2119c9e145e8ca5a9860 . meillo@133: .BU meillo@133: The unseen sequence (`u') meillo@133: .Ci c2360569e1d8d3678e294eb7c1354cb8bf7501c1 meillo@217: and the sequence negation prefix (`!') meillo@217: .Ci db74c2bd004b2dc9bf8086a6d8bf773ac051f3cc . meillo@133: .BU meillo@217: Quoting the original message in the reply meillo@217: .Ci 67411b1f95d6ec987b4c732459e1ba8a8ac192c6 . meillo@133: .BU meillo@217: Forwarding messages using MIME meillo@217: .Ci 6e271608b7b9c23771523f88d23a4d3593010cf1 . meillo@171: .LP meillo@217: An mmh setup with a profile that defines only the path to the meillo@136: mail storage, is already convenient to use. meillo@217: Again, Paul Vixie's supports the direction I took: meillo@136: ``the `main branch' should just be modern''. meillo@136: .[ meillo@136: paul vixie edginess nmh-workers meillo@136: .] meillo@131: meillo@133: meillo@133: meillo@133: meillo@133: meillo@133: .\" -------------------------------------------------------------- meillo@131: .H1 "Styling meillo@22: .P meillo@118: Kernighan and Pike have emphasized the importance of style in the meillo@219: preface of \fPThe Practice of Programming\fP: meillo@118: .[ [ meillo@118: kernighan pike practice of programming meillo@118: .], p. x] meillo@118: .QS meillo@118: Chapter 1 discusses programming style. meillo@219: Good style is so important to good programming that we have chosen meillo@118: to cover it first. meillo@118: .QE meillo@168: This section covers changes in mmh that were guided by the desire meillo@118: to improve on style. meillo@219: Many of them follow the advice given in the quoted book. meillo@118: meillo@118: meillo@127: meillo@127: meillo@127: .H2 "Code Style meillo@154: .Id code-style meillo@118: .P meillo@118: .U3 "Indentation Style meillo@118: .P meillo@219: Indentation styles are the holy cow of programming. meillo@219: Kernighan and Pike write: meillo@118: .[ [ meillo@118: kernighan pike practice of programming meillo@118: .], p. 10] meillo@118: .QS meillo@118: Programmers have always argued about the layout of programs, meillo@118: but the specific style is much less important than its consistent meillo@118: application. meillo@121: Pick one style, preferably ours, use it consistently, and don't waste meillo@118: time arguing. meillo@118: .QE meillo@118: .P meillo@118: I agree that the constant application is most important, meillo@118: but I believe that some styles have advantages over others. meillo@118: For instance the indentation with tab characters only. meillo@219: The number of tabs corresponds to the nesting level \(en meillo@118: one tab, one level. meillo@219: Tab characters provide flexible visual appearance because developers meillo@219: can adjust their width as prefered. meillo@219: There is no more need to check for the correct mixture of meillo@219: tabs and spaces. meillo@219: Two simple rules ensure the integrity and flexibility of the visual meillo@219: appearance: meillo@219: .LI 1 meillo@219: Leading whitespace must consist of tabs only. meillo@219: .LI 2 meillo@219: All other whitespace should be spaces. meillo@219: .LP meillo@121: Although reformatting existing code should be avoided, I did it. meillo@200: I did not waste time arguing; I just reformatted the code. meillo@118: .Ci a485ed478abbd599d8c9aab48934e7a26733ecb1 meillo@118: meillo@118: .U3 "Comments meillo@118: .P meillo@219: Kernighan and Pike demand: ``Don't belabor the obvious''. meillo@118: .[ [ meillo@118: kernighan pike practice of programming meillo@118: .], p. 23] meillo@219: Following the advice, I removed unnecessary comments. meillo@219: For instance, I removed all comments in the following code excerpt meillo@219: .Ci 426543622b377fc5d091455cba685e114b6df674 : meillo@118: .VS meillo@120: context_replace(curfolder, folder); /* update current folder */ meillo@120: seq_setcur(mp, mp->lowsel); /* update current message */ meillo@120: seq_save(mp); /* synchronize message sequences */ meillo@120: folder_free(mp); /* free folder/message structure */ meillo@120: context_save(); /* save the context file */ meillo@120: meillo@120: [...] meillo@120: meillo@120: int c; /* current character */ meillo@120: char *cp; /* miscellaneous character pointer */ meillo@120: meillo@120: [...] meillo@120: meillo@120: /* NUL-terminate the field */ meillo@120: *cp = '\0'; meillo@118: VE meillo@118: .P meillo@219: The information in each of the comments was present in the code meillo@219: statements already, except for the NUL-termination, which became meillo@219: obvious from the context. meillo@136: meillo@118: meillo@118: .U3 "Names meillo@118: .P meillo@219: Regarding this topic, Kernighan and Pike suggest: meillo@118: ``Use active names for functions''. meillo@118: .[ [ meillo@118: kernighan pike practice of programming meillo@118: .], p. 4] meillo@118: One application of this rule was the rename of meillo@118: .Fu check_charset() meillo@118: to meillo@219: .Fu is_native_charset() meillo@219: .Ci 8d77b48284c58c135a6b2787e721597346ab056d . meillo@219: The same change additionally fixed a violation of ``Be accurate'', meillo@181: .[ [ meillo@181: kernighan pike practice of programming meillo@181: .], p. 4] meillo@219: as the code did not match the expectation the function suggested. meillo@219: It did not compare charset names but prefixes of them only. meillo@219: In case the native charset was `ISO-8859-1', then meillo@219: .VS meillo@219: check_charset("ISO-8859-11", strlen("ISO-8859-11")) meillo@219: VE meillo@219: had returned true although the upper halves of the code pages meillo@219: are different. meillo@118: .P meillo@118: More important than using active names is using descriptive names. meillo@145: .VS meillo@145: m_unknown(in); /* the MAGIC invocation... */ meillo@145: VE meillo@145: Renaming the obscure meillo@118: .Fu m_unknown() meillo@219: function was a delightful event, although it made the code less funny meillo@219: .Ci 611d68d19204d7cbf5bd585391249cb5bafca846 . meillo@118: .P meillo@118: Magic numbers are generally considered bad style. meillo@118: Obviously, Kernighan and Pike agree: meillo@118: ``Give names to magic numbers''. meillo@118: .[ [ meillo@118: kernighan pike practice of programming meillo@118: .], p. 19] meillo@219: .P meillo@219: The argument meillo@219: .CW outnum meillo@219: of the function meillo@219: .Fu scan() meillo@219: in meillo@219: .Fn uip/scansbr.c meillo@219: holds the number of the message to be created. meillo@219: As well it encodes program logic with negative numbers and zero. meillo@219: This led to obscure code. meillo@219: I clarified the code by introducing two variables that extracted meillo@219: the hidden information: meillo@219: .VS meillo@219: int incing = (outnum > 0); meillo@219: int ismbox = (outnum != 0); meillo@219: VE meillo@219: The readable names are thus used in conditions; meillo@219: the variable meillo@219: .CW outnum meillo@219: is used only to extract ordinary message numbers meillo@219: .Ci b8b075c77be7794f3ae9ff0e8cedb12b48fd139f . meillo@219: .P meillo@219: Through the clarity improvement of the change detours in the program meillo@219: logic of related code parts became apparent. meillo@219: The implementation was simplified. meillo@219: This possibility to improve had been invisible before meillo@219: .Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723 . meillo@219: .P meillo@219: The names just described were a first step, yet the situation meillo@219: was further improved by giving names to the magic values of meillo@219: .CW outnum : meillo@118: .VS meillo@118: #define SCN_MBOX (-1) meillo@118: #define SCN_FOLD 0 meillo@118: VE meillo@219: The two variables were updated thereafter as well: meillo@219: .VS meillo@219: int incing = (outnum != SCN_MBOX && outnum != SCN_FOLD); meillo@219: int scanfolder = (outnum == SCN_FOLD); meillo@219: VE meillo@219: Furthermore, meillo@219: .CW ismbox meillo@219: was replaced by meillo@219: .CW scanfolder meillo@219: because that matched better to the program logic. meillo@118: .Ci 7ffb36d28e517a6f3a10272056fc127592ab1c19 meillo@219: meillo@118: meillo@133: meillo@133: meillo@133: .H2 "Structural Rework meillo@133: .P meillo@219: Although the stylistic changes described already improve the meillo@219: readability of the source code, all of them were changes ``in the small''. meillo@219: Structural changes, in contrast, affect much larger code areas. meillo@219: They are more difficult to accomplish but lead to larger improvements, meillo@219: especially as they often influence the outer shape of the tools as well. meillo@118: .P meillo@118: At the end of their chapter on style, meillo@118: Kernighan and Pike ask: ``But why worry about style?'' meillo@181: .[ [ meillo@181: kernighan pike practice of programming meillo@219: .], p. 28]. meillo@219: Following are two examples of structural rework that demonstrate meillo@136: why style is important in the first place. meillo@136: meillo@136: meillo@136: .U3 "Rework of \f(CWanno\fP meillo@118: .P meillo@120: Until 2002, meillo@120: .Pn anno meillo@219: had six functional command line switches: meillo@120: .Sw -component meillo@120: and meillo@120: .Sw -text , meillo@219: each with an argument, meillo@120: and the two pairs of flags, meillo@120: .Sw -[no]date meillo@120: and meillo@120: .Sw -[no]inplace . meillo@120: Then Jon Steinhart introduced his attachment system. meillo@120: In need for more advanced annotation handling, he extended meillo@120: .Pn anno . meillo@120: He added five more switches: meillo@120: .Sw -draft , meillo@120: .Sw -list , meillo@120: .Sw -delete , meillo@120: .Sw -append , meillo@120: and meillo@120: .Sw -number , meillo@219: the last one taking an argument meillo@219: .Ci 7480dbc14bc90f2d872d434205c0784704213252 . meillo@120: Later, meillo@120: .Sw -[no]preserve meillo@219: was added as well meillo@219: .Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f . meillo@120: Then, the Synopsis section of the man page meillo@120: .Mp anno (1) meillo@120: read: meillo@120: .VS meillo@219: anno [+folder] [msgs] [-component f(CIfieldfP] [-inplace | -noinplace] meillo@120: [-date | -nodate] [-draft] [-append] [-list] [-delete] meillo@219: [-number [f(CInumfP|fPallfP]] [-preserve | -nopreserve] [-version] meillo@219: [-help] [-text f(CIbodyfP] meillo@120: VE meillo@120: .LP meillo@120: The implementation followed the same structure. meillo@120: Problems became visible when meillo@120: .Cl "anno -list -number 42 meillo@219: worked on the current message instead of on message number 42, meillo@120: and meillo@120: .Cl "anno -list -number l:5 meillo@124: did not work on the last five messages but failed with the mysterious meillo@120: error message: ``anno: missing argument to -list''. meillo@121: Yet, the invocation matched the specification in the man page. meillo@120: There, the correct use of meillo@120: .Sw -number meillo@120: was defined as being meillo@120: .Cl "[-number [num|all]] meillo@120: and the textual description for the combination with meillo@120: .Sw -list meillo@120: read: meillo@120: .QS meillo@164: The meillo@164: .Sw -list meillo@164: option produces a listing of the field bodies for meillo@120: header fields with names matching the specified component, meillo@164: one per line. The listing is numbered, starting at 1, if the meillo@164: .Sw -number meillo@164: option is also used. meillo@120: .QE meillo@120: .LP meillo@120: The problem was manifold. meillo@120: Semantically, the argument to the meillo@120: .Sw -number meillo@120: switch is only necessary in combination with meillo@120: .Sw -delete , meillo@120: but not with meillo@120: .Sw -list . meillo@219: The code, however, required a numeric argument in any case. meillo@219: If the argument was missing or non-numeric, meillo@219: .Pn anno meillo@219: aborted with an error message that additionally had an off-by-one error. meillo@219: It printed the name of the switch one before the concerned one. meillo@120: .P meillo@219: Trying to fix these problems on the surface would not have solved them. meillo@219: They originate from a discrepance between the meillo@120: structure of the problem and the structure implemented in the program. meillo@219: Such structural differences can only be solved by adjusting the meillo@219: structure of the implementation to the structure of the problem. meillo@120: .P meillo@219: Steinhart had added the new meillo@120: .Sw -list meillo@120: and meillo@120: .Sw -delete meillo@219: switches in a style similar to the other switches though meillo@219: they are of structural different type. meillo@120: Semantically, meillo@120: .Sw -list meillo@120: and meillo@120: .Sw -delete meillo@219: introduce operation modes. meillo@120: Historically, meillo@120: .Pn anno meillo@120: had only one operation mode: adding header fields. meillo@219: With the extension, two more modes were added: meillo@120: listing and deleting header fields. meillo@120: The structure of the code changes did not pay respect to this meillo@219: fundamental change. meillo@120: Neither the implementation nor the documentation did clearly meillo@219: declare the exclusive operation modes as such. meillo@120: Having identified the problem, I solved it by putting structure into meillo@120: .Pn anno meillo@219: and its documentation meillo@219: .Ci d54c8db8bdf01e8381890f7729bc0ef4a055ea11 . meillo@120: .P meillo@173: The difference is visible in both the code and the documentation. meillo@219: For instance in the following code excerpt: meillo@120: .VS meillo@120: int delete = -2; /* delete header element if set */ meillo@120: int list = 0; /* list header elements if set */ meillo@120: [...] meillo@121: case DELETESW: /* delete annotations */ meillo@121: delete = 0; meillo@121: continue; meillo@121: case LISTSW: /* produce a listing */ meillo@121: list = 1; meillo@121: continue; meillo@120: VE meillo@121: .LP meillo@219: which was replaced by: meillo@120: .VS meillo@120: static enum { MODE_ADD, MODE_DEL, MODE_LIST } mode = MODE_ADD; meillo@120: [...] meillo@121: case DELETESW: /* delete annotations */ meillo@121: mode = MODE_DEL; meillo@121: continue; meillo@121: case LISTSW: /* produce a listing */ meillo@121: mode = MODE_LIST; meillo@121: continue; meillo@120: VE meillo@120: .LP meillo@121: The replacement code does not only reflect the problem's structure better, meillo@121: it is easier to understand as well. meillo@121: The same applies to the documentation. meillo@120: The man page was completely reorganized to propagate the same structure. meillo@219: This is already visible in the Synopsis section: meillo@120: .VS meillo@219: anno [+folder] [msgs] [-component f(CIfieldfP] [-text fPbodyfP] meillo@120: [-append] [-date | -nodate] [-preserve | -nopreserve] meillo@120: [-Version] [-help] meillo@120: meillo@219: anno -delete [+folder] [msgs] [-component fPfieldfP] [-text meillo@219: fPbodyfP] [-number fPnum fP| fPall fP] [-preserve | -nopreserve] meillo@120: [-Version] [-help] meillo@120: meillo@219: anno -list [+folder] [msgs] [-component fPfieldfP] [-number] meillo@120: [-Version] [-help] meillo@120: VE meillo@118: meillo@58: meillo@58: meillo@133: .U3 "Path Conversion meillo@133: .P meillo@134: Four kinds of path names can appear in MH: meillo@171: .LI 1 meillo@134: Absolute Unix directory paths, like meillo@134: .Fn /etc/passwd . meillo@171: .LI 2 meillo@134: Relative Unix directory paths, like meillo@134: .Fn ./foo/bar . meillo@171: .LI 3 meillo@134: Absolute MH folder paths, like meillo@219: .Fn +projects/mmh . meillo@171: .LI 4 meillo@134: Relative MH folder paths, like meillo@134: .Fn @subfolder . meillo@171: .LP meillo@219: Relative MH folder paths, are hardly documented meillo@219: although they are useful for large mail storages. meillo@134: The current mail folder is specified as `\c meillo@134: .Fn @ ', meillo@134: just like the current directory is specified as `\c meillo@134: .Fn . '. meillo@134: .P meillo@134: To allow MH tools to understand all four notations, meillo@219: they need to be able to convert between them. meillo@134: In nmh, these path name conversion functions were located in the files meillo@134: .Fn sbr/path.c meillo@134: (``return a pathname'') and meillo@134: .Fn sbr/m_maildir.c meillo@134: (``get the path for the mail directory''). meillo@134: The seven functions in the two files were documented with no more meillo@134: than two comments, which described obvious information. meillo@219: The signatures of the four exported functions did not explain their meillo@219: semantics: meillo@219: .LI 1 meillo@219: .CW "char *path(char *, int); meillo@219: .LI 2 meillo@219: .CW "char *pluspath(char *); meillo@219: .LI 3 meillo@219: .CW "char *m_mailpath(char *); meillo@219: .LI 4 meillo@219: .CW "char *m_maildir(char *); meillo@134: .P meillo@219: My investigations provided the following descriptions: meillo@171: .LI 1 meillo@134: The second parameter of meillo@134: .Fu path() meillo@219: defines the type as which the path given in the first parameter should meillo@219: be treated. meillo@134: Directory paths are converted to absolute directory paths. meillo@134: Folder paths are converted to absolute folder paths. meillo@173: Folder paths must not include a leading `\fL@\fP' character. meillo@134: Leading plus characters are preserved. meillo@134: The result is a pointer to newly allocated memory. meillo@171: .LI 2 meillo@134: .Fu pluspath() meillo@134: is a convenience-wrapper to meillo@134: .Fu path() , meillo@134: to convert folder paths only. meillo@134: This function can not be used for directory paths. meillo@134: An empty string parameter causes a buffer overflow. meillo@171: .LI 3 meillo@134: .Fu m_mailpath() meillo@134: converts directory paths to absolute directory paths. meillo@173: The characters `\fL+\fP' or `\fL@\fP' at the beginning of the path name are meillo@134: treated literal, i.e. as the first character of a relative directory path. meillo@134: Hence, this function can not be used for folder paths. meillo@219: In any case, the result is an absolute directory path, meillo@219: returned as a pointer to newly allocated memory. meillo@171: .LI 4 meillo@134: .Fu m_maildir() meillo@134: returns the parameter unchanged if it is an absolute directory path meillo@173: or begins with the entry `\fL.\fP' or `\fL..\fP'. meillo@134: All other strings are prepended with the current working directory. meillo@219: Hence, this function can not be used for folder paths. meillo@134: The result is either an absolute directory path or a relative meillo@219: directory path, starting with dot or dot-dot. meillo@134: In contrast to the other functions, the result is a pointer to meillo@134: static memory. meillo@134: .P meillo@134: The situation was obscure, irritating, error-prone, and non-orthogonal. meillo@219: Additionally, no clear terminology was used to name the different meillo@219: kinds of path names. meillo@219: Sometimes, the names were even misleading, much as the first argument of meillo@134: .Fu m_mailpath() , meillo@219: which was named meillo@219: .CW folder , meillo@219: although meillo@134: .Fu m_mailpath() meillo@219: could not be used with MH folder arguments. meillo@134: .P meillo@219: I clarified the path name conversion by complete rework. meillo@134: First of all, the terminology needed to be defined. meillo@134: A path name is either in the Unix domain, then it is called meillo@219: \fIdirectory path\fP (\fIdirpath\fP for short) or it is in the MH domain, meillo@219: then it is called \fIfolder path\fP (\fIfolpath\fP for short). meillo@134: The two terms need to be used with strict distinction. meillo@219: Often a clear terminology indicates that the problem is understood. meillo@134: Second, I exploited the concept of path type indicators. meillo@219: By requiring every path name to start with a distinct type identifier, meillo@219: the conversion between the types could be fully automated. meillo@219: This allows the tools to accept paths of any type from the user. meillo@134: Therefore, it was necessary to require relative directory paths to be meillo@134: prefixed with a dot character. meillo@134: In consequence, the dot character could no longer be an alias for the meillo@134: current message. meillo@134: .Ci cff0e16925e7edbd25b8b9d6d4fbdf03e0e60c01 meillo@134: Third, I created three new functions to replace the previous mess: meillo@171: .LI 1 meillo@134: .Fu expandfol() meillo@219: converts folder paths to absolute folder paths. meillo@134: Directory paths are simply passed through. meillo@134: This function is to be used for folder paths only, thus the name. meillo@134: The result is a pointer to static memory. meillo@171: .LI 2 meillo@134: .Fu expanddir() meillo@134: converts directory paths to absolute directory paths. meillo@134: Folder paths are treated as relative directory paths. meillo@134: This function is to be used for directory paths only, thus the name. meillo@134: The result is a pointer to static memory. meillo@171: .LI 3 meillo@134: .Fu toabsdir() meillo@134: converts any type of path to an absolute directory path. meillo@134: This is the function of choice for path conversion. meillo@134: Absolute directory paths are the most general representation of a meillo@134: path name. meillo@134: The result is a pointer to static memory. meillo@134: .P meillo@180: .\" XXX ueberfluessig? meillo@134: The new functions have names that indicate their use. meillo@134: Two of the functions convert relative to absolute path names of the meillo@134: same type. meillo@134: The third function converts any path name type to the most general one, meillo@134: the absolute directory path. meillo@134: All of the functions return pointers to static memory. meillo@219: The file meillo@219: .Fn sbr/path.c meillo@219: contains the implementation of the functions; meillo@134: .Fn sbr/m_maildir.c meillo@219: was removed. meillo@168: .Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0 meillo@134: .P meillo@134: Along with the path conversion rework, I also replaced meillo@134: .Fu getfolder(FDEF) meillo@134: with meillo@134: .Fu getdeffol() meillo@134: and meillo@134: .Fu getfolder(FCUR) meillo@134: with meillo@134: .Fu getcurfol() , meillo@219: which only wraps meillo@219: .Fu expandfol(""@"") meillo@219: for convenience. meillo@134: This code was moved from meillo@134: .Fn sbr/getfolder.c meillo@219: into meillo@219: .Fn sbr/path.c meillo@219: as well. meillo@168: .Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0 meillo@134: .P meillo@134: The related function meillo@134: .Fu etcpath() meillo@219: is now included in meillo@134: .Fn sbr/path.c , meillo@168: too meillo@168: .Ci b4c29794c12099556151d93a860ee51badae2e35 . meillo@134: Previously, it had been located in meillo@219: .Fn config/config.c . meillo@134: .P meillo@219: Now, meillo@134: .Fn sbr/path.c meillo@219: contains all path handling code. meillo@219: Besides being less code, its readability is highly improved. meillo@219: The functions follow a common style and are well documented. meillo@133: meillo@133: meillo@133: meillo@133: meillo@133: .H2 "Profile Reading meillo@133: .P meillo@220: The MH profile contains the configuration of a user-specific MH setup. meillo@220: MH tools read the profile right after starting up meillo@220: because it contains the location of the user's mail storage meillo@138: and similar settings that influence the whole setup. meillo@220: Furthermore, the profile contains the default switches for the tools meillo@220: as well. meillo@220: The context file is read along with the profile. meillo@138: .P meillo@138: For historic reasons, some MH tools did not read the profile and context. meillo@138: Among them were meillo@138: .Pn post /\c meillo@138: .Pn spost , meillo@138: .Pn mhmail , meillo@138: and meillo@138: .Pn slocal . meillo@138: The reason why these tools ignored the profile were not clearly stated. meillo@220: During a discussion on the nmh-workers mailing list, meillo@181: David Levine posted an explanation, quoting John Romine: meillo@138: .[ meillo@138: nmh-workers levine post profile meillo@138: .] meillo@220: meillo@138: .QS meillo@138: I asked John Romine and here's what he had to say, which meillo@138: agrees and provides an example that convinces me: meillo@138: .QS meillo@164: My take on this is that meillo@164: .Pn post meillo@164: should not be called by users directly, and it doesn't read the meillo@164: .Fn .mh_profile meillo@138: (only front-end UI programs read the profile). meillo@138: .QP meillo@164: For example, there can be contexts where meillo@164: .Pn post meillo@164: is called by a helper program (like `\c meillo@164: .Pn mhmail ') meillo@164: which may be run by a non-MH user. meillo@164: We don't want this to prompt the user to create an MH profile, etc. meillo@138: .QP meillo@164: My suggestion would be to have meillo@164: .Pn send meillo@164: pass a (hidden) `\c meillo@164: .Sw -fileproc meillo@164: .Ar proc ' meillo@164: option to meillo@164: .Pn post meillo@164: if needed. meillo@164: You could also meillo@164: use an environment variable (I think meillo@164: .Pn send /\c meillo@164: .Pn whatnow meillo@164: do this). meillo@138: .QE meillo@220: .sp \n(PDu meillo@164: I think that's the way to go. meillo@164: My personal preference is to use a command line option, meillo@164: not an environment variable. meillo@138: .QE meillo@220: meillo@138: .P meillo@220: To solve the problem that meillo@138: .Pn post meillo@220: does not honor the meillo@138: .Pe fileproc meillo@138: profile entry, meillo@138: the community roughly agreed that a switch meillo@138: .Sw -fileproc meillo@138: should be added to meillo@138: .Pn post meillo@138: to be able to pass a different fileproc. meillo@138: I strongly disagree with this approach because it does not solve meillo@138: the problem; it only removes a single symptom. meillo@220: The actual problem is that meillo@138: .Pn post meillo@220: does not behave as expected, meillo@220: though all programs should behave as expected. meillo@220: Clear and general concepts are a precondition for this. meillo@220: Thus, there should be no separation into ``front-end UI programs'' meillo@220: and ones that ``should not be called by users directly''. meillo@220: The real solution is having all MH tools read the profile. meillo@138: .P meillo@220: But the problem has a further aspect, meillo@220: which originates from meillo@220: .Pn mhmail meillo@220: mainly. meillo@138: .Pn mhmail meillo@138: was intended to be a replacement for meillo@138: .Pn mailx meillo@138: on systems with MH installations. meillo@220: In difference to meillo@220: .Pn mailx , meillo@138: .Pn mhmail meillo@220: used MH's meillo@138: .Pn post meillo@220: to send the message. meillo@220: The idea was that using meillo@138: .Pn mhmail meillo@220: should not be influenced whether the user had meillo@138: MH set up for himself or not. meillo@220: Therefore meillo@138: .Pn mhmail meillo@220: had not read the profile. meillo@138: As meillo@138: .Pn mhmail meillo@138: used meillo@138: .Pn post , meillo@138: .Pn post meillo@220: was not allowed to read the profile neither. meillo@138: This is the reason for the actual problem. meillo@220: Yet, this was not considered much of a problem because meillo@138: .Pn post meillo@138: was not intended to be used by users directly. meillo@220: To invoke meillo@220: .Pn post , meillo@138: .Pn send meillo@220: was used an a front-end. meillo@138: .Pn send meillo@138: read the profile and passed all relevant values on the command line to meillo@138: .Pn post meillo@138: \(en an awkward solution. meillo@138: .P meillo@138: The important insight is that meillo@138: .Pn mhmail meillo@220: is a wolf in sheep's clothing. meillo@220: This alien tool broke the concepts because it was treated like meillo@220: a normal MH tool. meillo@138: Instead it should have been treated accordingly to its foreign style. meillo@220: .P meillo@220: The solution is not to prevent the tools from reading the profile but meillo@220: to instruct them to read a different profile. meillo@138: .Pn mhmail meillo@220: could have set up a well-defined profile and caused the following meillo@138: .Pn post meillo@220: to use this profile by exporting an environment variable. meillo@220: With this approach, no special cases would have been introduced meillo@220: and no surprises would have been caused. meillo@220: By writing a wrapper program to provide a clean temporary profile, meillo@220: the concept could have been generalized orthogonally to the whole meillo@220: MH tool chest. meillo@220: .P meillo@220: In mmh, the wish to have meillo@220: .Pn mhmail meillo@220: as a replacement for meillo@220: .Pn mailx meillo@220: is considered obsolete. meillo@220: Mmh's meillo@220: .Pn mhmail meillo@220: does no longer cover this use-case meillo@220: .Ci d36e56e695fe1c482c7920644bfbb6386ac9edb0 . meillo@220: Currently, meillo@220: .Pn mhmail meillo@220: is in a transition state meillo@220: .Ci 32d4f9daaa70519be3072479232ff7be0500d009 . meillo@220: It may become a front-end to meillo@220: .Pn comp , meillo@220: which provides an alternative interface which can be more convenient meillo@220: in some cases. meillo@220: This would convert meillo@220: .Pn mhmail meillo@220: into an ordinary MH tool. meillo@220: If, however, this idea does not convince, then meillo@220: .Pn mhmail meillo@220: will be removed. meillo@220: .P meillo@220: In the mmh tool chest, every program reads the profile. meillo@220: (\c meillo@220: .Pn slocal meillo@220: is not considered part of the mmh tool chest (cf. Sec. meillo@220: .Cf slocal ).) meillo@220: Mmh has no meillo@220: .Pn post meillo@220: program, but it has meillo@220: .Pn spost , meillo@220: which now does read the profile meillo@220: .Ci 3e017a7abbdf69bf0dff7a4073275961eda1ded8 . meillo@220: Following this change, meillo@220: .Pn send meillo@220: and meillo@220: .Pn spost meillo@220: can be considered for merging. meillo@220: Besides meillo@220: .Pn send , meillo@220: .Pn spost meillo@220: is only invoked directly by the to-be-changed meillo@220: .Pn mhmail meillo@220: implementation and by meillo@220: .Pn rcvdist , meillo@220: which requires rework anyway. meillo@220: meillo@220: .P meillo@220: Jeffrey Honig quoted Marshall T. Rose explaining the decision that meillo@220: .Pn post meillo@220: ignores the profile: meillo@138: .[ meillo@197: nmh-workers honig post profile meillo@138: .] meillo@138: .QS meillo@138: when you run mh commands in a script, you want all the defaults to be meillo@138: what the man page says. meillo@138: when you run a command by hand, then you want your own defaults... meillo@138: .QE meillo@138: .LP meillo@220: The explanation neither matches the problem concered exactly meillo@220: nor is the interpretation clear. meillo@220: If the described desire addresses the technical level, meillo@220: then it conflicts fundametally with the Unix philosophy, meillo@220: precisely because the indistinquishability of human and script meillo@220: input is the main reason for the huge software leverage in Unix. meillo@220: If, however, the described desire addresses the user's view, meillo@220: then different technical solutions are more appropriate. meillo@220: The two cases can be regarded simply as two different MH setups. meillo@220: Hence, mapping the problem of different behavior between interactive and meillo@220: automated use on the concept of switching between different profiles, meillo@220: marks it already solved. meillo@133: meillo@133: meillo@127: meillo@121: .H2 "Standard Libraries meillo@22: .P meillo@121: MH is one decade older than the POSIX and ANSI C standards. meillo@121: Hence, MH included own implementations of functions meillo@220: that were neither standardized nor widely available, back then. meillo@220: Today, twenty years after POSIX and ANSI C were published, meillo@220: developers can expect that systems comply with these standards. meillo@121: In consequence, MH-specific replacements for standard functions meillo@121: can and should be dropped. meillo@220: Kernighan and Pike advise: ``Use standard libraries''. meillo@121: .[ [ meillo@121: kernighan pike practice of programming meillo@121: .], p. 196] meillo@121: Actually, MH had followed this advice in history, meillo@220: but it had not adjusted to more recent changes in this field. meillo@121: The meillo@121: .Fu snprintf() meillo@121: function, for instance, was standardized with C99 and is available meillo@121: almost everywhere because of its high usefulness. meillo@220: Thus, the project's own implementation of meillo@121: .Fu snprintf() meillo@123: was dropped in March 2012 in favor for using the one of the meillo@220: standard library meillo@220: .Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 . meillo@123: Such decisions limit the portability of mmh meillo@173: if systems do not support these standardized and widespread functions. meillo@123: This compromise is made because mmh focuses on the future. meillo@121: .P meillo@180: .\" XXX kuerzen und mit dem naechsten Absatz vereinen meillo@220: As I am still in my twenties, have no programming experience from meillo@220: past decades. meillo@220: I have not followed the evolution of C through time. meillo@220: I have not suffered from the the Unix wars. meillo@121: I have not longed for standardization. meillo@121: All my programming experience is from a time when ANSI C and POSIX meillo@121: were well established already. meillo@220: Thus, I needed to learn about the history in retrospective. meillo@121: I have only read a lot of books about the (good) old times. meillo@220: This put me in a difficult position when working with old code. meillo@123: I need to freshly acquire knowledge about old code constructs and ancient meillo@123: programming styles, whereas older programmers know these things by meillo@123: heart from their own experience. meillo@123: Being aware of the situation, I rather let people with more historic meillo@220: experience do the transition from ancient code constructs to meillo@220: standardized ones. meillo@121: Lyndon Nerenberg covered large parts of this task for the nmh project. meillo@121: He converted project-specific functions to POSIX replacements, meillo@121: also removing the conditionals compilation of now standardized features. meillo@220: Ken Hornstein and David Levine had their part in this work, as well. meillo@220: Often, I only pulled the changes over from nmh into mmh. meillo@220: These changes include many commits, among them: meillo@121: .Ci 768b5edd9623b7238e12ec8dfc409b82a1ed9e2d meillo@121: .Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 . meillo@102: .P meillo@220: Nevertheless, I worked on the task as well, tidying up the meillo@220: \fIMH standard library\fP, meillo@220: .Fn libmh.a . meillo@220: It is located in the meillo@123: .Fn sbr meillo@220: (``subroutines'') directory in the source tree and meillo@220: includes functions that mmh tools usually need. meillo@123: Among them are MH-specific functions for profile, context, sequence, meillo@123: and folder handling, but as well meillo@123: MH-independent functions, such as auxiliary string functions, meillo@123: portability interfaces and error-checking wrappers for critical meillo@123: functions of the standard library. meillo@220: .BU meillo@123: I have replaced the meillo@121: .Fu atooi() meillo@121: function with calls to meillo@220: .Fu strtoul() , meillo@220: setting the third parameter, the base, to eight. meillo@123: .Fu strtoul() meillo@220: is part of C89 and thus considered safe to use meillo@220: .Ci c490c51b3c0f8871b6953bd0c74551404f840a74 . meillo@220: .BU meillo@121: I did remove project-included fallback implementations of meillo@121: .Fu memmove() meillo@121: and meillo@220: .Fu strerror() meillo@220: .Ci b067ff5c465a5d243ce5a19e562085a9a1a97215 , meillo@121: although Peter Maydell had re-included them into nmh in 2008 meillo@121: to support SunOS 4. meillo@121: Nevertheless, these functions are part of ANSI C. meillo@121: Systems that do not even provide full ANSI C support should not meillo@121: put a load on mmh. meillo@220: .BU meillo@121: The meillo@121: .Fu copy() meillo@180: function copies the string in parameter one to the location in meillo@180: parameter two. meillo@121: In contrast to meillo@121: .Fu strcpy() , meillo@121: it returns a pointer to the terminating null-byte in the destination area. meillo@123: The code was adjusted to replace meillo@121: .Fu copy() meillo@123: with meillo@121: .Fu strcpy() , meillo@121: except within meillo@121: .Fu concat() , meillo@121: where meillo@121: .Fu copy() meillo@123: was more convenient. meillo@123: Therefore, the definition of meillo@121: .Fu copy() meillo@123: was moved into the source file of meillo@121: .Fu concat() meillo@220: and its visibility it limited to that meillo@220: .Ci 552fd7253e5ee9e554c5c7a8248a6322aa4363bb . meillo@220: .BU meillo@121: The function meillo@121: .Fu r1bindex() meillo@121: had been a generalized version of meillo@121: .Fu basename() meillo@121: with minor differences. meillo@121: As all calls to meillo@121: .Fu r1bindex() meillo@220: had the slash (`\fL/\fP') as delimiter anyway, meillo@121: replacing meillo@121: .Fu r1bindex() meillo@121: with the more specific and better-named function meillo@121: .Fu basename() meillo@121: became desirable. meillo@121: Unfortunately, many of the 54 calls to meillo@121: .Fu r1bindex() meillo@123: depended on a special behavior, meillo@121: which differed from the POSIX specification for meillo@121: .Fu basename() . meillo@121: Hence, meillo@121: .Fu r1bindex() meillo@121: was kept but renamed to meillo@123: .Fu mhbasename() , meillo@220: setting the delimiter to the slash meillo@220: .Ci 240013872c392fe644bd4f79382d9f5314b4ea60 . meillo@121: For possible uses of meillo@121: .Fu r1bindex() meillo@121: with a different delimiter, meillo@121: the ANSI C function meillo@121: .Fu strrchr() meillo@121: provides the core functionality. meillo@220: .BU meillo@121: The meillo@121: .Fu ssequal() meillo@121: function \(en apparently for ``substring equal'' \(en meillo@121: was renamed to meillo@121: .Fu isprefix() , meillo@220: because this is what it actually checked meillo@220: .Ci c20b4fa14515c7ab388ce35411d89a7a92300711. meillo@220: Its source file had included both of the following comments, no joke. meillo@220: .in -\n(PIu meillo@121: .VS meillo@121: /* meillo@121: * THIS CODE DOES NOT WORK AS ADVERTISED. meillo@121: * It is actually checking if s1 is a PREFIX of s2. meillo@121: * All calls to this function need to be checked to see meillo@121: * if that needs to be changed. Prefix checking is cheaper, so meillo@121: * should be kept if it's sufficient. meillo@121: */ meillo@121: meillo@121: /* meillo@121: * Check if s1 is a substring of s2. meillo@121: * If yes, then return 1, else return 0. meillo@121: */ meillo@121: VE meillo@220: .in +\n(PIu meillo@220: Eventually, the function was completely replaced with calls to meillo@220: .Fu strncmp() meillo@220: .Ci b0b1dd37ff515578cf7cba51625189eb34a196cb . meillo@121: meillo@102: meillo@102: meillo@102: meillo@133: meillo@133: .H2 "User Data Locations meillo@133: .P meillo@133: In nmh, a personal setup consists of the MH profile and the MH directory. meillo@133: The profile is a file named meillo@133: .Fn \&.mh_profile meillo@133: in the user's home directory. meillo@133: It contains the static configuration. meillo@133: It also contains the location of the MH directory in the profile entry meillo@133: .Pe Path . meillo@133: The MH directory contains the mail storage and is the first meillo@220: place to search for form files, scan formats, and similar meillo@133: configuration files. meillo@133: The location of the MH directory can be chosen freely by the user. meillo@220: The usual name is a directory named meillo@133: .Fn Mail meillo@220: in the user's home directory. meillo@133: .P meillo@200: The way MH data is split between profile and MH directory is a legacy. meillo@133: It is only sensible in a situation where the profile is the only meillo@133: configuration file. meillo@133: Why else should the mail storage and the configuration files be intermixed? meillo@220: They are of different kind: meillo@220: One kind is the data to be operated on and the other kind is meillo@220: the configuration to change how tools operate. meillo@133: Splitting the configuration between the profile and the MH directory meillo@220: is inappropriate, as well. meillo@220: I improved the situation by breaking compatibility. meillo@133: .P meillo@220: In mmh, personal data is grouped by type. meillo@220: This results in two distinct parts: meillo@171: the mail storage and the configuration. meillo@220: The mail storage directory still contains all the messages, meillo@133: but, in exception of public sequences files, nothing else. meillo@133: In difference to nmh, the auxiliary configuration files are no longer meillo@133: located there. meillo@133: Therefore, the directory is no longer called the user's \fIMH directory\fP meillo@220: but the user's \fImail storage\fP. meillo@133: Its location is still user-chosen, with the default name meillo@220: .Fn Mail meillo@133: in the user's home directory. meillo@220: The configuration is grouped together in the hidden directory meillo@133: .Fn \&.mmh meillo@133: in the user's home directory. meillo@133: This \fImmh directory\fP contains the context file, personal forms, meillo@133: scan formats, and the like, but also the user's profile, now named meillo@133: .Fn profile . meillo@220: The path to the profile is no longer meillo@133: .Fn $HOME/.mh_profile meillo@220: but meillo@133: .Fn $HOME/.mmh/profile . meillo@220: (The alternative of having file meillo@133: .Fn $HOME/.mh_profile meillo@220: and a configuration directory meillo@133: .Fn $HOME/.mmh meillo@220: appeared to be inconsistent.) meillo@220: .P meillo@133: The approach chosen for mmh is consistent, simple, and familiar to meillo@133: Unix users. meillo@220: The main achievement of the change is the clear and sensible separation meillo@220: of the mail storage and the configuration. meillo@168: .Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b meillo@133: .P meillo@220: As MH allows users to have multiple MH setups, meillo@220: it is necessary to switch the profile. meillo@133: The profile is the single entry point to access the rest of a meillo@133: personal MH setup. meillo@133: In nmh, the environment variable meillo@133: .Ev MH meillo@220: is used to specify a different profile. meillo@220: To operate in the same MH setup with a separate context, the meillo@133: .Ev MHCONTEXT meillo@220: environment variable is used. meillo@220: This allows having a separate current folder in each terminal at meillo@220: the same time, for instance. meillo@220: In mmh, three environment variables replace the two of nmh. meillo@133: .Ev MMH meillo@133: overrides the default location of the mmh directory (\c meillo@133: .Fn .mmh ). meillo@133: .Ev MMHP meillo@133: and meillo@133: .Ev MMHC meillo@220: override the paths to the profile and context file, respectively. meillo@133: This approach allows the set of personal configuration files to be chosen meillo@220: independently of the profile, context, and mail storage. meillo@133: The new approach has no functional disadvantages, meillo@133: as every setup I can imagine can be implemented with both approaches, meillo@220: possibly even easier with the new one. meillo@220: .Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b meillo@133: meillo@133: meillo@133: meillo@133: meillo@133: meillo@118: .H2 "Modularization meillo@220: .Id modularization meillo@118: .P meillo@123: The source code of the mmh tools is located in the meillo@122: .Fn uip meillo@123: (``user interface programs'') directory. meillo@180: Each tool has a source file with the name of the command. meillo@122: For example, meillo@122: .Pn rmm meillo@122: is built from meillo@122: .Fn uip/rmm.c . meillo@123: Some source files are used for multiple programs. meillo@122: For example meillo@122: .Fn uip/scansbr.c meillo@173: is used for both meillo@122: .Pn scan meillo@122: and meillo@122: .Pn inc . meillo@122: In nmh, 49 tools were built from 76 source files. meillo@123: This is a ratio of 1.6 source files per program. meillo@123: 32 programs depended on multiple source files; meillo@123: 17 programs depended on one source file only. meillo@122: In mmh, 39 tools are built from 51 source files. meillo@123: This is a ratio of 1.3 source files per program. meillo@123: 18 programs depend on multiple source files; meillo@123: 21 programs depend on one source file only. meillo@123: (These numbers and the ones in the following text ignore the MH library meillo@123: as well as shell scripts and multiple names for the same program.) meillo@180: .\" XXX graph meillo@122: .P meillo@123: Splitting the source code of a large program into multiple files can meillo@220: increase the readability of its source code, meillo@220: but most of the mmh tools are small and straight-forward programs. meillo@220: In exception of the MIME handling tools (i.e. meillo@122: .Pn mhbuild , meillo@122: .Pn mhstore , meillo@122: .Pn show , meillo@220: etc.), meillo@220: .Pn pick meillo@220: is the only tool with more than one thousand lines of source code. meillo@220: Splitting programs with less than one thousand lines of code into meillo@220: multiple source files leads seldom to better readability. meillo@220: For such tools, splitting still makes sense meillo@220: when parts of the code are reused in other programs meillo@179: and the reused code fragment is (1) not general enough meillo@179: for including it in the MH library meillo@179: or (2) has dependencies on a library that only few programs need. meillo@122: .Fn uip/packsbr.c , meillo@122: for instance, provides the core program logic for the meillo@122: .Pn packf meillo@122: and meillo@122: .Pn rcvpack meillo@122: programs. meillo@122: .Fn uip/packf.c meillo@122: and meillo@122: .Fn uip/rcvpack.c meillo@122: mainly wrap the core function appropriately. meillo@122: No other tools use the folder packing functions. meillo@123: As another example, meillo@123: .Fn uip/termsbr.c meillo@220: accesses terminal properties, which requires linking with the meillo@220: \fItermcap\fP or a \fIcurses\fP library. meillo@220: If meillo@123: .Fn uip/termsbr.c meillo@220: is included in the MH library, then every program needs to be linked meillo@220: with termcap or curses, although only few of the programs use meillo@220: the library. meillo@122: .P meillo@122: The task of MIME handling is complex enough that splitting its code meillo@122: into multiple source files improves the readability. meillo@122: The program meillo@122: .Pn mhstore , meillo@122: for instance, is compiled out of seven source files with 2\|500 meillo@122: lines of code in summary. meillo@122: The main code file meillo@122: .Fn uip/mhstore.c meillo@220: consists of 800 lines; the other 1\|700 lines are code reused in meillo@123: other MIME handling tools. meillo@123: It seems to be worthwhile to bundle the generic MIME handling code into meillo@123: a MH-MIME library, as a companion to the MH standard library. meillo@220: This is left to be done. meillo@122: .P meillo@169: The work already accomplished focussed on the non-MIME tools. meillo@122: The amount of code compiled into each program was reduced. meillo@123: This eases the understanding of the code base. meillo@122: In nmh, meillo@122: .Pn comp meillo@122: was built from six source files: meillo@122: .Fn comp.c , meillo@122: .Fn whatnowproc.c , meillo@122: .Fn whatnowsbr.c , meillo@122: .Fn sendsbr.c , meillo@122: .Fn annosbr.c , meillo@122: and meillo@122: .Fn distsbr.c . meillo@122: In mmh, it builds from only two: meillo@122: .Fn comp.c meillo@122: and meillo@122: .Fn whatnowproc.c . meillo@123: In nmh's meillo@123: .Pn comp , meillo@123: the core function of meillo@122: .Pn whatnow , meillo@122: .Pn send , meillo@122: and meillo@122: .Pn anno meillo@220: were all compiled into meillo@122: .Pn comp . meillo@123: This saved the need to execute these programs with meillo@220: the expensive system calls meillo@122: .Fu fork() meillo@122: and meillo@220: .Fu exec() . meillo@171: Whereas this approach improved the time performance, meillo@171: it interwove the source code. meillo@122: Core functionalities were not encapsulated into programs but into meillo@122: function, which were then wrapped by programs. meillo@122: For example, meillo@122: .Fn uip/annosbr.c meillo@122: included the function meillo@122: .Fu annotate() . meillo@122: Each program that wanted to annotate messages, included the source file meillo@123: .Fn uip/annosbr.c meillo@123: and called meillo@123: .Fu annotate() . meillo@123: Because the function meillo@123: .Fu annotate() meillo@123: was used like the tool meillo@123: .Pn anno , meillo@123: it had seven parameters, reflecting the command line switches of the tool. meillo@122: When another pair of command line switches was added to meillo@122: .Pn anno , meillo@122: a rather ugly hack was implemented to avoid adding another parameter meillo@220: to the function meillo@220: .Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f . meillo@122: .P meillo@122: In mmh, the relevant code of meillo@122: .Pn comp meillo@122: comprises the two files meillo@122: .Fn uip/comp.c meillo@122: and meillo@122: .Fn uip/whatnowproc.c , meillo@220: together 210 lines of code, meillo@220: whereas in nmh, meillo@122: .Pn comp meillo@122: comprises six files with 2\|450 lines. meillo@220: Not all of the code in these six files is actually used by meillo@122: .Pn comp , meillo@220: but the reader needed to read it all to know which parts are relevant. meillo@220: Understanding nmh's meillo@122: .Pn comp , meillo@123: required understanding the inner workings of meillo@122: .Fn uip/annosbr.c meillo@122: first. meillo@123: To be sure to fully understand a program, its whole source code needs meillo@122: to be examined. meillo@123: Not doing so is a leap of faith, assuming that the developers meillo@122: have avoided obscure programming techniques. meillo@220: Here, it should be recalled that information passed in obscure ways meillo@220: through the program's source base, due to the aforementioned hack meillo@220: to save an additional parameter in nmh's meillo@220: .Pn anno . meillo@220: .P meillo@220: In mmh, understanding meillo@220: .Pn comp meillo@220: requires to read only 210 lines of code to read, whereas the amount meillo@220: is ten times more for nmh's meillo@220: .Pn comp . meillo@220: .P meillo@220: By separating the tools on the program-level, meillo@220: the boundaries are clearly visible, as the interfaces are calls to meillo@122: .Fu exec() meillo@122: rather than arbitrary function calls. meillo@220: Additionally, this kind of separation is more strict because meillo@220: it is technically enforced by the operating system; meillo@220: it can not be simply bypassed with global variables. meillo@220: Good separation simplifies the understanding of program code meillo@220: because the area influenced by any particular statement is small. meillo@220: As I have read a lot in nmh's code base during the last two years, meillo@220: I have learned about the easy and the difficult parts. meillo@220: In my observation, the understanding of code is enormously eased meillo@220: if the influenced area is small and clearly bounded. meillo@123: .P meillo@220: Yet, the real problem is another: meillo@123: Nmh violates the golden ``one tool, one job'' rule of the Unix philosophy. meillo@123: Understanding meillo@122: .Pn comp meillo@123: requires understanding meillo@123: .Fn uip/annosbr.c meillo@123: and meillo@123: .Fn uip/sendsbr.c meillo@123: because meillo@123: .Pn comp meillo@220: annotates and sends messages. meillo@220: In nmh, there surely exist the tools meillo@220: .Pn anno meillo@220: and meillo@122: .Pn send , meillo@220: which cover these jobs, meillo@220: but meillo@122: .Pn comp meillo@123: and meillo@122: .Pn repl meillo@122: and meillo@122: .Pn forw meillo@122: and meillo@122: .Pn dist meillo@122: and meillo@122: .Pn whatnow meillo@122: and meillo@220: .Pn viamail meillo@220: \(en they all (!) \(en meillo@220: have the same annotating and sending functions included, once more. meillo@220: As a result, meillo@123: .Pn comp meillo@123: sends messages without using meillo@123: .Pn send . meillo@123: The situation is the same as if meillo@123: .Pn grep meillo@220: would page its output without using meillo@123: .Pn more meillo@123: just because both programs are part of the same code base. meillo@123: .P meillo@220: The clear separation on the surface of nmh meillo@220: \(en the tool chest approach \(en meillo@123: is violated on the level below. meillo@122: This violation is for the sake of time performance. meillo@220: Decades ago, sacrificing readability and conceptional beauty meillo@220: for speed might have been necessary to prevent MH from being meillo@220: unusably slow, but today this is not the case anymore. meillo@220: No longer should speed improvements that became unnecessary be kept. meillo@220: No longer should readability or conceptional beauty be sacrificed. meillo@220: No longer should the Unix philosophy's ``one tool, one job'' meillo@220: guideline be violated. meillo@123: Therefore, mmh's meillo@123: .Pn comp meillo@220: no longer sends messages. meillo@220: .P meillo@123: In mmh, different jobs are divided among separate programs that meillo@122: invoke each other as needed. meillo@123: In consequence, meillo@123: .Pn comp meillo@123: invokes meillo@123: .Pn whatnow meillo@123: which thereafter invokes meillo@220: .Pn send meillo@168: .Ci 3df5ab3c116e6d4a2fb4bb5cc9dfc5f781825815 meillo@220: .Ci c73c00bfccd22ec77e9593f47462aeca4a8cd9c0 . meillo@123: The clear separation on the surface is maintained on the level below. meillo@220: Human users and other tools use the same interface \(en meillo@123: annotations, for example, are made by invoking meillo@123: .Pn anno , meillo@220: no matter if requested by programs or by human beings meillo@168: .Ci 469a4163c2a1a43731d412eaa5d9cae7d670c48b meillo@168: .Ci aed384169af5204b8002d06e7a22f89197963d2d meillo@220: .Ci 3caf9e298a8861729ca8b8a84f57022b6f3ea742 . meillo@123: The decrease of tools built from multiple source files and thus meillo@123: the decrease of meillo@123: .Fn uip/*sbr.c meillo@220: files confirm the improvement meillo@168: .Ci 9e6d91313f01c96b4058d6bf419a8ca9a207bc33 meillo@168: .ci 81744a46ac9f845d6c2b9908074d269275178d2e meillo@168: .Ci f0f858069d21111f0dbea510044593f89c9b0829 meillo@168: .Ci 0503a6e9be34f24858b55b555a5c948182b9f24b meillo@168: .Ci 27826f9353e0f0b04590b7d0f8f83e60462b90f0 meillo@168: .Ci d1da1f94ce62160aebb30df4063ccbc53768656b meillo@220: .Ci c42222869e318fff5dec395eca3e776db3075455 . meillo@220: This is also visible in the complexity of the build dependency graphs: meillo@145: meillo@220: .sp meillo@220: Nmh: meillo@220: .BP input/deps-nmh.eps .5i meillo@220: .EP meillo@220: .sp meillo@220: Mmh: meillo@220: .BP input/deps-mmh.eps .8i meillo@220: .EP meillo@145: meillo@220: The figures display all program to source file relationships meillo@220: that are not one-to-one, meillo@220: i.e. all programs that are built from multiple source files. meillo@220: The primary source file of each program is omited from the graph.