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