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  

     2.1 --- a/intro.roff	Tue Jul 10 15:58:46 2012 +0200
     2.2 +++ b/intro.roff	Tue Jul 10 16:49:03 2012 +0200
     2.3 @@ -64,7 +64,7 @@
     2.4  Today, nmh has almost completely replaced the original MH.
     2.5  Some systems might still provide old MH, but mainly for historical reasons.
     2.6  .P
     2.7 -In the last years, the work on nmh was mostly maintenance work.
     2.8 +In the last years, the changes in nmh were mostly maintenance work.
     2.9  However, the development was revived in December 2011
    2.10  and stayed busy since then.
    2.11  
    2.12 @@ -200,16 +200,16 @@
    2.13  .P
    2.14  Despite the separation of the tool chest approach at the surface
    2.15  \(en a collection of small, separate programs \(en
    2.16 -on the source code level, it is much more interweaved.
    2.17 +on the source code level, it is much more interwoven.
    2.18  Several separate components were compiled into one program
    2.19  for efficiency reasons.
    2.20  This led to intricate innards.
    2.21  While clearly separated on the outside,
    2.22 -the programs turned out to be fairly interweaved inside.
    2.23 +the programs turned out to be fairly interwoven inside.
    2.24  .\" XXX FIXME rewrite...
    2.25 -.\" nicht zweimal ``interweaved''
    2.26 +.\" nicht zweimal ``interwoven''
    2.27  .\" Unfortunately, the clear separation on the outside turned out to be
    2.28 -.\" fairly interweaved inside.
    2.29 +.\" fairly interwoven inside.
    2.30  .P
    2.31  The advent of MIME raised the complexity of email by a magnitude.
    2.32  This is visible in nmh. The MIME-related parts are the most complex ones.
    2.33 @@ -224,9 +224,10 @@
    2.34  to be able to use them.
    2.35  This puts a burden on new users, because out-of-the-box nmh remains
    2.36  in the same ancient style.
    2.37 -If nmh is seen to be a back-end, then this compatibility surely is important.
    2.38 -However, in the same go, new users have difficulties using nmh for modern
    2.39 -emailing.
    2.40 +If nmh is seen to be a back-end,
    2.41 +then this compatibility surely is important.
    2.42 +However, at the same time, new users have difficulties using nmh for
    2.43 +modern emailing.
    2.44  The small but mature community around nmh needs few change
    2.45  as they have had their convenient setups for decades.
    2.46  .\" XXX Explain more
    2.47 @@ -381,7 +382,7 @@
    2.48  .IP "Streamlining
    2.49  Mmh should be stripped down to its core, which is the user agent (MUA).
    2.50  The feature set should be distilled to the indispensable ones,
    2.51 -effectively removing corner-cases.
    2.52 +effectively removing corner cases.
    2.53  Parts that don't add to the main task of being a conceptionally
    2.54  appealing MUA should be removed.
    2.55  This includes the mail submission and mail retrieval facilities.

     3.1 --- a/preface.roff	Tue Jul 10 15:58:46 2012 +0200
     3.2 +++ b/preface.roff	Tue Jul 10 16:49:03 2012 +0200
     3.3 @@ -1,7 +1,7 @@
     3.4  .H0 "Preface" no
     3.5  
     3.6  .P
     3.7 -I have discovered the mail client \fInmh\fP in Fall 2009.
     3.8 +I have discovered the mail client \fInmh\fP in fall 2009.
     3.9  At that time I used \fImutt\fP, as many advanced Unix users do.
    3.10  When I read about nmh, its concepts convinced me at once.
    3.11  The transition from mutt to nmh was similar to beginning with
    3.12 @@ -22,12 +22,12 @@
    3.13  expectations were rather common for modern emailing.
    3.14  As a computer scientist and programmer, I wanted to improve the situation.
    3.15  .P
    3.16 -In Spring 2010, I sent a message to the \fInmh-workers\fP mailing list,
    3.17 +In spring 2010, I sent a message to the \fInmh-workers\fP mailing list,
    3.18  asking for the possibility to offer a Google Summer of Code project for me.
    3.19  Participating in the development of nmh in this manner appeared attractive
    3.20  to me, because I would have been able to work full time on nmh.
    3.21  Although the nmh community had reacted generally positive to the suggestion,
    3.22 -the administrative work for a GSoC project would had been too much.
    3.23 +the administrative work for such a project would had been too much.
    3.24  Nonetheless, my proposal had activated the nmh community.
    3.25  In the following weeks, goals for nmh's future were discussed.
    3.26  In these discussions, I became involved in the
    3.27 @@ -59,7 +59,7 @@
    3.28  was simply set too high.
    3.29  Instead, I improved the code base as I read through it.
    3.30  I found minor bugs for which I proposed fixes.
    3.31 -In the same go, I improved the documentation in minor ways.
    3.32 +Additionally, I improved the documentation in minor ways.
    3.33  When I started with larger code changes,
    3.34  I had to discover that the community was reluctant to change.
    3.35  Its wish for compatibility was much stronger than its
    3.36 @@ -89,6 +89,7 @@
    3.37  .P
    3.38  This document explains the design goals and implementation decisions
    3.39  for mmh.
    3.40 +.\" XXX mmh taucht hier zum ersten mal auf.
    3.41  It discusses technical, historical, social and philosophical considerations.
    3.42  On the technical side, this document
    3.43  explains how an existing project was streamlined by removing rough edges
    3.44 @@ -202,7 +203,8 @@
    3.45  a look into the future of the mmh project.
    3.46  .P
    3.47  .I "Italic font
    3.48 -is used to emphasize new terms.
    3.49 +is used to emphasize new terms, and to name software projects and
    3.50 +man pages.
    3.51  .CW "Constant width font
    3.52  is used to denote names of programs, files,
    3.53  functions, command lines, code excrepts, program input and output.