docs/master: ch03.roff comparison

comparison ch03.roff @ 93:093ccf39a45e

Write text about removal of switches; Included the grap figure.

author	markus schnalke <meillo@marmaro.de>
date	Fri, 15 Jun 2012 23:37:58 +0200
parents	83bfb4dbf59f
children	edac7e46a9f2

comparison

equal deleted inserted replaced

-:e6f95015ba61
+:093ccf39a45e
 This option is likely to stay.
-.H2 "Removal of switches
+.H2 "Removal of Switches
 .P
+The command line switches of MH tools follow the X Window style.
+They are words, introduced by a single dash.
+For example:
+.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 ,
+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 it is basically the same task to accomplish, but it should be done
+in various ways, switches are a good approach to alter the behavior
+of a program.
+Changing the behavior of programs provides flexibility and customization
+to users, but in the same way it complicates the code, documentation and
+usage of the program.
+Therefore, the number of switches should be kept small.
+A small set of well-chosen switches does no harm.
+But usually, the number of switches increases over time.
+Already in 1985, Rose and Romine have identified this as a major
+problem of MH:
+.[ [
+rose romine real work
+.], p. 12]
+.sp
+.QP
+A complaint often heard about systems which undergo substantial development
+by many people over a number of years, is that more and more options are
+introduced which add little to the functionality but greatly increase the
+amount of information a user needs to know in order to get useful work done.
+This is usually referred to as creeping featurism.
+.QP
+Unfortunately MH, having undergone six years of off-and-on development by
+ten or so well-meaning programmers (the present authors included),
+suffers mightily from this.
+.sp
+.P
+Adding new switches only reluctantly is one part of the counter-action,
+the other is removing hardly used switches.
+Now that there are lots of switches already implemented,
+removing some of them is more important.
+Removing existing functionality is always difficult because it
+breaks programs that use these functions.
+Also, for every obsolete feature, there'll always be someone who still
+uses it and thus opposes its removal.
+This puts the developer into the position,
+where sensible improvements to style are regarded as destructive acts.
+Yet, living with the featurism is far worse, in my eyes.
+Future needs will demand adding new features,
+worsening the situation more and more.
+Rose and Romine added in a footnote,
+``[...]
+.Pn send
+will no doubt acquire an endless number of switches in the years to come.''
+Although clearly humorous, the comment displays the nature of
+the problem.
+Though refusing to add any new switches would encounter the problem
+at its root, it is not practical.
+But removing obsolete switches is an effective approach to deal with the
+problem.
+Working on an experimental branch,
+eased this work because I had not to offend users.
+.P
+Rose and Romine counted 24 visible and 9 more hidden switches for
+.Pn send .
+At the beginning of mmh, it were 32 visible and 12 hidden ones.
+At the time of writing, mmh's
+.Pn send
+has 7 visible switches and 1 hidden switch.
+(In each of the examples, the two generic help and version switches
+are included.)
+.P
+Figure XXX
+.\" XXX Ref
+displays the number of switches for each of the tools that was not
+removed from or newly added to mmh.
+Both, visible and hidden switches, were counted, but
+not the generic help and version switches.
+Whereas in the beginning of the project, the average tool had 11 switches,
+now it has no more than 5 \(en only half as many.
+If the `no' switches and similar inverse variant are folded onto
+their counter-parts, the numbers are 8 in pre-mmh to 4 now.
+The total number of functional switches in mmh dropped from 465
+to 234.
+.KS
+.in 1c
+.so input/switches.grap
+.KE
+.P
+A part of the switches vanished after functions were removed.
+This was the case for network mail transfer, for instance.
+Sometimes the work flow was the other way:
+The trying to reduce the number of switches suggested the removal of
+functions.
+.U3 "Draft Folder Facility
+.P
+A change early in the project was the completely transition from
+the single draft message to the draft folder facility.
+The draft folder facility was introduced in the mid-Eighties.
+(Rose and Romine called it a ``relatively new feature''
+.[
+rose romine real work
+.]
+in 1985.)
+Since then, the facility had existed but had remained deactive by default.
+The default activation and the related rework of the tools made it
+possible to remove the
+.Sw -[no]draftfolder ,
+and
+.Sw -draftmessage
+switches from
+.Pn comp ,
+.Pn repl ,
+.Pn forw ,
+.Pn dist ,
+.Pn whatnow ,
+and
+.Pn send .
+The only flexibility removed is having multiple draft folders
+within one profile.
+I consider this only a theoretical setup.
+In the same go, the
+.Sw -draft
+switch of
+.Pn anno ,
+.Pn refile ,
+and
+.Pn send
+was removed.
+The special-casing of `the' draft message became irrelevant after
+the rework of the draft system.
+(See Sec. XXX.)
+.U3 "Inplace
+.P
+.Pn anno
+had the switches
+.Sw -[no]inplace
+to either annotate the message inplace and thus preserve hard links,
+or annotate a copy to replace the original message, breaking hard links.
+Following the assumption that linked messages are the same message,
+and annotating it should not break the link, the
+.Sw -[no]inplace
+switches were removed and the previous default
+.Sw -inplace
+was made the only behavior.
+The
+.Sw -[no]inplace
+switches of
+.Pn repl ,
+.Pn forw ,
+and
+.Pn dist
+could be removed, too, as they were simply passed through to
+.Pn anno .
+.P
+.Pn burst
+also had
+.Sw -[no]inplace
+switches, but they had different meaning, as written in nmh's
+.Mp burst(1)
+man page:
+.sp
+.QP
+If -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.
+.sp
+.P
+With
+.Sw -inplace ,
+the digest had been replaced by the table of contents (i.e. the
+introduction text) and the bursted messages were placed right
+after this message, renumbering all following messages.
+Also, any trailing text of the digest will be lost, though,
+in practice, it usually consists of an end-of-digest marker only.
+The decision to drop the
+.Sw -inplace
+behavior was supported by the complexity and possible data loss
+it introduced.
+.Sw -noinplace
+was the default behavior already and is the chosen behavior now.
+.U3 "mbox and MMDF
+.P
+packf: file mbox mmdf
+rcvpack: mbox mmdf
+.ig
+ap: width
+dp: width
+burst: [no]quiet
+flist: [no]total
+folder: [no]header
+comp: file
+dist: file(msh)
+forw: filter, [no]mime, [no]dashstuffing(mhl)
+repl: [no]format/filter width
+mhmail: resent queued
+inc: snoop, (pop)
+mhbuild: [no]check, [no]ebcdicsafe, [no]headers, [no]list, [no]realsize
+	[no]rfc934mode, [no]contentid (caching)
+mhlist: [no]check [no]headers [no]realsize (caching)
+mhstore: [no]check [no]verbose (caching)
+scan: [no]clear [no]header [no]reverse
+mhl: [no]bell [no]clear [no]faceproc folder [no]moreproc length sleep
+	[no]dashstuffing(forw) digest list volume number issue number
+mhshow: [no]check [no]pause [no]serialonly (caching) [no]moreproc
+	length width
+prompter: erase kill [no]doteof
+refile: [no]preserve [no]unlink [no]rmmproc
+send: filter [no]format [no]forward [no]mime [no]msgid
+	[no]push split [no]unique (sasl) width snoop [no]dashstuffing
+	attach attachformat
+whatnow: (noedit) attach
+slocal: [no]suppressdups
+sortm: subject
+spost: [no]filter [no]format [no]remove [no]backup width [no]push idanno
+	[no]check(whom) whom(whom)
+whom: ???
+(pop) host, port, user, [no]pack, proxy
+(smtp) mail saml send soml client server user port
+(sasl) sasl, saslmech
+(tls)
+(caching) rcache wcache
+noedit
+nowhatnowproc
+format -> form
+version -> Version
+..
+.ig
+.P
+To ease typing, the switches can be abbreviated as much as the remaining
+prefix remains unambiguous.
+If in our example no other switch would start with the letter `t', then
+.Cl "-truncate" ,
+.Cl "-trunc" ,
+.Cl "-tr" ,
+and
+.Cl "-t
+would all be the same.
+As a result, switches can neither be grouped (as in
+.Cl "ls -ltr" )
+nor can switch arguments be appended directly to the switch (as in
+.Cl "sendmail -q30m" ).
+.P
+Many switches have negating counter-parts, which start with `no'.
+For example
+.Cl "-notruncate
+inverts the
+.Cl "-truncate
+switch.
+They exist to undo the effect of default switches in the profile.
+If the user has chosen to change the default behavior of some tool
+by adding a default switch to the profile,
+he can still undo this change in behavior by specifiying the inverse
+switch on the command line.
+.P
+In the best case, all switches are unambiguous on the first character,
+or on the three-letter prefix for the `no' variants.
+Reducing switch prefix collisions, shortens the necessary prefix lenght
+the user must type.
+Having less switches helps best.
+..
 .H1 "Modernizing
 .H2 "Removal of Code Relicts

Mercurial > docs > master

comparison ch03.roff @ 93:093ccf39a45e