docs/master: discussion.roff comparison

comparison discussion.roff @ 179:b59201e345e5

Applied further corrections by Aaron.

author	markus schnalke <meillo@marmaro.de>
date	Tue, 10 Jul 2012 23:13:45 +0200
parents	520b3c7abba1
children	731e747a805b

comparison

equal deleted inserted replaced

-:520b3c7abba1
+:b59201e345e5
 I explained my reasons in the commit messages
 in the version control system.
 Hence, others can comprehend my view and argue for undoing the change
 if I have missed an important aspect.
 I was quick in dropping parts.
-I rather re-included falsely dropped parts than going at a slower pace.
+I rather include falsely dropped parts again, than going at a slower pace.
-Mmh is experimental work; it required tough decisions.
+Mmh is experimental work; it requires tough decisions.
 .\" XXX ``exp. work'' schon oft gesagt
 .U3 "Forking
 .P
 Drafts with attachment headers are converted to MIME automatically by
 .Pn send .
 The conversion to MIME is invisible to the user.
 The draft stored in the draft folder is always in source form with
 attachment headers.
-If the MIMEification fails, for instance because the file to attach
+If the MIMEification fails (e.g. because the file to attach
-is not accessible, the original draft is not changed.
+is not accessible) the original draft is not changed.
 .P
 The attachment system handles the forwarding of messages, too.
 If the attachment header value starts with a plus character (`\fL+\fP'),
 like in
 .Cl "Attach: +bob 30 42" ,
 If the user did not call `mime', a broken message would be sent.
 Therefore, the
 .Pe automimeproc
 profile entry could be specified to have the `mime' command invoked
 automatically each time.
-Unfortunately, this approach conflicted with attachment system
+Unfortunately, this approach conflicted with the attachment system
 because the draft would already be in MIME format at the time
 when the attachment system wanted to MIMEify it.
 To use nmh's attachment system, `mime' must not be called at the
 WhatNow prompt and
 .Pe automimeproc
 This is a difficult task, yet it spares the user irritating work.
 Determining the correct MIME type of content is partly mechanical,
 partly intelligent work.
 Forcing the user to find out the correct MIME type,
 forces him to do partly mechanical work.
-Letting the computer do the work, can lead to bad choices for difficult
+Letting the computer do the work can lead to bad choices for difficult
 content.
 For mmh, the latter option was chosen.
 .P
 Determining the MIME type by the suffix of the file name is a dumb
 approach, yet it is simple to implement and provides good results
 .P
 One should note that this section completely ignores the original
 .Pn show
 program, because it was not capable to display MIME messages
 and is no longer part of mmh.
+.\" XXX ref to other section
 Although
 .Pn mhshow
 was renamed to
 .Pn show
 in mmh, this section uses the name
 .Pn mhshow ,
 in order to avoid confusion.
-.\" XXX ref to other section
 .P
 In mmh, the basic idea is that
 .Pn mhshow
 should display a message in one single pager session.
 Therefore,
 .Ci d0581ba306a7299113a346f9b4c46ce97bc4cef6
 This could already be requested with the, now removed,
 .Sw -serialonly
 switch of
 .Pn mhshow .
-As MIME parts are always processed exclusively , i.e. serially,
+As MIME parts are always processed exclusively, i.e. serially,
 the `%e' escape in
 .Pe mhshow-show-*
 profile entries became useless and was thus removed.
 .Ci a20d405db09b7ccca74d3e8c57550883da49e1ae
 .P
 Unless they are strongly convinced of the concepts, they will fail.
 I have seen friends of me giving up disappointed
 before they truly used the system,
 although they had been motivated in the beginning.
 They suffer hard enough to get used to the tool chest approach,
-we should spare them further inconveniences.
+we developers should spare them further inconveniences.
 .P
 Maintaining compatibility for its own sake is bad,
 because the code base collects more and more compatibility code.
 Sticking to the compatiblity code means remaining limited;
 whereas adjusting to the changes renders the compatibility unnecessary.
 .H2 "Modularization
 .P
 The source code of the mmh tools is located in the
 .Fn uip
 (``user interface programs'') directory.
-Each tools has a source file with the same name.
+Each tools has a source file with the name of the command.
 For example,
 .Pn rmm
 is built from
 .Fn uip/rmm.c .
 Some source files are used for multiple programs.
 Splitting the source code of a large program into multiple files can
 increase the readability of its source code.
 Most of the mmh tools, however, are simple and straight-forward programs.
 With the exception of the MIME handling tools,
 .Pn pick
-is the largest tools.
+is the largest tool.
 It contains 1\|037 lines of source code (measured with
 .Pn sloccount ), excluding the MH library.
 Only the MIME handling tools (\c
 .Pn mhbuild ,
 .Pn mhstore ,
 are larger.
 Splitting programs with less than 1\|000 lines of code into multiple
 source files seldom leads to better readability.
 For such tools, splitting makes sense
 when parts of the code are reused in other programs,
-and the reused code fragment is not general enough
+and the reused code fragment is (1) not general enough
-for including it in the MH library,
+for including it in the MH library
-or, if the code has dependencies on a library that only few programs need.
+or (2) has dependencies on a library that only few programs need.
 .Fn uip/packsbr.c ,
 for instance, provides the core program logic for the
 .Pn packf
 and
 .Pn rcvpack
 because
 .Pn comp
 does annotate and send messages.
 In nmh, there surely exists the tool
 .Pn send ,
-which does (almost) only send messages.
+which does mainly send messages.
 But
 .Pn comp
 and
 .Pn repl
 and
 .Pn dist
 and
 .Pn whatnow
 and
 .Pn viamail ,
-they all (!) have the same message sending function included, too.
+they all (!) have the same message sending function included, as well.
 In result,
 .Pn comp
 sends messages without using
 .Pn send .
 The situation is the same as if

Mercurial > docs > master

comparison discussion.roff @ 179:b59201e345e5