docs/master: discussion.roff comparison

comparison discussion.roff @ 168:277eeb5ba223

Applied suggestions by Lydi.

author	markus schnalke <meillo@marmaro.de>
date	Tue, 10 Jul 2012 11:46:20 +0200
parents	f102dcc06bb9
children	f4ffe121a0a2

comparison

equal deleted inserted replaced

-:4b6518242c73
+:277eeb5ba223
 .BU
 .Sw -[no]preserve
 of
 .Pn refile
-was removed because what use was it anyway?
+was removed
-Quoting nmh's man page of
+.Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
+because what use was it anyway?
+Quoting nmh's man page
 .Mp refile (1):
 .QS
 Normally when a message is refiled, for each destination
 folder it is assigned the number which is one above the current
 highest message number in that folder. Use of the
 .Pe automimeproc
 must not be set in the profile.
 But then the case of non-ASCII text without attachment headers was
 not caught.
 All in all, the solution was complex and irritating.
-My patch from December 2010 would have simplified the situation.
+My patch from December 2010
+.[
+nmh-workers attachment proposal
+.]
+would have simplified the situation.
 .P
 Mmh's current solution is even more elaborate.
 Any necessary MIMEification is done automatically.
 There is no `mime' command at the WhatNow prompt anymore.
 The draft will be converted automatically to MIME when either an
 In the beginning, MH had the concept of a draft message.
 This is the file
 .Fn draft
 in the MH directory, which is treated special.
 On composing a message, this draft file was used.
-As the draft file was one particular file, only one draft could be
-managed at any time.
 When starting to compose another message before the former one was sent,
 the user had to decide among:
 .BU
-Use the old draft to finish and send it before starting with a new one.
+Using the old draft to finish and send it before starting with a new one.
 .BU
-Discard the old draft, replacing it with the new one.
+Discarding the old draft and replacing it with a new one.
 .BU
-Preserve the old draft by refiling it to a folder.
+Preserving the old draft by refiling it to a folder.
 .P
-This was, it was only possible to work in alternation on multiple drafts.
+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-using for editing.
+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
-change anything.
+help anything.
 .P
 The draft folder facility exists to
 allow true parallel editing of drafts, in a straight forward way.
 It was introduced by Marshall T. Rose, already in 1984.
 Similar to other new features, the draft folder was inactive by default.
 by dropping the awkward draft message handling code.
 .Sw -draft
 switches were removed because operating on a draft message is no longer
 special.
 It became indistinguishable to operating on any other message.
-There is no more need to query the user for draft handling.
+.Ci 337338b404931f06f0db2119c9e145e8ca5a9860
+.P
+There is no more need to query the user for draft handling
+.Ci 2d48b455c303a807041c35e4248955f8bec59eeb .
 It is always possible to add another new draft.
 Refiling drafts is without difference to refiling other messages.
-All these special cases are gone.
+All of these special cases are gone.
 Yet, one draft-related switch remained.
 .Pn comp
 still has
 .Sw -[no]use
 for switching between two modes:
 .BU
-.Sw -use :
+.Sw -use
-Modify an existing draft.
+to modify an existing draft.
 .BU
-.Sw -nouse :
+.Sw -nouse
-Compose a new draft, possibly taking some existing message as a form.
+to compose a new draft, possibly taking some existing message as template.
 .P
 In either case, the behavior of
 .Pn comp
 is deterministic.
 .P
 Historically, a message was ``deleted'' by prepending a specific
 \fIbackup prefix\fP, usually the comma character, to the file name.
 The specific file would then be ignored by MH because only files with
 names consisting of digits only are treated as messages.
 Although files remained in the file system,
-the messages were no more visible in MH.
+the messages were no longer visible in MH.
-To truly delete them, a maintenance job is needed.
+To truly delete them, a maintenance job was needed.
-Usually a cron job is installed to delete them after a grace time.
+Usually a cron job was installed to delete them after a grace time.
 For instance:
 .VS
 find $HOME/Mail -type f -name ',*' -ctime +7 -delete
 VE
-In such a setup, the original message can be restored
+In such a setup, the original message could be restored
 within the grace time interval by stripping the
 backup prefix from the file name.
-But the user can not rely on this statement.
+But the user could not rely on this statement.
-If the last message of a folder with six messages (1-6) is removed,
+If the last message of a folder with six messages (\fL1-6\fP) was removed,
 message
 .Fn 6 ,
-becomes file
+became file
 .Fn ,6 .
-If then a new message enters the same folder, it will be given
+If then a new message entered the same folder, it would be named with
-the number one higher than the highest message.
+the number one above the highest existing message number.
-In this case the message is named
+In this case the message would be named
 .Fn 6
 then.
-If this message is removed as well,
+If this new message would be removed as well,
-then the backup of the former message gets overwritten.
+then the backup of the former message is overwritten.
-Hence, the ability to restore removed messages does not only depend on
+Hence, the ability to restore removed messages did not only depend on
 the ``sweeping cron job'' but also on the removing of further messages.
 It is undesirable to have such obscure and complex mechanisms.
-The user should be given a small set of clear assertions.
+The user should be given a small set of clear assertions, such as
 ``Removed files are restorable within a seven-day grace time.''
-is such a clear assertion.
 With the addition ``... unless a message with the same name in the
 same folder is removed before.'' the statement becomes complex.
 A user will hardly be able to keep track of any removal to know
 if the assertion still holds true for a specific file.
 In practice, the real mechanism is unclear to the user.
 (previously named
 .Pe Delete-Prog )
 was introduced very early to improve the situation.
 It could be set to any command, which would be executed to remove
 the specified messages.
-This would override the default action, described above.
+This would override the default action described above.
-Refiling the to-be-removed files to a garbage folder is the usual example.
+Refiling the to-be-removed files to a trash folder is the usual example.
 Nmh's man page
 .Mp rmm (1)
 proposes to set the
 .Pe rmmproc
 to
 .Cl "refile +d
-to move messages to the garbage folder,
+to move messages to the trash folder,
 .Fn +d ,
 instead of renaming them with the backup prefix.
 The man page proposes additionally the expunge command
 .Cl "rm `mhpath +d all`
-to empty the garbage folder.
+to empty the trash folder.
 .P
 Removing messages in such a way has advantages.
 The mail storage is prevented from being cluttered with removed messages
 because they are all collected in one place.
 Existing and removed messages are thus separated more strictly.
 To sweep it clean, the user can use
 .Cl "rmm -unlink +trash a" ,
 where the
 .Sw -unlink
 switch causes the files to be unlinked.
-.P
+.Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
-Dropping the legacy approach and completely converting to the new approach
+.Ci ca0b3e830b86700d9e5e31b1784de2bdcaf58fc5
+.P
+Dropping the legacy approach and converting to the new approach completely
 simplified the code base.
 The relationship between
 .Pn rmm
 and
 .Pn refile
 The point is not the customization of the setup,
 but the need to activate generally useful facilities.
 .P
 Yet, the real problem lies less in enabling the features, as this is
 straight forward as soon as one knows what he wants.
-The real problem is that new users need deep insights into the project
+The real problem is that new users need deep insight into the project
-before they find out what they are missing and that nmh actually
+to find out about inactive features nmh already provides.
-provides it already, it just was not activated.
 To give an example, I needed one year of using nmh
 before I became aware of the existence of the attachment system.
 One could argue that this fact disqualifies my reading of the
 documentation.
 If I would have installed nmh from source back then, I could agree.
 we 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;
-not using it renders it unnecessary.
+whereas adjusting to the changes renders the compatibility unnecessary.
-Keeping unused alternative in the code is a bad choice as they likely
+Keeping unused alternatives in the code is a bad choice as they likely
 gather bugs, by not being well tested.
 Also, the increased code size and the greater number of conditions
 increase the maintenance costs.
 If any MH implementation would be the back-end of widespread
 email clients with large user bases, compatibility would be more
 Hence, compatibility is hardly important for technical reasons.
 Its importance originates rather from personal reasons.
 Nmh's user base is small and old.
 Changing the interfaces would cause inconvenience to long-term users of MH.
 It would force them to change their many years old MH configurations.
-I do understand this aspect, but it keeps new users from using MH.
+I do understand this aspect, but by sticking to the old users,
-By sticking to the old users, new users are kept away.
+new users are kept away.
 Yet, the future lies in new users.
-Hence, mmh invites new users by providing a convenient and modern setup,
+In consequence, mmh invites new users by providing a convenient
-readily usable out-of-the-box.
+and modern setup, readily usable out-of-the-box.
 .P
 In mmh, all modern features are active by default and many previous
 approaches are removed or only accessible in manual ways.
 New default features include:
 .BU
 Forwarding messages using MIME.
 .Ci 6e271608b7b9c23771523f88d23a4d3593010cf1
 .P
 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'' appeal supports the direction I took:
+Again, Paul Vixie's ``edginess'' call supports the direction I took:
 ``the `main branch' should just be modern''.
 .[
 paul vixie edginess nmh-workers
 .]
 .QS
 Chapter 1 discusses programming style.
 Good style is so important to good programming that we have chose
 to cover it first.
 .QE
-This section covers changes in mmh that were motivated by the desire
+This section covers changes in mmh that were guided by the desire
 to improve on style.
 Many of them follow the rules given in the quoted book.
 .[
 kernighan pike practice of programming
 .]
 .Id code-style
 .P
 .U3 "Indentation Style
 .P
 Indentation styles are the holy cow of programmers.
-Again Kernighan and Pike:
+Kernighan and Pike
 .[ [
 kernighan pike practice of programming
 .], p. 10]
+wrote:
 .QS
 Programmers have always argued about the layout of programs,
 but the specific style is much less important than its consistent
 application.
 Pick one style, preferably ours, use it consistently, and don't waste
 .Pn anno
 had six functional command line switches,
 .Sw -component
 and
 .Sw -text ,
-which took an argument each,
+which have an argument each,
-and the two pairs of flags,
-.Sw -[no]date
-and
-.Sw -[no]inplace.,
-.Sw -component
-and
-.Sw -text ,
-which took an argument each,
 and the two pairs of flags,
 .Sw -[no]date
 and
 .Sw -[no]inplace .
 Then Jon Steinhart introduced his attachment system.
 All of the functions return pointers to static memory.
 All three functions are implemented in
 .Fn sbr/path.c .
 .Fn sbr/m_maildir.c
 is removed.
+.Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
 .P
 Along with the path conversion rework, I also replaced
 .Fu getfolder(FDEF)
 with
 .Fu getdeffol()
 .Fu expandfol("@") .
 This code was moved from
 .Fn sbr/getfolder.c
 to
 .Fn sbr/path.c .
+.Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
 .P
 The related function
 .Fu etcpath()
 was moved to
 .Fn sbr/path.c ,
-too.
+too
+.Ci b4c29794c12099556151d93a860ee51badae2e35 .
 Previously, it had been located in
 .Fn config/config.c ,
 for whatever reasons.
 .P
 .Fn sbr/path.c
 now contains all path handling code.
 Only 173 lines of code were needed to replace the previous 252 lines.
 The readability of the code is highly improved.
 Additionally, each of the six exported and one static functions
 is introduced by an explaining comment.
-.Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
 .H2 "Profile Reading
 and the configuration directory
 .Fn $HOME/.mmh
 appeared to be inconsistent.
 The approach chosen for mmh is consistent, simple, and familiar to
 Unix users.
-.P
+.Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
-MH allows users to have multiiple MH setups.
+.P
+MH allows users to have multiple MH setups.
 Therefore, it is necessary to select a different profile.
 The profile is the single entry point to access the rest of a
 personal MH setup.
 In nmh, the environment variable
 .Ev MH
 and
 .Ev MMHC
 override the paths to the profile and context files, respectively.
 This approach allows the set of personal configuration files to be chosen
 independently from the profile, context, and mail storage.
+.Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
 .P
 The separation of the files by type is sensible and convenient.
 The new approach has no functional disadvantages,
 as every setup I can imagine can be implemented with both approaches,
 possibly even easier with the new approach.
 other MIME handling tools.
 It seems to be worthwhile to bundle the generic MIME handling code into
 a MH-MIME library, as a companion to the MH standard library.
 This is left open for the future.
 .P
-The work already done, focussed on the non-MIME tools.
+The work already done focussed on the non-MIME tools.
 The amount of code compiled into each program was reduced.
 This eases the understanding of the code base.
 In nmh,
 .Pn comp
 was built from six source files:
 .Pn comp
 invokes
 .Pn whatnow
 which thereafter invokes
 .Pn send .
+.Ci 3df5ab3c116e6d4a2fb4bb5cc9dfc5f781825815
+.Ci c73c00bfccd22ec77e9593f47462aeca4a8cd9c0
 The clear separation on the surface is maintained on the level below.
 Human users and the tools use the same interface \(en
 annotations, for example, are made by invoking
 .Pn anno ,
 no matter if requested by programs or by human beings.
+.Ci 469a4163c2a1a43731d412eaa5d9cae7d670c48b
+.Ci aed384169af5204b8002d06e7a22f89197963d2d
+.Ci 3caf9e298a8861729ca8b8a84f57022b6f3ea742
 The decrease of tools built from multiple source files and thus
 the decrease of
 .Fn uip/*sbr.c
 files confirm the improvement.
+.Ci 9e6d91313f01c96b4058d6bf419a8ca9a207bc33
+.ci 81744a46ac9f845d6c2b9908074d269275178d2e
+.Ci f0f858069d21111f0dbea510044593f89c9b0829
+.Ci 0503a6e9be34f24858b55b555a5c948182b9f24b
+.Ci 27826f9353e0f0b04590b7d0f8f83e60462b90f0
+.Ci d1da1f94ce62160aebb30df4063ccbc53768656b
+.Ci c42222869e318fff5dec395eca3e776db3075455
 .P
 .\" XXX move this paragraph up somewhere
 One disadvantage needs to be taken with this change:
 The compiler can no longer check the integrity of the interfaces.
 By changing the command line interfaces of tools, it is

Mercurial > docs > master

comparison discussion.roff @ 168:277eeb5ba223