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