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