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