1.1 --- a/ch03.roff	Sat Jun 16 13:31:25 2012 +0200
     1.2 +++ b/ch03.roff	Sat Jun 16 17:28:11 2012 +0200
     1.3 @@ -951,12 +951,13 @@
     1.4  Switches change the behavior of programs.
     1.5  Programs that do one thing in one way require no switches.
     1.6  In most cases, doing something in exactly one way is too limiting.
     1.7 -If it is basically the same task to accomplish, but it should be done
     1.8 +If there is basically one task to accomplish, but it should be done
     1.9  in various ways, switches are a good approach to alter the behavior
    1.10  of a program.
    1.11  Changing the behavior of programs provides flexibility and customization
    1.12 -to users, but in the same way it complicates the code, documentation and
    1.13 +to users, but at the same time it complicates the code, documentation and
    1.14  usage of the program.
    1.15 +.\" XXX: Ref
    1.16  Therefore, the number of switches should be kept small.
    1.17  A small set of well-chosen switches does no harm.
    1.18  But usually, the number of switches increases over time.
    1.19 @@ -978,51 +979,54 @@
    1.20  suffers mightily from this.
    1.21  .sp
    1.22  .P
    1.23 -Adding new switches only reluctantly is one part of the counter-action,
    1.24 -the other is removing hardly used switches.
    1.25 -Now that there are lots of switches already implemented,
    1.26 -removing some of them is more important.
    1.27 +Being reluctant to adding new switches \(en or `options',
    1.28 +as Rose and Romine call them \(en is one part of a counter-action,
    1.29 +the other part is removing hardly used switches.
    1.30 +Nmh's tools had lots of switches already implemented,
    1.31 +hence, cleaning up by removing some of them was the more important part
    1.32 +of the counter-action.
    1.33  Removing existing functionality is always difficult because it
    1.34  breaks programs that use these functions.
    1.35  Also, for every obsolete feature, there'll always be someone who still
    1.36  uses it and thus opposes its removal.
    1.37  This puts the developer into the position,
    1.38  where sensible improvements to style are regarded as destructive acts.
    1.39 -Yet, living with the featurism is far worse, in my eyes.
    1.40 -Future needs will demand adding new features,
    1.41 +Yet, living with the featurism is far worse, in my eyes, because
    1.42 +future needs will demand adding further features,
    1.43  worsening the situation more and more.
    1.44  Rose and Romine added in a footnote,
    1.45  ``[...]
    1.46  .Pn send
    1.47  will no doubt acquire an endless number of switches in the years to come.''
    1.48 -Although clearly humorous, the comment displays the nature of
    1.49 -the problem.
    1.50 -Though refusing to add any new switches would encounter the problem
    1.51 -at its root, it is not practical.
    1.52 -But removing obsolete switches is an effective approach to deal with the
    1.53 -problem.
    1.54 -Working on an experimental branch,
    1.55 -eased this work because I had not to offend users.
    1.56 +Although clearly humorous, the comment points to the nature of the problem.
    1.57 +Refusing to add any new switches would encounter the problem at its root,
    1.58 +but this is not practical.
    1.59 +New needs will require new switches and it would be unwise to block
    1.60 +them strictly.
    1.61 +Nevertheless, removing obsolete switches still is an effective approach
    1.62 +to deal with the problem.
    1.63 +Working on an experimental branch without an established user base,
    1.64 +eased my work because I did not offend users when I removed existing
    1.65 +funtions.
    1.66  .P
    1.67  Rose and Romine counted 24 visible and 9 more hidden switches for
    1.68  .Pn send .
    1.69 -At the beginning of mmh, it were 32 visible and 12 hidden ones.
    1.70 -At the time of writing, mmh's
    1.71 -.Pn send
    1.72 -has 7 visible switches and 1 hidden switch.
    1.73 -(In each of the examples, the two generic help and version switches
    1.74 -are included.)
    1.75 +In nmh, they increased up to 32 visible and 12 hidden ones.
    1.76 +At the time of writing, no more than 7 visible switches and 1 hidden switch
    1.77 +have remained in mmh's
    1.78 +.Pn send .
    1.79 +(These numbers include two generic switches, help and version.)
    1.80  .P
    1.81 -Figure XXX
    1.82 +Fig. XXX
    1.83  .\" XXX Ref
    1.84 -displays the number of switches for each of the tools that was not
    1.85 -removed from or newly added to mmh.
    1.86 -Both, visible and hidden switches, were counted, but
    1.87 -not the generic help and version switches.
    1.88 +displays the number of switches for each of the tools that is available
    1.89 +in both, nmh and mmh.
    1.90 +Visible as well as hidden switches were counted,
    1.91 +but not the generic help and version switches.
    1.92  Whereas in the beginning of the project, the average tool had 11 switches,
    1.93  now it has no more than 5 \(en only half as many.
    1.94  If the `no' switches and similar inverse variant are folded onto
    1.95 -their counter-parts, the numbers are 8 in pre-mmh to 4 now.
    1.96 +their counter-parts, the average tool has 8 switches in pre-mmh to 4 now.
    1.97  The total number of functional switches in mmh dropped from 465
    1.98  to 234.
    1.99  
   1.100 @@ -1034,22 +1038,28 @@
   1.101  .P
   1.102  A part of the switches vanished after functions were removed.
   1.103  This was the case for network mail transfer, for instance.
   1.104 -Sometimes the work flow was the other way:
   1.105 -The trying to reduce the number of switches suggested the removal of
   1.106 -functions.
   1.107 +Sometimes, however, the work flow was the other way:
   1.108 +I looked through the
   1.109 +.Mp mh-chart (7)
   1.110 +man page to identify the tools with apparently too many switches.
   1.111 +Then considering the value of each of the switches by examining
   1.112 +the tool's man page and source code, aided by recherche and testing.
   1.113 +This way, the removal of functions was suggested by the aim to reduce
   1.114 +the number of switches per command.
   1.115 +
   1.116  
   1.117  .U3 "Draft Folder Facility
   1.118  .P
   1.119  A change early in the project was the completely transition from
   1.120  the single draft message to the draft folder facility.
   1.121 +.Ci 337338b404931f06f0db2119c9e145e8ca5a9860
   1.122  The draft folder facility was introduced in the mid-Eighties.
   1.123  (Rose and Romine called it a ``relatively new feature''
   1.124  .[
   1.125  rose romine real work
   1.126  .]
   1.127  in 1985.)
   1.128 -Since then, the facility had existed but had remained deactivated
   1.129 -by default.
   1.130 +Since then, the facility had existed but was deactivated by default.
   1.131  The default activation and the related rework of the tools made it
   1.132  possible to remove the
   1.133  .Sw -[no]draftfolder ,
   1.134 @@ -1063,9 +1073,10 @@
   1.135  .Pn whatnow ,
   1.136  and
   1.137  .Pn send .
   1.138 -The only flexibility removed is having multiple draft folders
   1.139 -within one profile.
   1.140 -I consider this only a theoretical setup.
   1.141 +.Ci 337338b404931f06f0db2119c9e145e8ca5a9860
   1.142 +The only flexibility removed with this change is having multiple
   1.143 +draft folders within one profile.
   1.144 +I consider this a theoretical problem only.
   1.145  In the same go, the
   1.146  .Sw -draft
   1.147  switch of
   1.148 @@ -1094,12 +1105,13 @@
   1.149  .Sw -[no]inplace
   1.150  to either annotate the message inplace and thus preserve hard links,
   1.151  or annotate a copy to replace the original message, breaking hard links.
   1.152 -Following the assumption that linked messages are the same message,
   1.153 -and annotating it should not break the link, the
   1.154 +Following the assumption that linked messages should truly be the
   1.155 +same message, and annotating it should not break the link, the
   1.156  .Sw -[no]inplace
   1.157  switches were removed and the previous default
   1.158  .Sw -inplace
   1.159  was made the only behavior.
   1.160 +.Ci c8195849d2e366c569271abb0f5f60f4ebf0b4d0
   1.161  The
   1.162  .Sw -[no]inplace
   1.163  switches of
   1.164 @@ -1141,6 +1153,7 @@
   1.165  it caused.
   1.166  .Sw -noinplace
   1.167  was chosen to be the definitive behavior.
   1.168 +.Ci 68a686adeb39223a5e1ad35e4a24890ec053679d
   1.169  
   1.170  
   1.171  .U3 "Forms and Format Strings
   1.172 @@ -1161,6 +1174,7 @@
   1.173  switches were dropped in favor for extending the
   1.174  .Sw -form
   1.175  switches.
   1.176 +.Ci f51956be123db66b00138f80464d06f030dbb88d
   1.177  If their argument starts with an equal sign (`='),
   1.178  then the rest of the argument is taken as a format string,
   1.179  otherwise the arguments is treated as the name of a format file.
   1.180 @@ -1187,6 +1201,7 @@
   1.181  .Pn forw
   1.182  was completely switched to MIME-type forwarding, thus removing the
   1.183  .Sw -[no]format .
   1.184 +.Ci 6e271608b7b9c23771523f88d23a4d3593010cf1
   1.185  For
   1.186  .Pn repl ,
   1.187  the
   1.188 @@ -1194,6 +1209,7 @@
   1.189  switches were reworked to
   1.190  .Sw -[no]filter
   1.191  switches.
   1.192 +.Ci 67411b1f95d6ec987b4c732459e1ba8a8ac192c6
   1.193  The
   1.194  .Sw -format
   1.195  switches of
   1.196 @@ -1202,6 +1218,7 @@
   1.197  .Pn post ,
   1.198  which had a third meaning,
   1.199  were removed likewise.
   1.200 +.Ci f3cb7cde0e6f10451b6848678d95860d512224b9
   1.201  Eventually, the ambiguity of the
   1.202  .Sw -format
   1.203  switches was resolved by not anymore having any such switch in mmh.
   1.204 @@ -1218,7 +1235,9 @@
   1.205  .Pn mhbuild
   1.206  and
   1.207  .Pn mhlist
   1.208 -were removed, doing real size calculations always now, as
   1.209 +were removed, doing real size calculations always now
   1.210 +.Ci 8d8f1c3abc586c005c904e52c4adbfe694d2201c ,
   1.211 +as
   1.212  ``This provides an accurate count at the expense of a small delay.''
   1.213  This small delay is not noticable on modern systems.
   1.214  .P
   1.215 @@ -1230,6 +1249,7 @@
   1.216  .[
   1.217  rfc 1864
   1.218  .]
   1.219 +.Ci 31dc797eb5178970d68962ca8939da3fd9a8efda
   1.220  (See Sec. XXX)
   1.221  .P
   1.222  The
   1.223 @@ -1239,13 +1259,16 @@
   1.224  switches of
   1.225  .Pn mhbuild
   1.226  were removed because they are considered obsolete.
   1.227 +.Ci 01a3480928da485b4d6109d36d751dfa71799d58
   1.228 +.Ci 3363e2624dce0eb8164cf8b3f1ab385c8ff72e88
   1.229  .P
   1.230  Content caching of external MIME parts, activated with the
   1.231  .Sw -rcache
   1.232  and
   1.233  .Sw -wcache
   1.234  switches was completely removed.
   1.235 -External MIME parts are truly rare today, having a caching facility
   1.236 +.Ci d1fefd9f614e4dc3cda16da6c69133c1b2005269
   1.237 +External MIME parts are rare today, having a caching facility
   1.238  for them is appears to be unnecessary.
   1.239  .P
   1.240  In pre-MIME times,
   1.241 @@ -1255,6 +1278,8 @@
   1.242  .Pn mhl
   1.243  could be simplified to a large extend, reducing the number of its
   1.244  switches from 21 to 6.
   1.245 +.Ci 350ad6d3542a07639213cf2a4fe524e829c1e7b6
   1.246 +.Ci 0e46503be3c855bddaeae3843e1b659279c35d70
   1.247  
   1.248  
   1.249  .U3 "Mail Transfer Switches
   1.250 @@ -1328,11 +1353,15 @@
   1.251  switches.
   1.252  .Sw -mbox
   1.253  is the sole  behavior now.
   1.254 +.Ci 3916ab66ad5d183705ac12357621ea8661afd3c0
   1.255  In the same go,
   1.256  .Pn packf
   1.257 -was reworked (see Sec. XXX) and its
   1.258 +and
   1.259 +.Pn rcvpack
   1.260 +were reworked (see Sec. XXX) and their
   1.261  .Sw -file
   1.262  switch became unnecessary.
   1.263 +.Ci ca1023716d4c2ab890696f3e41fa0d94267a940e
   1.264  
   1.265  
   1.266  .U3 "Terminal Magic
   1.267 @@ -1342,13 +1371,17 @@
   1.268  and
   1.269  .Pn mhl 's
   1.270  .Sw -[no]clear
   1.271 -switches).
   1.272 +switches
   1.273 +.Ci e57b17343dcb3ff373ef4dd089fbe778f0c7c270
   1.274 +.Ci 943765e7ac5693ae177fd8d2b5a2440e53ce816e ).
   1.275  Neither will
   1.276  .Pn mhl
   1.277  ring the bell (\c
   1.278 -.Sw -[no]bell )
   1.279 +.Sw -[no]bell
   1.280 +.Ci e11983f44e59d8de236affa5b0d0d3067c192e24 )
   1.281  nor page the output itself (\c
   1.282 -.Sw -length ).
   1.283 +.Sw -length
   1.284 +.Ci 5b9d883db0318ed2b84bb82dee880d7381f99188 ).
   1.285  .P
   1.286  Generally, the pager to use is no longer specified with the
   1.287  .Sw -[no]moreproc
   1.288 @@ -1357,6 +1390,7 @@
   1.289  and
   1.290  .Pn show /\c
   1.291  .Pn mhshow .
   1.292 +.Ci 39e87a75b5c2d3572ec72e717720b44af291e88a
   1.293  .P
   1.294  .Pn prompter
   1.295  lost its
   1.296 @@ -1374,12 +1408,14 @@
   1.297  Hence, the
   1.298  .Sw -[no]header
   1.299  switch was removed and headers are never printed.
   1.300 +.Ci 601cc73d1fa05ce96faa728f036d6c51b91701c7
   1.301  .P
   1.302  In
   1.303  .Pn mhlist ,
   1.304  the
   1.305  .Sw -[no]header
   1.306  switches were removed, too.
   1.307 +.Ci b24f96523aaf60e44e04a3ffb1d22e69a13a602f
   1.308  But in this case headers are always printed,
   1.309  because the output is not self-explaining.
   1.310  .P
   1.311 @@ -1395,6 +1431,7 @@
   1.312  and
   1.313  .Pn date ,
   1.314  consequently, the switches were removed.
   1.315 +.Ci c477dc5d1d03fa6d9a8ab3dd3508c63cbddc044e
   1.316  .P
   1.317  By removing all
   1.318  .Sw -header
   1.319 @@ -1422,6 +1459,7 @@
   1.320  was removed, but it can now be replaced by specifying
   1.321  .Sw -editor
   1.322  with an empty argument.
   1.323 +.Ci 75fca31a5b9d5c1a99c74ab14c94438d8852fba9
   1.324  (Specifying
   1.325  .Cl "-editor true
   1.326  is nearly the same, only differing by the previous editor being set.)
   1.327 @@ -1429,6 +1467,7 @@
   1.328  The more important change is the removal of the
   1.329  .Sw -nowhatnowproc
   1.330  switch.
   1.331 +.Ci ee4f43cf2ef0084ec698e4e87159a94c01940622
   1.332  This switch had introduced an awkward behavior, as explained in nmh's
   1.333  man page for
   1.334  .Mp comp (1):
   1.335 @@ -1476,6 +1515,7 @@
   1.336  I removed the
   1.337  .Sw -[no]total
   1.338  legacy.
   1.339 +.Ci ea21fe2c4bd23c639bef251398fae809875732ec
   1.340  .BU
   1.341  The
   1.342  .Sw -subject
   1.343 @@ -1485,6 +1525,7 @@
   1.344  It can be fully replaced by
   1.345  .Cl "-textfield subject
   1.346  thus it was removed.
   1.347 +.Ci 00140a3c86e9def69d98ba2ffd4d6e50ef6326ea
   1.348  
   1.349  
   1.350  .U3 "Various
   1.351 @@ -1494,6 +1535,7 @@
   1.352  switch was renamed to
   1.353  .Sw -Version
   1.354  (with capital `V').
   1.355 +.Ci 32b2354dbaf4bf934936eb5b102a4a3d2fdd209a
   1.356  Every program has the
   1.357  .Sw -version
   1.358  switch but its first three letters collided with the
   1.359 @@ -1522,12 +1564,13 @@
   1.360  .Sw -[no]reverse
   1.361  switches of
   1.362  .Pn scan
   1.363 +.Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
   1.364  is a bug fix, supported by the comments
   1.365  ``\-[no]reverse under #ifdef BERK (I really HATE this)''
   1.366  by Rose and
   1.367  ``Lists messages in reverse order with the `\-reverse' switch.
   1.368  This should be considered a bug.'' by Romine in the documentation.
   1.369 -The question remaining is why neither Rose and Romine had fixed this
   1.370 +The question remains why neither Rose and Romine had fixed this
   1.371  bug in the Eighties when they wrote these comments nor has anyone
   1.372  thereafter.
   1.373