# HG changeset patch # User markus schnalke # Date 1339796278 -7200 # Node ID 093ccf39a45e4c991e0778023cb178646bb947ab # Parent e6f95015ba614657c3182f42beecfcaac873bc7f Write text about removal of switches; Included the grap figure. diff -r e6f95015ba61 -r 093ccf39a45e ch03.roff --- a/ch03.roff Fri Jun 15 21:43:04 2012 +0200 +++ b/ch03.roff Fri Jun 15 23:37:58 2012 +0200 @@ -936,11 +936,302 @@ -.H2 "Removal of switches +.H2 "Removal of Switches .P +The command line switches of MH tools follow the X Window style. +They are words, introduced by a single dash. +For example: +.Cl "-truncate" . +Every program in mmh has two generic switches: +.Sw -help , +to print a short message on how to use the program, and +.Sw -Version , +to tell what version of mmh the program belongs to. +.P +Switches change the behavior of programs. +Programs that do one thing in one way require no switches. +In most cases, doing something in exactly one way is too limiting. +If it is basically the same task to accomplish, but it should be done +in various ways, switches are a good approach to alter the behavior +of a program. +Changing the behavior of programs provides flexibility and customization +to users, but in the same way it complicates the code, documentation and +usage of the program. +Therefore, the number of switches should be kept small. +A small set of well-chosen switches does no harm. +But usually, the number of switches increases over time. +Already in 1985, Rose and Romine have identified this as a major +problem of MH: +.[ [ +rose romine real work +.], p. 12] +.sp +.QP +A complaint often heard about systems which undergo substantial development +by many people over a number of years, is that more and more options are +introduced which add little to the functionality but greatly increase the +amount of information a user needs to know in order to get useful work done. +This is usually referred to as creeping featurism. +.QP +Unfortunately MH, having undergone six years of off-and-on development by +ten or so well-meaning programmers (the present authors included), +suffers mightily from this. +.sp +.P +Adding new switches only reluctantly is one part of the counter-action, +the other is removing hardly used switches. +Now that there are lots of switches already implemented, +removing some of them is more important. +Removing existing functionality is always difficult because it +breaks programs that use these functions. +Also, for every obsolete feature, there'll always be someone who still +uses it and thus opposes its removal. +This puts the developer into the position, +where sensible improvements to style are regarded as destructive acts. +Yet, living with the featurism is far worse, in my eyes. +Future needs will demand adding new features, +worsening the situation more and more. +Rose and Romine added in a footnote, +``[...] +.Pn send +will no doubt acquire an endless number of switches in the years to come.'' +Although clearly humorous, the comment displays the nature of +the problem. +Though refusing to add any new switches would encounter the problem +at its root, it is not practical. +But removing obsolete switches is an effective approach to deal with the +problem. +Working on an experimental branch, +eased this work because I had not to offend users. +.P +Rose and Romine counted 24 visible and 9 more hidden switches for +.Pn send . +At the beginning of mmh, it were 32 visible and 12 hidden ones. +At the time of writing, mmh's +.Pn send +has 7 visible switches and 1 hidden switch. +(In each of the examples, the two generic help and version switches +are included.) +.P +Figure XXX +.\" XXX Ref +displays the number of switches for each of the tools that was not +removed from or newly added to mmh. +Both, visible and hidden switches, were counted, but +not the generic help and version switches. +Whereas in the beginning of the project, the average tool had 11 switches, +now it has no more than 5 \(en only half as many. +If the `no' switches and similar inverse variant are folded onto +their counter-parts, the numbers are 8 in pre-mmh to 4 now. +The total number of functional switches in mmh dropped from 465 +to 234. +.KS +.in 1c +.so input/switches.grap +.KE +.P +A part of the switches vanished after functions were removed. +This was the case for network mail transfer, for instance. +Sometimes the work flow was the other way: +The trying to reduce the number of switches suggested the removal of +functions. +.U3 "Draft Folder Facility +.P +A change early in the project was the completely transition from +the single draft message to the draft folder facility. +The draft folder facility was introduced in the mid-Eighties. +(Rose and Romine called it a ``relatively new feature'' +.[ +rose romine real work +.] +in 1985.) +Since then, the facility had existed but had remained deactive by default. +The default activation and the related rework of the tools made it +possible to remove the +.Sw -[no]draftfolder , +and +.Sw -draftmessage +switches from +.Pn comp , +.Pn repl , +.Pn forw , +.Pn dist , +.Pn whatnow , +and +.Pn send . +The only flexibility removed is having multiple draft folders +within one profile. +I consider this only a theoretical setup. +In the same go, the +.Sw -draft +switch of +.Pn anno , +.Pn refile , +and +.Pn send +was removed. +The special-casing of `the' draft message became irrelevant after +the rework of the draft system. +(See Sec. XXX.) + +.U3 "Inplace +.P +.Pn anno +had the switches +.Sw -[no]inplace +to either annotate the message inplace and thus preserve hard links, +or annotate a copy to replace the original message, breaking hard links. +Following the assumption that linked messages are the same message, +and annotating it should not break the link, the +.Sw -[no]inplace +switches were removed and the previous default +.Sw -inplace +was made the only behavior. +The +.Sw -[no]inplace +switches of +.Pn repl , +.Pn forw , +and +.Pn dist +could be removed, too, as they were simply passed through to +.Pn anno . +.P +.Pn burst +also had +.Sw -[no]inplace +switches, but they had different meaning, as written in nmh's +.Mp burst(1) +man page: +.sp +.QP +If -noinplace is given, each digest is preserved, no table +of contents is produced, and the messages contained within +the digest are placed at the end of the folder. Other messages +are not tampered with in any way. +.sp +.P +With +.Sw -inplace , +the digest had been replaced by the table of contents (i.e. the +introduction text) and the bursted messages were placed right +after this message, renumbering all following messages. +Also, any trailing text of the digest will be lost, though, +in practice, it usually consists of an end-of-digest marker only. +The decision to drop the +.Sw -inplace +behavior was supported by the complexity and possible data loss +it introduced. +.Sw -noinplace +was the default behavior already and is the chosen behavior now. + +.U3 "mbox and MMDF +.P +packf: file mbox mmdf +rcvpack: mbox mmdf + + +.ig + +ap: width +dp: width +burst: [no]quiet +flist: [no]total +folder: [no]header + +comp: file +dist: file(msh) +forw: filter, [no]mime, [no]dashstuffing(mhl) +repl: [no]format/filter width + +mhmail: resent queued +inc: snoop, (pop) +mhbuild: [no]check, [no]ebcdicsafe, [no]headers, [no]list, [no]realsize + [no]rfc934mode, [no]contentid (caching) +mhlist: [no]check [no]headers [no]realsize (caching) +mhstore: [no]check [no]verbose (caching) + +scan: [no]clear [no]header [no]reverse + +mhl: [no]bell [no]clear [no]faceproc folder [no]moreproc length sleep + [no]dashstuffing(forw) digest list volume number issue number +mhshow: [no]check [no]pause [no]serialonly (caching) [no]moreproc + length width + +prompter: erase kill [no]doteof + +refile: [no]preserve [no]unlink [no]rmmproc + +send: filter [no]format [no]forward [no]mime [no]msgid + [no]push split [no]unique (sasl) width snoop [no]dashstuffing + attach attachformat +whatnow: (noedit) attach + +slocal: [no]suppressdups + +sortm: subject + +spost: [no]filter [no]format [no]remove [no]backup width [no]push idanno + [no]check(whom) whom(whom) + +whom: ??? + + +(pop) host, port, user, [no]pack, proxy +(smtp) mail saml send soml client server user port +(sasl) sasl, saslmech +(tls) +(caching) rcache wcache + +noedit +nowhatnowproc + + +format -> form + +version -> Version + +.. + +.ig + +.P +To ease typing, the switches can be abbreviated as much as the remaining +prefix remains unambiguous. +If in our example no other switch would start with the letter `t', then +.Cl "-truncate" , +.Cl "-trunc" , +.Cl "-tr" , +and +.Cl "-t +would all be the same. +As a result, switches can neither be grouped (as in +.Cl "ls -ltr" ) +nor can switch arguments be appended directly to the switch (as in +.Cl "sendmail -q30m" ). +.P +Many switches have negating counter-parts, which start with `no'. +For example +.Cl "-notruncate +inverts the +.Cl "-truncate +switch. +They exist to undo the effect of default switches in the profile. +If the user has chosen to change the default behavior of some tool +by adding a default switch to the profile, +he can still undo this change in behavior by specifiying the inverse +switch on the command line. +.P +In the best case, all switches are unambiguous on the first character, +or on the three-letter prefix for the `no' variants. +Reducing switch prefix collisions, shortens the necessary prefix lenght +the user must type. +Having less switches helps best. + +.. .H1 "Modernizing