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