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