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