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