docs/master
view discussion.roff @ 193:74a76ad00ba0
Improvements in the graphs.
| author | markus schnalke <meillo@marmaro.de> |
|---|---|
| date | Wed, 11 Jul 2012 20:34:01 +0200 |
| parents | 4c5055a0e981 |
| children | 05a243dffaca |
line source
1 .H0 "Discussion
2 .P
3 This main chapter discusses the practical work accomplished in the
4 mmh project.
5 It is structured along the goals set for the project.
6 The concrete work undertaken
7 is described in the examples of how the general goals were achieved.
8 The discussion compares the current version of mmh with the state of
9 nmh just before the mmh project started, i.e. fall 2011.
10 Current changes of nmh will be mentioned only as side notes.
11 .\" XXX where do I discuss the parallel development of nmh?
12 .P
13 For the reader's convenience, the structure of modern email systems
14 is depicted in the figure.
15 It illustrates the path a message takes from sender to recipient.
16 .sp
17 .KS
18 .in 2c
19 .so input/mail-agents.pic
20 .KE
21 .sp
22 .LP
23 The ellipses denote mail agents, i.e. different jobs in email processing:
24 .IP "Mail User Agent (MUA)
25 The only program the user interacts directly with.
26 It includes functions to compose new mail, display received mail,
27 and to manage the mail storage.
28 Also called \fImail client\fP.
29 .IP "Mail Submission Agent (MSA)
30 A special kind of Mail Transfer Agent, used to submit mail into the
31 mail transport system.
32 .IP "Mail Transfer Agent (MTA)
33 A node in the mail transport system.
34 Transfers incoming mail to a transport node nearer to the final destination.
35 It may be the final destination itself.
36 .IP "Mail Delivery Agent (MDA)
37 Delivers mail by storing it onto disk, usually according to a set of rules.
38 .IP "Mail Retrieval Agent (MRA)
39 Initiates the transfer of mail from a remote server to the local machine.
40 (The dashed arrow represents the pull request.)
41 .P
42 The dashed boxes represent groups that usually reside on single machines.
43 The box on the lower left represents the sender's local system.
44 The box on the upper left represents the first mail transfer node.
45 The box on the upper right represents the transfer node responsible for the
46 destination address.
47 The box on the lower right represents the recipient's local system.
48 Often, the boxes above the dotted line are servers on the Internet.
49 Many mail clients, including nmh, have all of the components below
50 the dotted line implemented.
51 Not so in mmh, which is an MUA only.
58 .\" --------------------------------------------------------------
59 .H1 "Streamlining
61 .P
62 MH once provided anything necessary for email handling.
63 The community around nmh has the similar understanding that nmh should
64 provide a complete email system.
65 In fundamental contrast, mmh shall be an MUA only.
66 I believe that the development of all-in-one mail systems is obsolete.
67 Today, email is too complex to be fully covered by a single project.
68 Such a project will not be able to excel in all aspects.
69 Instead, the aspects of email should be covered by multiple projects,
70 which then can be combined to form a complete system.
71 Excellent implementations for the various aspects of email already exist.
72 Just to name three examples: Postfix is a specialized MTA,
73 .\" XXX homepages verlinken
74 Procmail is a specialized MDA, and Fetchmail is a specialized MRA.
75 I believe that it is best to use such specialized tools instead of
76 providing the same function again as a side-component in the project.
77 .\" XXX mail agent picture here
78 .P
79 Doing something well requires focusing on a small set of specific aspects.
80 Under the assumption that development focussed on a particular area
81 produces better results there, specialized projects will be superior
82 in their field of focus.
83 Hence, all-in-one mail system projects \(en no matter if monolithic
84 or modular \(en will never be the best choice in any of the fields.
85 Even in providing the best consistent all-in-one system, they are likely
86 to be beaten by projects that focus only on integrating existing mail
87 components to create a homogeneous system.
88 .P
89 The limiting resource in the community development of free software
90 is usually man power.
91 .\" XXX FIXME ref!
92 If the development power is spread over a large development area,
93 it becomes even more difficult to compete with the specialists in the
94 various fields.
95 The concrete situation for MH-based mail systems is even tougher,
96 given their small and aged community, concerning both developers and users.
97 .P
98 In consequence, I believe that the available development resources
99 should focus on the point where MH is most unique.
100 This is clearly the user interface \(en the MUA.
101 Peripheral parts should be removed to streamline mmh for the MUA task.
104 .H2 "Mail Transfer Facilities
105 .Id mail-transfer-facilities
106 .P
107 In contrast to nmh, which also provides mail submission and mail retrieval
108 agents, mmh is an MUA only.
109 This general difference initiated the development of mmh.
110 The removal of the mail transfer facilities was the first work task
111 in the mmh project.
112 .P
113 Focusing on one mail agent role only, is motivated by Eric Allman's
114 experience with Sendmail.
115 He identified the limitation of Sendmail to the MTA task as one reason for
116 its success:
117 .[ [
118 costales sendmail
119 .], p. xviii]
120 .QS
121 Second, I limited myself to the routing function \(en
122 I wouldn't write user agents or delivery back-ends.
123 This was a departure of the dominant through of the time,
124 in which routing logic, local delivery, and often the network code
125 were incorporated directly into the user agents.
126 .QE
127 .P
128 In nmh, the MSA is called \fIMessage Transfer Service\fP (MTS).
129 This facility, implemented by the
130 .Pn post
131 command, established network connections and spoke SMTP to submit
132 messages to be relayed to the outside world.
133 The changes in email demanded changes in this part of nmh as well.
134 Encryption and authentication for network connections
135 needed to be supported, hence TLS and SASL were introduced into nmh.
136 This added complexity to nmh without improving it in its core functions.
137 Also, keeping up with recent developments in the field of
138 mail transfer requires development power and specialists.
139 In mmh, this whole facility was simply cut off.
140 .Ci f6aa95b724fd8c791164abe7ee5468bf5c34f226
141 .Ci fecd5d34f65597a4dfa16aeabea7d74b191532c3
142 .Ci 156d35f6425bea4c1ed3c4c79783dc613379c65b
143 Instead, mmh depends on an external MSA.
144 The only outgoing interface available to mmh is the
145 .Pn sendmail
146 command, which almost any MSA provides.
147 If not, a wrapper program can be written.
148 It must read the message from the standard input, extract the
149 recipient addresses from the message header, and hand the message
150 over to the MSA.
151 For example, a wrapper script for qmail would be:
152 .VS
153 #!/bin/sh
154 exec qmail-inject # ignore command line arguments
155 VE
156 The requirement to parse the recipient addresses out of the message header
157 is likely to be removed in the future.
158 Then mmh would pass the recipient addresses as command line arguments.
159 This appears to be the better interface.
160 .\" XXX implement it
161 .P
162 To retrieve mail, the
163 .Pn inc
164 command acted as an MRA.
165 It established network connections
166 and spoke POP3 to retrieve mail from remote servers.
167 As with mail submission, the network connections required encryption and
168 authentication, thus TLS and SASL were added.
169 Support for message retrieval through IMAP will soon become necessary
170 additions, too, and likewise for any other changes in mail transfer.
171 Not so for mmh because it has dropped the support for retrieving mail
172 from remote locations.
173 .Ci ab7b48411962d26439f92f35ed084d3d6275459c
174 Instead, it depends on an external tool to cover this task.
175 Mmh has two paths for messages to enter mmh's mail storage:
176 (1) Mail can be incorporated with
177 .Pn inc
178 from the system maildrop, or (2) with
179 .Pn rcvstore
180 by reading them, one at a time, from the standard input.
181 .P
182 With the removal of the MSA and MRA, mmh converted from an all-in-one
183 mail system to being an MUA only.
184 Now, of course, mmh depends on third-party software.
185 An external MSA is required to transfer mail to the outside world;
186 an external MRA is required to retrieve mail from remote machines.
187 Excellent implementations of such software exist,
188 which likely are superior than the internal version.
189 Additionally, the best suiting programs can be freely chosen.
190 .P
191 As it had already been possible to use an external MSA or MRA,
192 why not keep the internal version for convenience?
193 .\" XXX ueberleitung
194 The question whether there is sense in having a fall-back pager in all
195 the command line tools, for the cases when
196 .Pn more
197 or
198 .Pn less
199 are not available, appears to be ridiculous.
200 Of course, MSAs and MRAs are more complex than text pagers
201 and not necessarily available but still the concept of orthogonal
202 design holds: ``Write programs that do one thing and do it well.''
203 .[
204 mcilroy unix phil
205 p. 53
206 .]
207 .[
208 mcilroy bstj foreword
209 .]
210 Here, this part of the Unix philosophy was applied not only
211 to the programs but to the project itself.
212 In other words:
213 Develop projects that focus on one thing and do it well.
214 Projects which have grown complex should be split, for the same
215 reasons that programs which have grown complex should be split.
216 If it is conceptionally more elegant to have the MSA and MRA as
217 separate projects then they should be separated.
218 In my opinion, this is the case here.
219 The RFCs propose this separation by clearly distinguishing the different
220 mail handling tasks.
221 .[
222 rfc 821
223 .]
224 The small interfaces between the mail agents support the separation.
225 .P
226 Email once had been small and simple.
227 At that time,
228 .Pn /bin/mail
229 had covered everything there was to email and still was small and simple.
230 Later, the essential complexity of email increased.
231 (Essential complexity is the complexity defined by the problem itself.\0
232 .[[
233 brooks no silver bullet
234 .]])
235 Email systems reacted to this change: they grew.
236 RFCs started to introduce the concept of mail agents to separate the
237 various tasks because they became more extensive and new tasks appeared.
238 As the mail systems grew even more, parts were split off.
239 For instance, a POP server was included in the original MH;
240 it was removed in nmh.
241 Now is the time to go one step further and split off the MSA and MRA, too.
242 Not only does this decrease the code size of the project,
243 more importantly, it unburdens mmh of the whole field of
244 message transfer with all its implications for the project.
245 There is no more need for concern with changes in network transfer.
246 This independence is gained by depending on an external program
247 that covers the field.
248 Today, this is a reasonable exchange.
249 .P
250 .\" XXX ueberleitung ???
251 Functionality can be added in three different ways:
252 .LI 1
253 Implementing the function in the project itself.
254 .LI 2
255 Depending on a library that provides the function.
256 .LI 3
257 Depending on a program that provides the function.
258 .LP
259 .\" XXX Rework sentence
260 While implementing the function in the project itself leads to the
261 largest increase in code size and requires the most maintenance
262 and development work,
263 it increases the project's independence of other software the most.
264 Using libraries or external programs requires less maintenance work
265 but introduces dependencies on external software.
266 Programs have the smallest interfaces and provide the best separation,
267 but possibly limit the information exchange.
268 External libraries are more strongly connected than external programs,
269 thus information can be exchanged in a more flexible manner.
270 Adding code to a project increases maintenance work.
271 .\" XXX ref
272 Implementing complex functions in the project itself adds
273 a lot of code.
274 This should be avoided if possible.
275 Hence, the dependencies only change in their character,
276 not in their existence.
277 In mmh, library dependencies on
278 .Pn libsasl2
279 and
280 .Pn libcrypto /\c
281 .Pn libssl
282 were traded against program dependencies on an MSA and an MRA.
283 This also meant trading build-time dependencies against run-time
284 dependencies.
285 Besides providing stronger separation and greater flexibility,
286 program dependencies also allowed
287 over 6\|000 lines of code to be removed from mmh.
288 This made mmh's code base about 12\|% smaller.
289 Reducing the project's code size by such an amount without actually
290 losing functionality is a convincing argument.
291 Actually, as external MSAs and MRAs are likely superior to the
292 project's internal versions, the common user even gains functionality.
293 .P
294 Users of MH should not have problems setting up an external MSA and MRA.
295 Also, the popular MSAs and MRAs have large communities and a lot
296 of available documentation.
297 Choices for MSAs range from full-featured MTAs such as
298 .\" XXX refs
299 .I Postfix ,
300 over mid-size MTAs such as
301 .I masqmail
302 and
303 .I dma ,
304 to small forwarders such as
305 .I ssmtp
306 and
307 .I nullmailer .
308 Choices for MRAs include
309 .I fetchmail ,
310 .I getmail ,
311 .I mpop
312 and
313 .I fdm .
316 .H2 "Non-MUA Tools
317 .P
318 One goal of mmh is to remove the tools that are not part of the MUA's task.
319 Furthermore, any tools that do not significantly improve the MUA's job
320 should be removed.
321 Loosely related and rarely used tools distract from the lean appearance.
322 They require maintenance work without adding much to the core task.
323 By removing these tools, the project shall become more streamlined
324 and focused.
325 In mmh, the following tools are not available anymore:
326 .BU
327 .Pn conflict
328 was removed
329 .Ci 8b235097cbd11d728c07b966cf131aa7133ce5a9
330 because it is a mail system maintenance tool that is not MUA-related.
331 It even checked
332 .Fn /etc/passwd
333 and
334 .Fn /etc/group
335 for consistency, which is completely unrelated to email.
336 A tool like
337 .Pn conflict
338 is surely useful, but it should not be shipped with mmh.
339 .\" XXX historic reasons?
340 .BU
341 .Pn rcvtty
342 was removed
343 .Ci 14767c94b3827be7c867196467ed7aea5f6f49b0
344 because its use case of writing to the user's terminal
345 on receival of mail is obsolete.
346 If users like to be informed of new mail, the shell's
347 .Ev MAILPATH
348 variable or graphical notifications are technically more appealing.
349 Writing directly to terminals is hardly ever desired today.
350 If, though, one prefers this approach, the standard tool
351 .Pn write
352 can be used in a way similar to:
353 .VS
354 scan -file - | write `id -un`
355 VE
356 .BU
357 .Pn viamail
358 .\" XXX was macht viamail
359 was removed
360 .Ci eda72d6a7a7c20ff123043fb7f19c509ea01f932
361 when the new attachment system was activated, because
362 .Pn forw
363 could then cover the task itself.
364 The program
365 .Pn sendfiles
366 was rewritten as a shell script wrapper around
367 .Pn forw .
368 .Ci 0e82199cf3c991a173e0ac8aa776efdb3ded61e6
369 .BU
370 .Pn msgchk
371 .\" XXX was macht msgchk
372 was removed
373 .Ci bb9360ead7eb7a3fedcce2eeedfc660014e41dbe ,
374 because it lost its use case when POP support was removed.
375 A call to
376 .Pn msgchk
377 provided hardly more information than:
378 .VS
379 ls -l /var/mail/meillo
380 VE
381 It did distinguish between old and new mail, but
382 these details can be retrieved with
383 .Pn stat (1),
384 too.
385 A small shell script could be written to print the information
386 in a similar way, if truly necessary.
387 As mmh's
388 .Pn inc
389 only incorporates mail from the user's local maildrop,
390 and thus no data transfers over slow networks are involved,
391 there is hardly any need to check for new mail before incorporating it.
392 .BU
393 .Pn msh
394 was removed
395 .Ci 916690191222433a6923a4be54b0d8f6ac01bd02
396 because the tool was in conflict with the philosophy of MH.
397 It provided an interactive shell to access the features of MH,
398 but it was not just a shell tailored to the needs of mail handling.
399 Instead, it was one large program that had several MH tools built in.
400 This conflicts with the major feature of MH of being a tool chest.
401 .Pn msh 's
402 main use case had been accessing Bulletin Boards, which have ceased to
403 be popular.
404 .P
405 Removing
406 .Pn msh
407 together with the truly archaic code relicts
408 .Pn vmh
409 and
410 .Pn wmh
411 saved more than 7\|000 lines of C code \(en
412 about 15\|% of the project's original source code amount.
413 Having less code \(en with equal readability, of course \(en
414 for the same functionality is an advantage.
415 Less code means less bugs and less maintenance work.
416 As
417 .Pn rcvtty
418 and
419 .Pn msgchk
420 are assumed to be rarely used and can be implemented in different ways,
421 why should one keep them?
422 Removing them streamlines mmh.
423 .Pn viamail 's
424 use case is now partly obsolete and partly covered by
425 .Pn forw ,
426 hence there's no reason to still maintain it.
427 .Pn conflict
428 is not related to the mail client, and
429 .Pn msh
430 conflicts with the basic concept of MH.
431 These two tools might still be useful, but they should not be part of mmh.
432 .P
433 Finally, there is
434 .Pn slocal .
435 .Pn slocal
436 is an MDA and thus not directly MUA-related.
437 It should be removed from mmh, because including it conflicts with
438 the idea that mmh is an MUA only.
439 .Pn slocal
440 should rather become a separate project.
441 However,
442 .Pn slocal
443 provides rule-based processing of messages, like filing them into
444 different folders, which is otherwise not available in mmh.
445 Although
446 .Pn slocal
447 neither pulls in dependencies, nor does it include a separate
448 technical area (cf. Sec.
449 .Cf mail-transfer-facilities ),
450 it still accounts for about 1\|000 lines of code that need to be maintained.
451 As
452 .Pn slocal
453 is almost self-standing, it should be split off into a separate project.
454 This would cut the strong connection between the MUA mmh and the MDA
455 .Pn slocal .
456 For anyone not using MH,
457 .Pn slocal
458 would become yet another independent MDA, like
459 .I procmail .
460 Then
461 .Pn slocal
462 could be installed without the complete MH system.
463 Likewise, mmh users could decide to use
464 .I procmail
465 without having a second, unused MDA,
466 .Pn slocal ,
467 installed.
468 That appears to be conceptionally the best solution.
469 Yet,
470 .Pn slocal
471 is not split off.
472 I defer the decision over
473 .Pn slocal
474 out of a need for deeper investigation.
475 In the meanwhile, it remains part of mmh.
476 However, its continued existence is not significant because
477 .Pn slocal
478 is unrelated to the rest of the project.
482 .H2 "Displaying Messages
483 .Id mhshow
484 .P
485 Since the very beginning, already in the first concept paper,
486 .\" XXX ref!!!
487 .Pn show
488 had been MH's message display program.
489 .Pn show
490 mapped message numbers and sequences to files and invoked
491 .Pn mhl
492 to have the files formatted.
493 With MIME, this approach was not sufficient anymore.
494 MIME messages can consist of multiple parts. Some parts are not
495 directly displayable and text content might be encoded in
496 foreign charsets.
497 .Pn show 's
498 understanding of messages and
499 .Pn mhl 's
500 display capabilities could not cope with the task any longer.
501 .P
502 Instead of extending these tools, additional tools were written from
503 scratch and added to the MH tool chest.
504 Doing so is encouraged by the tool chest approach.
505 Modular design is a great advantage for extending a system,
506 as new tools can be added without interfering with existing ones.
507 First, the new MIME features were added in form of the single program
508 .Pn mhn .
509 The command
510 .Cl "mhn -show 42
511 would show the MIME message numbered 42.
512 With the 1.0 release of nmh in February 1999, Richard Coleman finished
513 the split of
514 .Pn mhn
515 into a set of specialized tools, which together covered the
516 multiple aspects of MIME.
517 One of them was
518 .Pn mhshow ,
519 which replaced
520 .Cl "mhn -show" .
521 It was capable of displaying MIME messages appropriately.
522 .P
523 From then on, two message display tools were part of nmh,
524 .Pn show
525 and
526 .Pn mhshow .
527 To ease the life of users,
528 .Pn show
529 was extended to automatically hand the job over to
530 .Pn mhshow
531 if displaying the message would be beyond
532 .Pn show 's
533 abilities.
534 In consequence, the user would simply invoke
535 .Pn show
536 (possibly through
537 .Pn next
538 or
539 .Pn prev )
540 and get the message printed with either
541 .Pn show
542 or
543 .Pn mhshow ,
544 whatever was more appropriate.
545 .P
546 Having two similar tools for essentially the same task is redundant.
547 Usually, users would not distinguish between
548 .Pn show
549 and
550 .Pn mhshow
551 in their daily mail reading.
552 Having two separate display programs was therefore mainly unnecessary
553 from a user's point of view.
554 Besides, the development of both programs needed to be in sync,
555 to ensure that the programs behaved in a similar way,
556 because they were used like a single tool.
557 Different behavior would have surprised the user.
558 .P
559 Today, non-MIME messages are rather seen to be a special case of
560 MIME messages, although it is the other way round.
561 As
562 .Pn mhshow
563 had already been able to display non-MIME messages, it appeared natural
564 to drop
565 .Pn show
566 in favor of using
567 .Pn mhshow
568 exclusively.
569 .Ci 4c1efddfd499300c7e74263e57d8aa137e84c853
570 Removing
571 .Pn show
572 is no loss in function, because functionally
573 .Pn mhshow
574 covers it completely.
575 The old behavior of
576 .Pn show
577 can still be emulated with the simple command line:
578 .VS
579 mhl `mhpath c`
580 VE
581 .P
582 For convenience,
583 .Pn mhshow
584 was renamed to
585 .Pn show
586 after
587 .Pn show
588 was gone.
589 It is clear that such a rename may confuse future developers when
590 trying to understand the history.
591 Nevertheless, I consider the convenience on the user's side,
592 to call
593 .Pn show
594 when they want a message to be displayed, to outweigh the inconvenience
595 on the developer's side when understanding the project history.
596 .P
597 To prepare for the transition,
598 .Pn mhshow
599 was reworked to behave more like
600 .Pn show
601 first.
602 (cf. Sec.
603 .Cf mhshow )
604 .\" XXX code commits?
605 Once the tools behaved more alike, the replacing appeared to be
606 even more natural.
607 Today, mmh's new
608 .Pn show
609 has become the one single message display program once more,
610 with the difference
611 that today it handles MIME messages as well as non-MIME messages.
612 The outcome of the transition is one program less to maintain,
613 no second display program for users to deal with,
614 and less system complexity.
615 .P
616 Still, removing the old
617 .Pn show
618 hurts in one regard: It had been such a simple program.
619 Its lean elegance is missing from the new
620 .Pn show ,
621 .\" XXX
622 however there is no alternative;
623 supporting MIME demands higher essential complexity.
625 .ig
626 XXX
627 Consider including text on scan listings here
629 Scan listings shall not contain body content. Hence, removed this feature.
630 Scan listings shall operator on message headers and non-message information
631 only. Displaying the beginning of the body complicates everything too much.
632 That's no surprise, because it's something completely different. If you
633 want to examine the body, then use show(1)/mhshow(1).
634 Changed the default scan formats accordingly.
635 .Ci 70b2643e0da8485174480c644ad9785c84f5bff4
636 ..
641 .H2 "Configure Options
642 .P
643 Customization is a double-edged sword.
644 It allows better suiting setups, but not for free.
645 There is the cost of code complexity to be able to customize.
646 There is the cost of less tested setups, because there are
647 more possible setups and especially corner cases.
648 Additionally, there is the cost of choice itself.
649 The code complexity directly affects the developers.
650 Less tested code affects both users and developers.
651 The problem of choice affects the users, for once by having to choose,
652 but also by more complex interfaces that require more documentation.
653 Whenever options add few advantages but increase the complexity of the
654 system, they should be considered for removal.
655 I have reduced the number of project-specific configure options from
656 fifteen to three.
658 .U3 "Mail Transfer Facilities
659 .P
660 With the removal of the mail transfer facilities five configure
661 options vanished:
662 .P
663 The switches
664 .Sw --with-tls
665 and
666 .Sw --with-cyrus-sasl
667 had activated the support for transfer encryption and authentication.
668 .\" XXX cf
669 .\" XXX gruende kurz wiederholen
670 This is not needed anymore.
671 .Ci fecd5d34f65597a4dfa16aeabea7d74b191532c3
672 .Ci 156d35f6425bea4c1ed3c4c79783dc613379c65b
673 .P
674 .\" XXX cf
675 .\" XXX ``For the same reason ...''
676 The configure switch
677 .Sw --enable-pop
678 activated the message retrieval facility.
679 The code area that would be conditionally compiled in for TLS and SASL
680 support had been small.
681 The conditionally compiled code area for POP support had been much larger.
682 Whereas the code base changes would only slightly change on toggling
683 TLS or SASL support, it changed much on toggling POP support.
684 The changes in the code base could hardly be overviewed.
685 By having POP support togglable, a second code base had been created,
686 one that needed to be tested.
687 This situation is basically similar for the conditional TLS and SASL
688 code, but there the changes are minor and can yet be overviewed.
689 Still, conditional compilation of a code base creates variations
690 of the original program.
691 More variations require more testing and maintenance work.
692 .P
693 Two other options only specified default configuration values:
694 .Sw --with-mts
695 defined the default transport service.
696 .Ci f6aa95b724fd8c791164abe7ee5468bf5c34f226
697 With
698 .Sw --with-smtpservers
699 default SMTP servers could be specified.
700 .Ci 128545e06224233b7e91fc4c83f8830252fe16c9
701 Both of them became irrelevant when the SMTP transport service was removed.
702 .\" XXX code ref
703 In mmh, all messages are handed over to
704 .Pn sendmail
705 for transportation.
708 .U3 "Backup Prefix
709 .P
710 The backup prefix is the string that was prepended to message
711 filenames to tag them as deleted.
712 By default it had been the comma character (`\fL,\fP').
713 .\" XXX Zeitlich ordnen
714 In July 2000, Kimmo Suominen introduced
715 the configure option
716 .Sw --with-hash-backup
717 to change the default to the hash character `\f(CW#\fP'.
718 The choice was probably personal preference, because first, the
719 option was named
720 .Sw --with-backup-prefix.
721 and had the prefix character as argument.
722 But giving the hash character as argument caused too many problems
723 for Autoconf,
724 thus the option was limited to use the hash character as the default prefix.
725 This supports the assumption, that the choice for the hash was
726 personal preference only.
727 Being related or not, words that start with the hash character
728 introduce a comment in the Unix shell.
729 Thus, the command line
730 .Cl "rm #13 #15
731 calls
732 .Pn rm
733 without arguments because the first hash character starts the comment
734 that reaches until the end of the line.
735 To delete the backup files,
736 .Cl "rm ./#13 ./#15"
737 needs to be used.
738 Using the hash as backup prefix can be seen as a precaution against
739 data loss.
740 .P
741 First, I removed the configure option but added the profile entry
742 .Pe backup-prefix ,
743 which allows to specify an arbitrary string as backup prefix.
744 .Ci 6c40d481d661d532dd527eaf34cebb6d3f8ed086
745 Profile entries are the common method to change mmh's behavior.
746 This change did not remove the choice but moved it to a location where
747 it suited better.
748 .P
749 Eventually, however, the new trash folder concept
750 (cf. Sec.
751 .Cf trash-folder )
752 removed the need for the backup prefix completely.
753 .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
754 .Ci ca0b3e830b86700d9e5e31b1784de2bdcaf58fc5
757 .U3 "Editor and Pager
758 .P
759 The two configure options
760 .CW --with-editor=EDITOR
761 .CW --with-pager=PAGER
762 were used to specify the default editor and pager at configure time.
763 Doing so at configure time made sense in the eighties,
764 when the set of available editors and pagers varied much across
765 different systems.
766 Today, the situation is more homogeneous.
767 The programs
768 .Pn vi
769 and
770 .Pn more
771 can be expected to be available on every Unix system,
772 as they are specified by POSIX since two decades.
773 (The specifications for
774 .Pn vi
775 and
776 .Pn more
777 appeared in
778 .[
779 posix 1987
780 .]
781 and,
782 .[
783 posix 1992
784 .]
785 respectively.)
786 As a first step, these two tools were hard-coded as defaults.
787 .Ci 5d43a99db70c12a673028c7758c20cbe3e13ef5f
788 Not changed were the
789 .Pe editor
790 and
791 .Pe moreproc
792 profile entries, which allowed the user to override the system defaults.
793 Later, the concept was reworked to respect the standard environment
794 variables
795 .Ev VISUAL
796 and
797 .Ev PAGER
798 if they are set.
799 Today, mmh determines the editor to use in the following order,
800 taking the first available and non-empty item:
801 .LI 1
802 Environment variable
803 .Ev MMHEDITOR
804 .LI 2
805 Profile entry
806 .Pe Editor
807 .LI 3
808 Environment variable
809 .Ev VISUAL
810 .LI 4
811 Environment variable
812 .Ev EDITOR
813 .LI 5
814 Command
815 .Pn vi .
816 .LP
817 .Ci f85f4b7ae62e3d05a945dcd46ead51f0a2a89a9b
818 .P
819 The pager to use is determined in a similar order,
820 also taking the first available and non-empty item:
821 .LI 1
822 Environment variable
823 .Ev MMHPAGER
824 .LI 2
825 Profile entry
826 .Pe Pager
827 (replaces
828 .Pe moreproc )
829 .LI 3
830 Environment variable
831 .Ev PAGER
832 .LI 4
833 Command
834 .Pn more .
835 .LP
836 .Ci 0c4214ea2aec6497d0d67b436bbee9bc1d225f1e
837 .P
838 By respecting the
839 .Ev VISUAL /\c
840 .Ev EDITOR
841 and
842 .Ev PAGER
843 environment variables,
844 the new behavior confirms better to the common style on Unix systems.
845 Additionally, the new approach is more uniform and clearer to users.
848 .U3 "ndbm
849 .P
850 .Pn slocal
851 used to depend on
852 .I ndbm ,
853 a database library.
854 The database is used to store the `\fLMessage-ID\fP's of all
855 messages delivered.
856 This enables
857 .Pn slocal
858 to suppress delivering the same message to the same user twice.
859 (This features was enabled by the
860 .Sw -suppressdup
861 switch.)
862 .P
863 A variety of versions of the database library exist.
864 .[
865 wolter unix incompat notes dbm
866 .]
867 Complicated autoconf code was needed to detect them correctly.
868 Furthermore, the configure switches
869 .Sw --with-ndbm=ARG
870 and
871 .Sw --with-ndbmheader=ARG
872 were added to help with difficult setups that would
873 not be detected automatically or correctly.
874 .P
875 By removing the suppress duplicates feature of
876 .Pn slocal ,
877 the dependency on
878 .I ndbm
879 vanished and 120 lines of complex autoconf code could be saved.
880 .Ci ecd6d6a20cb7a1507e3a20d6c4cb3a1cf14c6bbf
881 The change removed functionality too, but that is minor to the
882 improvement by dropping the dependency and the complex autoconf code.
883 .\" XXX argument: slocal ist sowieso nicht teil vom mmh kern
885 .U3 "mh-e Support
886 .P
887 The configure option
888 .Sw --disable-mhe
889 was removed when the mh-e support was reworked.
890 Mh-e is the Emacs front-end to MH.
891 It requires MH to provide minor additional functions.
892 The
893 .Sw --disable-mhe
894 configure option could switch these extensions off.
895 After removing the support for old versions of mh-e,
896 only the
897 .Sw -build
898 switches of
899 .Pn forw
900 and
901 .Pn repl
902 are left to be mh-e extensions.
903 They are now always built in because they add little code and complexity.
904 In consequence, the
905 .Sw --disable-mhe
906 configure option was removed
907 .Ci a7ce7b4a580d77b6c2c4d980812beb589aa4c643
908 Removing the option removed a second code setup that would have
909 needed to be tested.
910 .\" XXX datum?
911 This change was first accomplished in nmh and thereafter merged into mmh.
912 .P
913 The interface changes in mmh require mh-e to be adjusted in order
914 to be able to use mmh as back-end.
915 This will require minor changes to mh-e, but removing the
916 .Sw -build
917 switches would require more rework.
919 .U3 "Masquerading
920 .P
921 The configure option
922 .Sw --enable-masquerade
923 could take up to three arguments:
924 `draft_from', `mmailid', and `username_extension'.
925 They activated different types of address masquerading.
926 All of them were implemented in the SMTP-speaking
927 .Pn post
928 command, which provided an MSA.
929 Address masquerading is an MTA's task and mmh does not cover
930 this field anymore.
931 Hence, true masquerading needs to be implemented in the external MTA.
932 .P
933 The
934 .I mmailid
935 masquerading type is the oldest one of the three and the only one
936 available in the original MH.
937 It provided a
938 .I username
939 to
940 .I fakeusername
941 mapping, based on the password file's GECOS field.
942 The man page
943 .Mp mh-tailor (5)
944 described the use case as being the following:
945 .QS
946 This is useful if you want the messages you send to always
947 appear to come from the name of an MTA alias rather than your
948 actual account name. For instance, many organizations set up
949 `First.Last' sendmail aliases for all users. If this is
950 the case, the GECOS field for each user should look like:
951 ``First [Middle] Last <First.Last>''
952 .QE
953 .P
954 As mmh sends outgoing mail via the local MTA only,
955 the best location to do such global rewrites is there.
956 Besides, the MTA is conceptionally the right location because it
957 does the reverse mapping for incoming mail (aliasing), too.
958 Furthermore, masquerading set up there is readily available for all
959 mail software on the system.
960 Hence, mmailid masquerading was removed.
961 .Ci 0836c8000ccb34b59410ef1c15b1b7feac70ce5f
962 .P
963 The
964 .I username_extension
965 masquerading type did not replace the username but would append a suffix,
966 specified by the
967 .Ev USERNAME_EXTENSION
968 environment variable, to it.
969 This provided support for the
970 .I user-extension
971 feature of qmail and the similar
972 .I "plussed user
973 processing of sendmail.
974 The decision to remove this username_extension masquerading was
975 motivated by the fact that
976 .Pn spost
977 had not supported it already.
978 .Ci 2abae0bfd0ad5bf898461e50aa4b466d641f23d9
979 Username extensions are possible in mmh, but less convenient to use.
980 .\" XXX covered by next paragraph
981 .\" XXX format file %(getenv USERNAME_EXTENSION)
982 .P
983 The
984 .I draft_from
985 masquerading type instructed
986 .Pn post
987 to use the value of the
988 .Hd From
989 header field as SMTP envelope sender.
990 Sender addresses could be replaced completely.
991 .Ci b14ea6073f77b4359aaf3fddd0e105989db9
992 Mmh offers a kind of masquerading similar in effect, but
993 with technical differences.
994 As mmh does not transfer messages itself, the local MTA has final control
995 over the sender's address. Any masquerading mmh introduces may be reverted
996 by the MTA.
997 In times of pedantic spam checking, an MTA will take care to use
998 sensible envelope sender addresses to keep its own reputation up.
999 Nonetheless, the MUA can set the
1000 .Hd From
1001 header field and thereby propose
1002 a sender address to the MTA.
1003 The MTA may then decide to take that one or generate the canonical sender
1004 address for use as envelope sender address.
1005 .P
1006 In mmh, the MTA will always extract the recipient and sender from the
1007 message header (\c
1008 .Pn sendmail 's
1009 .Sw -t
1010 switch).
1011 The
1012 .Hd From
1013 header field of the draft may be set arbitrary by the user.
1014 If it is missing, the canonical sender address will be generated by the MTA.
1016 .U3 "Remaining Options
1017 .P
1018 Two configure options remain in mmh.
1019 One is the locking method to use:
1020 .Sw --with-locking=[dot|fcntl|flock|lockf] .
1021 The idea of removing all methods except the portable dot locking
1022 and having that one as the default is appealing, but this change
1023 requires deeper technical investigation into the topic.
1024 The other option,
1025 .Sw --enable-debug ,
1026 compiles the programs with debugging symbols and does not strip them.
1027 This option is likely to stay.
1032 .H2 "Command Line Switches
1033 .P
1034 The command line switches of MH tools is similar to the X Window style.
1035 .\" XXX ref
1036 They are words, introduced by a single dash.
1037 For example:
1038 .Cl "-truncate" .
1039 Every program in mmh has two generic switches:
1040 .Sw -help ,
1041 to print a short message on how to use the program, and
1042 .Sw -Version
1043 (with capital `V'), to tell what version of mmh the program belongs to.
1044 .P
1045 Switches change the behavior of programs.
1046 Programs that do one thing in one way require no switches.
1047 In most cases, doing something in exactly one way is too limiting.
1048 If there is basically one task to accomplish, but it should be done
1049 in various ways, switches are a good approach to alter the behavior
1050 of a program.
1051 Changing the behavior of programs provides flexibility and customization
1052 to users, but at the same time it complicates the code, documentation and
1053 usage of the program.
1054 .\" XXX: Ref
1055 Therefore, the number of switches should be kept small.
1056 A small set of well-chosen switches does no harm.
1057 But usually, the number of switches increases over time.
1058 Already in 1985, Rose and Romine have identified this as a major
1059 problem of MH:
1060 .[ [
1061 rose romine real work
1062 .], p. 12]
1063 .QS
1064 A complaint often heard about systems which undergo substantial development
1065 by many people over a number of years, is that more and more options are
1066 introduced which add little to the functionality but greatly increase the
1067 amount of information a user needs to know in order to get useful work done.
1068 This is usually referred to as creeping featurism.
1069 .QP
1070 Unfortunately MH, having undergone six years of off-and-on development by
1071 ten or so well-meaning programmers (the present authors included),
1072 suffers mightily from this.
1073 .QE
1074 .P
1075 Being reluctant to adding new switches \(en or `options',
1076 as Rose and Romine call them \(en is one part of a counter-action,
1077 the other part is removing hardly used switches.
1078 Nmh's tools had lots of switches already implemented,
1079 hence, cleaning up by removing some of them was the more important part
1080 of the counter-action.
1081 Removing existing functionality is always difficult because it
1082 breaks programs that use these functions.
1083 Also, for every obsolete feature, there'll always be someone who still
1084 uses it and thus opposes its removal.
1085 This puts the developer into the position,
1086 where sensible improvements to style are regarded as destructive acts.
1087 Yet, living with the featurism is far worse, in my eyes, because
1088 future needs will demand adding further features,
1089 worsening the situation more and more.
1090 Rose and Romine added in a footnote,
1091 ``[...]
1092 .Pn send
1093 will no doubt acquire an endless number of switches in the years to come.''
1094 Although clearly humorous, the comment points to the nature of the problem.
1095 Refusing to add any new switches would encounter the problem at its root,
1096 but this is not practical.
1097 New needs will require new switches and it would be unwise to block
1098 them strictly.
1099 Nevertheless, removing obsolete switches still is an effective approach
1100 to deal with the problem.
1101 Working on an experimental branch without an established user base,
1102 eased my work because I did not offend users when I removed existing
1103 functions.
1104 .P
1105 Rose and Romine counted 24 visible and 9 more hidden switches for
1106 .Pn send .
1107 In nmh, they increased up to 32 visible and 12 hidden ones.
1108 At the time of writing, no more than 4 visible switches and 1 hidden switch
1109 have remained in mmh's
1110 .Pn send .
1111 These numbers include two generic switches,
1112 .Sw -help
1113 and
1114 .Sw -Version .
1115 Hidden switches are ones not documented.
1116 In mmh, 12 tools have hidden switches.
1117 9 of them are
1118 .Sw -debug
1119 switches, the other 6 provide special interfaces for internal use.
1120 .P
1121 The figure displays the number of switches for each of the tools
1122 that is available in both nmh and mmh.
1123 The tools are sorted by the number of switches they had in nmh.
1124 Visible and hidden switches were counted,
1125 but not the generic help and version switches.
1126 Whereas in the beginning of the project, the average tool had 11 switches,
1127 now it has no more than 5 \(en only half as many.
1128 If the `no' switches and similar inverse variant are folded onto
1129 their counter-parts, the average tool had 8 switches in pre-mmh times and
1130 has 4 now.
1131 The total number of functional switches in mmh dropped from 465
1132 to 233.
1134 .KS
1135 .in 1c
1136 .so input/switches.grap
1137 .KE
1139 .P
1140 A part of the switches vanished after functions were removed.
1141 This was the case for network mail transfer, for instance.
1142 Sometimes, however, the work flow was the other way:
1143 I looked through the
1144 .Mp mh-chart (7)
1145 man page to identify the tools with apparently too many switches.
1146 Then considering the value of each of the switches by examining
1147 the tool's man page and source code, aided by recherche and testing.
1148 This way, the removal of functions was suggested by the aim to reduce
1149 the number of switches per command.
1152 .U3 "Draft Folder Facility
1153 .P
1154 A change early in the project was the complete transition from
1155 the single draft message to the draft folder facility.
1156 .Ci 337338b404931f06f0db2119c9e145e8ca5a9860
1157 .\" XXX ref to section ...
1158 The draft folder facility was introduced in the mid-eighties, when
1159 Rose and Romine called it a ``relatively new feature''.
1160 .[
1161 rose romine real work
1162 .]
1163 Since then, the facility had existed but was inactive by default.
1164 The default activation and the related rework of the tools made it
1165 possible to remove the
1166 .Sw -[no]draftfolder ,
1167 and
1168 .Sw -draftmessage
1169 switches from
1170 .Pn comp ,
1171 .Pn repl ,
1172 .Pn forw ,
1173 .Pn dist ,
1174 .Pn whatnow ,
1175 and
1176 .Pn send .
1177 .Ci 337338b404931f06f0db2119c9e145e8ca5a9860
1178 The only flexibility removed with this change is having multiple
1179 draft folders within one profile.
1180 I consider this a theoretical problem only.
1181 At the same time, the
1182 .Sw -draft
1183 switch of
1184 .Pn anno ,
1185 .Pn refile ,
1186 and
1187 .Pn send
1188 was removed.
1189 The special treatment of \fIthe\fP draft message became irrelevant after
1190 the rework of the draft system.
1191 (cf. Sec.
1192 .Cf draft-folder )
1193 Furthermore,
1194 .Pn comp
1195 no longer needs a
1196 .Sw -file
1197 switch as the draft folder facility together with the
1198 .Sw -form
1199 switch are sufficient.
1202 .U3 "In Place Editing
1203 .P
1204 .Pn anno
1205 had the switches
1206 .Sw -[no]inplace
1207 to either annotate the message in place and thus preserve hard links,
1208 or annotate a copy to replace the original message, breaking hard links.
1209 Following the assumption that linked messages should truly be the
1210 same message, and annotating it should not break the link, the
1211 .Sw -[no]inplace
1212 switches were removed and the previous default
1213 .Sw -inplace
1214 was made the only behavior.
1215 .Ci c8195849d2e366c569271abb0f5f60f4ebf0b4d0
1216 The
1217 .Sw -[no]inplace
1218 switches of
1219 .Pn repl ,
1220 .Pn forw ,
1221 and
1222 .Pn dist
1223 could be removed, too, as they were simply passed through to
1224 .Pn anno .
1225 .P
1226 .Pn burst
1227 also had
1228 .Sw -[no]inplace
1229 switches, but with different meaning.
1230 With
1231 .Sw -inplace ,
1232 the digest had been replaced by the table of contents (i.e. the
1233 introduction text) and the burst messages were placed right
1234 after this message, renumbering all following messages.
1235 Also, any trailing text of the digest was lost, though,
1236 in practice, it usually consists of an end-of-digest marker only.
1237 Nontheless, this behavior appeared less elegant than the
1238 .Sw -noinplace
1239 behavior, which already had been the default.
1240 Nmh's
1241 .Mp burst (1)
1242 man page reads:
1243 .QS
1244 If
1245 .Sw -noinplace
1246 is given, each digest is preserved, no table
1247 of contents is produced, and the messages contained within
1248 the digest are placed at the end of the folder. Other messages
1249 are not tampered with in any way.
1250 .QE
1251 .LP
1252 The decision to drop the
1253 .Sw -inplace
1254 behavior was supported by the code complexity and the possible data loss
1255 it caused.
1256 .Sw -noinplace
1257 was chosen to be the definitive behavior.
1258 .Ci 68a686adeb39223a5e1ad35e4a24890ec053679d
1261 .U3 "Forms and Format Strings
1262 .P
1263 Historically, the tools that had
1264 .Sw -form
1265 switches to supply a form file had
1266 .Sw -format
1267 switches as well to supply the contents of a form file as a string
1268 on the command line directly.
1269 In consequence, the following two lines equaled:
1270 .VS
1271 scan -form scan.mailx
1272 scan -format "`cat .../scan.mailx`"
1273 VE
1274 The
1275 .Sw -format
1276 switches were dropped in favor for extending the
1277 .Sw -form
1278 switches.
1279 .Ci f51956be123db66b00138f80464d06f030dbb88d
1280 If their argument starts with an equal sign (`='),
1281 then the rest of the argument is taken as a format string,
1282 otherwise the arguments is treated as the name of a format file.
1283 Thus, now the following two lines equal:
1284 .VS
1285 scan -form scan.mailx
1286 scan -form "=`cat .../scan.mailx`"
1287 VE
1288 This rework removed the prefix collision between
1289 .Sw -form
1290 and
1291 .Sw -format .
1292 Now, typing
1293 .Sw -fo
1294 suffices to specify form or format string.
1295 .P
1296 The different meaning of
1297 .Sw -format
1298 for
1299 .Pn repl
1300 and
1301 .Pn forw
1302 was removed in mmh.
1303 .Pn forw
1304 was completely switched to MIME-type forwarding, thus removing the
1305 .Sw -[no]format .
1306 .Ci 6e271608b7b9c23771523f88d23a4d3593010cf1
1307 For
1308 .Pn repl ,
1309 the
1310 .Sw -[no]format
1311 switches were reworked to
1312 .Sw -[no]filter
1313 switches.
1314 .Ci 67411b1f95d6ec987b4c732459e1ba8a8ac192c6
1315 The
1316 .Sw -format
1317 switches of
1318 .Pn send
1319 and
1320 .Pn post ,
1321 which had a third meaning,
1322 were removed likewise.
1323 .Ci f3cb7cde0e6f10451b6848678d95860d512224b9
1324 Eventually, the ambiguity of the
1325 .Sw -format
1326 switches was resolved by not anymore having any such switch in mmh.
1329 .U3 "MIME Tools
1330 .P
1331 The MIME tools, which were once part of
1332 .Pn mhn
1333 .\" XXX
1334 (whatever that stood for),
1335 had several switches that added little practical value to the programs.
1336 The
1337 .Sw -[no]realsize
1338 switches of
1339 .Pn mhbuild
1340 and
1341 .Pn mhlist
1342 were removed, doing real size calculations always now
1343 .Ci 8d8f1c3abc586c005c904e52c4adbfe694d2201c ,
1344 as nmh's
1345 .Mp mhbuild (1)
1346 man page states
1347 ``This provides an accurate count at the expense of a small delay.''
1348 This small delay is not noticable on modern systems.
1349 .P
1350 The
1351 .Sw -[no]check
1352 switches were removed together with the support for
1353 .Hd Content-MD5
1354 header fields.
1355 .[
1356 rfc 1864
1357 .]
1358 .Ci 31dc797eb5178970d68962ca8939da3fd9a8efda
1359 (cf. Sec.
1360 .Cf content-md5 )
1361 .P
1362 The
1363 .Sw -[no]ebcdicsafe
1364 and
1365 .Sw -[no]rfc934mode
1366 switches of
1367 .Pn mhbuild
1368 were removed because they are considered obsolete.
1369 .Ci 01a3480928da485b4d6109d36d751dfa71799d58
1370 .Ci 3363e2624dce0eb8164cf8b3f1ab385c8ff72e88
1371 .P
1372 Content caching of external MIME parts, activated with the
1373 .Sw -rcache
1374 and
1375 .Sw -wcache
1376 switches was completely removed.
1377 .Ci d1fefd9f614e4dc3cda16da6c69133c1b2005269
1378 External MIME parts are rare today, having a caching facility
1379 for them appears to be unnecessary.
1380 .P
1381 In pre-MIME times,
1382 .Pn mhl
1383 had covered many tasks that are part of MIME handling today.
1384 Therefore,
1385 .Pn mhl
1386 could be simplified to a large extend, reducing the number of its
1387 switches from 21 to 6.
1388 .Ci 350ad6d3542a07639213cf2a4fe524e829c1e7b6
1389 .Ci 0e46503be3c855bddaeae3843e1b659279c35d70
1394 .U3 "Header Printing
1395 .P
1396 .Pn folder 's
1397 data output is self-explaining enough that
1398 displaying the header line makes little sense.
1399 Hence, the
1400 .Sw -[no]header
1401 switch was removed and headers are never printed.
1402 .Ci 601cc73d1fa05ce96faa728f036d6c51b91701c7
1403 .P
1404 In
1405 .Pn mhlist ,
1406 the
1407 .Sw -[no]header
1408 switches were removed, too.
1409 .Ci b24f96523aaf60e44e04a3ffb1d22e69a13a602f
1410 But in this case headers are always printed,
1411 because the output is not self-explaining.
1412 .P
1413 .Pn scan
1414 also had
1415 .Sw -[no]header
1416 switches.
1417 Printing the header had been sensible until the introduction of
1418 format strings made it impossible to display the column headings.
1419 Only the folder name and the current date remained to be printed.
1420 As this information can be perfectly retrieved by
1421 .Pn folder
1422 and
1423 .Pn date ,
1424 consequently, the switches were removed.
1425 .Ci c477dc5d1d03fa6d9a8ab3dd3508c63cbddc044e
1426 .P
1427 By removing all
1428 .Sw -header
1429 switches, the collision with
1430 .Sw -help
1431 on the first two letters was resolved.
1432 Currently,
1433 .Sw -h
1434 evaluates to
1435 .Sw -help
1436 for all tools of mmh.
1439 .U3 "Suppressing Edits or the Invocation of the WhatNow Shell
1440 .P
1441 The
1442 .Sw -noedit
1443 switch of
1444 .Pn comp ,
1445 .Pn repl ,
1446 .Pn forw ,
1447 .Pn dist ,
1448 and
1449 .Pn whatnow
1450 was removed, but it can now be replaced by specifying
1451 .Sw -editor
1452 with an empty argument.
1453 .Ci 75fca31a5b9d5c1a99c74ab14c94438d8852fba9
1454 (Specifying
1455 .Cl "-editor /bin/true
1456 is nearly the same, only differing by the previous editor being set.)
1457 .P
1458 The more important change is the removal of the
1459 .Sw -nowhatnowproc
1460 switch.
1461 .Ci ee4f43cf2ef0084ec698e4e87159a94c01940622
1462 This switch had introduced an awkward behavior, as explained in nmh's
1463 man page for
1464 .Mp comp (1):
1465 .QS
1466 The
1467 .Sw -editor
1468 .Ar editor
1469 switch indicates the editor to use for
1470 the initial edit. Upon exiting from the editor,
1471 .Pn comp
1472 will invoke the
1473 .Pn whatnow
1474 program. See
1475 .Mp whatnow (1)
1476 for a discussion of available options.
1477 The invocation of this program can be
1478 inhibited by using the
1479 .Sw -nowhatnowproc
1480 switch. (In truth of fact, it is the
1481 .Pn whatnow
1482 program which starts the initial edit.
1483 Hence,
1484 .Sw -nowhatnowproc
1485 will prevent any edit from occurring.)
1486 .QE
1487 .P
1488 Effectively, the
1489 .Sw -nowhatnowproc
1490 switch creates only a draft message.
1491 As
1492 .Cl "-whatnowproc /bin/true
1493 causes the same behavior, the
1494 .Sw -nowhatnowproc
1495 switch was removed for being redundant.
1496 Likely, the
1497 .Sw -nowhatnowproc
1498 switch was intended to be used by front-ends.
1502 .U3 "Various
1503 .BU
1504 With the removal of MMDF maildrop format support,
1505 .Pn packf
1506 and
1507 .Pn rcvpack
1508 no longer needed their
1509 .Sw -mbox
1510 and
1511 .Sw -mmdf
1512 switches.
1513 .Sw -mbox
1514 is the sole behavior now.
1515 .Ci 3916ab66ad5d183705ac12357621ea8661afd3c0
1516 Further rework in both tools made the
1517 .Sw -file
1518 switch unnecessary.
1519 .Ci ca1023716d4c2ab890696f3e41fa0d94267a940e
1521 .BU
1522 Mmh's tools will no longer clear the screen (\c
1523 .Pn scan 's
1524 and
1525 .Pn mhl 's
1526 .Sw -[no]clear
1527 switches
1528 .Ci e57b17343dcb3ff373ef4dd089fbe778f0c7c270
1529 .Ci 943765e7ac5693ae177fd8d2b5a2440e53ce816e ).
1530 Neither will
1531 .Pn mhl
1532 ring the bell (\c
1533 .Sw -[no]bell
1534 .Ci e11983f44e59d8de236affa5b0d0d3067c192e24 )
1535 nor page the output itself (\c
1536 .Sw -length
1537 .Ci 5b9d883db0318ed2b84bb82dee880d7381f99188 ).
1538 .\" XXX Ref
1539 Generally, the pager to use is no longer specified with the
1540 .Sw -[no]moreproc
1541 command line switches for
1542 .Pn mhl
1543 and
1544 .Pn show /\c
1545 .Pn mhshow .
1546 .Ci 39e87a75b5c2d3572ec72e717720b44af291e88a
1548 .BU
1549 In order to avoid prefix collisions among switch names, the
1550 .Sw -version
1551 switch was renamed to
1552 .Sw -Version
1553 (with capital `V').
1554 .Ci 32b2354dbaf4bf934936eb5b102a4a3d2fdd209a
1555 Every program has the
1556 .Sw -version
1557 switch but its first three letters collided with the
1558 .Sw -verbose
1559 switch, present in many programs.
1560 The rename solved this problem once for all.
1561 Although this rename breaks a basic interface, having the
1562 .Sw -V
1563 abbreviation to display the version information, isn't all too bad.
1565 .BU
1566 .Sw -[no]preserve
1567 of
1568 .Pn refile
1569 was removed
1570 .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
1571 because what use was it anyway?
1572 Quoting nmh's man page
1573 .Mp refile (1):
1574 .QS
1575 Normally when a message is refiled, for each destination
1576 folder it is assigned the number which is one above the current
1577 highest message number in that folder. Use of the
1578 .Sw -preserv
1579 [sic!] switch will override this message renaming, and try
1580 to preserve the number of the message. If a conflict for a
1581 particular folder occurs when using the
1582 .Sw -preserve
1583 switch, then
1584 .Pn refile
1585 will use the next available message number which
1586 is above the message number you wish to preserve.
1587 .QE
1589 .BU
1590 The removal of the
1591 .Sw -[no]reverse
1592 switches of
1593 .Pn scan
1594 .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
1595 is a bug fix, supported by the comments
1596 ``\-[no]reverse under #ifdef BERK (I really HATE this)''
1597 by Rose and
1598 ``Lists messages in reverse order with the `\-reverse' switch.
1599 This should be considered a bug.'' by Romine in the documentation.
1600 .\" XXX Ref: welche datei genau.
1601 The question remains why neither Rose and Romine had fixed this
1602 bug in the eighties when they wrote these comments nor has anyone
1603 thereafter.
1606 .ig
1608 forw: [no]dashstuffing(mhl)
1610 mhshow: [no]pause [no]serialonly
1612 mhmail: resent queued
1613 inc: snoop, (pop)
1615 mhl: [no]faceproc folder sleep
1616 [no]dashstuffing(forw) digest list volume number issue number
1618 prompter: [no]doteof
1620 refile: [no]preserve [no]unlink [no]rmmproc
1622 send: [no]forward [no]mime [no]msgid
1623 [no]push split [no]unique (sasl) width snoop [no]dashstuffing
1624 attach attachformat
1625 whatnow: (noedit) attach
1627 slocal: [no]suppressdups
1629 spost: [no]filter [no]backup width [no]push idanno
1630 [no]check(whom) whom(whom)
1632 whom: ???
1634 ..
1637 .ig
1639 .P
1640 In the best case, all switches are unambiguous on the first character,
1641 or on the three-letter prefix for the `no' variants.
1642 Reducing switch prefix collisions, shortens the necessary prefix length
1643 the user must type.
1644 Having less switches helps best.
1646 ..
1649 .\" XXX: whatnow prompt commands
1654 .\" --------------------------------------------------------------
1655 .H1 "Modernizing
1656 .P
1657 In the more than thirty years of MH's existence, its code base was
1658 increasingly extended.
1659 New features entered the project and became alternatives to the
1660 existing behavior.
1661 Relicts from several decades have gathered in the code base,
1662 but seldom obsolete features were dropped.
1663 This section describes the removing of old code
1664 and the modernizing of the default setup.
1665 It focuses on the functional aspect only;
1666 the non-functional aspects of code style are discussed in Sec.
1667 .Cf code-style .
1670 .H2 "Code Relicts
1671 .P
1672 My position regarding the removal of obsolete functions of mmh,
1673 .\" XXX ``in order to remove old code,''
1674 is much more revolutional than the nmh community appreciates.
1675 Working on an experimental version, I was quickly able to drop
1676 functionality I considered ancient.
1677 The need for consensus with peers would have slowed this process down.
1678 Without the need to justify my decisions, I was able to rush forward.
1679 In December 2011, Paul Vixie motivated the nmh developers to just
1680 .\" XXX ugs
1681 do the work:
1682 .[
1683 paul vixie edginess nmh-workers
1684 .]
1685 .QS
1686 let's stop walking on egg shells with this code base. there's no need to
1687 discuss whether to keep using vfork, just note in [sic!] passing, [...]
1688 we don't need a separate branch for removing vmh
1689 or ridding ourselves of #ifdef's or removing posix replacement functions
1690 or depending on pure ansi/posix ``libc''.
1691 .QP
1692 these things should each be a day or two of work and the ``main branch''
1693 should just be modern. [...]
1694 let's push forward, aggressively.
1695 .QE
1696 .LP
1697 I did so already in the months before.
1698 I pushed forward.
1699 .\" XXX semicolon ?
1700 I simply dropped the cruft.
1701 .P
1702 The decision to drop a feature was based on literature research and
1703 careful thinking, but whether having had contact with this particular
1704 feature within my own computer life served as a rule of thumb.
1705 I explained my reasons in the commit messages
1706 in the version control system.
1707 Hence, others can comprehend my view and argue for undoing the change
1708 if I have missed an important aspect.
1709 I was quick in dropping parts.
1710 I rather include falsely dropped parts again, than going at a slower pace.
1711 Mmh is experimental work; it requires tough decisions.
1712 .\" XXX ``exp. work'' schon oft gesagt
1715 .U3 "Forking
1716 .P
1717 Being a tool chest, MH creates many processes.
1718 In earlier times
1719 .Fu fork()
1720 had been an expensive system call, because the process's image needed
1721 to be completely duplicated at once.
1722 This expensive work was especially unnecessary in the commonly occuring
1723 case wherein the image is replaced by a call to
1724 .Fu exec()
1725 right after having forked the child process.
1726 The
1727 .Fu vfork()
1728 system call was invented to speed up this particular case.
1729 It completely omits the duplication of the image.
1730 On old systems this resulted in significant speed ups.
1731 Therefore MH used
1732 .Fu vfork()
1733 whenever possible.
1734 .P
1735 Modern memory management units support copy-on-write semantics, which make
1736 .Fu fork()
1737 almost as fast as
1738 .Fu vfork() .
1739 The man page of
1740 .Mp vfork (2)
1741 in FreeBSD 8.0 states:
1742 .QS
1743 This system call will be eliminated when proper system sharing mechanisms
1744 are implemented. Users should not depend on the memory sharing semantics
1745 of vfork() as it will, in that case, be made synonymous to fork(2).
1746 .QE
1747 .LP
1748 Vixie supports the removal with the note that ``the last
1749 system on which fork was so slow that an mh user would notice it, was
1750 Eunice. that was 1987''.
1751 .[
1752 nmh-workers vixie edginess
1753 .]
1754 I replaced all calls to
1755 .Fu vfork()
1756 with calls to
1757 .Fu fork() .
1758 .Ci 40821f5c1316e9205a08375e7075909cc9968e7d
1759 .P
1760 Related to the costs of
1761 .Fu fork()
1762 is the probability of its success.
1763 In the eighties, on heavy loaded systems, calls to
1764 .Fu fork()
1765 were prone to failure.
1766 Hence, many of the
1767 .Fu fork()
1768 calls in the code were wrapped into loops to retry the
1769 .Fu fork()
1770 several times, to increase the chances to succeed, eventually.
1771 On modern systems, a failing
1772 .Fu fork()
1773 call is unusual.
1774 Hence, in the rare case when
1775 .Fu fork()
1776 fails, mmh programs simply abort.
1777 .Ci 5fbf37ee68e018998ada61eeab73e035b26834b6
1780 .U3 "Header Fields
1781 .BU
1782 The
1783 .Hd Encrypted
1784 header field was introduced by RFC\|822,
1785 but already marked as legacy in RFC\|2822.
1786 Today, OpenPGP provides the basis for standardized exchange of encrypted
1787 messages [RFC\|4880, RFC\|3156].
1788 Hence, the support for
1789 .Hd Encrypted
1790 header fields is removed in mmh.
1791 .Ci 064527f7b57ab050e5af13e15ad99aeeab125857
1792 .BU
1793 The native support for
1794 .Hd Face
1795 header fields has been removed, as well.
1796 .Ci 8e5be81f784682822f5e868c1bf3c8624682bd23
1797 This feature is similar to the
1798 .Hd X-Face
1799 header field in its intent,
1800 but takes a different approach to store the image.
1801 Instead of encoding the image data directly into the header field,
1802 it contains the hostname and UDP port where the image
1803 date can be retrieved.
1804 There is even a third Face system,
1805 which is the successor of
1806 .Hd X-Face ,
1807 although it re-uses the
1808 .Hd Face
1809 header field.
1810 It was invented in 2005 and supports colored PNG images.
1811 None of the Face systems described here is popular today.
1812 Hence, mmh has no direct support for them.
1813 .BU
1814 .Id content-md5
1815 The
1816 .Hd Content-MD5
1817 header field was introduced by RFC\|1864.
1818 It provides detection of data corruption during the transfer.
1819 But it can not ensure verbatim end-to-end delivery of the contents
1820 [RFC\|1864].
1821 The proper approach to verify content integrity in an
1822 end-to-end relationship is the use of digital signatures.
1823 .\" XXX (RFCs FIXME).
1824 On the other hand, transfer protocols should detect corruption during
1825 the transmission.
1826 The TCP includes a checksum field therefore.
1827 These two approaches in combinations render the
1828 .Hd Content-MD5
1829 header field superfluous.
1830 Not a single one out of 4\|200 messages from two decades
1831 in an nmh-workers mailing list archive contains a
1832 .Hd Content-MD5
1833 header field.
1834 Neither did any of the 60\|000 messages in my personal mail storage.
1835 Removing the support for this header field,
1836 removed the last place where MD5 computation was needed.
1837 .Ci 31dc797eb5178970d68962ca8939da3fd9a8efda
1838 Hence, the MD5 code could be removed as well.
1839 Over 500 lines of code vanished by this one change.
1842 .U3 "MMDF maildrop support
1843 .P
1844 This type of format is conceptionally similar to the mbox format,
1845 but uses a different message delimiter (`\fL\\1\\1\\1\\1\fP',
1846 commonly written as `\fL^A^A^A^A\fP', instead of `\fLFrom\0\fP').
1847 Mbox is the de-facto standard maildrop format on Unix,
1848 whereas the MMDF maildrop format is now forgotten.
1849 By dropping the MMDF maildrop format support,
1850 mbox became the only packed mailbox format supported in mmh.
1851 .P
1852 The simplifications within the code were moderate.
1853 Mainly, the reading and writing of MMDF mailbox files was removed.
1854 But also, switches of
1855 .Pn packf
1856 and
1857 .Pn rcvpack
1858 could be removed.
1859 .Ci 3916ab66ad5d183705ac12357621ea8661afd3c0
1860 In the message parsing function
1861 .Fn sbr/m_getfld.c ,
1862 knowledge of MMDF packed mail boxes was removed.
1863 .Ci 684ec30d81e1223a282764452f4902ed4ad1c754
1864 Further code structure simplifications may be possible there,
1865 because only one single packed mailbox format is left to be supported.
1866 I have not worked on them yet because
1867 .Fu m_getfld()
1868 is heavily optimized and thus dangerous to touch.
1869 The risk of damaging the intricate workings of the optimized code is
1870 too high.
1873 .U3 "Prompter's Control Keys
1874 .P
1875 The program
1876 .Pn prompter
1877 queries the user to fill in a message form.
1878 When used by
1879 .Pn comp
1880 as
1881 .Cl "comp -editor prompter" ,
1882 the resulting behavior is similar to
1883 .Pn mailx .
1884 Apparently,
1885 .Pn prompter
1886 had not been touched lately.
1887 Otherwise it's hardly explainable why it
1888 still offered the switches
1889 .Sw -erase
1890 .Ar chr
1891 and
1892 .Sw -kill
1893 .Ar chr
1894 to name the characters for command line editing.
1895 The times when this had been necessary are long time gone.
1896 Today these things work out-of-the-box, and if not, are configured
1897 with the standard tool
1898 .Pn stty .
1899 The switches are removed now
1900 .Ci 0bd9750710cdbab80cfb4036dd87af20afe1552f .
1903 .U3 "Hardcopy Terminal Support
1904 .P
1905 More of a funny anecdote is a check for being connected to a
1906 hardcopy terminal.
1907 It remained in the code until spring 2012, when I finally removed it
1908 .Ci b7764c4a6b71d37918a97594d866258f154017ca .
1909 .P
1910 The check only prevented a pager to be placed between the printing
1911 program (\c
1912 .Pn mhl )
1913 and the terminal.
1914 In nmh, this could have been ensured statically with the
1915 .Sw -nomoreproc
1916 at the command line, too.
1917 In mmh, setting the profile entry
1918 .Pe Pager
1919 or the environment variable
1920 .Ev PAGER
1921 to
1922 .Pn cat
1923 is sufficient.
1928 .H2 "Attachments
1929 .P
1930 The mind model of email attachments is unrelated to MIME.
1931 Although the MIME RFCs (2045 through 2049) define the technical
1932 requirements for having attachments, they do not mention the word
1933 attachment.
1934 Instead of attachments, MIME talks about ``multi-part message bodies''
1935 [RFC\|2045], a more general concept.
1936 Multi-part messages are messages
1937 ``in which one or more different
1938 sets of data are combined in a single body''
1939 [RFC\|2046].
1940 MIME keeps its descriptions generic;
1941 it does not imply specific usage models.
1942 One usage model became prevalent: attachments.
1943 The idea is having a main text document with files of arbitrary kind
1944 attached to it.
1945 In MIME terms, this is a multi-part message having a text part first
1946 and parts of arbitrary type following.
1947 .P
1948 MH's MIME support is a direct implementation of the RFCs.
1949 The perception of the topic described in the RFCs is clearly visible
1950 in MH's implementation.
1951 .\" XXX rewrite ``no idea''.
1952 As a result,
1953 MH had all the MIME features but no idea of attachments.
1954 But users do not need all the MIME features,
1955 they want convenient attachment handling.
1958 .U3 "Composing MIME Messages
1959 .P
1960 In order to improve the situation on the message composing side,
1961 Jon Steinhart had added an attachment system to nmh in 2002.
1962 .Ci 7480dbc14bc90f2d872d434205c0784704213252
1963 In the file
1964 .Fn docs/README-ATTACHMENTS ,
1965 he described his motivation to do so as such:
1966 .QS
1967 Although nmh contains the necessary functionality for MIME message
1968 handing [sic!], the interface to this functionality is pretty obtuse.
1969 There's no way that I'm ever going to convince my partner to write
1970 .Pn mhbuild
1971 composition files!
1972 .QE
1973 .LP
1974 With this change, the mind model of attachments entered nmh.
1975 In the same document:
1976 .QS
1977 These changes simplify the task of managing attachments on draft files.
1978 They allow attachments to be added, listed, and deleted.
1979 MIME messages are automatically created when drafts with attachments
1980 are sent.
1981 .QE
1982 .LP
1983 Unfortunately, the attachment system,
1984 like any new facilities in nmh,
1985 was inactive by default.
1986 .P
1987 During my work in Argentina, I tried to improve the attachment system.
1988 But, because of great opposition in the nmh community,
1989 my patch died as a proposal on the mailing list, after long discussions.
1990 .[
1991 nmh-workers attachment proposal
1992 .]
1993 In January 2012, I extended the patch and applied it to mmh.
1994 .Ci 8ff284ff9167eff8f5349481529332d59ed913b1
1995 In mmh, the attachment system is active by default.
1996 Instead of command line switches, the
1997 .Pe Attachment-Header
1998 profile entry is used to specify
1999 the name of the attachment header field.
2000 It is pre-defined to
2001 .Hd Attach .
2002 .P
2003 To add an attachment to a draft, a header line needs to be added:
2004 .VS
2005 To: bob
2006 Subject: The file you wanted
2007 Attach: /path/to/the/file-bob-wanted
2008 --------
2009 Here it is.
2010 VE
2011 The header field can be added to the draft manually in the editor,
2012 or by using the `attach' command at the WhatNow prompt, or
2013 non-interactively with
2014 .Pn anno :
2015 .VS
2016 anno -append -nodate -component Attach -text /path/to/attachment
2017 VE
2018 Drafts with attachment headers are converted to MIME automatically by
2019 .Pn send .
2020 The conversion to MIME is invisible to the user.
2021 The draft stored in the draft folder is always in source form with
2022 attachment headers.
2023 If the MIMEification fails (e.g. because the file to attach
2024 is not accessible) the original draft is not changed.
2025 .P
2026 The attachment system handles the forwarding of messages, too.
2027 If the attachment header value starts with a plus character (`\fL+\fP'),
2028 like in
2029 .Cl "Attach: +bob 30 42" ,
2030 the given messages in the specified folder will be attached.
2031 This allowed to simplify
2032 .Pn forw .
2033 .Ci f41f04cf4ceca7355232cf7413e59afafccc9550
2034 .P
2035 Closely related to attachments is non-ASCII text content,
2036 because it requires MIME too.
2037 In nmh, the user needed to call `mime' at the WhatNow prompt
2038 to have the draft converted to MIME.
2039 This was necessary whenever the draft contained non-ASCII characters.
2040 If the user did not call `mime', a broken message would be sent.
2041 Therefore, the
2042 .Pe automimeproc
2043 profile entry could be specified to have the `mime' command invoked
2044 automatically each time.
2045 Unfortunately, this approach conflicted with the attachment system
2046 because the draft would already be in MIME format at the time
2047 when the attachment system wanted to MIMEify it.
2048 To use nmh's attachment system, `mime' must not be called at the
2049 WhatNow prompt and
2050 .Pe automimeproc
2051 must not be set in the profile.
2052 But then the case of non-ASCII text without attachment headers was
2053 not caught.
2054 All in all, the solution was complex and irritating.
2055 My patch from December 2010
2056 .[
2057 nmh-workers attachment proposal
2058 .]
2059 would have simplified the situation.
2060 .P
2061 Mmh's current solution is even more elaborate.
2062 Any necessary MIMEification is done automatically.
2063 There is no `mime' command at the WhatNow prompt anymore.
2064 The draft will be converted automatically to MIME when either an
2065 attachment header or non-ASCII text is present.
2066 Furthermore, the hash character (`\fL#\fP') is not special any more
2067 at line beginnings in the draft message.
2068 .\" XXX REF ?
2069 Users need not concern themselves with the whole topic at all.
2070 .P
2071 Although the new approach does not anymore support arbitrary MIME
2072 compositions directly, the full power of
2073 .Pn mhbuild
2074 can still be accessed.
2075 Given no attachment headers are included, the user can create
2076 .Pn mhbuild
2077 composition drafts like in nmh.
2078 Then, at the WhatNow prompt, he needs to invoke
2079 .Cl "edit mhbuild
2080 to convert it to MIME.
2081 Because the resulting draft does neither contain non-ASCII characters
2082 nor has it attachment headers, the attachment system will not touch it.
2083 .P
2084 The approach taken in mmh is tailored towards today's most common case:
2085 a text part, possibly with attachments.
2086 This case was simplified.
2089 .U3 "MIME Type Guessing
2090 .P
2091 From the programmer's point of view, the use of
2092 .Pn mhbuild
2093 composition drafts had one notable advantage over attachment headers:
2094 The user provides the appropriate MIME types for files to include.
2095 The attachment system needs to find out the correct MIME type itself.
2096 This is a difficult task, yet it spares the user irritating work.
2097 Determining the correct MIME type of content is partly mechanical,
2098 partly intelligent work.
2099 Forcing the user to find out the correct MIME type,
2100 forces him to do partly mechanical work.
2101 Letting the computer do the work can lead to bad choices for difficult
2102 content.
2103 For mmh, the latter option was chosen.
2104 .P
2105 Determining the MIME type by the suffix of the file name is a dumb
2106 approach, yet it is simple to implement and provides good results
2107 for the common cases.
2108 Mmh implements this approach in the
2109 .Pn print-mimetype
2110 script.
2111 .Ci 4b5944268ea0da7bb30598a27857304758ea9b44
2112 Using it is the default choice.
2113 .P
2114 A far better, though less portable, approach is the use of
2115 .Pn file .
2116 This standard tool tries to determine the type of files.
2117 Unfortunately, its capabilities and accuracy varies from system to system.
2118 Additionally, its output was only intended for human beings,
2119 but not to be used by programs.
2120 It varies much.
2121 Nevertheless, modern versions of GNU
2122 .Pn file ,
2123 which is prevalent on the popular GNU/Linux systems,
2124 provide MIME type output in machine-readable form.
2125 Although this solution is highly system-dependent,
2126 it solves the difficult problem well.
2127 On systems where GNU
2128 .Pn file ,
2129 version 5.04 or higher, is available it should be used.
2130 One needs to specify the following profile entry to do so:
2131 .Ci 3baec236a39c5c89a9bda8dbd988d643a21decc6
2132 .VS
2133 Mime-Type-Query: file -b --mime
2134 VE
2135 .LP
2136 Other versions of
2137 .Pn file
2138 might possibly be usable with wrapper scripts to reformat the output.
2139 The diversity among
2140 .Pn file
2141 implementations is great; one needs to check the local variant.
2142 .P
2143 If no MIME type can be determined, text content gets sent as
2144 `text/plain' and anything else under the generic fall-back type
2145 `application/octet-stream'.
2146 It is not possible in mmh to override the automatic MIME type guessing
2147 for a specific file.
2148 To do so, either the user would need to know in advance for which file
2149 the automatic guessing fails, or the system would require interaction.
2150 I consider both cases impractical.
2151 The existing solution should be sufficient.
2152 If not, the user may always fall back to
2153 .Pn mhbuild
2154 composition drafts and ignore the attachment system.
2157 .U3 "Storing Attachments
2158 .P
2159 Extracting MIME parts of a message and storing them to disk is performed by
2160 .Pn mhstore .
2161 The program has two operation modes,
2162 .Sw -auto
2163 and
2164 .Sw -noauto .
2165 With the former one, each part is stored under the filename given in the
2166 MIME part's meta information, if available.
2167 This naming information is usually available for modern attachments.
2168 If no filename is available, this MIME part is stored as if
2169 .Sw -noauto
2170 would have been specified.
2171 In the
2172 .Sw -noauto
2173 mode, the parts are processed according to rules, defined by
2174 .Pe mhstore-store-*
2175 profile entries.
2176 These rules define generic filename templates for storing
2177 or commands to post-process the contents in arbitrary ways.
2178 If no matching rule is available the part is stored under a generic
2179 filename, built from message number, MIME part number, and MIME type.
2180 .P
2181 The
2182 .Sw -noauto
2183 mode had been the default in nmh because it was considered safe,
2184 in contrast to the
2185 .Sw -auto
2186 mode.
2187 In mmh,
2188 .Sw -auto
2189 is not dangerous anymore.
2190 Two changes were necessary:
2191 .LI 1
2192 Any directory path is removed from the proposed filename.
2193 Thus, the files are always stored in the expected directory.
2194 .Ci 41b6eadbcecf63c9a66aa5e582011987494abefb
2195 .LI 2
2196 Tar files are not extracted automatically any more.
2197 Thus, the rest of the file system will not be touched.
2198 .Ci 94c80042eae3383c812d9552089953f9846b1bb6
2199 .LP
2200 Now, the outcome of mmh's
2201 .Cl "mhstore -auto
2202 can be foreseen from the output of
2203 .Cl "mhlist -verbose" .
2204 .P
2205 The
2206 .Sw -noauto
2207 mode is seen to be more powerful but less convenient.
2208 On the other hand,
2209 .Sw -auto
2210 is safe now and
2211 storing attachments under their original name is intuitive.
2212 Hence,
2213 .Sw -auto
2214 serves better as the default option.
2215 .Ci 3410b680416c49a7617491af38bc1929855a331d
2216 .P
2217 Files are stored into the directory given by the
2218 .Pe Nmh-Storage
2219 profile entry, if set, or
2220 into the current working directory, otherwise.
2221 Storing to different directories is only possible with
2222 .Pe mhstore-store-*
2223 profile entries.
2224 .P
2225 Still, in both modes, existing files get overwritten silently.
2226 This can be considered a bug.
2227 Yet, each other behavior has its draw-backs, too.
2228 Refusing to replace files requires adding a
2229 .Sw -force
2230 option.
2231 Users will likely need to invoke
2232 .Pn mhstore
2233 a second time with
2234 .Sw -force .
2235 Eventually, only the user can decide in the specific case.
2236 This requires interaction, which I like to avoid if possible.
2237 Appending a unique suffix to the filename is another bad option.
2238 For now, the behavior remains as it is.
2239 .P
2240 In mmh, only MIME parts of type message are special in
2241 .Pn mhstore 's
2242 .Sw -auto
2243 mode.
2244 Instead of storing message/rfc822 parts as files to disk,
2245 they are stored as messages into the current mail folder.
2246 The same applies to message/partial, although the parts are
2247 automatically reassembled beforehand.
2248 MIME parts of type message/external-body are not automatically retrieved
2249 anymore.
2250 Instead, information on how to retrieve them is output.
2251 Not supporting this rare case saved nearly one thousand lines of code.
2252 .Ci 55e1d8c654ee0f7c45b9361ce34617983b454c32
2253 .\" XXX mention somewhere else too: (The profile entry `nmh-access-ftp'
2254 .\" and sbr/ruserpass.c for reading ~/.netrc are gone now.)
2255 `application/octet-stream; type=tar' is not special anymore.
2256 Automatically extracting such MIME parts had been the dangerous part
2257 of the
2258 .Sw -auto
2259 mode.
2260 .Ci 94c80042eae3383c812d9552089953f9846b1bb6
2264 .U3 "Showing MIME Messages
2265 .P
2266 The program
2267 .Pn mhshow
2268 had been written to display MIME messages.
2269 It implemented the conceptional view of the MIME RFCs.
2270 Nmh's
2271 .Pn mhshow
2272 handled each MIME part independently, presenting them separately
2273 to the user.
2274 This does not match today's understanding of email attachments,
2275 where displaying a message is seen to be a single, integrated operation.
2276 Today, email messages are expected to consist of a main text part
2277 plus possibly attachments.
2278 They are not any more seen to be arbitrary MIME hierarchies with
2279 information on how to display the individual parts.
2280 I adjusted
2281 .Pn mhshow 's
2282 behavior to the modern view on the topic.
2283 .P
2284 One should note that this section completely ignores the original
2285 .Pn show
2286 program, because it was not capable to display MIME messages
2287 and is no longer part of mmh.
2288 .\" XXX ref to other section
2289 Although
2290 .Pn mhshow
2291 was renamed to
2292 .Pn show
2293 in mmh, this section uses the name
2294 .Pn mhshow ,
2295 in order to avoid confusion.
2296 .P
2297 In mmh, the basic idea is that
2298 .Pn mhshow
2299 should display a message in one single pager session.
2300 Therefore,
2301 .Pn mhshow
2302 invokes a pager session for all its output,
2303 whenever it prints to a terminal.
2304 .Ci a4197ea6ffc5c1550e8b52d5a654bcaaaee04a4e
2305 In consequence,
2306 .Pn mhl
2307 does no more invoke a pager.
2308 .Ci 0e46503be3c855bddaeae3843e1b659279c35d70
2309 With
2310 .Pn mhshow
2311 replacing the original
2312 .Pn show ,
2313 output from
2314 .Pn mhl
2315 does not go to the terminal directly, but through
2316 .Pn mhshow .
2317 Hence,
2318 .Pn mhl
2319 does not need to invoke a pager.
2320 The one and only job of
2321 .Pn mhl
2322 is to format messages or parts of them.
2323 The only place in mmh, where a pager is invoked is
2324 .Pn mhshow .
2325 .P
2326 .Pe mhshow-show-*
2327 profile entries can be used to display MIME parts in a specific way.
2328 For instance, PDF and Postscript files could be converted to plain text
2329 to display them in the terminal.
2330 In mmh, MIME parts will always be displayed serially.
2331 The request to display the MIME type `multipart/parallel' in parallel
2332 is ignored.
2333 It is simply treated as `multipart/mixed'.
2334 .Ci d0581ba306a7299113a346f9b4c46ce97bc4cef6
2335 This could already be requested with the, now removed,
2336 .Sw -serialonly
2337 switch of
2338 .Pn mhshow .
2339 As MIME parts are always processed exclusively, i.e. serially,
2340 the `%e' escape in
2341 .Pe mhshow-show-*
2342 profile entries became useless and was thus removed.
2343 .Ci a20d405db09b7ccca74d3e8c57550883da49e1ae
2344 .P
2345 In the intended setup, only text content would be displayed.
2346 Non-text content would be converted to text by appropriate
2347 .Pe mhshow-show-*
2348 profile entries before, if possible and wanted.
2349 All output would be displayed in a single pager session.
2350 Other kinds of attachments are ignored.
2351 With
2352 .Pe mhshow-show-*
2353 profile entries for them, they can be displayed serially along
2354 the message.
2355 For parallel display, the attachments need to be stored to disk first.
2356 .P
2357 To display text content in foreign charsets, they need to be converted
2358 to the native charset.
2359 Therefore,
2360 .Pe mhshow-charset-*
2361 profile entries used to be needed.
2362 In mmh, the conversion is performed automatically by piping the
2363 text through the
2364 .Pn iconv
2365 command, if necessary.
2366 .Ci 2433122c20baccb10b70b49c04c6b0497b5b3b60
2367 Custom
2368 .Pe mhshow-show-*
2369 rules for textual content might need a
2370 .Cl "iconv -f %c %f |
2371 prefix to have the text converted to the native charset.
2372 .P
2373 Although the conversion of foreign charsets to the native one
2374 has improved, it is not consistent enough.
2375 Further work needs to be done and
2376 the basic concepts in this field need to be re-thought.
2377 Though, the default setup of mmh displays message in foreign charsets
2378 correctly without the need to configure anything.
2381 .ig
2383 .P
2384 mhshow/mhstore: Removed support for retrieving message/external-body parts.
2385 These tools will not download the contents automatically anymore. Instead,
2386 they print the information needed to get the contents. If someone should
2387 really receive one of those rare message/external-body messages, he can
2388 do the job manually. We save nearly a thousand lines of code. That's worth
2389 it!
2390 (The profile entry `nmh-access-ftp' and sbr/ruserpass.c for reading
2391 ~/.netrc are gone now.)
2392 .Ci 55e1d8c654ee0f7c45b9361ce34617983b454c32
2394 ..
2398 .H2 "Signing and Encrypting
2399 .P
2400 Nmh offers no direct support for digital signatures and message encryption.
2401 This functionality needed to be added through third-party software.
2402 In mmh, the functionality should be included because it
2403 is a part of modern email and likely wanted by users of mmh.
2404 A fresh mmh installation should support signing and encrypting
2405 out-of-the-box.
2406 Therefore, Neil Rickert's
2407 .Pn mhsign
2408 and
2409 .Pn mhpgp
2410 scripts
2411 .[
2412 neil rickert mhsign mhpgp
2413 .]
2414 were included into mmh
2415 .Ci f45cdc98117a84f071759462c7ae212f4bc5ab2e
2416 .Ci 58cf09aa36e9f7f352a127158bbf1c5678bc6ed8 .
2417 The scripts fit well because they are lightweight and
2418 similar of style to the existing tools.
2419 Additionally, no licensing difficulties appeared,
2420 as they are part of the public domain.
2421 .P
2422 .Pn mhsign
2423 handles the signing and encrypting part.
2424 It comprises about 250 lines of shell code and interfaces between
2425 .Pn gnupg
2426 and
2427 the MH system.
2428 It was meant to be invoked manually at the WhatNow prompt, but in mmh,
2429 .Pn send
2430 invokes
2431 .pn mhsign
2432 automatically
2433 .Ci c7b5e1df086bcc37ff40163ee67571f076cf6683 .
2434 Special header fields were introduced to request this action.
2435 If a draft contains the
2436 .Hd Sign
2437 header field,
2438 .Pn send
2439 will initiate the signing.
2440 The signing key is either chosen automatically or specified by the
2441 .Pe Pgpkey
2442 profile entry.
2443 .Pn send
2444 always create signatures using the PGP/MIME standard, \" REF XXX
2445 but by manually invoking
2446 .Pn mhsign ,
2447 old-style non-MIME signatures can be created as well.
2448 To encrypt an outgoing message, the draft needs to contain an
2449 .Hd Enc
2450 header field.
2451 Public keys of all recipients are searched for in the gnupg keyring and
2452 in a file called
2453 .Fn pgpkeys ,
2454 which contains exceptions and overrides.
2455 Unless public keys are found for all recipients,
2456 .Pn mhsign
2457 will refuse to encrypt it.
2458 Currently, messages with hidden (BCC) recipients can not be encrypted.
2459 This work is pending because it requires a structurally more complex
2460 approach.
2461 .P
2462 .Pn mhpgp
2463 is the companion to
2464 .Pn mhsign .
2465 It verifies signatures and decrypts messages.
2466 Encrypted messages can either be temporarily decrypted for display
2467 or permanently decrypted and stored into the current folder.
2468 Currently,
2469 .Pn mhpgp
2470 needs to be invoked manually.
2471 The integration into
2472 .Pn show
2473 and
2474 .Pn mhstore
2475 to verify signatures and decrypt messages as needs
2476 is planned but not realized yet.
2477 .P
2478 Both scripts were written for nmh, hence they needed to be adjust
2479 according to the differences between nmh and mmh.
2480 For instance, they use the backup prefix no longer.
2481 Furthermore, compatibility support for old PGP features was dropped.
2482 .P
2483 The integrated message signing and encrypting support is one of the
2484 most recent features in mmh.
2485 It has not yet had the time to mature.
2486 User feedback and personal experience need to be accumulated to
2487 direct the further development of the facility.
2488 Although the feedback and experience is still missing,
2489 it seems to be worthwhile to consider adding
2490 .Sw -[no]sign
2491 and
2492 .Sw -[no]enc
2493 switches to
2494 .Pn send ,
2495 to be able to override the corresponding header fields.
2496 A profile entry:
2497 .VS
2498 send: -sign
2499 VE
2500 would then activate signing for all outgoing messages.
2501 With the present approach, a
2502 .Hd Send
2503 header component needs to be added to each draft template
2504 to achieve the same result.
2505 Adding the switches would ease the work greatly and keep the
2506 template files clean.
2511 .H2 "Draft and Trash Folder
2512 .P
2514 .U3 "Draft Folder
2515 .Id draft-folder
2516 .P
2517 In the beginning, MH had the concept of a draft message.
2518 This is the file
2519 .Fn draft
2520 in the MH directory, which is treated special.
2521 On composing a message, this draft file was used.
2522 When starting to compose another message before the former one was sent,
2523 the user had to decide among:
2524 .LI 1
2525 Using the old draft to finish and send it before starting with a new one.
2526 .LI 2
2527 Discarding the old draft and replacing it with a new one.
2528 .LI 3
2529 Preserving the old draft by refiling it to a folder.
2530 .LP
2531 It was only possible to work in alternation on multiple drafts.
2532 Therefore, the current draft needed to be refiled to a folder and
2533 another one re-used for editing.
2534 Working on multiple drafts at the same time was impossible.
2535 The usual approach of switching to a different MH context did not
2536 help anything.
2537 .P
2538 The draft folder facility exists to
2539 allow true parallel editing of drafts, in a straight forward way.
2540 It was introduced by Marshall T. Rose, already in 1984.
2541 Similar to other new features, the draft folder was inactive by default.
2542 Even in nmh, the highly useful draft folder was not available
2543 out-of-the-box.
2544 At least, Richard Coleman added the man page
2545 .Mp mh-draft (5)
2546 to better document the feature.
2547 .P
2548 Not using the draft folder facility has the single advantage of having
2549 the draft file at a static location.
2550 This is simple in simple cases but the concept does not scale for more
2551 complex cases.
2552 The concept of the draft message is too limited for the problem.
2553 Therefore the draft folder was introduced.
2554 It is the more powerful and more natural concept.
2555 The draft folder is a folder like any other folder in MH.
2556 Its messages can be listed like any other messages.
2557 A draft message is no longer a special case.
2558 Tools do not need special switches to work on the draft message.
2559 Hence corner cases were removed.
2560 .P
2561 The trivial part of the work was activating the draft folder with a
2562 default name.
2563 I chose the name
2564 .Fn +drafts
2565 for obvious reasons.
2566 In consequence, the command line switches
2567 .Sw -draftfolder
2568 and
2569 .Sw -draftmessage
2570 could be removed.
2571 More difficult but also more improving was updating the tools to the
2572 new concept.
2573 For nearly three decades, the tools needed to support two draft handling
2574 approaches.
2575 By fully switching to the draft folder, the tools could be simplified
2576 by dropping the awkward draft message handling code.
2577 .Sw -draft
2578 switches were removed because operating on a draft message is no longer
2579 special.
2580 It became indistinguishable to operating on any other message.
2581 .Ci 337338b404931f06f0db2119c9e145e8ca5a9860
2582 .P
2583 There is no more need to query the user for draft handling
2584 .Ci 2d48b455c303a807041c35e4248955f8bec59eeb .
2585 It is always possible to add another new draft.
2586 Refiling drafts is without difference to refiling other messages.
2587 All of these special cases are gone.
2588 Yet, one draft-related switch remained.
2589 .Pn comp
2590 still has
2591 .Sw -[no]use
2592 for switching between two modes:
2593 .LI 1
2594 .Sw -use
2595 to modify an existing draft.
2596 .LI 2
2597 .Sw -nouse
2598 to compose a new draft, possibly taking some existing message as template.
2599 .LP
2600 In either case, the behavior of
2601 .Pn comp
2602 is deterministic.
2603 .P
2604 .Pn send
2605 now operates on the current message in the draft folder by default.
2606 As message and folder can both be overridden by specifying them on
2607 the command line, it is possible to send any message in the mail storage
2608 by simply specifying its number and folder.
2609 In contrast to the other tools,
2610 .Pn send
2611 takes the draft folder as its default folder.
2612 .P
2613 Dropping the draft message concept in favor for the draft folder concept,
2614 removed special cases with regular cases.
2615 This simplified the source code of the tools, as well as the concepts.
2616 In mmh, draft management does not break with the MH concepts
2617 but applies them.
2618 .Cl "scan +drafts" ,
2619 for instance, is a truly natural request.
2620 Most of the work was already performed by Rose in the eighties.
2621 The original improvement of mmh is dropping the old draft message approach
2622 and thus simplifying the tools, the documentation and the system as a whole.
2623 Although my part in the draft handling improvement was small,
2624 it was an important one.
2627 .U3 "Trash Folder
2628 .Id trash-folder
2629 .P
2630 Similar to the situation for drafts is the situation for removed messages.
2631 Historically, a message was ``deleted'' by prepending a specific
2632 \fIbackup prefix\fP, usually the comma character,
2633 to the file name.
2634 The specific file would then be ignored by MH because only files with
2635 names consisting of digits only are treated as messages.
2636 Although files remained in the file system,
2637 the messages were no longer visible in MH.
2638 To truly delete them, a maintenance job was needed.
2639 Usually a cron job was installed to delete them after a grace time.
2640 For instance:
2641 .VS
2642 find $HOME/Mail -type f -name ',*' -ctime +7 -delete
2643 VE
2644 In such a setup, the original message could be restored
2645 within the grace time interval by stripping the
2646 backup prefix from the file name.
2647 But the user could not rely on this statement.
2648 If the last message of a folder with six messages (\fL1-6\fP) was removed,
2649 message
2650 .Fn 6 ,
2651 became file
2652 .Fn ,6 .
2653 If then a new message entered the same folder, it would be named with
2654 the number one above the highest existing message number.
2655 In this case the message would be named
2656 .Fn 6
2657 then.
2658 If this new message would be removed as well,
2659 then the backup of the former message is overwritten.
2660 Hence, the ability to restore removed messages did not only depend on
2661 the sweeping cron job but also on the removing of further messages.
2662 It is undesirable to have such obscure and complex mechanisms.
2663 The user should be given a small set of clear assertions, such as
2664 ``Removed files are restorable within a seven-day grace time.''
2665 With the addition ``... unless a message with the same name in the
2666 same folder is removed before.'' the statement becomes complex.
2667 A user will hardly be able to keep track of any removal to know
2668 if the assertion still holds true for a specific file.
2669 In practice, the real mechanism is unclear to the user.
2670 The consequences of further removals are not obvious.
2671 .P
2672 Furthermore, the backup files are scattered within the whole mail storage.
2673 This complicates managing them.
2674 It is possible with the help of
2675 .Pn find ,
2676 but everything would be more convenient
2677 if the deleted messages would be collected in one place.
2678 .P
2679 The profile entry
2680 .Pe rmmproc
2681 (previously named
2682 .Pe Delete-Prog )
2683 was introduced very early to improve the situation.
2684 It could be set to any command, which would be executed to remove
2685 the specified messages.
2686 This would override the default action described above.
2687 Refiling the to-be-removed files to a trash folder is the usual example.
2688 Nmh's man page
2689 .Mp rmm (1)
2690 proposes to set the
2691 .Pe rmmproc
2692 to
2693 .Cl "refile +d
2694 to move messages to the trash folder,
2695 .Fn +d ,
2696 instead of renaming them with the backup prefix.
2697 The man page proposes additionally the expunge command
2698 .Cl "rm `mhpath +d all`
2699 to empty the trash folder.
2700 .P
2701 Removing messages in such a way has advantages.
2702 The mail storage is prevented from being cluttered with removed messages
2703 because they are all collected in one place.
2704 Existing and removed messages are thus separated more strictly.
2705 No backup files are silently overwritten.
2706 But most important is the ability to keep removed messages in the MH domain.
2707 Messages in the trash folder can be listed like those in any other folder.
2708 Deleted messages can be displayed like any other messages.
2709 .Pn refile
2710 can restore deleted messages.
2711 All operations on deleted files are still covered by the MH tools.
2712 The trash folder is just like any other folder in the mail storage.
2713 .P
2714 Similar to the draft folder case, I dropped the old backup prefix approach
2715 in favor for replacing it by the better suiting trash folder system.
2716 Hence,
2717 .Pn rmm
2718 calls
2719 .Pn refile
2720 to move the to-be-removed message to the trash folder,
2721 .Fn +trash
2722 by default.
2723 To sweep it clean, the user can use
2724 .Cl "rmm -unlink +trash a" ,
2725 where the
2726 .Sw -unlink
2727 switch causes the files to be unlinked.
2728 .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
2729 .Ci ca0b3e830b86700d9e5e31b1784de2bdcaf58fc5
2730 .P
2731 Dropping the legacy approach and converting to the new approach completely
2732 simplified the code base.
2733 The relationship between
2734 .Pn rmm
2735 and
2736 .Pn refile
2737 was inverted.
2738 In mmh,
2739 .Pn rmm
2740 invokes
2741 .Pn refile ,
2742 which used to be the other way round.
2743 Yet, the relationship is simpler now.
2744 Loops, like described in nmh's man page for
2745 .Mp refile (1),
2746 can no longer occur:
2747 .QS
2748 Since
2749 .Pn refile
2750 uses your
2751 .Pe rmmproc
2752 to delete the message, the
2753 .Pe rmmproc
2754 must NOT call
2755 .Pn refile
2756 without specifying
2757 .Sw -normmproc
2758 or you will create an infinite loop.
2759 .QE
2760 .LP
2761 .Pn rmm
2762 either unlinks a message with
2763 .Fu unlink()
2764 or invokes
2765 .Pn refile
2766 to move it to the trash folder.
2767 .Pn refile
2768 does not invoke any tools.
2769 .P
2770 By generalizing the message removal in the way that it became covered
2771 by the MH concepts made the whole system more powerful.
2777 .H2 "Modern Defaults
2778 .P
2779 Nmh has a bunch of convenience-improving features inactive by default,
2780 although one can expect every new user wanting to have them active.
2781 The reason they are inactive by default is the wish to stay compatible
2782 with old versions.
2783 But what is the definition for old versions?
2784 Still, the highly useful draft folder facility has not been activated
2785 by default although it was introduced over twenty-five years ago.
2786 .[
2787 rose romine real work
2788 .]
2789 The community seems not to care.
2790 This is one of several examples that require new users to first build up
2791 a profile before they can access the modern features of nmh.
2792 Without an extensive profile, the setup is hardly usable
2793 for modern emailing.
2794 The point is not the customization of the setup,
2795 but the need to activate generally useful facilities.
2796 .P
2797 Yet, the real problem lies less in enabling the features, as this is
2798 straight forward as soon as one knows what he wants.
2799 The real problem is that new users need deep insight into the project
2800 to find out about inactive features nmh already provides.
2801 To give an example, I needed one year of using nmh
2802 before I became aware of the existence of the attachment system.
2803 One could argue that this fact disqualifies my reading of the
2804 documentation.
2805 If I would have installed nmh from source back then, I could agree.
2806 Yet, I had used a prepackaged version and had expected that it would
2807 just work.
2808 Nevertheless, I had been convinced by the concepts of MH already
2809 and I am a software developer,
2810 still I required a lot of time to discover the cool features.
2811 How can we expect users to be even more advanced than me,
2812 just to allow them use MH in a convenient and modern way?
2813 Unless they are strongly convinced of the concepts, they will fail.
2814 I have seen friends of me giving up disappointed
2815 before they truly used the system,
2816 although they had been motivated in the beginning.
2817 They suffer hard enough to get used to the tool chest approach,
2818 we developers should spare them further inconveniences.
2819 .P
2820 Maintaining compatibility for its own sake is bad,
2821 because the code base collects more and more compatibility code.
2822 Sticking to the compatiblity code means remaining limited;
2823 whereas adjusting to the changes renders the compatibility unnecessary.
2824 Keeping unused alternatives in the code is a bad choice as they likely
2825 gather bugs, by not being well tested.
2826 Also, the increased code size and the greater number of conditions
2827 increase the maintenance costs.
2828 If any MH implementation would be the back-end of widespread
2829 email clients with large user bases, compatibility would be more
2830 important.
2831 Yet, it appears as if this is not the case.
2832 Hence, compatibility is hardly important for technical reasons.
2833 Its importance originates rather from personal reasons.
2834 Nmh's user base is small and old.
2835 Changing the interfaces would cause inconvenience to long-term users of MH.
2836 It would force them to change their many years old MH configurations.
2837 I do understand this aspect, but by sticking to the old users,
2838 new users are kept away.
2839 Yet, the future lies in new users.
2840 In consequence, mmh invites new users by providing a convenient
2841 and modern setup, readily usable out-of-the-box.
2842 .P
2843 In mmh, all modern features are active by default and many previous
2844 approaches are removed or only accessible in manual ways.
2845 New default features include:
2846 .BU
2847 The attachment system (\c
2848 .Hd Attach ).
2849 .Ci 8ff284ff9167eff8f5349481529332d59ed913b1
2850 .BU
2851 The draft folder facility (\c
2852 .Fn +drafts ).
2853 .Ci 337338b404931f06f0db2119c9e145e8ca5a9860
2854 .BU
2855 The unseen sequence (`u')
2856 .Ci c2360569e1d8d3678e294eb7c1354cb8bf7501c1
2857 and the sequence negation prefix (`!').
2858 .Ci db74c2bd004b2dc9bf8086a6d8bf773ac051f3cc
2859 .BU
2860 Quoting the original message in the reply.
2861 .Ci 67411b1f95d6ec987b4c732459e1ba8a8ac192c6
2862 .BU
2863 Forwarding messages using MIME.
2864 .Ci 6e271608b7b9c23771523f88d23a4d3593010cf1
2865 .LP
2866 In consequence, a setup with a profile that defines only the path to the
2867 mail storage, is already convenient to use.
2868 Again, Paul Vixie's ``edginess'' call supports the direction I took:
2869 ``the `main branch' should just be modern''.
2870 .[
2871 paul vixie edginess nmh-workers
2872 .]
2878 .\" --------------------------------------------------------------
2879 .H1 "Styling
2880 .P
2881 Kernighan and Pike have emphasized the importance of style in the
2882 preface of their book:
2883 .[ [
2884 kernighan pike practice of programming
2885 .], p. x]
2886 .QS
2887 Chapter 1 discusses programming style.
2888 Good style is so important to good programming that we have chose
2889 to cover it first.
2890 .QE
2891 This section covers changes in mmh that were guided by the desire
2892 to improve on style.
2893 Many of them follow the rules given in the quoted book.
2894 .[
2895 kernighan pike practice of programming
2896 .]
2901 .H2 "Code Style
2902 .Id code-style
2903 .P
2904 .U3 "Indentation Style
2905 .P
2906 Indentation styles are the holy cow of programmers.
2907 Kernighan and Pike
2908 .[ [
2909 kernighan pike practice of programming
2910 .], p. 10]
2911 wrote:
2912 .QS
2913 Programmers have always argued about the layout of programs,
2914 but the specific style is much less important than its consistent
2915 application.
2916 Pick one style, preferably ours, use it consistently, and don't waste
2917 time arguing.
2918 .QE
2919 .P
2920 I agree that the constant application is most important,
2921 but I believe that some styles have advantages over others.
2922 For instance the indentation with tab characters only.
2923 Tab characters directly map to the nesting level \(en
2924 one tab, one level.
2925 Tab characters are flexible because developers can adjust them to
2926 whatever width they like to have.
2927 There is no more need to run
2928 .Pn unexpand
2929 or
2930 .Pn entab
2931 programs to ensure the correct mixture of leading tabs and spaces.
2932 The simple rules are: (1) Leading whitespace must consist of tabs only.
2933 (2) Any other whitespace should consist of spaces.
2934 These two rules ensure the integrity of the visual appearance.
2935 Although reformatting existing code should be avoided, I did it.
2936 I did not waste time arguing; I just reformated the code.
2937 .Ci a485ed478abbd599d8c9aab48934e7a26733ecb1
2939 .U3 "Comments
2940 .P
2941 Section 1.6 of
2942 .[ [
2943 kernighan pike practice of programming
2944 .], p. 23]
2945 demands: ``Don't belabor the obvious.''
2946 Hence, I simply removed all the comments in the following code excerpt:
2947 .VS
2948 context_replace(curfolder, folder); /* update current folder */
2949 seq_setcur(mp, mp->lowsel); /* update current message */
2950 seq_save(mp); /* synchronize message sequences */
2951 folder_free(mp); /* free folder/message structure */
2952 context_save(); /* save the context file */
2954 [...]
2956 int c; /* current character */
2957 char *cp; /* miscellaneous character pointer */
2959 [...]
2961 /* NUL-terminate the field */
2962 *cp = '\0';
2963 VE
2964 .Ci 426543622b377fc5d091455cba685e114b6df674
2965 .P
2966 The program code explains enough itself, already.
2969 .U3 "Names
2970 .P
2971 Kernighan and Pike suggest:
2972 ``Use active names for functions''.
2973 .[ [
2974 kernighan pike practice of programming
2975 .], p. 4]
2976 One application of this rule was the rename of
2977 .Fu check_charset()
2978 to
2979 .Fu is_native_charset() .
2980 .Ci 8d77b48284c58c135a6b2787e721597346ab056d
2981 The same change fixed a violation of ``Be accurate''
2982 .[ [
2983 kernighan pike practice of programming
2984 .], p. 4]
2985 as well.
2986 The code did not match the expectation the function suggested,
2987 as it, for whatever reason, only compared the first ten characters
2988 of the charset name.
2989 .P
2990 More important than using active names is using descriptive names.
2991 .VS
2992 m_unknown(in); /* the MAGIC invocation... */
2993 VE
2994 Renaming the obscure
2995 .Fu m_unknown()
2996 function was a delightful event, although it made the code less funny.
2997 .Ci 611d68d19204d7cbf5bd585391249cb5bafca846
2998 .P
2999 Magic numbers are generally considered bad style.
3000 Obviously, Kernighan and Pike agree:
3001 ``Give names to magic numbers''.
3002 .[ [
3003 kernighan pike practice of programming
3004 .], p. 19]
3005 One such change was naming the type of input \(en mbox or mail folder \(en
3006 to be scanned:
3007 .VS
3008 #define SCN_MBOX (-1)
3009 #define SCN_FOLD 0
3010 VE
3011 .Ci 7ffb36d28e517a6f3a10272056fc127592ab1c19
3012 .P
3013 The argument
3014 .Ar outnum
3015 of the function
3016 .Fu scan()
3017 in
3018 .Fn uip/scansbr.c
3019 defines the number of the message to be created.
3020 If no message is to be created, the argument is misused to transport
3021 program logic.
3022 This lead to obscure code.
3023 I improved the clarity of the code by introducing two variables:
3024 .VS
3025 int incing = (outnum > 0);
3026 int ismbox = (outnum != 0);
3027 VE
3028 They cover the magic values and are used for conditions.
3029 The variable
3030 .Ar outnum
3031 is only used when it holds an ordinary message number.
3032 .Ci b8b075c77be7794f3ae9ff0e8cedb12b48fd139f
3033 The clarity improvement of the change showed detours in the program logic
3034 of related code parts.
3035 Having the new variables with descriptive names, a more
3036 straight forward implementation became apparent.
3037 Before the code was clarified, the possibility to improve had not be seen.
3038 .Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723
3042 .H2 "Structural Rework
3043 .P
3044 Although the stylistic changes described up to here improve the
3045 readability of the source code, all of them are changes ``in the small''.
3046 Structural changes affect a much larger area.
3047 They are more difficult to do but lead to larger improvements,
3048 especially as they influence the outer shape of the tools as well.
3049 .P
3050 At the end of their chapter on style,
3051 Kernighan and Pike ask: ``But why worry about style?''
3052 .[ [
3053 kernighan pike practice of programming
3054 .], p. 28]
3055 Following are two examples of structural rework that show
3056 why style is important in the first place.
3059 .U3 "Rework of \f(CWanno\fP
3060 .P
3061 Until 2002,
3062 .Pn anno
3063 had six functional command line switches,
3064 .Sw -component
3065 and
3066 .Sw -text ,
3067 which have an argument each,
3068 and the two pairs of flags,
3069 .Sw -[no]date
3070 and
3071 .Sw -[no]inplace .
3072 Then Jon Steinhart introduced his attachment system.
3073 In need for more advanced annotation handling, he extended
3074 .Pn anno .
3075 He added five more switches:
3076 .Sw -draft ,
3077 .Sw -list ,
3078 .Sw -delete ,
3079 .Sw -append ,
3080 and
3081 .Sw -number ,
3082 the last one taking an argument.
3083 .Ci 7480dbc14bc90f2d872d434205c0784704213252
3084 Later,
3085 .Sw -[no]preserve
3086 was added.
3087 .Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f
3088 Then, the Synopsis section of the man page
3089 .Mp anno (1)
3090 read:
3091 .VS
3092 anno [+folder] [msgs] [-component field] [-inplace | -noinplace]
3093 [-date | -nodate] [-draft] [-append] [-list] [-delete]
3094 [-number [num|all]] [-preserve | -nopreserve] [-version]
3095 [-help] [-text body]
3096 VE
3097 .LP
3098 The implementation followed the same structure.
3099 Problems became visible when
3100 .Cl "anno -list -number 42
3101 worked on the current message instead on message number 42,
3102 and
3103 .Cl "anno -list -number l:5
3104 did not work on the last five messages but failed with the mysterious
3105 error message: ``anno: missing argument to -list''.
3106 Yet, the invocation matched the specification in the man page.
3107 There, the correct use of
3108 .Sw -number
3109 was defined as being
3110 .Cl "[-number [num|all]]
3111 and the textual description for the combination with
3112 .Sw -list
3113 read:
3114 .QS
3115 The
3116 .Sw -list
3117 option produces a listing of the field bodies for
3118 header fields with names matching the specified component,
3119 one per line. The listing is numbered, starting at 1, if the
3120 .Sw -number
3121 option is also used.
3122 .QE
3123 .LP
3124 The problem was manifold.
3125 The code required a numeric argument to the
3126 .Sw -number
3127 switch.
3128 If it was missing or non-numeric,
3129 .Pn anno
3130 aborted with an error message that had an off-by-one error,
3131 printing the switch one before the failing one.
3132 Semantically, the argument to the
3133 .Sw -number
3134 switch is only necessary in combination with
3135 .Sw -delete ,
3136 but not with
3137 .Sw -list .
3138 .P
3139 Trying to fix these problems on the surface would not have solved
3140 them truly, as they originate from a discrepance between the
3141 structure of the problem and the structure implemented in the program.
3142 Such structural differences can not be cured on the surface.
3143 They need to be solved by adjusting the structure of the implementation
3144 to the structure of the problem.
3145 .P
3146 In 2002, the new switches
3147 .Sw -list
3148 and
3149 .Sw -delete
3150 were added in the same way, the
3151 .Sw -number
3152 switch for instance had been added.
3153 Yet, they are of structural different type.
3154 Semantically,
3155 .Sw -list
3156 and
3157 .Sw -delete
3158 introduce modes of operation.
3159 Historically,
3160 .Pn anno
3161 had only one operation mode: adding header fields.
3162 With the extension it got two more modes:
3163 .\" XXX got
3164 listing and deleting header fields.
3165 The structure of the code changes did not pay respect to this
3166 fundamental change to
3167 .Pn anno 's
3168 behavior.
3169 Neither the implementation nor the documentation did clearly
3170 define them as being exclusive modes of operation.
3171 Having identified the problem, I solved it by putting structure into
3172 .Pn anno
3173 and its documentation.
3174 .Ci d54c8db8bdf01e8381890f7729bc0ef4a055ea11
3175 .P
3176 The difference is visible in both the code and the documentation.
3177 The following code excerpt:
3178 .VS
3179 int delete = -2; /* delete header element if set */
3180 int list = 0; /* list header elements if set */
3181 [...]
3182 case DELETESW: /* delete annotations */
3183 delete = 0;
3184 continue;
3185 case LISTSW: /* produce a listing */
3186 list = 1;
3187 continue;
3188 VE
3189 .LP
3190 was replaced by:
3191 .VS
3192 static enum { MODE_ADD, MODE_DEL, MODE_LIST } mode = MODE_ADD;
3193 [...]
3194 case DELETESW: /* delete annotations */
3195 mode = MODE_DEL;
3196 continue;
3197 case LISTSW: /* produce a listing */
3198 mode = MODE_LIST;
3199 continue;
3200 VE
3201 .LP
3202 The replacement code does not only reflect the problem's structure better,
3203 it is easier to understand as well.
3204 The same applies to the documentation.
3205 The man page was completely reorganized to propagate the same structure.
3206 This is visible in the Synopsis section:
3207 .VS
3208 anno [+folder] [msgs] [-component field] [-text body]
3209 [-append] [-date | -nodate] [-preserve | -nopreserve]
3210 [-Version] [-help]
3212 anno -delete [+folder] [msgs] [-component field] [-text
3213 body] [-number num | all ] [-preserve | -nopreserve]
3214 [-Version] [-help]
3216 anno -list [+folder] [msgs] [-component field] [-number]
3217 [-Version] [-help]
3218 VE
3219 .\" XXX think about explaining the -preserve rework?
3223 .U3 "Path Conversion
3224 .P
3225 Four kinds of path names can appear in MH:
3226 .LI 1
3227 Absolute Unix directory paths, like
3228 .Fn /etc/passwd .
3229 .LI 2
3230 Relative Unix directory paths, like
3231 .Fn ./foo/bar .
3232 .LI 3
3233 Absolute MH folder paths, like
3234 .Fn +friends/phil .
3235 .LI 4
3236 Relative MH folder paths, like
3237 .Fn @subfolder .
3238 .LP
3239 The last type, relative MH folder paths, are hardly documented.
3240 Nonetheless, they are useful for large mail storages.
3241 The current mail folder is specified as `\c
3242 .Fn @ ',
3243 just like the current directory is specified as `\c
3244 .Fn . '.
3245 .P
3246 To allow MH tools to understand all four notations,
3247 they need to convert between them.
3248 .\" XXX between?
3249 In nmh, these path name conversion functions were located in the files
3250 .Fn sbr/path.c
3251 (``return a pathname'') and
3252 .Fn sbr/m_maildir.c
3253 (``get the path for the mail directory'').
3254 The seven functions in the two files were documented with no more
3255 than two comments, which described obvious information.
3256 The function signatures were neither explaining:
3257 .VS
3258 char *path(char *, int);
3259 char *pluspath(char *);
3260 char *m_mailpath(char *);
3261 char *m_maildir(char *);
3262 VE
3263 .P
3264 My investigation provides the following description:
3265 .LI 1
3266 The second parameter of
3267 .Fu path()
3268 defines the type of path given as first parameter.
3269 Directory paths are converted to absolute directory paths.
3270 Folder paths are converted to absolute folder paths.
3271 Folder paths must not include a leading `\fL@\fP' character.
3272 Leading plus characters are preserved.
3273 The result is a pointer to newly allocated memory.
3274 .LI 2
3275 .Fu pluspath()
3276 is a convenience-wrapper to
3277 .Fu path() ,
3278 to convert folder paths only.
3279 This function can not be used for directory paths.
3280 An empty string parameter causes a buffer overflow.
3281 .LI 3
3282 .Fu m_mailpath()
3283 converts directory paths to absolute directory paths.
3284 The characters `\fL+\fP' or `\fL@\fP' at the beginning of the path name are
3285 treated literal, i.e. as the first character of a relative directory path.
3286 Hence, this function can not be used for folder paths.
3287 In any case, the result is an absolute directory path.
3288 The result is a pointer to newly allocated memory.
3289 .LI 4
3290 .Fu m_maildir()
3291 returns the parameter unchanged if it is an absolute directory path
3292 or begins with the entry `\fL.\fP' or `\fL..\fP'.
3293 All other strings are prepended with the current working directory.
3294 Hence, this functions can not be used for folder paths.
3295 The result is either an absolute directory path or a relative
3296 directory path, starting with a dot.
3297 In contrast to the other functions, the result is a pointer to
3298 static memory.
3299 .P
3300 The situation was obscure, irritating, error-prone, and non-orthogonal.
3301 No clear terminology was used to name the different kinds of path names.
3302 The first argument of
3303 .Fu m_mailpath() ,
3304 for instance, was named
3305 .Ar folder ,
3306 though
3307 .Fu m_mailpath()
3308 can not be used for MH folders.
3309 .P
3310 I reworked the path name conversion completely, introducing clarity.
3311 First of all, the terminology needed to be defined.
3312 A path name is either in the Unix domain, then it is called
3313 \fIdirectory path\fP, `dirpath' for short, or it is in the MH domain,
3314 then it is called \fIfolder path\fP, `folpath' for short.
3315 The two terms need to be used with strict distinction.
3316 Having a clear terminology is often an indicator of having understood
3317 the problem itself.
3318 Second, I exploited the concept of path type indicators.
3319 By requesting every path name to start with a clear type identifier,
3320 conversion between the types can be fully automated.
3321 Thus the tools can accept paths of any type from the user.
3322 Therefore, it was necessary to require relative directory paths to be
3323 prefixed with a dot character.
3324 In consequence, the dot character could no longer be an alias for the
3325 current message.
3326 .Ci cff0e16925e7edbd25b8b9d6d4fbdf03e0e60c01
3327 Third, I created three new functions to replace the previous mess:
3328 .LI 1
3329 .Fu expandfol()
3330 converts folder paths to absolute folder paths,
3331 without the leading plus character.
3332 Directory paths are simply passed through.
3333 This function is to be used for folder paths only, thus the name.
3334 The result is a pointer to static memory.
3335 .LI 2
3336 .Fu expanddir()
3337 converts directory paths to absolute directory paths.
3338 Folder paths are treated as relative directory paths.
3339 This function is to be used for directory paths only, thus the name.
3340 The result is a pointer to static memory.
3341 .LI 3
3342 .Fu toabsdir()
3343 converts any type of path to an absolute directory path.
3344 This is the function of choice for path conversion.
3345 Absolute directory paths are the most general representation of a
3346 path name.
3347 The result is a pointer to static memory.
3348 .P
3349 .\" XXX ueberfluessig?
3350 The new functions have names that indicate their use.
3351 Two of the functions convert relative to absolute path names of the
3352 same type.
3353 The third function converts any path name type to the most general one,
3354 the absolute directory path.
3355 All of the functions return pointers to static memory.
3356 All three functions are implemented in
3357 .Fn sbr/path.c .
3358 .Fn sbr/m_maildir.c
3359 is removed.
3360 .Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
3361 .P
3362 Along with the path conversion rework, I also replaced
3363 .Fu getfolder(FDEF)
3364 with
3365 .Fu getdeffol()
3366 and
3367 .Fu getfolder(FCUR)
3368 with
3369 .Fu getcurfol() ,
3370 which is only a convenience wrapper for
3371 .Fu expandfol("@") .
3372 This code was moved from
3373 .Fn sbr/getfolder.c
3374 to
3375 .Fn sbr/path.c .
3376 .Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
3377 .P
3378 The related function
3379 .Fu etcpath()
3380 was moved to
3381 .Fn sbr/path.c ,
3382 too
3383 .Ci b4c29794c12099556151d93a860ee51badae2e35 .
3384 Previously, it had been located in
3385 .Fn config/config.c ,
3386 for whatever reasons.
3387 .P
3388 .Fn sbr/path.c
3389 now contains all path handling code.
3390 .\" XXX naechste zeile weg?
3391 Only 173 lines of code were needed to replace the previous 252 lines.
3392 The readability of the code is highly improved.
3393 Additionally, each of the six exported and one static functions
3394 is introduced by an explaining comment.
3399 .H2 "Profile Reading
3400 .P
3401 The MH profile contains the configuration for the user-specific MH setup.
3402 MH tools read the profile right after starting up,
3403 as it contains the location of the user's mail storage
3404 and similar settings that influence the whole setup.
3405 Furthermore, the profile contains the default switches for the tools,
3406 hence, it must be read before the command line switches are processed.
3407 .P
3408 For historic reasons, some MH tools did not read the profile and context.
3409 Among them were
3410 .Pn post /\c
3411 .Pn spost ,
3412 .Pn mhmail ,
3413 and
3414 .Pn slocal .
3415 The reason why these tools ignored the profile were not clearly stated.
3416 During the discussion on the nmh-workers mailing list,
3417 David Levine posted an explanation, quoting John Romine:
3418 .[
3419 nmh-workers levine post profile
3420 .]
3421 .QS
3422 I asked John Romine and here's what he had to say, which
3423 agrees and provides an example that convinces me:
3424 .QS
3425 My take on this is that
3426 .Pn post
3427 should not be called by users directly, and it doesn't read the
3428 .Fn .mh_profile
3429 (only front-end UI programs read the profile).
3430 .QP
3431 For example, there can be contexts where
3432 .Pn post
3433 is called by a helper program (like `\c
3434 .Pn mhmail ')
3435 which may be run by a non-MH user.
3436 We don't want this to prompt the user to create an MH profile, etc.
3437 .QP
3438 My suggestion would be to have
3439 .Pn send
3440 pass a (hidden) `\c
3441 .Sw -fileproc
3442 .Ar proc '
3443 option to
3444 .Pn post
3445 if needed.
3446 You could also
3447 use an environment variable (I think
3448 .Pn send /\c
3449 .Pn whatnow
3450 do this).
3451 .QE
3452 I think that's the way to go.
3453 My personal preference is to use a command line option,
3454 not an environment variable.
3455 .QE
3456 .P
3457 To solve the problem of
3458 .Pn post
3459 not honoring the
3460 .Pe fileproc
3461 profile entry,
3462 the community roughly agreed that a switch
3463 .Sw -fileproc
3464 should be added to
3465 .Pn post
3466 to be able to pass a different fileproc.
3467 I strongly disagree with this approach because it does not solve
3468 the problem; it only removes a single symptom.
3469 The problem is that
3470 .Pn post
3471 does not behave as expected.
3472 But all programs should behave as expected.
3473 Clear and simple concepts are a precondition for this.
3474 Hence, the real solution is having all MH tools read the profile.
3475 .P
3476 The problem has a further aspect.
3477 It mainly originates in
3478 .Pn mhmail .
3479 .Pn mhmail
3480 was intended to be a replacement for
3481 .Pn mailx
3482 on systems with MH installations.
3483 .Pn mhmail
3484 should have been able to use just like
3485 .Pn mailx ,
3486 but sending the message via MH's
3487 .Pn post
3488 instead of
3489 .Pn sendmail .
3490 Using
3491 .Pn mhmail
3492 should not be influenced by the question whether the user had
3493 MH set up for himself or not.
3494 .Pn mhmail
3495 did not read the profile as this requests the user to set up MH
3496 if not done yet.
3497 As
3498 .Pn mhmail
3499 used
3500 .Pn post ,
3501 .Pn post
3502 could not read the profile neither.
3503 This is the reason why
3504 .Pn post
3505 does not read the profile.
3506 This is the reason for the actual problem.
3507 It was not much of a problem because
3508 .Pn post
3509 was not intended to be used by users directly.
3510 .Pn send
3511 is the interactive front-end to
3512 .Pn post .
3513 .Pn send
3514 read the profile and passed all relevant values on the command line to
3515 .Pn post
3516 \(en an awkward solution.
3517 .P
3518 The important insight is that
3519 .Pn mhmail
3520 is no true MH tool.
3521 The concepts broke because this outlandish tool was treated as any other
3522 MH tool.
3523 Instead it should have been treated accordingly to its foreign style.
3524 The solution is not to prevent the tools reading the profile but
3525 to instruct them reading a different profile.
3526 .Pn mhmail
3527 could have set up a well-defined profile and caused all MH tools
3528 in the session to use it by exporting an environment variable.
3529 With this approach, no special cases would have been introduced,
3530 no surprises would have been caused.
3531 By writing a clean-profile-wrapper, the concept could have been
3532 generalized orthogonally to the whole MH tool chest.
3533 Then Rose's motivation behind the decision that
3534 .Pn post
3535 ignores the profile, as quoted by Jeffrey Honig,
3536 would have become possible:
3537 .[
3538 nmh-workers post profile
3539 .]
3540 .QS
3541 when you run mh commands in a script, you want all the defaults to be
3542 what the man page says.
3543 when you run a command by hand, then you want your own defaults...
3544 .QE
3545 .LP
3546 Yet, I consider this explanation shortsighted.
3547 We should rather regard theses two cases as just two different MH setups,
3548 based on two different profiles.
3549 Mapping such problems on the concepts of switching between different
3550 profiles, solves them once for all.
3551 .P
3552 In mmh, the wish to have
3553 .Pn mhmail
3554 as a replacement for
3555 .Pn mailx
3556 is considered obsolete.
3557 Mmh's
3558 .Pn mhmail
3559 does no longer cover this use-case.
3560 Currently,
3561 .Pn mhmail
3562 is in a transition state.
3563 .Ci 32d4f9daaa70519be3072479232ff7be0500d009
3564 It may become a front-end to
3565 .Pn comp ,
3566 which provides an interface more convenient in some cases.
3567 In this case,
3568 .Pn mhmail
3569 will become an ordinary MH tool, reading the profile.
3570 If, however, this idea will not convince, then
3571 .Pn mhmail
3572 will be removed.
3573 .P
3574 Every program in the mmh tool chest reads the profile.
3575 The only exception is
3576 .Pn slocal ,
3577 which is not considered part of the mmh tool chest.
3578 This MDA is only distributed with mmh, currently.
3579 Mmh has no
3580 .Pn post
3581 program, but
3582 .Pn spost ,
3583 which now reads the profile.
3584 .Ci 3e017a7abbdf69bf0dff7a4073275961eda1ded8
3585 With this change,
3586 .Pn send
3587 and
3588 .Pn spost
3589 can be considered to be merged.
3590 .Pn spost
3591 is only invoked directly by the to-be-changed
3592 .Pn mhmail
3593 implementation and by
3594 .Pn rcvdist ,
3595 which will require rework.
3596 .P
3597 The
3598 .Fu context_foil()
3599 function to pretend to have read an empty profile was removed.
3600 .Ci 68af8da96bea87a5541988870130b6209ce396f6
3601 All mmh tools read the profile.
3605 .H2 "Standard Libraries
3606 .P
3607 MH is one decade older than the POSIX and ANSI C standards.
3608 Hence, MH included own implementations of functions
3609 that are standardized and thus widely available today,
3610 but were not back then.
3611 Today, twenty years after the POSIX and ANSI C were published,
3612 developers can expect systems to comply with these standards.
3613 In consequence, MH-specific replacements for standard functions
3614 can and should be dropped.
3615 Kernighan and Pike advise: ``Use standard libraries.''
3616 .[ [
3617 kernighan pike practice of programming
3618 .], p. 196]
3619 Actually, MH had followed this advice in history,
3620 but it had not adjusted to the changes in this field.
3621 The
3622 .Fu snprintf()
3623 function, for instance, was standardized with C99 and is available
3624 almost everywhere because of its high usefulness.
3625 The project's own implementation of
3626 .Fu snprintf()
3627 was dropped in March 2012 in favor for using the one of the
3628 standard library.
3629 .Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32
3630 Such decisions limit the portability of mmh
3631 if systems do not support these standardized and widespread functions.
3632 This compromise is made because mmh focuses on the future.
3633 .P
3634 .\" XXX kuerzen und mit dem naechsten Absatz vereinen
3635 I am still in my twenties and my C and Unix experience comprises
3636 only half a dozen years.
3637 Hence, I need to learn about the history in retrospective.
3638 I have not used those ancient constructs myself.
3639 I have not suffered from their incompatibilities.
3640 I have not longed for standardization.
3641 All my programming experience is from a time when ANSI C and POSIX
3642 were well established already.
3643 I have only read a lot of books about the (good) old times.
3644 This puts me in a difficult position when working with old code.
3645 I need to freshly acquire knowledge about old code constructs and ancient
3646 programming styles, whereas older programmers know these things by
3647 heart from their own experience.
3648 .P
3649 Being aware of the situation, I rather let people with more historic
3650 experience replace ancient code constructs with standardized ones.
3651 Lyndon Nerenberg covered large parts of this task for the nmh project.
3652 He converted project-specific functions to POSIX replacements,
3653 also removing the conditionals compilation of now standardized features.
3654 Ken Hornstein and David Levine had their part in the work, too.
3655 Often, I only needed to pull over changes from nmh into mmh.
3656 These changes include many commits; these are among them:
3657 .Ci 768b5edd9623b7238e12ec8dfc409b82a1ed9e2d
3658 .Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 .
3659 .P
3660 During my own work, I tidied up the \fIMH standard library\fP,
3661 .Fn libmh.a ,
3662 which is located in the
3663 .Fn sbr
3664 (``subroutines'') directory in the source tree.
3665 The MH library includes functions that mmh tools usually need.
3666 Among them are MH-specific functions for profile, context, sequence,
3667 and folder handling, but as well
3668 MH-independent functions, such as auxiliary string functions,
3669 portability interfaces and error-checking wrappers for critical
3670 functions of the standard library.
3671 .P
3672 I have replaced the
3673 .Fu atooi()
3674 function with calls to
3675 .Fu strtoul()
3676 with the third parameter, the base, set to eight.
3677 .Fu strtoul()
3678 is part of C89 and thus considered safe to use.
3679 .Ci c490c51b3c0f8871b6953bd0c74551404f840a74
3680 .P
3681 I did remove project-included fallback implementations of
3682 .Fu memmove()
3683 and
3684 .Fu strerror() ,
3685 although Peter Maydell had re-included them into nmh in 2008
3686 to support SunOS 4.
3687 Nevertheless, these functions are part of ANSI C.
3688 Systems that do not even provide full ANSI C support should not
3689 put a load on mmh.
3690 .Ci b067ff5c465a5d243ce5a19e562085a9a1a97215
3691 .P
3692 The
3693 .Fu copy()
3694 function copies the string in parameter one to the location in
3695 parameter two.
3696 In contrast to
3697 .Fu strcpy() ,
3698 it returns a pointer to the terminating null-byte in the destination area.
3699 The code was adjusted to replace
3700 .Fu copy()
3701 with
3702 .Fu strcpy() ,
3703 except within
3704 .Fu concat() ,
3705 where
3706 .Fu copy()
3707 was more convenient.
3708 Therefore, the definition of
3709 .Fu copy()
3710 was moved into the source file of
3711 .Fu concat()
3712 and its visibility is now limited to it.
3713 .Ci 552fd7253e5ee9e554c5c7a8248a6322aa4363bb
3714 .P
3715 The function
3716 .Fu r1bindex()
3717 had been a generalized version of
3718 .Fu basename()
3719 with minor differences.
3720 As all calls to
3721 .Fu r1bindex()
3722 had the slash (`/') as delimiter anyway,
3723 replacing
3724 .Fu r1bindex()
3725 with the more specific and better-named function
3726 .Fu basename()
3727 became desirable.
3728 Unfortunately, many of the 54 calls to
3729 .Fu r1bindex()
3730 depended on a special behavior,
3731 which differed from the POSIX specification for
3732 .Fu basename() .
3733 Hence,
3734 .Fu r1bindex()
3735 was kept but renamed to
3736 .Fu mhbasename() ,
3737 fixing the delimiter to the slash.
3738 .Ci 240013872c392fe644bd4f79382d9f5314b4ea60
3739 For possible uses of
3740 .Fu r1bindex()
3741 with a different delimiter,
3742 the ANSI C function
3743 .Fu strrchr()
3744 provides the core functionality.
3745 .P
3746 The
3747 .Fu ssequal()
3748 function \(en apparently for ``substring equal'' \(en
3749 was renamed to
3750 .Fu isprefix() ,
3751 because this is what it actually checks.
3752 .Ci c20b4fa14515c7ab388ce35411d89a7a92300711
3753 Its source file had included the following comments, no joke.
3754 .VS
3755 /*
3756 * THIS CODE DOES NOT WORK AS ADVERTISED.
3757 * It is actually checking if s1 is a PREFIX of s2.
3758 * All calls to this function need to be checked to see
3759 * if that needs to be changed. Prefix checking is cheaper, so
3760 * should be kept if it's sufficient.
3761 */
3763 /*
3764 * Check if s1 is a substring of s2.
3765 * If yes, then return 1, else return 0.
3766 */
3767 VE
3768 Two months later, it was completely removed by replacing it with
3769 .Fu strncmp() .
3770 .Ci b0b1dd37ff515578cf7cba51625189eb34a196cb
3776 .H2 "User Data Locations
3777 .P
3778 In nmh, a personal setup consists of the MH profile and the MH directory.
3779 The profile is a file named
3780 .Fn \&.mh_profile
3781 in the user's home directory.
3782 It contains the static configuration.
3783 It also contains the location of the MH directory in the profile entry
3784 .Pe Path .
3785 The MH directory contains the mail storage and is the first
3786 place to search for personal forms, scan formats, and similar
3787 configuration files.
3788 The location of the MH directory can be chosen freely by the user.
3789 The default and usual name is a directory named
3790 .Fn Mail
3791 in the home directory.
3792 .P
3793 The way MH data is splitted between profile and MH directory is a legacy.
3794 It is only sensible in a situation where the profile is the only
3795 configuration file.
3796 Why else should the mail storage and the configuration files be intermixed?
3797 They are different kinds of data:
3798 The data to be operated on and the configuration to change how
3799 tools operate.
3800 .\" XXX bad ... inapropriate?
3801 Splitting the configuration between the profile and the MH directory
3802 is bad.
3803 Merging the mail storage and the configuration in one directory is bad
3804 as well.
3805 As the mail storage and the configuration were not separated sensibly
3806 in the first place, I did it now.
3807 .P
3808 Personal mmh data is grouped by type, resulting in two distinct parts:
3809 the mail storage and the configuration.
3810 In mmh, the mail storage directory still contains all the messages,
3811 but, in exception of public sequences files, nothing else.
3812 In difference to nmh, the auxiliary configuration files are no longer
3813 located there.
3814 Therefore, the directory is no longer called the user's \fIMH directory\fP
3815 but his \fImail storage\fP.
3816 Its location is still user-chosen, with the default name
3817 .Fn Mail ,
3818 in the user's home directory.
3819 In mmh, the configuration is grouped together in
3820 the hidden directory
3821 .Fn \&.mmh
3822 in the user's home directory.
3823 This \fImmh directory\fP contains the context file, personal forms,
3824 scan formats, and the like, but also the user's profile, now named
3825 .Fn profile .
3826 The location of the profile is no longer fixed to
3827 .Fn $HOME/.mh_profile
3828 but to
3829 .Fn $HOME/.mmh/profile .
3830 Having both the file
3831 .Fn $HOME/.mh_profile
3832 and the configuration directory
3833 .Fn $HOME/.mmh
3834 appeared to be inconsistent.
3835 The approach chosen for mmh is consistent, simple, and familiar to
3836 Unix users.
3837 .Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
3838 .P
3839 MH allows users to have multiple MH setups.
3840 Therefore, it is necessary to select a different profile.
3841 The profile is the single entry point to access the rest of a
3842 personal MH setup.
3843 In nmh, the environment variable
3844 .Ev MH
3845 could be used to specifiy a different profile.
3846 To operate in the same MH setup with a separate context,
3847 the
3848 .Ev MHCONTEXT
3849 environment variable could be used.
3850 This allows having own current folders and current messages in
3851 each terminal, for instance.
3852 In mmh, three environment variables are used.
3853 .Ev MMH
3854 overrides the default location of the mmh directory (\c
3855 .Fn .mmh ).
3856 .Ev MMHP
3857 and
3858 .Ev MMHC
3859 override the paths to the profile and context files, respectively.
3860 This approach allows the set of personal configuration files to be chosen
3861 independently from the profile, context, and mail storage.
3862 .Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
3863 .P
3864 The separation of the files by type is sensible and convenient.
3865 The new approach has no functional disadvantages,
3866 as every setup I can imagine can be implemented with both approaches,
3867 possibly even easier with the new approach.
3868 The main achievement of the change is the clear and sensible split
3869 between mail storage and configuration.
3875 .H2 "Modularization
3876 .P
3877 The source code of the mmh tools is located in the
3878 .Fn uip
3879 (``user interface programs'') directory.
3880 Each tool has a source file with the name of the command.
3881 For example,
3882 .Pn rmm
3883 is built from
3884 .Fn uip/rmm.c .
3885 Some source files are used for multiple programs.
3886 For example
3887 .Fn uip/scansbr.c
3888 is used for both
3889 .Pn scan
3890 and
3891 .Pn inc .
3892 In nmh, 49 tools were built from 76 source files.
3893 This is a ratio of 1.6 source files per program.
3894 32 programs depended on multiple source files;
3895 17 programs depended on one source file only.
3896 In mmh, 39 tools are built from 51 source files.
3897 This is a ratio of 1.3 source files per program.
3898 18 programs depend on multiple source files;
3899 21 programs depend on one source file only.
3900 (These numbers and the ones in the following text ignore the MH library
3901 as well as shell scripts and multiple names for the same program.)
3902 .\" XXX graph
3903 .P
3904 Splitting the source code of a large program into multiple files can
3905 increase the readability of its source code.
3906 .\" XXX however?
3907 Most of the mmh tools are simple and straight-forward programs.
3908 With the exception of the MIME handling tools,
3909 .Pn pick
3910 is the largest tool.
3911 It contains 1\|037 lines of source code, excluding the MH library.
3912 Only the MIME handling tools (\c
3913 .Pn mhbuild ,
3914 .Pn mhstore ,
3915 .Pn show ,
3916 etc.)
3917 are larger.
3918 Splitting programs with less than 1\|000 lines of code into multiple
3919 source files seldom leads to better readability.
3920 For such tools, splitting makes sense
3921 when parts of the code are reused in other programs,
3922 and the reused code fragment is (1) not general enough
3923 for including it in the MH library
3924 or (2) has dependencies on a library that only few programs need.
3925 .Fn uip/packsbr.c ,
3926 for instance, provides the core program logic for the
3927 .Pn packf
3928 and
3929 .Pn rcvpack
3930 programs.
3931 .Fn uip/packf.c
3932 and
3933 .Fn uip/rcvpack.c
3934 mainly wrap the core function appropriately.
3935 No other tools use the folder packing functions.
3936 As another example,
3937 .Fn uip/termsbr.c
3938 provides termcap support, which requires linking with a termcap or
3939 curses library.
3940 Including
3941 .Fn uip/termsbr.c
3942 into the MH library would require every program to be linked with
3943 termcap or curses, although only few of the programs require it.
3944 .P
3945 The task of MIME handling is complex enough that splitting its code
3946 into multiple source files improves the readability.
3947 The program
3948 .Pn mhstore ,
3949 for instance, is compiled out of seven source files with 2\|500
3950 lines of code in summary.
3951 The main code file
3952 .Fn uip/mhstore.c
3953 consists of 800 lines; the other 1\|700 lines of code are reused in
3954 other MIME handling tools.
3955 It seems to be worthwhile to bundle the generic MIME handling code into
3956 a MH-MIME library, as a companion to the MH standard library.
3957 This is left open for the future.
3958 .P
3959 The work already accomplished focussed on the non-MIME tools.
3960 The amount of code compiled into each program was reduced.
3961 This eases the understanding of the code base.
3962 In nmh,
3963 .Pn comp
3964 was built from six source files:
3965 .Fn comp.c ,
3966 .Fn whatnowproc.c ,
3967 .Fn whatnowsbr.c ,
3968 .Fn sendsbr.c ,
3969 .Fn annosbr.c ,
3970 and
3971 .Fn distsbr.c .
3972 In mmh, it builds from only two:
3973 .Fn comp.c
3974 and
3975 .Fn whatnowproc.c .
3976 In nmh's
3977 .Pn comp ,
3978 the core function of
3979 .Pn whatnow ,
3980 .Pn send ,
3981 and
3982 .Pn anno
3983 were compiled into
3984 .Pn comp .
3985 This saved the need to execute these programs with
3986 .Fu fork()
3987 and
3988 .Fu exec() ,
3989 two expensive system calls.
3990 Whereas this approach improved the time performance,
3991 it interwove the source code.
3992 Core functionalities were not encapsulated into programs but into
3993 function, which were then wrapped by programs.
3994 For example,
3995 .Fn uip/annosbr.c
3996 included the function
3997 .Fu annotate() .
3998 Each program that wanted to annotate messages, included the source file
3999 .Fn uip/annosbr.c
4000 and called
4001 .Fu annotate() .
4002 Because the function
4003 .Fu annotate()
4004 was used like the tool
4005 .Pn anno ,
4006 it had seven parameters, reflecting the command line switches of the tool.
4007 When another pair of command line switches was added to
4008 .Pn anno ,
4009 a rather ugly hack was implemented to avoid adding another parameter
4010 to the function.
4011 .Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f
4012 .P
4013 Separation simplifies the understanding of program code
4014 because the area influenced by any particular statement is smaller.
4015 The separating on the program-level is more strict than the separation
4016 on the function level.
4017 In mmh, the relevant code of
4018 .Pn comp
4019 comprises the two files
4020 .Fn uip/comp.c
4021 and
4022 .Fn uip/whatnowproc.c ,
4023 together 210 lines of code.
4024 In nmh,
4025 .Pn comp
4026 comprises six files with 2\|450 lines.
4027 Not all of the code in these six files was actually used by
4028 .Pn comp ,
4029 but the code reader needed to read all of the code first to know which
4030 parts were used.
4031 .P
4032 As I have read a lot in the code base during the last two years,
4033 I learned about the easy and the difficult parts.
4034 Code is easy to understand if the influenced code area is small
4035 and its boundaries are strictly defined.
4036 Furthermore, the code needs to solve the problem in a straight-forward way.
4037 .P
4038 .\" XXX move this paragraph somewhere else?
4039 Reading
4040 .Pn rmm 's
4041 source code in
4042 .Fn uip/rmm.c
4043 is my recommendation for a beginner's entry point into the code base of nmh.
4044 The reasons are that the task of
4045 .Pn rmm
4046 is straight forward and it consists of one small source code file only,
4047 yet its source includes code constructs typical for MH tools.
4048 With the introduction of the trash folder in mmh,
4049 .Pn rmm
4050 became a bit more complex, because it invokes
4051 .Pn refile .
4052 Still, it is a good example for a simple tool with clear sources.
4053 .P
4054 Understanding
4055 .Pn comp
4056 .\" XXX kate fragen: more vs. as much
4057 requires to read 210 lines of code in mmh, but ten times more in nmh.
4058 Due to the aforementioned hack in
4059 .Pn anno
4060 to save the additional parameter, information passed through the program's
4061 source base in obscure ways.
4062 Thus, understanding
4063 .Pn comp ,
4064 required understanding the inner workings of
4065 .Fn uip/annosbr.c
4066 first.
4067 To be sure to fully understand a program, its whole source code needs
4068 to be examined.
4069 Not doing so is a leap of faith, assuming that the developers
4070 have avoided obscure programming techniques.
4071 By separating the tools on the program-level, the boundaries are
4072 clearly visible and technically enforced.
4073 The interfaces are calls to
4074 .Fu exec()
4075 rather than arbitrary function calls.
4076 .P
4077 But the real problem is another:
4078 Nmh violates the golden ``one tool, one job'' rule of the Unix philosophy.
4079 .\" XXX ref
4080 Understanding
4081 .Pn comp
4082 requires understanding
4083 .Fn uip/annosbr.c
4084 and
4085 .Fn uip/sendsbr.c
4086 because
4087 .Pn comp
4088 does annotate and send messages.
4089 In nmh, there surely exists the tool
4090 .Pn send ,
4091 which does mainly send messages.
4092 But
4093 .Pn comp
4094 and
4095 .Pn repl
4096 and
4097 .Pn forw
4098 and
4099 .Pn dist
4100 and
4101 .Pn whatnow
4102 and
4103 .Pn viamail ,
4104 they all (!) have the same message sending function included, as well.
4105 In result,
4106 .Pn comp
4107 sends messages without using
4108 .Pn send .
4109 The situation is the same as if
4110 .Pn grep
4111 would page without
4112 .Pn more
4113 just because both programs are part of the same code base.
4114 .P
4115 The clear separation on the surface \(en the tool chest approach \(en
4116 is violated on the level below.
4117 This violation is for the sake of time performance.
4118 On systems where
4119 .Fu fork()
4120 and
4121 .Fu exec()
4122 are expensive, the quicker response might be noticable.
4123 In the old times, sacrificing readability and conceptional beauty for
4124 speed might even have been a must to prevent MH from being unusably slow.
4125 Whatever the reasons had been, today they are gone.
4126 No longer should we sacrifice readability or conceptional beauty.
4127 No longer should we violate the Unix philosophy's ``one tool, one job''
4128 guideline.
4129 .\" XXX ref
4130 No longer should we keep speed improvements that became unnecessary.
4131 .P
4132 Therefore, mmh's
4133 .Pn comp
4134 does no longer send messages.
4135 In mmh, different jobs are divided among separate programs that
4136 invoke each other as needed.
4137 In consequence,
4138 .Pn comp
4139 invokes
4140 .Pn whatnow
4141 which thereafter invokes
4142 .Pn send .
4143 .Ci 3df5ab3c116e6d4a2fb4bb5cc9dfc5f781825815
4144 .Ci c73c00bfccd22ec77e9593f47462aeca4a8cd9c0
4145 The clear separation on the surface is maintained on the level below.
4146 Human users and the tools use the same interface \(en
4147 annotations, for example, are made by invoking
4148 .Pn anno ,
4149 no matter if requested by programs or by human beings.
4150 .Ci 469a4163c2a1a43731d412eaa5d9cae7d670c48b
4151 .Ci aed384169af5204b8002d06e7a22f89197963d2d
4152 .Ci 3caf9e298a8861729ca8b8a84f57022b6f3ea742
4153 The decrease of tools built from multiple source files and thus
4154 the decrease of
4155 .Fn uip/*sbr.c
4156 files confirm the improvement.
4157 .Ci 9e6d91313f01c96b4058d6bf419a8ca9a207bc33
4158 .ci 81744a46ac9f845d6c2b9908074d269275178d2e
4159 .Ci f0f858069d21111f0dbea510044593f89c9b0829
4160 .Ci 0503a6e9be34f24858b55b555a5c948182b9f24b
4161 .Ci 27826f9353e0f0b04590b7d0f8f83e60462b90f0
4162 .Ci d1da1f94ce62160aebb30df4063ccbc53768656b
4163 .Ci c42222869e318fff5dec395eca3e776db3075455
4164 .P
4165 .\" XXX move this paragraph up somewhere
4166 One disadvantage needs to be taken with this change:
4167 The compiler can no longer check the integrity of the interfaces.
4168 By changing the command line interfaces of tools, it is
4169 the developer's job to adjust the invocations of these tools as well.
4170 As this is a manual task and regression tests, which could detect such
4171 problems, are not available yet, it is prone to errors.
4172 These errors will not be detected at compile time but at run time.
4173 Installing regression tests is a pending task.
4174 In the best case, a uniform way of invoking tools from other tools
4175 can be developed to allow automated testing at compile time.
4178 .ig
4179 XXX consider writing about mhl vs. mhlproc
4181 sbr/showfile.c
4183 23 /*
4184 24 ** If you have your lproc listed as "mhl",
4185 25 ** then really invoked the mhlproc instead
4186 26 ** (which is usually mhl anyway).
4187 27 */
4189 Sat Nov 24 19:09:14 1984 /mtr (agent: Marshall Rose) <uci@udel-dewey>
4191 sbr/showfile.c: if lproc is "mhl", use mhlproc for consistency
4192 (Actually, user should use "lproc: show", "showproc: mhl".)
4193 ..