1.1 --- a/discussion.roff	Tue Jun 26 17:01:35 2012 +0200
     1.2 +++ b/discussion.roff	Tue Jun 26 22:06:20 2012 +0200
     1.3 @@ -1900,7 +1900,7 @@
     1.4  In nmh, this could have been ensured statically with the
     1.5  .Sw -nomoreproc
     1.6  at the command line, too.
     1.7 -In mmh, seting the profile entry
     1.8 +In mmh, setting the profile entry
     1.9  .Pe Pager
    1.10  or the environment variable
    1.11  .Ev PAGER
    1.12 @@ -2060,7 +2060,7 @@
    1.13  Because the resulting draft does neither contain non-ASCII characters
    1.14  nor has it attachment headers, the attachment system will not touch it.
    1.15  .P
    1.16 -The approach taken in mmh is taylored towards todays most common case:
    1.17 +The approach taken in mmh is tailored towards todays most common case:
    1.18  a text part with possibly attachments.
    1.19  This case is simplified a lot for users.
    1.20  
    1.21 @@ -2338,7 +2338,7 @@
    1.22  Therefore,
    1.23  .Pe mhshow-charset-*
    1.24  profile entries used to be needed.
    1.25 -In mmh, the convertion is done automatically by piping the text through
    1.26 +In mmh, the conversion is done automatically by piping the text through
    1.27  the
    1.28  .Pn iconv
    1.29  command, if necessary.
    1.30 @@ -2349,7 +2349,7 @@
    1.31  .Cl "iconv -f %c %f |
    1.32  prefix to have the text converted to the native charset.
    1.33  .P
    1.34 -Although the convertion of foreign charsets to the native one
    1.35 +Although the conversion of foreign charsets to the native one
    1.36  has improved, it is not consistent enough.
    1.37  Further work needs to be done and
    1.38  the basic concepts in this field need to be re-thought.
    1.39 @@ -2414,7 +2414,7 @@
    1.40  If I would have installed nmh from source back then, I could agree.
    1.41  Yet, I had used a prepackaged version and had expected that it would
    1.42  just work.
    1.43 -Nevertheless, I had been conviced by the concepts of MH already
    1.44 +Nevertheless, I had been convinced by the concepts of MH already
    1.45  and I am a software developer,
    1.46  still I required a lot of time to discover the cool features.
    1.47  How can we expect users to be even more advanced than me,
    1.48 @@ -2508,7 +2508,7 @@
    1.49  Programmers have always argued about the layout of programs,
    1.50  but the specific style is much less important than its consistent
    1.51  application.
    1.52 -Pick one style, preferibly ours, use it consistently, and don't waste
    1.53 +Pick one style, preferably ours, use it consistently, and don't waste
    1.54  time arguing.
    1.55  .QE
    1.56  .P
    1.57 @@ -2526,8 +2526,8 @@
    1.58  programs to ensure the correct mixture of leading tabs and spaces.
    1.59  The simple rules are: (1) Leading whitespace must consist of tabs only.
    1.60  (2) Any other whitespace should consist of spaces.
    1.61 -These two rules ensure the integrity of the visual appearence.
    1.62 -Although reformating existing code should be avoided, I did it.
    1.63 +These two rules ensure the integrity of the visual appearance.
    1.64 +Although reformatting existing code should be avoided, I did it.
    1.65  I did not waste time arguing; I just did it.
    1.66  .Ci a485ed478abbd599d8c9aab48934e7a26733ecb1
    1.67  
    1.68 @@ -2620,7 +2620,7 @@
    1.69  The clarity improvement of the change showed detours in the program logic
    1.70  of related code parts.
    1.71  Having the new variables with descriptive names, a more
    1.72 -staight forward implementation became appearant.
    1.73 +straight forward implementation became apparent.
    1.74  Before the clarification was done,
    1.75  the possibility to improve had not be seen.
    1.76  .Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723
    1.77 @@ -2629,9 +2629,9 @@
    1.78  .P
    1.79  At the end of their chapter on style,
    1.80  Kernighan and Pike ask: ``But why worry about style?''
    1.81 -The following description of my rework of
    1.82 +The following example of my rework of
    1.83  .Pn anno
    1.84 -should give answers.
    1.85 +provides an answer why style is important in the first place.
    1.86  .P
    1.87  Until 2002,
    1.88  .Pn anno
    1.89 @@ -2663,9 +2663,11 @@
    1.90  and
    1.91  .Sw -number ,
    1.92  the last one taking an argument.
    1.93 +.Ci 7480dbc14bc90f2d872d434205c0784704213252
    1.94  Later,
    1.95  .Sw -[no]preserve
    1.96  was added.
    1.97 +.Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f
    1.98  Then, the Synopsis section of the man page
    1.99  .Mp anno (1)
   1.100  read:
   1.101 @@ -2684,7 +2686,7 @@
   1.102  .Cl "anno -list -number l:5
   1.103  did not work on the last five messages but failed with the misterious
   1.104  error message: ``anno: missing argument to -list''.
   1.105 -Yet, the invokation matched the specification in the man page.
   1.106 +Yet, the invocation matched the specification in the man page.
   1.107  There, the correct use of
   1.108  .Sw -number
   1.109  was defined as being
   1.110 @@ -2752,39 +2754,36 @@
   1.111  .Ci d54c8db8bdf01e8381890f7729bc0ef4a055ea11
   1.112  .P
   1.113  The difference is visible in both, the code and the documentation.
   1.114 -The following code excrept was replaced:
   1.115 +The following code excerpt:
   1.116  .VS
   1.117  int delete = -2;  /* delete header element if set */
   1.118  int list = 0;  /* list header elements if set */
   1.119 -
   1.120  [...]
   1.121 -
   1.122 -case DELETESW:  /* delete annotations */
   1.123 -	delete = 0;
   1.124 -	continue;
   1.125 -case LISTSW:  /* produce a listing */
   1.126 -	list = 1;
   1.127 -	continue;
   1.128 +	case DELETESW:  /* delete annotations */
   1.129 +		delete = 0;
   1.130 +		continue;
   1.131 +	case LISTSW:  /* produce a listing */
   1.132 +		list = 1;
   1.133 +		continue;
   1.134  VE
   1.135 -At its place moved the following code:
   1.136 +.LP
   1.137 +was replaced by:
   1.138  .VS
   1.139  static enum { MODE_ADD, MODE_DEL, MODE_LIST } mode = MODE_ADD;
   1.140 -
   1.141  [...]
   1.142 -
   1.143 -case DELETESW:  /* delete annotations */
   1.144 -	mode = MODE_DEL;
   1.145 -	continue;
   1.146 -case LISTSW:  /* produce a listing */
   1.147 -	mode = MODE_LIST;
   1.148 -	continue;
   1.149 +	case DELETESW:  /* delete annotations */
   1.150 +		mode = MODE_DEL;
   1.151 +		continue;
   1.152 +	case LISTSW:  /* produce a listing */
   1.153 +		mode = MODE_LIST;
   1.154 +		continue;
   1.155  VE
   1.156  .LP
   1.157 -The replacement code does not only match the problem's structure,
   1.158 -but it is easier to understand as well.
   1.159 -.P
   1.160 +The replacement code does not only reflect the problem's structure better,
   1.161 +it is easier to understand as well.
   1.162 +The same applies to the documentation.
   1.163  The man page was completely reorganized to propagate the same structure.
   1.164 -This is already visible in the Synopsis section:
   1.165 +This is visible in the Synopsis section:
   1.166  .VS
   1.167  anno [+folder] [msgs] [-component field] [-text body]
   1.168  	[-append] [-date | -nodate] [-preserve | -nopreserve]
   1.169 @@ -2797,39 +2796,158 @@
   1.170  anno -list [+folder] [msgs] [-component field] [-number]
   1.171  	[-Version] [-help]
   1.172  VE
   1.173 +.\" XXX think about explaining the -preserve rework?
   1.174  
   1.175  
   1.176  
   1.177 -.H2 "Standard Code
   1.178 +.H2 "Standard Libraries
   1.179  .P
   1.180 -POSIX
   1.181 +MH is one decade older than the POSIX and ANSI C standards.
   1.182 +Hence, MH included own implementations of functions
   1.183 +that are standardized and thus widely available today,
   1.184 +but were not back then.
   1.185 +Today, twenty years after the POSIX and ANSI C were published,
   1.186 +developers can expect system to comply with these standards.
   1.187 +In consequence, MH-specific replacements for standard functions
   1.188 +can and should be dropped.
   1.189 +Kernighan and Pike advise: ``Use standard libraries.''
   1.190 +.[ [
   1.191 +kernighan pike practice of programming
   1.192 +.], p. 196]
   1.193 +Actually, MH had followed this advice in history,
   1.194 +but it had not adjusted to the changes in this field.
   1.195 +The
   1.196 +.Fu snprintf()
   1.197 +function, for instance, was standardized with C99 and is available
   1.198 +almost everywhere because of its high usefulness.
   1.199 +In mmh, the included implementation of
   1.200 +.Fu snprintf()
   1.201 +was dropped in favor for using the one of the standard library.
   1.202 +Such decisions could limit the portability of mmh,
   1.203 +if systems don't support these standardized and widespread functions.
   1.204 +This compromise is made.
   1.205 +.P
   1.206 +I am not even thirty years old and my C and Unix experience comprises
   1.207 +only five to seven years.
   1.208 +Hence, I need to learn about the history in retrospective.
   1.209 +I have not used those ancient constructs myself.
   1.210 +I have not suffered from their incompatibilities.
   1.211 +I have not longed for standardization.
   1.212 +All my programming experience is from a time when ANSI C and POSIX
   1.213 +were well established already.
   1.214 +I have only read a lot of books about the (good) old times.
   1.215 +This puts me in a difficult positions when working with old code.
   1.216 +I needed to acquire knowledge about old code constructs and ancient
   1.217 +programming styles.
   1.218 +Other know these things by heart from their own experience.
   1.219 +.P
   1.220 +Being aware of these facts, I rather let people with more historic
   1.221 +experience solve the task of replacing ancient code constructs
   1.222 +with standardized ones.
   1.223 +Lyndon Nerenberg covered large parts of this task for the nmh project.
   1.224 +He converted project-specific functions to POSIX replacements,
   1.225 +also removing the conditionals compilation of now standardized features.
   1.226 +Often, I only needed to pull over changes from nmh into mmh.
   1.227 +These changes include many commits; these are among them:
   1.228 +.Ci 768b5edd9623b7238e12ec8dfc409b82a1ed9e2d
   1.229 +.Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 .
   1.230  
   1.231  .P
   1.232 -One part of this task was converting obsolete code constructs
   1.233 -to standard replacements.
   1.234 -As I'm not even thirty years old and have no more than seven years of
   1.235 -Unix experience, I needed to learn about the history in retrospective.
   1.236 -Older people likely have used those ancient constructs themselves
   1.237 -and have suffered from their incompatibilities and have longed for
   1.238 -standardization.
   1.239 -Unfortunately, I have only read that others had done so.
   1.240 -This put me in a much more difficult positions when working on the old
   1.241 -code.
   1.242 -I needed to recherche what other would have known by heart from
   1.243 -experience.
   1.244 -All my programming experience comes from a time past ANSI C
   1.245 -and past POSIX.
   1.246 -Although I knew about the times before, I took the
   1.247 -current state implicitly for granted most of the time.
   1.248 +During my own work, I have replaced the
   1.249 +.Fu atooi()
   1.250 +function with calls to
   1.251 +.Fu strtoul() ,
   1.252 +with the third parameter \(en the base \(en set to eight.
   1.253 +.Fu strtoul()
   1.254 +is part of C89 and thus safe to use.
   1.255 +.Ci c490c51b3c0f8871b6953bd0c74551404f840a74
   1.256  .P
   1.257 -Being aware of
   1.258 -these facts, I rather let people with more historic experience solve the 
   1.259 -task of converting the ancient code constructs to standardized ones.
   1.260 -Luckily, Lyndon Nerenberg focused on this task at the nmh project.
   1.261 -He converted large parts of the code to POSIX constructs, removing
   1.262 -the conditionals compilation for now standardized features.
   1.263 -I'm thankful for this task being solved.
   1.264 -I only pulled the changes into mmh.
   1.265 +I did remove project-included fallback implementations of
   1.266 +.Fu memmove()
   1.267 +and
   1.268 +.Fu strerror() ,
   1.269 +although Peter Maydell had re-included them into nmh in 2008
   1.270 +to support SunOS 4.
   1.271 +Nevertheless, these functions are part of ANSI C.
   1.272 +Systems that do not even provide full ANSI C support should not
   1.273 +put a load on mmh.
   1.274 +.Ci b067ff5c465a5d243ce5a19e562085a9a1a97215
   1.275 +.P
   1.276 +The
   1.277 +.Fu copy()
   1.278 +function copies the string in argument one to the location in two.
   1.279 +In contrast to
   1.280 +.Fu strcpy() ,
   1.281 +it returns a pointer to the terminating null-byte in the destination area.
   1.282 +.Fu copy()
   1.283 +was replaced with
   1.284 +.Fu strcpy() ,
   1.285 +except within
   1.286 +.Fu concat() ,
   1.287 +where
   1.288 +.Fu copy()
   1.289 +is more convenient.
   1.290 +Of course,
   1.291 +.Fu copy()
   1.292 +is locally defined in the source file of
   1.293 +.Fu concat()
   1.294 +now.
   1.295 +.Ci 552fd7253e5ee9e554c5c7a8248a6322aa4363bb
   1.296 +.P
   1.297 +The function
   1.298 +.Fu r1bindex()
   1.299 +had been a generalized version of
   1.300 +.Fu basename()
   1.301 +with minor differences.
   1.302 +As all calls to
   1.303 +.Fu r1bindex()
   1.304 +had the slash (`/') as delimiter anyway,
   1.305 +replacing
   1.306 +.Fu r1bindex()
   1.307 +with the more specific and better-named function
   1.308 +.Fu basename()
   1.309 +became desirable.
   1.310 +Unfortunately, many of the 54 calls to
   1.311 +.Fu r1bindex()
   1.312 +depended on its special behavior,
   1.313 +which differed from the POSIX specification for
   1.314 +.Fu basename() .
   1.315 +Hence,
   1.316 +.Fu r1bindex()
   1.317 +was kept but renamed to
   1.318 +.Fu mhbasename()
   1.319 +and its second argument, the delimiter, was fixed to the slash.
   1.320 +.Ci 240013872c392fe644bd4f79382d9f5314b4ea60
   1.321 +For possible uses of
   1.322 +.Fu r1bindex()
   1.323 +with a different delimiter,
   1.324 +the ANSI C function
   1.325 +.Fu strrchr()
   1.326 +provides the core functionality.
   1.327 +.P
   1.328 +The
   1.329 +.Fu ssequal()
   1.330 +function \(en apparently for ``substring equal'' \(en
   1.331 +was renamed to
   1.332 +.Fu isprefix() ,
   1.333 +because this is what it actually checks.
   1.334 +.Ci c20b4fa14515c7ab388ce35411d89a7a92300711
   1.335 +Its source file had included the following comments, no joke.
   1.336 +.VS
   1.337 +/*
   1.338 + * THIS CODE DOES NOT WORK AS ADVERTISED.
   1.339 + * It is actually checking if s1 is a PREFIX of s2.
   1.340 + * All calls to this function need to be checked to see
   1.341 + * if that needs to be changed. Prefix checking is cheaper, so
   1.342 + * should be kept if it's sufficient.
   1.343 + */
   1.344 +
   1.345 +/*
   1.346 + * Check if s1 is a substring of s2.
   1.347 + * If yes, then return 1, else return 0.
   1.348 + */
   1.349 +VE
   1.350 +
   1.351  
   1.352  
   1.353