docs/master: discussion.roff comparison

comparison discussion.roff @ 164:5c01017be420

Reacted to suggestions by Aaron Mueller.

author	markus schnalke <meillo@marmaro.de>
date	Mon, 09 Jul 2012 23:42:59 +0200
parents	8b411125645d
children	ea6eec1722d1

comparison

equal deleted inserted replaced

-:0628571d32d7
+:5c01017be420
 Just to name three examples: Postfix is a specialized MTA,
 .\" XXX homepages verlinken
 Procmail is a specialized MDA, and Fetchmail is a specialized MRA.
 I believe that it is best to use such specialized tools instead of
 providing the same function again as a side-component in the project.
+.\" XXX mail agent picture here
 .P
 Doing something well, requires to focus on a small set of specific aspects.
 Under the assumption that focused development produces better results
 in the particular area, specialized projects will be superior
 in their field of focus.
 mcilroy bstj foreword
 .]
 Here, this part of the Unix philosophy was applied not only
 to the programs but to the project itself.
 In other words:
-``Develop projects that focus on one thing and do it well.''
+Develop projects that focus on one thing and do it well.
-Projects grown complex should be split for the same reasons programs grown
+Projects grown complex should be split for the same reasons programs
-complex should be split.
+grown complex should be split.
 If it is conceptionally more elegant to have the MSA and MRA as
 separate projects then they should be separated.
 This is the case here, in my opinion.
 The RFCs propose this separation by clearly distinguishing the different
 mail handling tasks.
 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.
 In nmh, for instance, the POP server, which was included in the original
 MH, was removed.
-Now is the time to go one step further and split the MSA and MRA off, too.
+Now is the time to go one step further and split off the MSA and MRA, too.
 Not only does this decrease the code size of the project,
 but, more important, it unburdens mmh of the whole field of
 message transfer with all its implications for the project.
 There is no more need to concern with changes in network transfer.
 This independence is received by depending on an external program
 was reworked to behave more like
 .Pn show
 first.
 (cf. Sec.
 .Cf mhshow )
+.\" XXX code commits?
 Once the tools behaved more alike, the replacing appeared to be
 even more natural.
 Today, mmh's new
 .Pn show
 has become the one single message display program once more,
 of the original program.
 More variations require more testing and maintenance work.
 .P
 Two other options only specified default configuration values:
 .Sw --with-mts
-defined the default transport service, either
+defined the default transport service.
-.Ar smtp
-or
-.Ar sendmail .
-.\" XXX naechster Satz ganz raus?
-In mmh this fixed to
-.Ar sendmail .
 .Ci f6aa95b724fd8c791164abe7ee5468bf5c34f226
 With
 .Sw --with-smtpservers
-default SMTP servers for the
+default SMTP servers could be specified.
-.Ar smtp
-transport service could be specified.
 .Ci 128545e06224233b7e91fc4c83f8830252fe16c9
-Both of them became irrelevant.
+Both of them became irrelevant when the SMTP transport service was removed.
+.\" XXX code ref
+In mmh, all messages are handed over to
+.Pn sendmail
+for transportation.
 .U3 "Backup Prefix
 .P
 The backup prefix is the string that was prepended to message
 filenames to tag them as deleted.
 it suited better.
 .P
 Eventually, however, the new trash folder concept
 (cf. Sec.
 .Cf trash-folder )
-obsoleted the concept of the backup prefix completely.
+removed the need for the backup prefix completely.
 .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
 .Ci ca0b3e830b86700d9e5e31b1784de2bdcaf58fc5
 .U3 "Editor and Pager
 .Cl "-truncate" .
 Every program in mmh has two generic switches:
 .Sw -help ,
 to print a short message on how to use the program, and
 .Sw -Version
-[sic!], to tell what version of mmh the program belongs to.
+(with capital `V'), to tell what version of mmh the program belongs to.
 .P
 Switches change the behavior of programs.
 Programs that do one thing in one way require no switches.
 In most cases, doing something in exactly one way is too limiting.
 If there is basically one task to accomplish, but it should be done
 .U3 "Draft Folder Facility
 .P
 A change early in the project was the complete transition from
 the single draft message to the draft folder facility.
 .Ci 337338b404931f06f0db2119c9e145e8ca5a9860
+.\" XXX ref to section ...
 The draft folder facility was introduced in the mid-eighties, when
 Rose and Romine called it a ``relatively new feature''.
 .[
 rose romine real work
 .]
 was removed.
 The special treatment of \fIthe\fP draft message became irrelevant after
 the rework of the draft system.
 (cf. Sec.
 .Cf draft-folder )
-Equally,
+Furthermore,
 .Pn comp
-lost its
+no longer needs a
 .Sw -file
-switch.
+switch as the draft folder facility together with the
-The draft folder facility, together with the
 .Sw -form
-switch, are sufficient.
+switch are sufficient.
 .U3 "In Place Editing
 .P
 .Pn anno
 .Sw -noinplace
 behavior, which already had been the default.
 Nmh's
 .Mp burst (1)
 man page reads:
-.sp \n(PDu
 .QS
-If -noinplace is given, each digest is preserved, no table
+If
+.Sw -noinplace
+is given, each digest is preserved, no table
 of contents is produced, and the messages contained within
 the digest are placed at the end of the folder. Other messages
 are not tampered with in any way.
 .QE
 .LP
 .U3 "MIME Tools
 .P
 The MIME tools, which were once part of
 .Pn mhn
-[sic!],
+.\" XXX
+(whatever that stood for),
 had several switches that added little practical value to the programs.
 The
 .Sw -[no]realsize
 switches of
 .Pn mhbuild
 .Ci ee4f43cf2ef0084ec698e4e87159a94c01940622
 This switch had introduced an awkward behavior, as explained in nmh's
 man page for
 .Mp comp (1):
 .QS
-The \-editor editor switch indicates the editor to use for
+The
-the initial edit. Upon exiting from the editor, comp will
+.Sw -editor
-invoke the whatnow program. See whatnow(1) for a discussion
+.Ar editor
-of available options. The invocation of this program can be
+switch indicates the editor to use for
-inhibited by using the \-nowhatnowproc switch. (In truth of
+the initial edit. Upon exiting from the editor,
-fact, it is the whatnow program which starts the initial
+.Pn comp
-edit. Hence, \-nowhatnowproc will prevent any edit from
+will invoke the
-occurring.)
+.Pn whatnow
+program. See
+.Mp whatnow (1)
+for a discussion of available options.
+The invocation of this program can be
+inhibited by using the
+.Sw -nowhatnowproc
+switch. (In truth of fact, it is the
+.Pn whatnow
+program which starts the initial edit.
+Hence,
+.Sw -nowhatnowproc
+will prevent any edit from occurring.)
 .QE
 .P
 Effectively, the
 .Sw -nowhatnowproc
 switch creates only a draft message.
 was removed because what use was it anyway?
 .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
-\-preserv [sic!] switch will override this message renaming, and try
+.Sw -preserv
+[sic!] switch will override this message renaming, and try
 to preserve the number of the message. If a conflict for a
-particular folder occurs when using the \-preserve switch,
+particular folder occurs when using the
-then refile will use the next available message number which
+.Sw -preserve
+switch, then
+.Pn refile
+will use the next available message number which
 is above the message number you wish to preserve.
 .QE
 .BU
 The removal of the
 .\" --------------------------------------------------------------
 .H1 "Modernizing
 .P
-In the more thirty years of MH's existence, its code base was
+In the more than thirty years of MH's existence, its code base was
 increasingly extended.
 New features entered the project and became alternatives to the
 existing behavior.
 Relicts from several decades have gathered in the code base,
 but seldom obsolete features were dropped.
 .QS
 let's stop walking on egg shells with this code base. there's no need to
 discuss whether to keep using vfork, just note in [sic!] passing, [...]
 we don't need a separate branch for removing vmh
 or ridding ourselves of #ifdef's or removing posix replacement functions
-or depending on pure ansi/posix "libc".
+or depending on pure ansi/posix ``libc''.
 .QP
-these things should each be a day or two of work and the "main branch"
+these things should each be a day or two of work and the ``main branch''
 should just be modern. [...]
 let's push forward, aggressively.
 .QE
 .LP
 I did so already in the months before.
 .U3 "Trash Folder
 .Id trash-folder
 .P
 Similar to the situation for drafts is the situation for removed messages.
 Historically, a message was ``deleted'' by prepending a specific
-\fIbackup prefix\fP, usually the comma character,
+\fIbackup prefix\fP, usually the comma character, to the file name.
-to the file name.
+The specific file would then be ignored by MH because only files with
-The specific message would vanish from MH because only files with
+names consisting of digits only are treated as messages.
-non-digit characters in their name are not treated as messages.
 Although files remained in the file system,
 the messages were no more visible in MH.
 To truly delete them, a maintenance job is needed.
 Usually a cron job is 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
 within the grace time interval by stripping the
-the backup prefix from the file name.
+backup prefix from the file name.
-But one can not rely on this statement.
+But the user can not rely on this statement.
 If the last message of a folder with six messages (1-6) is removed,
 message
 .Fn 6 ,
 becomes file
 .Fn ,6 .
 If then a new message enters the same folder, it will be given
-the number one higher than the highest existing message.
+the number one higher than the highest message.
 In this case the message is named
 .Fn 6
 then.
 If this message is removed as well,
 then the backup of the former message gets overwritten.
 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.
-The the real mechanism is practically obscure to the user.
+In practice, the real mechanism is unclear to the user.
 The consequences of further removals are not obvious.
 .P
 Further more, the backup files are scattered within the whole mail storage.
 This complicates managing them.
-It is possible, with help of
+It is possible with the help of
 .Pn find ,
 but everything would be more convenient
 if the deleted messages would be collected in one place.
 .P
 The profile entry
 .Pe rmmproc
 (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 removed
+It could be set to any command, which would be executed to remove
 the specified messages.
 This would override the default action, described above.
 Refiling the to-be-removed files to a garbage folder is the usual example.
 Nmh's man page
 .Mp rmm (1)
 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.
 No backup files are silently overwritten.
-Most important is the ability to keep removed messages in the MH domain.
+But most important is the ability to keep removed messages in the MH domain.
 Messages in the trash folder can be listed like those in any other folder.
 Deleted messages can be displayed like any other messages.
 Restoring a deleted messages can be done with
 .Pn refile .
 All operations on deleted files are still covered by the MH tools.
 calls
 .Pn refile
 to move the to-be-removed message to the trash folder,
 .Fn +trash
 by default.
-To sweep it clean, one can use
+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
 .Pn rmm
 invokes
 .Pn refile ,
 which used to be the other way round.
 Yet, the relationship is simpler now.
-No more can loops, like described in nmh's man page for
+Loops, like described in nmh's man page for
 .Mp refile (1),
-occur:
+can no longer occur:
 .QS
 Since
 .Pn refile
 uses your
 .Pe rmmproc
 .Cl "[-number [num|all]]
 and the textual description for the combination with
 .Sw -list
 read:
 .QS
-The -list option produces a listing of the field bodies for
+The
+.Sw -list
+option produces a listing of the field bodies for
 header fields with names matching the specified component,
-one per line. The listing is numbered, starting at 1, if
+one per line. The listing is numbered, starting at 1, if the
-the -number option is also used.
+.Sw -number
+option is also used.
 .QE
 .LP
 The problem was manifold.
 The code required a numeric argument to the
 .Sw -number
 David Levine posted an explanation, quoting John Romine:
 .QS
 I asked John Romine and here's what he had to say, which
 agrees and provides an example that convinces me:
 .QS
-My take on this is that post should not be called by
+My take on this is that
-users directly, and it doesn't read the .mh_profile
+.Pn post
+should not be called by users directly, and it doesn't read the
+.Fn .mh_profile
 (only front-end UI programs read the profile).
 .QP
-For example, there can be contexts where post is called
+For example, there can be contexts where
-by a helper program (like 'mhmail') which may be run by
+.Pn post
-a non-MH user.  We don't want this to prompt the user
+is called by a helper program (like `\c
-to create an MH profile, etc.
+.Pn mhmail ')
+which may be run by a non-MH user.
+We don't want this to prompt the user to create an MH profile, etc.
 .QP
-My suggestion would be to have send pass a (hidden)
+My suggestion would be to have
-`\-fileproc proc' option to post if needed.  You could also
+.Pn send
-use an environment variable (I think send/whatnow do
+pass a (hidden) `\c
-this).
+.Sw -fileproc
+.Ar proc '
+option to
+.Pn post
+if needed.
+You could also
+use an environment variable (I think
+.Pn send /\c
+.Pn whatnow
+do this).
 .QE
-I think that's the way to go.  My personal preference is to use a command line option, not an environment variable.
+I think that's the way to go.
+My personal preference is to use a command line option,
+not an environment variable.
 .QE
 .P
 To solve the problem of
 .Pn post
 not honoring the

Mercurial > docs > master

comparison discussion.roff @ 164:5c01017be420