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