1.1 --- a/discussion.roff	Tue Jul 10 15:58:46 2012 +0200
     1.2 +++ b/discussion.roff	Tue Jul 10 16:49:03 2012 +0200
     1.3 @@ -6,7 +6,7 @@
     1.4  The concrete work undertaken
     1.5  is described in the examples of how the general goals were achieved.
     1.6  The discussion compares the current version of mmh with the state of
     1.7 -nmh just before the mmh project started, i.e. Fall 2011.
     1.8 +nmh just before the mmh project started, i.e. fall 2011.
     1.9  Current changes of nmh will be mentioned only as side notes.
    1.10  .\" XXX where do I discuss the parallel development of nmh?
    1.11  
    1.12 @@ -45,6 +45,7 @@
    1.13  .P
    1.14  The limiting resource in the community development of Free Software
    1.15  is usually man power.
    1.16 +.\" XXX FIXME ref!
    1.17  If the development power is spread over a large development area,
    1.18  it becomes even more difficult to compete with the specialists in the
    1.19  various fields.
    1.20 @@ -189,7 +190,7 @@
    1.21  .[[
    1.22  brooks no silver bullet
    1.23  .]])
    1.24 -Email systems reacted to this change: They grew.
    1.25 +Email systems reacted to this change: they grew.
    1.26  RFCs started to introduce the concept of mail agents to separate the
    1.27  various tasks because they became more extensive and new tasks appeared.
    1.28  As the mail systems grew even more, parts were split off.
    1.29 @@ -206,13 +207,13 @@
    1.30  .P
    1.31  .\" XXX ueberleitung ???
    1.32  Functionality can be added in three different ways:
    1.33 -.BU
    1.34 +.LI 1
    1.35  Implementing the function in the project itself.
    1.36 -.BU
    1.37 +.LI 2
    1.38  Depending on a library that provides the function.
    1.39 -.BU
    1.40 +.LI 3
    1.41  Depending on a program that provides the function.
    1.42 -.P
    1.43 +.LP
    1.44  .\" XXX Rework sentence
    1.45  While implementing the function in the project itself leads to the
    1.46  largest increase in code size and requires the most maintenance
    1.47 @@ -602,7 +603,7 @@
    1.48  It allows better suiting setups, but not for free.
    1.49  There is the cost of code complexity to be able to customize.
    1.50  There is the cost of less tested setups, because there are
    1.51 -more possible setups and especially corner-cases.
    1.52 +more possible setups and especially corner cases.
    1.53  Additionally, there is the cost of choice itself.
    1.54  The code complexity directly affects the developers.
    1.55  Less tested code affects both, users and developers.
    1.56 @@ -756,41 +757,41 @@
    1.57  if they are set.
    1.58  Today, mmh determines the editor to use in the following order,
    1.59  taking the first available and non-empty item:
    1.60 -.IP (1)
    1.61 +.LI 1
    1.62  Environment variable
    1.63  .Ev MMHEDITOR
    1.64 -.IP (2)
    1.65 +.LI 2
    1.66  Profile entry
    1.67  .Pe Editor
    1.68 -.IP (3)
    1.69 +.LI 3
    1.70  Environment variable
    1.71  .Ev VISUAL
    1.72 -.IP (4)
    1.73 +.LI 4
    1.74  Environment variable
    1.75  .Ev EDITOR
    1.76 -.IP (5)
    1.77 +.LI 5
    1.78  Command
    1.79  .Pn vi .
    1.80 -.P
    1.81 +.LP
    1.82  .Ci f85f4b7ae62e3d05a945dcd46ead51f0a2a89a9b
    1.83  .P
    1.84  The pager to use is determined in a similar order,
    1.85  also taking the first available and non-empty item:
    1.86 -.IP (1)
    1.87 +.LI 1
    1.88  Environment variable
    1.89  .Ev MMHPAGER
    1.90 -.IP (2)
    1.91 +.LI 2
    1.92  Profile entry
    1.93  .Pe Pager
    1.94  (replaces
    1.95  .Pe moreproc )
    1.96 -.IP (3)
    1.97 +.LI 3
    1.98  Environment variable
    1.99  .Ev PAGER
   1.100 -.IP (4)
   1.101 +.LI 4
   1.102  Command
   1.103  .Pn more .
   1.104 -.P
   1.105 +.LP
   1.106  .Ci 0c4214ea2aec6497d0d67b436bbee9bc1d225f1e
   1.107  .P
   1.108  By respecting the
   1.109 @@ -989,7 +990,8 @@
   1.110  
   1.111  .H2 "Command Line Switches
   1.112  .P
   1.113 -The command line switches of MH tools follow the X Window style.
   1.114 +The command line switches of MH tools is similar to the X Window style.
   1.115 +.\" XXX ref
   1.116  They are words, introduced by a single dash.
   1.117  For example:
   1.118  .Cl "-truncate" .
   1.119 @@ -1462,13 +1464,9 @@
   1.120  .Sw -mbox
   1.121  is the sole behavior now.
   1.122  .Ci 3916ab66ad5d183705ac12357621ea8661afd3c0
   1.123 -In the same go,
   1.124 -.Pn packf
   1.125 -and
   1.126 -.Pn rcvpack
   1.127 -were reworked and their
   1.128 +Further rework in both tools made the
   1.129  .Sw -file
   1.130 -switch became unnecessary.
   1.131 +switch unnecessary.
   1.132  .Ci ca1023716d4c2ab890696f3e41fa0d94267a940e
   1.133  
   1.134  .BU
   1.135 @@ -2141,11 +2139,11 @@
   1.136  .Sw -auto
   1.137  is not dangerous anymore.
   1.138  Two changes were necessary:
   1.139 -.BU
   1.140 +.LI 1
   1.141  Any directory path is removed from the proposed filename.
   1.142  Thus, the files are always stored in the expected directory.
   1.143  .Ci 41b6eadbcecf63c9a66aa5e582011987494abefb
   1.144 -.BU
   1.145 +.LI 2
   1.146  Tar files are not extracted automatically any more.
   1.147  Thus, the rest of the file system will not be touched.
   1.148  .Ci 94c80042eae3383c812d9552089953f9846b1bb6
   1.149 @@ -2408,8 +2406,8 @@
   1.150  .Pn send
   1.151  will refuse to encrypt and send it.
   1.152  Currently, messages with hidden (BCC) recipients can not be encrypted.
   1.153 -This corner-case requires a more complex solution.
   1.154 -Covering it is left to do.
   1.155 +This work is pending because it requires a structurally more complex
   1.156 +approach.
   1.157  .P
   1.158  The integrated message signing and encrypting support is one of the
   1.159  most recent features in mmh.
   1.160 @@ -2474,13 +2472,13 @@
   1.161  On composing a message, this draft file was used.
   1.162  When starting to compose another message before the former one was sent,
   1.163  the user had to decide among:
   1.164 -.BU
   1.165 +.LI 1
   1.166  Using the old draft to finish and send it before starting with a new one.
   1.167 -.BU
   1.168 +.LI 2
   1.169  Discarding the old draft and replacing it with a new one.
   1.170 -.BU
   1.171 +.LI 3
   1.172  Preserving the old draft by refiling it to a folder.
   1.173 -.P
   1.174 +.LP
   1.175  It was only possible to work in alternation on multiple drafts.
   1.176  Therefore, the current draft needed to be refiled to a folder and
   1.177  another one re-used for editing.
   1.178 @@ -2509,7 +2507,7 @@
   1.179  Its messages can be listed like any other messages.
   1.180  A draft message is no longer a special case.
   1.181  Tools do not need special switches to work on the draft message.
   1.182 -Hence corner-cases were removed.
   1.183 +Hence corner cases were removed.
   1.184  .P
   1.185  The trivial part of the work was activating the draft folder with a
   1.186  default name.
   1.187 @@ -2543,13 +2541,13 @@
   1.188  still has
   1.189  .Sw -[no]use
   1.190  for switching between two modes:
   1.191 -.BU
   1.192 +.LI 1
   1.193  .Sw -use
   1.194  to modify an existing draft.
   1.195 -.BU
   1.196 +.LI 2
   1.197  .Sw -nouse
   1.198  to compose a new draft, possibly taking some existing message as template.
   1.199 -.P
   1.200 +.LP
   1.201  In either case, the behavior of
   1.202  .Pn comp
   1.203  is deterministic.
   1.204 @@ -2814,7 +2812,7 @@
   1.205  .BU
   1.206  Forwarding messages using MIME.
   1.207  .Ci 6e271608b7b9c23771523f88d23a4d3593010cf1
   1.208 -.P
   1.209 +.LP
   1.210  In consequence, a setup with a profile that defines only the path to the
   1.211  mail storage, is already convenient to use.
   1.212  Again, Paul Vixie's ``edginess'' call supports the direction I took:
   1.213 @@ -3080,10 +3078,9 @@
   1.214  .Sw -delete ,
   1.215  but not with
   1.216  .Sw -list .
   1.217 -In the former case it is even necessary.
   1.218  .P
   1.219 -Trying to fix these problems on the surface would not have solved it truly.
   1.220 -The problems discovered originate from a discrepance between the semantic
   1.221 +Trying to fix these problems on the surface would not have solved
   1.222 +them truly, as they originate from a discrepance between the semantic
   1.223  structure of the problem and the structure implemented in the program.
   1.224  Such structural differences can not be cured on the surface.
   1.225  They need to be solved by adjusting the structure of the implementation
   1.226 @@ -3105,7 +3102,7 @@
   1.227  Historically,
   1.228  .Pn anno
   1.229  had only one operation mode: adding header fields.
   1.230 -With the extension, it got two moder modes:
   1.231 +With the extension, it got two more modes:
   1.232  listing and deleting header fields.
   1.233  The structure of the code changes did not pay respect to this
   1.234  fundamental change to
   1.235 @@ -3168,19 +3165,19 @@
   1.236  .U3 "Path Conversion
   1.237  .P
   1.238  Four kinds of path names can appear in MH:
   1.239 -.IP (1)
   1.240 +.LI 1
   1.241  Absolute Unix directory paths, like
   1.242  .Fn /etc/passwd .
   1.243 -.IP (2)
   1.244 +.LI 2
   1.245  Relative Unix directory paths, like
   1.246  .Fn ./foo/bar .
   1.247 -.IP (3)
   1.248 +.LI 3
   1.249  Absolute MH folder paths, like
   1.250  .Fn +friends/phil .
   1.251 -.IP (4)
   1.252 +.LI 4
   1.253  Relative MH folder paths, like
   1.254  .Fn @subfolder .
   1.255 -.P
   1.256 +.LP
   1.257  The last type, relative MH folder paths, are hardly documented.
   1.258  Nonetheless, they are useful for large mail storages.
   1.259  The current mail folder is specified as `\c
   1.260 @@ -3206,7 +3203,7 @@
   1.261  VE
   1.262  .P
   1.263  My investigation provides the following description:
   1.264 -.BU
   1.265 +.LI 1
   1.266  The second parameter of
   1.267  .Fu path()
   1.268  defines the type of path given as first parameter.
   1.269 @@ -3215,14 +3212,14 @@
   1.270  Folder paths must not include a leading `@' character.
   1.271  Leading plus characters are preserved.
   1.272  The result is a pointer to newly allocated memory.
   1.273 -.BU
   1.274 +.LI 2
   1.275  .Fu pluspath()
   1.276  is a convenience-wrapper to
   1.277  .Fu path() ,
   1.278  to convert folder paths only.
   1.279  This function can not be used for directory paths.
   1.280  An empty string parameter causes a buffer overflow.
   1.281 -.BU
   1.282 +.LI 3
   1.283  .Fu m_mailpath()
   1.284  converts directory paths to absolute directory paths.
   1.285  The characters `+' or `@' at the beginning of the path name are
   1.286 @@ -3230,7 +3227,7 @@
   1.287  Hence, this function can not be used for folder paths.
   1.288  In any case, the result is an absolute directory path.
   1.289  The result is a pointer to newly allocated memory.
   1.290 -.BU
   1.291 +.LI 4
   1.292  .Fu m_maildir()
   1.293  returns the parameter unchanged if it is an absolute directory path
   1.294  or begins with the entry `.' or `..'.
   1.295 @@ -3269,20 +3266,20 @@
   1.296  current message.
   1.297  .Ci cff0e16925e7edbd25b8b9d6d4fbdf03e0e60c01
   1.298  Third, I created three new functions to replace the previous mess:
   1.299 -.BU
   1.300 +.LI 1
   1.301  .Fu expandfol()
   1.302  converts folder paths to absolute folder paths,
   1.303  without the leading plus character.
   1.304  Directory paths are simply passed through.
   1.305  This function is to be used for folder paths only, thus the name.
   1.306  The result is a pointer to static memory.
   1.307 -.BU
   1.308 +.LI 2
   1.309  .Fu expanddir()
   1.310  converts directory paths to absolute directory paths.
   1.311  Folder paths are treated as relative directory paths.
   1.312  This function is to be used for directory paths only, thus the name.
   1.313  The result is a pointer to static memory.
   1.314 -.BU
   1.315 +.LI 3
   1.316  .Fu toabsdir()
   1.317  converts any type of path to an absolute directory path.
   1.318  This is the function of choice for path conversion.
   1.319 @@ -3485,7 +3482,7 @@
   1.320  when you run a command by hand, then you want your own defaults...
   1.321  .QE
   1.322  .LP
   1.323 -Yet, I consider this explanation short-sighted.
   1.324 +Yet, I consider this explanation shortsighted.
   1.325  We should rather regard theses two cases as just two different MH setups,
   1.326  based on two different profiles.
   1.327  Mapping such problems on the concepts of switching between different
   1.328 @@ -3745,7 +3742,7 @@
   1.329  in the first place, I did it now.
   1.330  .P
   1.331  Personal mmh data is grouped by type, resulting in two distinct parts:
   1.332 -The mail storage and the configuration.
   1.333 +the mail storage and the configuration.
   1.334  In mmh, the mail storage directory still contains all the messages,
   1.335  but, in exception of public sequences files, nothing else.
   1.336  In difference to nmh, the auxiliary configuration files are no longer
   1.337 @@ -3925,8 +3922,8 @@
   1.338  and
   1.339  .Fu exec() ,
   1.340  two expensive system calls.
   1.341 -Whereis this approach improved the time performance,
   1.342 -it interweaved the source code.
   1.343 +Whereas this approach improved the time performance,
   1.344 +it interwove the source code.
   1.345  Core functionalities were not encapsulated into programs but into
   1.346  function, which were then wrapped by programs.
   1.347  For example,
   1.348 @@ -3969,13 +3966,9 @@
   1.349  .P
   1.350  As I have read a lot in the code base during the last two years,
   1.351  I learned about the easy and the difficult parts.
   1.352 -Code is easy to understand if:
   1.353 -.BU
   1.354 -The influenced code area is small.
   1.355 -.BU
   1.356 -The boundaries are strictly defined.
   1.357 -.BU
   1.358 -The code is written straight-forward.
   1.359 +Code is easy to understand if the influenced code area is small
   1.360 +and its boundaries are strictly defined.
   1.361 +Further more, the code needs to solve the problem in a straight-forward way.
   1.362  .P
   1.363  .\" XXX move this paragraph somewhere else?
   1.364  Reading
   1.365 @@ -4109,7 +4102,7 @@
   1.366  As this is a manual task and regression tests, which could detect such
   1.367  problems, are not available yet, it is prone to errors.
   1.368  These errors will not be detected at compile time but at run time.
   1.369 -Installing regression tests is a task left to do.
   1.370 +Installing regression tests is a pending task.
   1.371  In the best case, a uniform way of invoking tools from other tools
   1.372  can be developed to allow automated testing at compile time.
   1.373