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