docs/master

changeset 173:4c7db172fb59

Various corrections and improvements.
author markus schnalke <meillo@marmaro.de>
date Tue, 10 Jul 2012 17:26:05 +0200
parents 6800d594b2b7
children 35fc40a5011d
files discussion.roff intro.roff preface.roff summary.roff
diffstat 4 files changed, 43 insertions(+), 43 deletions(-) [+]
line diff
     1.1 --- a/discussion.roff	Tue Jul 10 17:20:21 2012 +0200
     1.2 +++ b/discussion.roff	Tue Jul 10 17:26:05 2012 +0200
     1.3 @@ -21,8 +21,8 @@
     1.4  provide a complete email system.
     1.5  In fundamental contrast, mmh shall be a MUA only.
     1.6  I believe that the development of all-in-one mail systems is obsolete.
     1.7 -Today, email is too complex to be fully covered by single projects.
     1.8 -Such a project won't be able to excel in all aspects.
     1.9 +Today, email is too complex to be fully covered by a single project.
    1.10 +Such a project will not be able to excel in all aspects.
    1.11  Instead, the aspects of email should be covered by multiple projects,
    1.12  which then can be combined to form a complete system.
    1.13  Excellent implementations for the various aspects of email already exist.
    1.14 @@ -43,7 +43,7 @@
    1.15  to be beaten by projects that focus only on integrating existing mail
    1.16  components to create a homogeneous system.
    1.17  .P
    1.18 -The limiting resource in the community development of Free Software
    1.19 +The limiting resource in the community development of free software
    1.20  is usually man power.
    1.21  .\" XXX FIXME ref!
    1.22  If the development power is spread over a large development area,
    1.23 @@ -154,7 +154,7 @@
    1.24  .Pn more
    1.25  or
    1.26  .Pn less
    1.27 -aren't available, appears to be ridiculous.
    1.28 +are not available, appears to be ridiculous.
    1.29  Of course, MSAs and MRAs are more complex than text pagers
    1.30  and not necessarily available but still the concept of orthogonal
    1.31  design holds: ``Write programs that do one thing and do it well.''
    1.32 @@ -274,7 +274,7 @@
    1.33  .H2 "Non-MUA Tools
    1.34  .P
    1.35  One goal of mmh is to remove the tools that are not part of the MUA's task.
    1.36 -Further more, any tools that don't significantly improve the MUA's job
    1.37 +Further more, any tools that do not significantly improve the MUA's job
    1.38  should be removed.
    1.39  Loosely related and rarely used tools distract from the lean appearance.
    1.40  They require maintenance work without adding much to the core task.
    1.41 @@ -353,7 +353,7 @@
    1.42  .Ci 916690191222433a6923a4be54b0d8f6ac01bd02
    1.43  because the tool was in conflict with the philosophy of MH.
    1.44  It provided an interactive shell to access the features of MH,
    1.45 -but it wasn't just a shell tailored to the needs of mail handling.
    1.46 +but it was not just a shell tailored to the needs of mail handling.
    1.47  Instead, it was one large program that had several MH tools built in.
    1.48  This conflicts with the major feature of MH of being a tool chest.
    1.49  .Pn msh 's
    1.50 @@ -448,14 +448,14 @@
    1.51  mapped message numbers and sequences to files and invoked
    1.52  .Pn mhl
    1.53  to have the files formatted.
    1.54 -With MIME, this approach wasn't sufficient anymore.
    1.55 +With MIME, this approach was not sufficient anymore.
    1.56  MIME messages can consist of multiple parts. Some parts are not
    1.57  directly displayable and text content might be encoded in
    1.58  foreign charsets.
    1.59  .Pn show 's
    1.60  understanding of messages and
    1.61  .Pn mhl 's
    1.62 -display capabilities couldn't cope with the task any longer.
    1.63 +display capabilities could not cope with the task any longer.
    1.64  .P
    1.65  Instead of extending these tools, additional tools were written from
    1.66  scratch and added to the MH tool chest.
    1.67 @@ -502,8 +502,7 @@
    1.68  whatever was more appropriate.
    1.69  .P
    1.70  Having two similar tools for essentially the same task is redundant.
    1.71 -Usually,
    1.72 -users wouldn't distinguish between
    1.73 +Usually, users would not distinguish between
    1.74  .Pn show
    1.75  and
    1.76  .Pn mhshow
    1.77 @@ -606,7 +605,7 @@
    1.78  more possible setups and especially corner cases.
    1.79  Additionally, there is the cost of choice itself.
    1.80  The code complexity directly affects the developers.
    1.81 -Less tested code affects both, users and developers.
    1.82 +Less tested code affects both users and developers.
    1.83  The problem of choice affects the users, for once by having to choose,
    1.84  but also by more complex interfaces that require more documentation.
    1.85  Whenever options add few advantages but increase the complexity of the
    1.86 @@ -668,28 +667,28 @@
    1.87  .P
    1.88  The backup prefix is the string that was prepended to message
    1.89  filenames to tag them as deleted.
    1.90 -By default it had been the comma character `\f(CW,\fP'.
    1.91 +By default it had been the comma character (`\fL,\fP').
    1.92  .\" XXX Zeitlich ordnen
    1.93  In July 2000, Kimmo Suominen introduced
    1.94  the configure option
    1.95  .Sw --with-hash-backup
    1.96 -to change the default to the hash symbol `\f(CW#\fP'.
    1.97 +to change the default to the hash character `\f(CW#\fP'.
    1.98  The choice was probably personal preference, because first, the
    1.99  option was named
   1.100  .Sw --with-backup-prefix.
   1.101 -and had the prefix symbol as argument.
   1.102 -But giving the hash symbol as argument caused too many problems
   1.103 +and had the prefix character as argument.
   1.104 +But giving the hash character as argument caused too many problems
   1.105  for Autoconf,
   1.106 -thus the option was limited to use the hash symbol as the default prefix.
   1.107 +thus the option was limited to use the hash character as the default prefix.
   1.108  This supports the assumption, that the choice for the hash was
   1.109  personal preference only.
   1.110 -Being related or not, words that start with the hash symbol
   1.111 +Being related or not, words that start with the hash character
   1.112  introduce a comment in the Unix shell.
   1.113  Thus, the command line
   1.114  .Cl "rm #13 #15
   1.115  calls
   1.116  .Pn rm
   1.117 -without arguments because the first hash symbol starts the comment
   1.118 +without arguments because the first hash character starts the comment
   1.119  that reaches until the end of the line.
   1.120  To delete the backup files,
   1.121  .Cl "rm ./#13 ./#15"
   1.122 @@ -933,7 +932,7 @@
   1.123  The decision to remove this username_extension masquerading was
   1.124  motivated by the fact that
   1.125  .Pn spost
   1.126 -hadn't supported it already.
   1.127 +had not supported it already.
   1.128  .Ci 2abae0bfd0ad5bf898461e50aa4b466d641f23d9
   1.129  Username extensions are possible in mmh, but less convenient to use.
   1.130  .\" XXX covered by next paragraph
   1.131 @@ -1834,7 +1833,7 @@
   1.132  .Pn mailx .
   1.133  Apparently,
   1.134  .Pn prompter
   1.135 -hadn't been touched lately.
   1.136 +had not been touched lately.
   1.137  Otherwise it's hardly explainable why it
   1.138  still offered the switches
   1.139  .Sw -erase
   1.140 @@ -1902,7 +1901,7 @@
   1.141  .\" XXX rewrite ``no idea''.
   1.142  As a result,
   1.143  MH had all the MIME features but no idea of attachments.
   1.144 -But users don't need all the MIME features,
   1.145 +But users do not need all the MIME features,
   1.146  they want convenient attachment handling.
   1.147  
   1.148  
   1.149 @@ -1975,7 +1974,7 @@
   1.150  is not accessible, the original draft is not changed.
   1.151  .P
   1.152  The attachment system handles the forwarding of messages, too.
   1.153 -If the attachment header value starts with a plus character (`+'),
   1.154 +If the attachment header value starts with a plus character (`\fL+\fP'),
   1.155  like in
   1.156  .Cl "Attach: +bob 30 42" ,
   1.157  the given messages in the specified folder will be attached.
   1.158 @@ -2014,7 +2013,7 @@
   1.159  There is no `mime' command at the WhatNow prompt anymore.
   1.160  The draft will be converted automatically to MIME when either an
   1.161  attachment header or non-ASCII text is present.
   1.162 -Furthermore, the hash character (`#') is not special any more
   1.163 +Furthermore, the hash character (`\fL#\fP') is not special any more
   1.164  at line beginnings in the draft message.
   1.165  .\" XXX REF ?
   1.166  Users need not concern themselves with the whole topic at all.
   1.167 @@ -2333,7 +2332,7 @@
   1.168  
   1.169  .P
   1.170  mhshow/mhstore: Removed support for retrieving message/external-body parts.
   1.171 -These tools won't download the contents automatically anymore. Instead,
   1.172 +These tools will not download the contents automatically anymore. Instead,
   1.173  they print the information needed to get the contents. If someone should
   1.174  really receive one of those rare message/external-body messages, he can
   1.175  do the job manually. We save nearly a thousand lines of code. That's worth
   1.176 @@ -2580,7 +2579,8 @@
   1.177  .P
   1.178  Similar to the situation for drafts is the situation for removed messages.
   1.179  Historically, a message was ``deleted'' by prepending a specific
   1.180 -\fIbackup prefix\fP, usually the comma character, to the file name.
   1.181 +\fIbackup prefix\fP, usually the comma character,
   1.182 +to the file name.
   1.183  The specific file would then be ignored by MH because only files with
   1.184  names consisting of digits only are treated as messages.
   1.185  Although files remained in the file system,
   1.186 @@ -2764,7 +2764,7 @@
   1.187  I have seen friends of me giving up disappointed
   1.188  before they truly used the system,
   1.189  although they had been motivated in the beginning.
   1.190 -They suffer hard enough to get used to the toolchest approach,
   1.191 +They suffer hard enough to get used to the tool chest approach,
   1.192  we should spare them further inconveniences.
   1.193  .P
   1.194  Maintaining compatibility for its own sake is bad,
   1.195 @@ -3115,7 +3115,7 @@
   1.196  and its documentation.
   1.197  .Ci d54c8db8bdf01e8381890f7729bc0ef4a055ea11
   1.198  .P
   1.199 -The difference is visible in both, the code and the documentation.
   1.200 +The difference is visible in both the code and the documentation.
   1.201  The following code excerpt:
   1.202  .VS
   1.203  int delete = -2;  /* delete header element if set */
   1.204 @@ -3209,7 +3209,7 @@
   1.205  defines the type of path given as first parameter.
   1.206  Directory paths are converted to absolute directory paths.
   1.207  Folder paths are converted to absolute folder paths.
   1.208 -Folder paths must not include a leading `@' character.
   1.209 +Folder paths must not include a leading `\fL@\fP' character.
   1.210  Leading plus characters are preserved.
   1.211  The result is a pointer to newly allocated memory.
   1.212  .LI 2
   1.213 @@ -3222,7 +3222,7 @@
   1.214  .LI 3
   1.215  .Fu m_mailpath()
   1.216  converts directory paths to absolute directory paths.
   1.217 -The characters `+' or `@' at the beginning of the path name are
   1.218 +The characters `\fL+\fP' or `\fL@\fP' at the beginning of the path name are
   1.219  treated literal, i.e. as the first character of a relative directory path.
   1.220  Hence, this function can not be used for folder paths.
   1.221  In any case, the result is an absolute directory path.
   1.222 @@ -3230,7 +3230,7 @@
   1.223  .LI 4
   1.224  .Fu m_maildir()
   1.225  returns the parameter unchanged if it is an absolute directory path
   1.226 -or begins with the entry `.' or `..'.
   1.227 +or begins with the entry `\fL.\fP' or `\fL..\fP'.
   1.228  All other strings are prepended with the current working directory.
   1.229  Hence, this functions can not be used for folder paths.
   1.230  The result is either an absolute directory path or a relative
   1.231 @@ -3468,7 +3468,7 @@
   1.232  With this approach, no special cases would have been introduced,
   1.233  no surprises would have been caused.
   1.234  By writing a clean-profile-wrapper, the concept could have been
   1.235 -generalized orthogonally to the whole MH toolchest.
   1.236 +generalized orthogonally to the whole MH tool chest.
   1.237  Then Rose's motivation behind the decision that
   1.238  .Pn post
   1.239  ignores the profile, as quoted by Jeffrey Honig,
   1.240 @@ -3490,7 +3490,7 @@
   1.241  .P
   1.242  In mmh, the wish to have
   1.243  .Pn mhmail
   1.244 -as as replacement for
   1.245 +as a replacement for
   1.246  .Pn mailx
   1.247  is considered obsolete.
   1.248  Mmh's
   1.249 @@ -3510,10 +3510,10 @@
   1.250  .Pn mhmail
   1.251  will be removed.
   1.252  .P
   1.253 -Every program in the mmh toolchest reads the profile.
   1.254 +Every program in the mmh tool chest reads the profile.
   1.255  The only exception is
   1.256  .Pn slocal ,
   1.257 -which is not considered part of the mmh toolchest.
   1.258 +which is not considered part of the mmh tool chest.
   1.259  This MDA is only distributed with mmh, currently.
   1.260  Mmh has no
   1.261  .Pn post
   1.262 @@ -3567,7 +3567,7 @@
   1.263  standard library.
   1.264  .Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32
   1.265  Such decisions limit the portability of mmh
   1.266 -if systems don't support these standardized and widespread functions.
   1.267 +if systems do not support these standardized and widespread functions.
   1.268  This compromise is made because mmh focuses on the future.
   1.269  .P
   1.270  I am not yet thirty years old and my C and Unix experience comprises
   1.271 @@ -3763,7 +3763,7 @@
   1.272  .Fn $HOME/.mh_profile
   1.273  but to
   1.274  .Fn $HOME/.mmh/profile .
   1.275 -Having both, the file
   1.276 +Having both the file
   1.277  .Fn $HOME/.mh_profile
   1.278  and the configuration directory
   1.279  .Fn $HOME/.mmh
   1.280 @@ -3821,7 +3821,7 @@
   1.281  Some source files are used for multiple programs.
   1.282  For example
   1.283  .Fn uip/scansbr.c
   1.284 -is used for both,
   1.285 +is used for both
   1.286  .Pn scan
   1.287  and
   1.288  .Pn inc .
   1.289 @@ -4045,7 +4045,7 @@
   1.290  .Pn more
   1.291  just because both programs are part of the same code base.
   1.292  .P
   1.293 -The clear separation on the surface \(en the toolchest approach \(en
   1.294 +The clear separation on the surface \(en the tool chest approach \(en
   1.295  is violated on the level below.
   1.296  This violation is for the sake of time performance.
   1.297  On systems where
     2.1 --- a/intro.roff	Tue Jul 10 17:20:21 2012 +0200
     2.2 +++ b/intro.roff	Tue Jul 10 17:26:05 2012 +0200
     2.3 @@ -228,7 +228,7 @@
     2.4  then this compatibility surely is important.
     2.5  However, at the same time, new users have difficulties using nmh for
     2.6  modern emailing.
     2.7 -The small but mature community around nmh needs few change
     2.8 +The small but mature community around nmh needs little change
     2.9  as they have had their convenient setups for decades.
    2.10  .\" XXX Explain more
    2.11  
    2.12 @@ -383,7 +383,7 @@
    2.13  Mmh should be stripped down to its core, which is the user agent (MUA).
    2.14  The feature set should be distilled to the indispensable ones,
    2.15  effectively removing corner cases.
    2.16 -Parts that don't add to the main task of being a conceptionally
    2.17 +Parts that do not add to the main task of being a conceptionally
    2.18  appealing MUA should be removed.
    2.19  This includes the mail submission and mail retrieval facilities.
    2.20  Choice should be reduced to the main options.
     3.1 --- a/preface.roff	Tue Jul 10 17:20:21 2012 +0200
     3.2 +++ b/preface.roff	Tue Jul 10 17:26:05 2012 +0200
     3.3 @@ -44,10 +44,10 @@
     3.4  .P
     3.5  Half a year later, starting in August 2010,
     3.6  I took one semester off to travel through Latin America.
     3.7 -During my time in Argentina, I wanted to work on Free Software.
     3.8 +During my time in Argentina, I wanted to work on free software.
     3.9  This brought me back to nmh.
    3.10  Richard Sandelman, an active nmh user, took care of the official basis.
    3.11 -Juan Granda, an Argentine Free Software developer,
    3.12 +Juan Granda, an Argentine free software developer,
    3.13  provided a computer with Internet connection.
    3.14  Thanks to them, I was able to work on nmh during my three-month
    3.15  stay in Santiago del Estero, Argentina.
     4.1 --- a/summary.roff	Tue Jul 10 17:20:21 2012 +0200
     4.2 +++ b/summary.roff	Tue Jul 10 17:26:05 2012 +0200
     4.3 @@ -74,7 +74,7 @@
     4.4  different filesystem approaches would collide with Unix.
     4.5  Nevertheless, an abstraction layer could provide a mapping from such
     4.6  storage back-ends to the MH storage format.
     4.7 -Or the mmh toolchest could be reworked to operate on a generic back-end,
     4.8 +Or the mmh tool chest could be reworked to operate on a generic back-end,
     4.9  making the MH storage format only one of many possible back-ends.
    4.10  Research in this area is highly appreciated.
    4.11  .\" XXX targeting the right problems?!