1.1 --- a/ch03.roff	Fri Jun 15 21:43:04 2012 +0200
     1.2 +++ b/ch03.roff	Fri Jun 15 23:37:58 2012 +0200
     1.3 @@ -936,11 +936,302 @@
     1.4  
     1.5  
     1.6  
     1.7 -.H2 "Removal of switches
     1.8 +.H2 "Removal of Switches
     1.9  .P
    1.10 +The command line switches of MH tools follow the X Window style.
    1.11 +They are words, introduced by a single dash.
    1.12 +For example:
    1.13 +.Cl "-truncate" .
    1.14 +Every program in mmh has two generic switches:
    1.15 +.Sw -help ,
    1.16 +to print a short message on how to use the program, and 
    1.17 +.Sw -Version ,
    1.18 +to tell what version of mmh the program belongs to.
    1.19 +.P
    1.20 +Switches change the behavior of programs.
    1.21 +Programs that do one thing in one way require no switches.
    1.22 +In most cases, doing something in exactly one way is too limiting.
    1.23 +If it is basically the same task to accomplish, but it should be done
    1.24 +in various ways, switches are a good approach to alter the behavior
    1.25 +of a program.
    1.26 +Changing the behavior of programs provides flexibility and customization
    1.27 +to users, but in the same way it complicates the code, documentation and
    1.28 +usage of the program.
    1.29 +Therefore, the number of switches should be kept small.
    1.30 +A small set of well-chosen switches does no harm.
    1.31 +But usually, the number of switches increases over time.
    1.32 +Already in 1985, Rose and Romine have identified this as a major
    1.33 +problem of MH:
    1.34 +.[ [
    1.35 +rose romine real work
    1.36 +.], p. 12]
    1.37 +.sp
    1.38 +.QP
    1.39 +A complaint often heard about systems which undergo substantial development
    1.40 +by many people over a number of years, is that more and more options are
    1.41 +introduced which add little to the functionality but greatly increase the
    1.42 +amount of information a user needs to know in order to get useful work done.
    1.43 +This is usually referred to as creeping featurism.
    1.44 +.QP
    1.45 +Unfortunately MH, having undergone six years of off-and-on development by
    1.46 +ten or so well-meaning programmers (the present authors included),
    1.47 +suffers mightily from this.
    1.48 +.sp
    1.49 +.P
    1.50 +Adding new switches only reluctantly is one part of the counter-action,
    1.51 +the other is removing hardly used switches.
    1.52 +Now that there are lots of switches already implemented,
    1.53 +removing some of them is more important.
    1.54 +Removing existing functionality is always difficult because it
    1.55 +breaks programs that use these functions.
    1.56 +Also, for every obsolete feature, there'll always be someone who still
    1.57 +uses it and thus opposes its removal.
    1.58 +This puts the developer into the position,
    1.59 +where sensible improvements to style are regarded as destructive acts.
    1.60 +Yet, living with the featurism is far worse, in my eyes.
    1.61 +Future needs will demand adding new features,
    1.62 +worsening the situation more and more.
    1.63 +Rose and Romine added in a footnote,
    1.64 +``[...]
    1.65 +.Pn send
    1.66 +will no doubt acquire an endless number of switches in the years to come.''
    1.67 +Although clearly humorous, the comment displays the nature of
    1.68 +the problem.
    1.69 +Though refusing to add any new switches would encounter the problem
    1.70 +at its root, it is not practical.
    1.71 +But removing obsolete switches is an effective approach to deal with the
    1.72 +problem.
    1.73 +Working on an experimental branch,
    1.74 +eased this work because I had not to offend users.
    1.75 +.P
    1.76 +Rose and Romine counted 24 visible and 9 more hidden switches for
    1.77 +.Pn send .
    1.78 +At the beginning of mmh, it were 32 visible and 12 hidden ones.
    1.79 +At the time of writing, mmh's
    1.80 +.Pn send
    1.81 +has 7 visible switches and 1 hidden switch.
    1.82 +(In each of the examples, the two generic help and version switches
    1.83 +are included.)
    1.84 +.P
    1.85 +Figure XXX
    1.86 +.\" XXX Ref
    1.87 +displays the number of switches for each of the tools that was not
    1.88 +removed from or newly added to mmh.
    1.89 +Both, visible and hidden switches, were counted, but
    1.90 +not the generic help and version switches.
    1.91 +Whereas in the beginning of the project, the average tool had 11 switches,
    1.92 +now it has no more than 5 \(en only half as many.
    1.93 +If the `no' switches and similar inverse variant are folded onto
    1.94 +their counter-parts, the numbers are 8 in pre-mmh to 4 now.
    1.95 +The total number of functional switches in mmh dropped from 465
    1.96 +to 234.
    1.97  
    1.98 +.KS
    1.99 +.in 1c
   1.100 +.so input/switches.grap
   1.101 +.KE
   1.102  
   1.103 +.P
   1.104 +A part of the switches vanished after functions were removed.
   1.105 +This was the case for network mail transfer, for instance.
   1.106 +Sometimes the work flow was the other way:
   1.107 +The trying to reduce the number of switches suggested the removal of
   1.108 +functions.
   1.109  
   1.110 +.U3 "Draft Folder Facility
   1.111 +.P
   1.112 +A change early in the project was the completely transition from
   1.113 +the single draft message to the draft folder facility.
   1.114 +The draft folder facility was introduced in the mid-Eighties.
   1.115 +(Rose and Romine called it a ``relatively new feature''
   1.116 +.[
   1.117 +rose romine real work
   1.118 +.]
   1.119 +in 1985.)
   1.120 +Since then, the facility had existed but had remained deactive by default.
   1.121 +The default activation and the related rework of the tools made it
   1.122 +possible to remove the
   1.123 +.Sw -[no]draftfolder ,
   1.124 +and
   1.125 +.Sw -draftmessage
   1.126 +switches from
   1.127 +.Pn comp ,
   1.128 +.Pn repl ,
   1.129 +.Pn forw ,
   1.130 +.Pn dist ,
   1.131 +.Pn whatnow ,
   1.132 +and
   1.133 +.Pn send .
   1.134 +The only flexibility removed is having multiple draft folders
   1.135 +within one profile.
   1.136 +I consider this only a theoretical setup.
   1.137 +In the same go, the
   1.138 +.Sw -draft
   1.139 +switch of
   1.140 +.Pn anno ,
   1.141 +.Pn refile ,
   1.142 +and
   1.143 +.Pn send
   1.144 +was removed.
   1.145 +The special-casing of `the' draft message became irrelevant after
   1.146 +the rework of the draft system.
   1.147 +(See Sec. XXX.)
   1.148 +
   1.149 +.U3 "Inplace
   1.150 +.P
   1.151 +.Pn anno
   1.152 +had the switches
   1.153 +.Sw -[no]inplace
   1.154 +to either annotate the message inplace and thus preserve hard links,
   1.155 +or annotate a copy to replace the original message, breaking hard links.
   1.156 +Following the assumption that linked messages are the same message,
   1.157 +and annotating it should not break the link, the
   1.158 +.Sw -[no]inplace
   1.159 +switches were removed and the previous default
   1.160 +.Sw -inplace
   1.161 +was made the only behavior.
   1.162 +The
   1.163 +.Sw -[no]inplace
   1.164 +switches of
   1.165 +.Pn repl ,
   1.166 +.Pn forw ,
   1.167 +and
   1.168 +.Pn dist
   1.169 +could be removed, too, as they were simply passed through to
   1.170 +.Pn anno .
   1.171 +.P
   1.172 +.Pn burst
   1.173 +also had
   1.174 +.Sw -[no]inplace
   1.175 +switches, but they had different meaning, as written in nmh's
   1.176 +.Mp burst(1)
   1.177 +man page:
   1.178 +.sp
   1.179 +.QP
   1.180 +If -noinplace is given, each digest is preserved, no table
   1.181 +of contents is produced, and the messages contained within
   1.182 +the digest are placed at the end of the folder. Other messages
   1.183 +are not tampered with in any way.
   1.184 +.sp
   1.185 +.P
   1.186 +With
   1.187 +.Sw -inplace ,
   1.188 +the digest had been replaced by the table of contents (i.e. the
   1.189 +introduction text) and the bursted messages were placed right
   1.190 +after this message, renumbering all following messages.
   1.191 +Also, any trailing text of the digest will be lost, though,
   1.192 +in practice, it usually consists of an end-of-digest marker only.
   1.193 +The decision to drop the
   1.194 +.Sw -inplace
   1.195 +behavior was supported by the complexity and possible data loss
   1.196 +it introduced.
   1.197 +.Sw -noinplace
   1.198 +was the default behavior already and is the chosen behavior now.
   1.199 +
   1.200 +.U3 "mbox and MMDF
   1.201 +.P
   1.202 +packf: file mbox mmdf
   1.203 +rcvpack: mbox mmdf
   1.204 +
   1.205 +
   1.206 +.ig
   1.207 +
   1.208 +ap: width
   1.209 +dp: width
   1.210 +burst: [no]quiet
   1.211 +flist: [no]total
   1.212 +folder: [no]header
   1.213 +
   1.214 +comp: file
   1.215 +dist: file(msh)
   1.216 +forw: filter, [no]mime, [no]dashstuffing(mhl)
   1.217 +repl: [no]format/filter width
   1.218 +
   1.219 +mhmail: resent queued
   1.220 +inc: snoop, (pop)
   1.221 +mhbuild: [no]check, [no]ebcdicsafe, [no]headers, [no]list, [no]realsize
   1.222 +	[no]rfc934mode, [no]contentid (caching)
   1.223 +mhlist: [no]check [no]headers [no]realsize (caching)
   1.224 +mhstore: [no]check [no]verbose (caching)
   1.225 +
   1.226 +scan: [no]clear [no]header [no]reverse
   1.227 +
   1.228 +mhl: [no]bell [no]clear [no]faceproc folder [no]moreproc length sleep
   1.229 +	[no]dashstuffing(forw) digest list volume number issue number
   1.230 +mhshow: [no]check [no]pause [no]serialonly (caching) [no]moreproc
   1.231 +	length width
   1.232 +
   1.233 +prompter: erase kill [no]doteof
   1.234 +
   1.235 +refile: [no]preserve [no]unlink [no]rmmproc
   1.236 +
   1.237 +send: filter [no]format [no]forward [no]mime [no]msgid
   1.238 +	[no]push split [no]unique (sasl) width snoop [no]dashstuffing
   1.239 +	attach attachformat
   1.240 +whatnow: (noedit) attach
   1.241 +
   1.242 +slocal: [no]suppressdups
   1.243 +
   1.244 +sortm: subject
   1.245 +
   1.246 +spost: [no]filter [no]format [no]remove [no]backup width [no]push idanno
   1.247 +	[no]check(whom) whom(whom)
   1.248 +
   1.249 +whom: ???
   1.250 +
   1.251 +
   1.252 +(pop) host, port, user, [no]pack, proxy
   1.253 +(smtp) mail saml send soml client server user port
   1.254 +(sasl) sasl, saslmech
   1.255 +(tls)
   1.256 +(caching) rcache wcache
   1.257 +
   1.258 +noedit
   1.259 +nowhatnowproc
   1.260 +
   1.261 +
   1.262 +format -> form
   1.263 +
   1.264 +version -> Version
   1.265 +
   1.266 +..
   1.267 +
   1.268 +.ig
   1.269 +
   1.270 +.P
   1.271 +To ease typing, the switches can be abbreviated as much as the remaining
   1.272 +prefix remains unambiguous.
   1.273 +If in our example no other switch would start with the letter `t', then
   1.274 +.Cl "-truncate" ,
   1.275 +.Cl "-trunc" ,
   1.276 +.Cl "-tr" ,
   1.277 +and
   1.278 +.Cl "-t
   1.279 +would all be the same.
   1.280 +As a result, switches can neither be grouped (as in
   1.281 +.Cl "ls -ltr" )
   1.282 +nor can switch arguments be appended directly to the switch (as in
   1.283 +.Cl "sendmail -q30m" ).
   1.284 +.P
   1.285 +Many switches have negating counter-parts, which start with `no'.
   1.286 +For example
   1.287 +.Cl "-notruncate
   1.288 +inverts the
   1.289 +.Cl "-truncate
   1.290 +switch.
   1.291 +They exist to undo the effect of default switches in the profile.
   1.292 +If the user has chosen to change the default behavior of some tool
   1.293 +by adding a default switch to the profile,
   1.294 +he can still undo this change in behavior by specifiying the inverse
   1.295 +switch on the command line.
   1.296 +.P
   1.297 +In the best case, all switches are unambiguous on the first character,
   1.298 +or on the three-letter prefix for the `no' variants.
   1.299 +Reducing switch prefix collisions, shortens the necessary prefix lenght
   1.300 +the user must type.
   1.301 +Having less switches helps best.
   1.302 +
   1.303 +..
   1.304  
   1.305  .H1 "Modernizing
   1.306