1.1 --- a/discussion.roff	Tue Jul 10 10:26:04 2012 +0200
     1.2 +++ b/discussion.roff	Tue Jul 10 11:46:20 2012 +0200
     1.3 @@ -1518,8 +1518,10 @@
     1.4  .Sw -[no]preserve
     1.5  of
     1.6  .Pn refile
     1.7 -was removed because what use was it anyway?
     1.8 -Quoting nmh's man page of
     1.9 +was removed
    1.10 +.Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
    1.11 +because what use was it anyway?
    1.12 +Quoting nmh's man page
    1.13  .Mp refile (1):
    1.14  .QS
    1.15  Normally when a message is refiled, for each destination
    1.16 @@ -2002,7 +2004,11 @@
    1.17  But then the case of non-ASCII text without attachment headers was
    1.18  not caught.
    1.19  All in all, the solution was complex and irritating.
    1.20 -My patch from December 2010 would have simplified the situation.
    1.21 +My patch from December 2010
    1.22 +.[
    1.23 +nmh-workers attachment proposal
    1.24 +.]
    1.25 +would have simplified the situation.
    1.26  .P
    1.27  Mmh's current solution is even more elaborate.
    1.28  Any necessary MIMEification is done automatically.
    1.29 @@ -2465,23 +2471,21 @@
    1.30  .Fn draft
    1.31  in the MH directory, which is treated special.
    1.32  On composing a message, this draft file was used.
    1.33 -As the draft file was one particular file, only one draft could be
    1.34 -managed at any time.
    1.35  When starting to compose another message before the former one was sent,
    1.36  the user had to decide among:
    1.37  .BU
    1.38 -Use the old draft to finish and send it before starting with a new one.
    1.39 +Using the old draft to finish and send it before starting with a new one.
    1.40  .BU
    1.41 -Discard the old draft, replacing it with the new one.
    1.42 +Discarding the old draft and replacing it with a new one.
    1.43  .BU
    1.44 -Preserve the old draft by refiling it to a folder.
    1.45 +Preserving the old draft by refiling it to a folder.
    1.46  .P
    1.47 -This was, it was only possible to work in alternation on multiple drafts.
    1.48 +It was only possible to work in alternation on multiple drafts.
    1.49  Therefore, the current draft needed to be refiled to a folder and
    1.50 -another one re-using for editing.
    1.51 +another one re-used for editing.
    1.52  Working on multiple drafts at the same time was impossible.
    1.53  The usual approach of switching to a different MH context did not
    1.54 -change anything.
    1.55 +help anything.
    1.56  .P
    1.57  The draft folder facility exists to
    1.58  allow true parallel editing of drafts, in a straight forward way.
    1.59 @@ -2526,21 +2530,24 @@
    1.60  switches were removed because operating on a draft message is no longer
    1.61  special.
    1.62  It became indistinguishable to operating on any other message.
    1.63 -There is no more need to query the user for draft handling.
    1.64 +.Ci 337338b404931f06f0db2119c9e145e8ca5a9860
    1.65 +.P
    1.66 +There is no more need to query the user for draft handling
    1.67 +.Ci 2d48b455c303a807041c35e4248955f8bec59eeb .
    1.68  It is always possible to add another new draft.
    1.69  Refiling drafts is without difference to refiling other messages.
    1.70 -All these special cases are gone.
    1.71 +All of these special cases are gone.
    1.72  Yet, one draft-related switch remained.
    1.73  .Pn comp
    1.74  still has
    1.75  .Sw -[no]use
    1.76  for switching between two modes:
    1.77  .BU
    1.78 -.Sw -use :
    1.79 -Modify an existing draft.
    1.80 +.Sw -use
    1.81 +to modify an existing draft.
    1.82  .BU
    1.83 -.Sw -nouse :
    1.84 -Compose a new draft, possibly taking some existing message as a form.
    1.85 +.Sw -nouse
    1.86 +to compose a new draft, possibly taking some existing message as template.
    1.87  .P
    1.88  In either case, the behavior of
    1.89  .Pn comp
    1.90 @@ -2578,35 +2585,34 @@
    1.91  The specific file would then be ignored by MH because only files with
    1.92  names consisting of digits only are treated as messages.
    1.93  Although files remained in the file system,
    1.94 -the messages were no more visible in MH.
    1.95 -To truly delete them, a maintenance job is needed.
    1.96 -Usually a cron job is installed to delete them after a grace time.
    1.97 +the messages were no longer visible in MH.
    1.98 +To truly delete them, a maintenance job was needed.
    1.99 +Usually a cron job was installed to delete them after a grace time.
   1.100  For instance:
   1.101  .VS
   1.102  find $HOME/Mail -type f -name ',*' -ctime +7 -delete
   1.103  VE
   1.104 -In such a setup, the original message can be restored
   1.105 +In such a setup, the original message could be restored
   1.106  within the grace time interval by stripping the
   1.107  backup prefix from the file name.
   1.108 -But the user can not rely on this statement.
   1.109 -If the last message of a folder with six messages (1-6) is removed,
   1.110 +But the user could not rely on this statement.
   1.111 +If the last message of a folder with six messages (\fL1-6\fP) was removed,
   1.112  message
   1.113  .Fn 6 ,
   1.114 -becomes file
   1.115 +became file
   1.116  .Fn ,6 .
   1.117 -If then a new message enters the same folder, it will be given
   1.118 -the number one higher than the highest message.
   1.119 -In this case the message is named
   1.120 +If then a new message entered the same folder, it would be named with
   1.121 +the number one above the highest existing message number.
   1.122 +In this case the message would be named
   1.123  .Fn 6
   1.124  then.
   1.125 -If this message is removed as well,
   1.126 -then the backup of the former message gets overwritten.
   1.127 -Hence, the ability to restore removed messages does not only depend on
   1.128 +If this new message would be removed as well,
   1.129 +then the backup of the former message is overwritten.
   1.130 +Hence, the ability to restore removed messages did not only depend on
   1.131  the ``sweeping cron job'' but also on the removing of further messages.
   1.132  It is undesirable to have such obscure and complex mechanisms.
   1.133 -The user should be given a small set of clear assertions.
   1.134 +The user should be given a small set of clear assertions, such as
   1.135  ``Removed files are restorable within a seven-day grace time.''
   1.136 -is such a clear assertion.
   1.137  With the addition ``... unless a message with the same name in the
   1.138  same folder is removed before.'' the statement becomes complex.
   1.139  A user will hardly be able to keep track of any removal to know
   1.140 @@ -2628,20 +2634,20 @@
   1.141  was introduced very early to improve the situation.
   1.142  It could be set to any command, which would be executed to remove
   1.143  the specified messages.
   1.144 -This would override the default action, described above.
   1.145 -Refiling the to-be-removed files to a garbage folder is the usual example.
   1.146 +This would override the default action described above.
   1.147 +Refiling the to-be-removed files to a trash folder is the usual example.
   1.148  Nmh's man page
   1.149  .Mp rmm (1)
   1.150  proposes to set the
   1.151  .Pe rmmproc
   1.152  to
   1.153  .Cl "refile +d
   1.154 -to move messages to the garbage folder,
   1.155 +to move messages to the trash folder,
   1.156  .Fn +d ,
   1.157  instead of renaming them with the backup prefix.
   1.158  The man page proposes additionally the expunge command
   1.159  .Cl "rm `mhpath +d all`
   1.160 -to empty the garbage folder.
   1.161 +to empty the trash folder.
   1.162  .P
   1.163  Removing messages in such a way has advantages.
   1.164  The mail storage is prevented from being cluttered with removed messages
   1.165 @@ -2670,8 +2676,10 @@
   1.166  where the
   1.167  .Sw -unlink
   1.168  switch causes the files to be unlinked.
   1.169 +.Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
   1.170 +.Ci ca0b3e830b86700d9e5e31b1784de2bdcaf58fc5
   1.171  .P
   1.172 -Dropping the legacy approach and completely converting to the new approach
   1.173 +Dropping the legacy approach and converting to the new approach completely
   1.174  simplified the code base.
   1.175  The relationship between
   1.176  .Pn rmm
   1.177 @@ -2739,9 +2747,8 @@
   1.178  .P
   1.179  Yet, the real problem lies less in enabling the features, as this is
   1.180  straight forward as soon as one knows what he wants.
   1.181 -The real problem is that new users need deep insights into the project
   1.182 -before they find out what they are missing and that nmh actually
   1.183 -provides it already, it just was not activated.
   1.184 +The real problem is that new users need deep insight into the project
   1.185 +to find out about inactive features nmh already provides.
   1.186  To give an example, I needed one year of using nmh
   1.187  before I became aware of the existence of the attachment system.
   1.188  One could argue that this fact disqualifies my reading of the
   1.189 @@ -2764,8 +2771,8 @@
   1.190  Maintaining compatibility for its own sake is bad,
   1.191  because the code base collects more and more compatibility code.
   1.192  Sticking to the compatiblity code means remaining limited;
   1.193 -not using it renders it unnecessary.
   1.194 -Keeping unused alternative in the code is a bad choice as they likely
   1.195 +whereas adjusting to the changes renders the compatibility unnecessary.
   1.196 +Keeping unused alternatives in the code is a bad choice as they likely
   1.197  gather bugs, by not being well tested.
   1.198  Also, the increased code size and the greater number of conditions
   1.199  increase the maintenance costs.
   1.200 @@ -2778,11 +2785,11 @@
   1.201  Nmh's user base is small and old.
   1.202  Changing the interfaces would cause inconvenience to long-term users of MH.
   1.203  It would force them to change their many years old MH configurations.
   1.204 -I do understand this aspect, but it keeps new users from using MH.
   1.205 -By sticking to the old users, new users are kept away.
   1.206 +I do understand this aspect, but by sticking to the old users,
   1.207 +new users are kept away.
   1.208  Yet, the future lies in new users.
   1.209 -Hence, mmh invites new users by providing a convenient and modern setup,
   1.210 -readily usable out-of-the-box.
   1.211 +In consequence, mmh invites new users by providing a convenient
   1.212 +and modern setup, readily usable out-of-the-box.
   1.213  .P
   1.214  In mmh, all modern features are active by default and many previous
   1.215  approaches are removed or only accessible in manual ways.
   1.216 @@ -2809,7 +2816,7 @@
   1.217  .P
   1.218  In consequence, a setup with a profile that defines only the path to the
   1.219  mail storage, is already convenient to use.
   1.220 -Again, Paul Vixie's ``edginess'' appeal supports the direction I took:
   1.221 +Again, Paul Vixie's ``edginess'' call supports the direction I took:
   1.222  ``the `main branch' should just be modern''.
   1.223  .[
   1.224  paul vixie edginess nmh-workers
   1.225 @@ -2832,7 +2839,7 @@
   1.226  Good style is so important to good programming that we have chose
   1.227  to cover it first.
   1.228  .QE
   1.229 -This section covers changes in mmh that were motivated by the desire
   1.230 +This section covers changes in mmh that were guided by the desire
   1.231  to improve on style.
   1.232  Many of them follow the rules given in the quoted book.
   1.233  .[
   1.234 @@ -2848,10 +2855,11 @@
   1.235  .U3 "Indentation Style
   1.236  .P
   1.237  Indentation styles are the holy cow of programmers.
   1.238 -Again Kernighan and Pike:
   1.239 +Kernighan and Pike
   1.240  .[ [
   1.241  kernighan pike practice of programming
   1.242  .], p. 10]
   1.243 +wrote:
   1.244  .QS
   1.245  Programmers have always argued about the layout of programs,
   1.246  but the specific style is much less important than its consistent
   1.247 @@ -3001,15 +3009,7 @@
   1.248  .Sw -component
   1.249  and
   1.250  .Sw -text ,
   1.251 -which took an argument each,
   1.252 -and the two pairs of flags,
   1.253 -.Sw -[no]date
   1.254 -and
   1.255 -.Sw -[no]inplace.,
   1.256 -.Sw -component
   1.257 -and
   1.258 -.Sw -text ,
   1.259 -which took an argument each,
   1.260 +which have an argument each,
   1.261  and the two pairs of flags,
   1.262  .Sw -[no]date
   1.263  and
   1.264 @@ -3300,6 +3300,7 @@
   1.265  .Fn sbr/path.c .
   1.266  .Fn sbr/m_maildir.c
   1.267  is removed.
   1.268 +.Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
   1.269  .P
   1.270  Along with the path conversion rework, I also replaced
   1.271  .Fu getfolder(FDEF)
   1.272 @@ -3315,12 +3316,14 @@
   1.273  .Fn sbr/getfolder.c
   1.274  to
   1.275  .Fn sbr/path.c .
   1.276 +.Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
   1.277  .P
   1.278  The related function
   1.279  .Fu etcpath()
   1.280  was moved to
   1.281  .Fn sbr/path.c ,
   1.282 -too.
   1.283 +too
   1.284 +.Ci b4c29794c12099556151d93a860ee51badae2e35 .
   1.285  Previously, it had been located in
   1.286  .Fn config/config.c ,
   1.287  for whatever reasons.
   1.288 @@ -3331,7 +3334,6 @@
   1.289  The readability of the code is highly improved.
   1.290  Additionally, each of the six exported and one static functions
   1.291  is introduced by an explaining comment.
   1.292 -.Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
   1.293  
   1.294  
   1.295  
   1.296 @@ -3772,8 +3774,9 @@
   1.297  appeared to be inconsistent.
   1.298  The approach chosen for mmh is consistent, simple, and familiar to
   1.299  Unix users.
   1.300 +.Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
   1.301  .P
   1.302 -MH allows users to have multiiple MH setups.
   1.303 +MH allows users to have multiple MH setups.
   1.304  Therefore, it is necessary to select a different profile.
   1.305  The profile is the single entry point to access the rest of a
   1.306  personal MH setup.
   1.307 @@ -3796,6 +3799,7 @@
   1.308  override the paths to the profile and context files, respectively.
   1.309  This approach allows the set of personal configuration files to be chosen
   1.310  independently from the profile, context, and mail storage.
   1.311 +.Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
   1.312  .P
   1.313  The separation of the files by type is sensible and convenient.
   1.314  The new approach has no functional disadvantages,
   1.315 @@ -3891,7 +3895,7 @@
   1.316  a MH-MIME library, as a companion to the MH standard library.
   1.317  This is left open for the future.
   1.318  .P
   1.319 -The work already done, focussed on the non-MIME tools.
   1.320 +The work already done focussed on the non-MIME tools.
   1.321  The amount of code compiled into each program was reduced.
   1.322  This eases the understanding of the code base.
   1.323  In nmh,
   1.324 @@ -4076,15 +4080,27 @@
   1.325  .Pn whatnow
   1.326  which thereafter invokes
   1.327  .Pn send .
   1.328 +.Ci 3df5ab3c116e6d4a2fb4bb5cc9dfc5f781825815
   1.329 +.Ci c73c00bfccd22ec77e9593f47462aeca4a8cd9c0
   1.330  The clear separation on the surface is maintained on the level below.
   1.331  Human users and the tools use the same interface \(en
   1.332  annotations, for example, are made by invoking
   1.333  .Pn anno ,
   1.334  no matter if requested by programs or by human beings.
   1.335 +.Ci 469a4163c2a1a43731d412eaa5d9cae7d670c48b
   1.336 +.Ci aed384169af5204b8002d06e7a22f89197963d2d
   1.337 +.Ci 3caf9e298a8861729ca8b8a84f57022b6f3ea742
   1.338  The decrease of tools built from multiple source files and thus
   1.339  the decrease of
   1.340  .Fn uip/*sbr.c
   1.341  files confirm the improvement.
   1.342 +.Ci 9e6d91313f01c96b4058d6bf419a8ca9a207bc33
   1.343 +.ci 81744a46ac9f845d6c2b9908074d269275178d2e
   1.344 +.Ci f0f858069d21111f0dbea510044593f89c9b0829
   1.345 +.Ci 0503a6e9be34f24858b55b555a5c948182b9f24b
   1.346 +.Ci 27826f9353e0f0b04590b7d0f8f83e60462b90f0
   1.347 +.Ci d1da1f94ce62160aebb30df4063ccbc53768656b
   1.348 +.Ci c42222869e318fff5dec395eca3e776db3075455
   1.349  .P
   1.350  .\" XXX move this paragraph up somewhere
   1.351  One disadvantage needs to be taken with this change: