# HG changeset patch # User markus schnalke # Date 1341931743 -7200 # Node ID 346ff7e201f56052a492f5c1099a4859304f336b # Parent 97461b0b34d2d366467e3b30f5d05347e7edc93c Applied suggestions by Boris. diff -r 97461b0b34d2 -r 346ff7e201f5 discussion.roff --- a/discussion.roff Tue Jul 10 15:58:46 2012 +0200 +++ b/discussion.roff Tue Jul 10 16:49:03 2012 +0200 @@ -6,7 +6,7 @@ The concrete work undertaken is described in the examples of how the general goals were achieved. The discussion compares the current version of mmh with the state of -nmh just before the mmh project started, i.e. Fall 2011. +nmh just before the mmh project started, i.e. fall 2011. Current changes of nmh will be mentioned only as side notes. .\" XXX where do I discuss the parallel development of nmh? @@ -45,6 +45,7 @@ .P The limiting resource in the community development of Free Software is usually man power. +.\" XXX FIXME ref! If the development power is spread over a large development area, it becomes even more difficult to compete with the specialists in the various fields. @@ -189,7 +190,7 @@ .[[ brooks no silver bullet .]]) -Email systems reacted to this change: They grew. +Email systems reacted to this change: they grew. RFCs started to introduce the concept of mail agents to separate the various tasks because they became more extensive and new tasks appeared. As the mail systems grew even more, parts were split off. @@ -206,13 +207,13 @@ .P .\" XXX ueberleitung ??? Functionality can be added in three different ways: -.BU +.LI 1 Implementing the function in the project itself. -.BU +.LI 2 Depending on a library that provides the function. -.BU +.LI 3 Depending on a program that provides the function. -.P +.LP .\" XXX Rework sentence While implementing the function in the project itself leads to the largest increase in code size and requires the most maintenance @@ -602,7 +603,7 @@ It allows better suiting setups, but not for free. There is the cost of code complexity to be able to customize. There is the cost of less tested setups, because there are -more possible setups and especially corner-cases. +more possible setups and especially corner cases. Additionally, there is the cost of choice itself. The code complexity directly affects the developers. Less tested code affects both, users and developers. @@ -756,41 +757,41 @@ if they are set. Today, mmh determines the editor to use in the following order, taking the first available and non-empty item: -.IP (1) +.LI 1 Environment variable .Ev MMHEDITOR -.IP (2) +.LI 2 Profile entry .Pe Editor -.IP (3) +.LI 3 Environment variable .Ev VISUAL -.IP (4) +.LI 4 Environment variable .Ev EDITOR -.IP (5) +.LI 5 Command .Pn vi . -.P +.LP .Ci f85f4b7ae62e3d05a945dcd46ead51f0a2a89a9b .P The pager to use is determined in a similar order, also taking the first available and non-empty item: -.IP (1) +.LI 1 Environment variable .Ev MMHPAGER -.IP (2) +.LI 2 Profile entry .Pe Pager (replaces .Pe moreproc ) -.IP (3) +.LI 3 Environment variable .Ev PAGER -.IP (4) +.LI 4 Command .Pn more . -.P +.LP .Ci 0c4214ea2aec6497d0d67b436bbee9bc1d225f1e .P By respecting the @@ -989,7 +990,8 @@ .H2 "Command Line Switches .P -The command line switches of MH tools follow the X Window style. +The command line switches of MH tools is similar to the X Window style. +.\" XXX ref They are words, introduced by a single dash. For example: .Cl "-truncate" . @@ -1462,13 +1464,9 @@ .Sw -mbox is the sole behavior now. .Ci 3916ab66ad5d183705ac12357621ea8661afd3c0 -In the same go, -.Pn packf -and -.Pn rcvpack -were reworked and their +Further rework in both tools made the .Sw -file -switch became unnecessary. +switch unnecessary. .Ci ca1023716d4c2ab890696f3e41fa0d94267a940e .BU @@ -2141,11 +2139,11 @@ .Sw -auto is not dangerous anymore. Two changes were necessary: -.BU +.LI 1 Any directory path is removed from the proposed filename. Thus, the files are always stored in the expected directory. .Ci 41b6eadbcecf63c9a66aa5e582011987494abefb -.BU +.LI 2 Tar files are not extracted automatically any more. Thus, the rest of the file system will not be touched. .Ci 94c80042eae3383c812d9552089953f9846b1bb6 @@ -2408,8 +2406,8 @@ .Pn send will refuse to encrypt and send it. Currently, messages with hidden (BCC) recipients can not be encrypted. -This corner-case requires a more complex solution. -Covering it is left to do. +This work is pending because it requires a structurally more complex +approach. .P The integrated message signing and encrypting support is one of the most recent features in mmh. @@ -2474,13 +2472,13 @@ On composing a message, this draft file was used. When starting to compose another message before the former one was sent, the user had to decide among: -.BU +.LI 1 Using the old draft to finish and send it before starting with a new one. -.BU +.LI 2 Discarding the old draft and replacing it with a new one. -.BU +.LI 3 Preserving the old draft by refiling it to a folder. -.P +.LP It was only possible to work in alternation on multiple drafts. Therefore, the current draft needed to be refiled to a folder and another one re-used for editing. @@ -2509,7 +2507,7 @@ Its messages can be listed like any other messages. A draft message is no longer a special case. Tools do not need special switches to work on the draft message. -Hence corner-cases were removed. +Hence corner cases were removed. .P The trivial part of the work was activating the draft folder with a default name. @@ -2543,13 +2541,13 @@ still has .Sw -[no]use for switching between two modes: -.BU +.LI 1 .Sw -use to modify an existing draft. -.BU +.LI 2 .Sw -nouse to compose a new draft, possibly taking some existing message as template. -.P +.LP In either case, the behavior of .Pn comp is deterministic. @@ -2814,7 +2812,7 @@ .BU Forwarding messages using MIME. .Ci 6e271608b7b9c23771523f88d23a4d3593010cf1 -.P +.LP In consequence, a setup with a profile that defines only the path to the mail storage, is already convenient to use. Again, Paul Vixie's ``edginess'' call supports the direction I took: @@ -3080,10 +3078,9 @@ .Sw -delete , but not with .Sw -list . -In the former case it is even necessary. .P -Trying to fix these problems on the surface would not have solved it truly. -The problems discovered originate from a discrepance between the semantic +Trying to fix these problems on the surface would not have solved +them truly, as they originate from a discrepance between the semantic structure of the problem and the structure implemented in the program. Such structural differences can not be cured on the surface. They need to be solved by adjusting the structure of the implementation @@ -3105,7 +3102,7 @@ Historically, .Pn anno had only one operation mode: adding header fields. -With the extension, it got two moder modes: +With the extension, it got two more modes: listing and deleting header fields. The structure of the code changes did not pay respect to this fundamental change to @@ -3168,19 +3165,19 @@ .U3 "Path Conversion .P Four kinds of path names can appear in MH: -.IP (1) +.LI 1 Absolute Unix directory paths, like .Fn /etc/passwd . -.IP (2) +.LI 2 Relative Unix directory paths, like .Fn ./foo/bar . -.IP (3) +.LI 3 Absolute MH folder paths, like .Fn +friends/phil . -.IP (4) +.LI 4 Relative MH folder paths, like .Fn @subfolder . -.P +.LP The last type, relative MH folder paths, are hardly documented. Nonetheless, they are useful for large mail storages. The current mail folder is specified as `\c @@ -3206,7 +3203,7 @@ VE .P My investigation provides the following description: -.BU +.LI 1 The second parameter of .Fu path() defines the type of path given as first parameter. @@ -3215,14 +3212,14 @@ Folder paths must not include a leading `@' character. Leading plus characters are preserved. The result is a pointer to newly allocated memory. -.BU +.LI 2 .Fu pluspath() is a convenience-wrapper to .Fu path() , to convert folder paths only. This function can not be used for directory paths. An empty string parameter causes a buffer overflow. -.BU +.LI 3 .Fu m_mailpath() converts directory paths to absolute directory paths. The characters `+' or `@' at the beginning of the path name are @@ -3230,7 +3227,7 @@ Hence, this function can not be used for folder paths. In any case, the result is an absolute directory path. The result is a pointer to newly allocated memory. -.BU +.LI 4 .Fu m_maildir() returns the parameter unchanged if it is an absolute directory path or begins with the entry `.' or `..'. @@ -3269,20 +3266,20 @@ current message. .Ci cff0e16925e7edbd25b8b9d6d4fbdf03e0e60c01 Third, I created three new functions to replace the previous mess: -.BU +.LI 1 .Fu expandfol() converts folder paths to absolute folder paths, without the leading plus character. Directory paths are simply passed through. This function is to be used for folder paths only, thus the name. The result is a pointer to static memory. -.BU +.LI 2 .Fu expanddir() converts directory paths to absolute directory paths. Folder paths are treated as relative directory paths. This function is to be used for directory paths only, thus the name. The result is a pointer to static memory. -.BU +.LI 3 .Fu toabsdir() converts any type of path to an absolute directory path. This is the function of choice for path conversion. @@ -3485,7 +3482,7 @@ when you run a command by hand, then you want your own defaults... .QE .LP -Yet, I consider this explanation short-sighted. +Yet, I consider this explanation shortsighted. We should rather regard theses two cases as just two different MH setups, based on two different profiles. Mapping such problems on the concepts of switching between different @@ -3745,7 +3742,7 @@ in the first place, I did it now. .P Personal mmh data is grouped by type, resulting in two distinct parts: -The mail storage and the configuration. +the mail storage and the configuration. In mmh, the mail storage directory still contains all the messages, but, in exception of public sequences files, nothing else. In difference to nmh, the auxiliary configuration files are no longer @@ -3925,8 +3922,8 @@ and .Fu exec() , two expensive system calls. -Whereis this approach improved the time performance, -it interweaved the source code. +Whereas this approach improved the time performance, +it interwove the source code. Core functionalities were not encapsulated into programs but into function, which were then wrapped by programs. For example, @@ -3969,13 +3966,9 @@ .P As I have read a lot in the code base during the last two years, I learned about the easy and the difficult parts. -Code is easy to understand if: -.BU -The influenced code area is small. -.BU -The boundaries are strictly defined. -.BU -The code is written straight-forward. +Code is easy to understand if the influenced code area is small +and its boundaries are strictly defined. +Further more, the code needs to solve the problem in a straight-forward way. .P .\" XXX move this paragraph somewhere else? Reading @@ -4109,7 +4102,7 @@ As this is a manual task and regression tests, which could detect such problems, are not available yet, it is prone to errors. These errors will not be detected at compile time but at run time. -Installing regression tests is a task left to do. +Installing regression tests is a pending task. In the best case, a uniform way of invoking tools from other tools can be developed to allow automated testing at compile time. diff -r 97461b0b34d2 -r 346ff7e201f5 intro.roff --- a/intro.roff Tue Jul 10 15:58:46 2012 +0200 +++ b/intro.roff Tue Jul 10 16:49:03 2012 +0200 @@ -64,7 +64,7 @@ Today, nmh has almost completely replaced the original MH. Some systems might still provide old MH, but mainly for historical reasons. .P -In the last years, the work on nmh was mostly maintenance work. +In the last years, the changes in nmh were mostly maintenance work. However, the development was revived in December 2011 and stayed busy since then. @@ -200,16 +200,16 @@ .P Despite the separation of the tool chest approach at the surface \(en a collection of small, separate programs \(en -on the source code level, it is much more interweaved. +on the source code level, it is much more interwoven. Several separate components were compiled into one program for efficiency reasons. This led to intricate innards. While clearly separated on the outside, -the programs turned out to be fairly interweaved inside. +the programs turned out to be fairly interwoven inside. .\" XXX FIXME rewrite... -.\" nicht zweimal ``interweaved'' +.\" nicht zweimal ``interwoven'' .\" Unfortunately, the clear separation on the outside turned out to be -.\" fairly interweaved inside. +.\" fairly interwoven inside. .P The advent of MIME raised the complexity of email by a magnitude. This is visible in nmh. The MIME-related parts are the most complex ones. @@ -224,9 +224,10 @@ to be able to use them. This puts a burden on new users, because out-of-the-box nmh remains in the same ancient style. -If nmh is seen to be a back-end, then this compatibility surely is important. -However, in the same go, new users have difficulties using nmh for modern -emailing. +If nmh is seen to be a back-end, +then this compatibility surely is important. +However, at the same time, new users have difficulties using nmh for +modern emailing. The small but mature community around nmh needs few change as they have had their convenient setups for decades. .\" XXX Explain more @@ -381,7 +382,7 @@ .IP "Streamlining Mmh should be stripped down to its core, which is the user agent (MUA). The feature set should be distilled to the indispensable ones, -effectively removing corner-cases. +effectively removing corner cases. Parts that don't add to the main task of being a conceptionally appealing MUA should be removed. This includes the mail submission and mail retrieval facilities. diff -r 97461b0b34d2 -r 346ff7e201f5 preface.roff --- a/preface.roff Tue Jul 10 15:58:46 2012 +0200 +++ b/preface.roff Tue Jul 10 16:49:03 2012 +0200 @@ -1,7 +1,7 @@ .H0 "Preface" no .P -I have discovered the mail client \fInmh\fP in Fall 2009. +I have discovered the mail client \fInmh\fP in fall 2009. At that time I used \fImutt\fP, as many advanced Unix users do. When I read about nmh, its concepts convinced me at once. The transition from mutt to nmh was similar to beginning with @@ -22,12 +22,12 @@ expectations were rather common for modern emailing. As a computer scientist and programmer, I wanted to improve the situation. .P -In Spring 2010, I sent a message to the \fInmh-workers\fP mailing list, +In spring 2010, I sent a message to the \fInmh-workers\fP mailing list, asking for the possibility to offer a Google Summer of Code project for me. Participating in the development of nmh in this manner appeared attractive to me, because I would have been able to work full time on nmh. Although the nmh community had reacted generally positive to the suggestion, -the administrative work for a GSoC project would had been too much. +the administrative work for such a project would had been too much. Nonetheless, my proposal had activated the nmh community. In the following weeks, goals for nmh's future were discussed. In these discussions, I became involved in the @@ -59,7 +59,7 @@ was simply set too high. Instead, I improved the code base as I read through it. I found minor bugs for which I proposed fixes. -In the same go, I improved the documentation in minor ways. +Additionally, I improved the documentation in minor ways. When I started with larger code changes, I had to discover that the community was reluctant to change. Its wish for compatibility was much stronger than its @@ -89,6 +89,7 @@ .P This document explains the design goals and implementation decisions for mmh. +.\" XXX mmh taucht hier zum ersten mal auf. It discusses technical, historical, social and philosophical considerations. On the technical side, this document explains how an existing project was streamlined by removing rough edges @@ -202,7 +203,8 @@ a look into the future of the mmh project. .P .I "Italic font -is used to emphasize new terms. +is used to emphasize new terms, and to name software projects and +man pages. .CW "Constant width font is used to denote names of programs, files, functions, command lines, code excrepts, program input and output.