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