docs/master: discussion.roff comparison

comparison discussion.roff @ 171:346ff7e201f5

Applied suggestions by Boris.

author	markus schnalke <meillo@marmaro.de>
date	Tue, 10 Jul 2012 16:49:03 +0200
parents	f4ffe121a0a2
children	4c7db172fb59

comparison

equal deleted inserted replaced

-:97461b0b34d2
+:346ff7e201f5
 mmh project.
 It is structured along the goals set for the project.
 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?
 to be beaten by projects that focus only on integrating existing mail
 components to create a homogeneous system.
 .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.
 The concrete situation for MH-based mail systems is even tougher,
 given their small and aged community, concerning both developers and users.
 Later, the essential complexity of email increased.
 (Essential complexity is the complexity defined by the problem itself.\0
 .[[
 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.
 For instance, a POP server was included in the original MH;
 it was removed in nmh.
 that covers the field.
 Today, this is a reasonable exchange.
 .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
 and development work,
 it increases the project's independence of other software the most.
 .P
 Customization is a double-edged sword.
 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.
 The problem of choice affects the users, for once by having to choose,
 but also by more complex interfaces that require more documentation.
 and
 .Ev PAGER
 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
 .Ev VISUAL /\c
 .Ev EDITOR
 .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" .
 Every program in mmh has two generic switches:
 .Sw -help ,
 .Sw -mmdf
 switches.
 .Sw -mbox
 is the sole behavior now.
 .Ci 3916ab66ad5d183705ac12357621ea8661afd3c0
-In the same go,
+Further rework in both tools made the
-.Pn packf
-and
-.Pn rcvpack
-were reworked and their
 .Sw -file
-switch became unnecessary.
+switch unnecessary.
 .Ci ca1023716d4c2ab890696f3e41fa0d94267a940e
 .BU
 Mmh's tools will no longer clear the screen (\c
 .Pn scan 's
 mode.
 In mmh,
 .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
 .LP
 Now, the outcome of mmh's
 .Fn pgpkeys .
 Unless public keys are found for all recipients,
 .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.
+This work is pending because it requires a structurally more complex
-Covering it is left to do.
+approach.
 .P
 The integrated message signing and encrypting support is one of the
 most recent features in mmh.
 Feedback from users and the experience I will gather myself
 will direct the further development of the facility.
 .Fn draft
 in the MH directory, which is treated special.
 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.
 Working on multiple drafts at the same time was impossible.
 The usual approach of switching to a different MH context did not
 It is the more powerful and more natural concept.
 The draft folder is a folder like any other folder in MH.
 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.
 I chose the name
 .Fn +drafts
 Yet, one draft-related switch remained.
 .Pn comp
 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.
 .P
 .Pn send
 Quoting the original message in the reply.
 .Ci 67411b1f95d6ec987b4c732459e1ba8a8ac192c6
 .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:
 ``the `main branch' should just be modern''.
 .[
 .Sw -number
 switch is only necessary in combination with
 .Sw -delete ,
 but not with
 .Sw -list .
-In the former case it is even necessary.
+.P
-.P
+Trying to fix these problems on the surface would not have solved
-Trying to fix these problems on the surface would not have solved it truly.
+them truly, as they originate from a discrepance between the semantic
-The problems discovered 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
 to the structure of the problem.
 .P
 .Sw -delete
 introduce modes of operation.
 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
 .Pn anno 's
 behavior.
 .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
 .Fn @ ',
 just like the current directory is specified as `\c
 char *m_mailpath(char *);
 char *m_maildir(char *);
 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.
 Directory paths are converted to absolute directory paths.
 Folder paths are converted to absolute folder paths.
 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
 treated literal, i.e. as the first character of a relative directory path.
 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 `..'.
 All other strings are prepended with the current working directory.
 Hence, this functions can not be used for folder paths.
 prefixed with a dot character.
 In consequence, the dot character could no longer be an alias for the
 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.
 Absolute directory paths are the most general representation of a
 path name.
 when you run mh commands in a script, you want all the defaults to be
 what the man page says.
 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
 profiles, solves them once for all.
 .P
 as well.
 As the mail storage and the configuration were not separated sensibly
 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
 located there.
 Therefore, the directory is no longer called the user's \fIMH directory\fP
 This saved the need to execute these programs with
 .Fu fork()
 and
 .Fu exec() ,
 two expensive system calls.
-Whereis this approach improved the time performance,
+Whereas this approach improved the time performance,
-it interweaved the source code.
+it interwove the source code.
 Core functionalities were not encapsulated into programs but into
 function, which were then wrapped by programs.
 For example,
 .Fn uip/annosbr.c
 included the function
 but the code reader needed to read all of the code first to know which
 parts were used.
 .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:
+Code is easy to understand if the influenced code area is small
-.BU
+and its boundaries are strictly defined.
-The influenced code area is small.
+Further more, the code needs to solve the problem in a straight-forward way.
-.BU
-The boundaries are strictly defined.
-.BU
-The code is written straight-forward.
 .P
 .\" XXX move this paragraph somewhere else?
 Reading
 .Pn rmm 's
 source code in
 By changing the command line interfaces of tools, it is
 the developer's job to adjust the invocations of these tools as well.
 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.
 .ig

Mercurial > docs > master

comparison discussion.roff @ 171:346ff7e201f5