docs/master

diff ch03.roff @ 95:edac7e46a9f2

More text about switches.
author markus schnalke <meillo@marmaro.de>
date Sat, 16 Jun 2012 13:26:30 +0200
parents 093ccf39a45e
children 12348d620245
line diff
     1.1 --- a/ch03.roff	Sat Jun 16 09:26:57 2012 +0200
     1.2 +++ b/ch03.roff	Sat Jun 16 13:26:30 2012 +0200
     1.3 @@ -1076,8 +1076,17 @@
     1.4  The special-casing of `the' draft message became irrelevant after
     1.5  the rework of the draft system.
     1.6  (See Sec. XXX.)
     1.7 +Equally,
     1.8 +.Pn comp
     1.9 +lost its
    1.10 +.Sw -file
    1.11 +switch.
    1.12 +The draft folder facility, together with the
    1.13 +.Sw -form
    1.14 +switch, are sufficient.
    1.15  
    1.16 -.U3 "Inplace
    1.17 +
    1.18 +.U3 "Inplace Editing
    1.19  .P
    1.20  .Pn anno
    1.21  had the switches
    1.22 @@ -1103,98 +1112,455 @@
    1.23  .Pn burst
    1.24  also had
    1.25  .Sw -[no]inplace
    1.26 -switches, but they had different meaning, as written in nmh's
    1.27 -.Mp burst(1)
    1.28 -man page:
    1.29 -.sp
    1.30 +switches, but with different meaning.
    1.31 +With
    1.32 +.Sw -inplace ,
    1.33 +the digest had been replaced by the table of contents (i.e. the
    1.34 +introduction text) and the bursted messages were placed right
    1.35 +after this message, renumbering all following messages.
    1.36 +Also, any trailing text of the digest was lost, though,
    1.37 +in practice, it usually consists of an end-of-digest marker only.
    1.38 +Nontheless, this behavior appeared less elegant than the
    1.39 +.Sw -noinplace
    1.40 +behavior, which already had been the default.
    1.41 +Nmh's
    1.42 +.Mp burst (1)
    1.43 +man page reads:
    1.44 +.sp \n(PDu
    1.45  .QP
    1.46  If -noinplace is given, each digest is preserved, no table
    1.47  of contents is produced, and the messages contained within
    1.48  the digest are placed at the end of the folder. Other messages
    1.49  are not tampered with in any way.
    1.50 -.sp
    1.51 -.P
    1.52 -With
    1.53 -.Sw -inplace ,
    1.54 -the digest had been replaced by the table of contents (i.e. the
    1.55 -introduction text) and the bursted messages were placed right
    1.56 -after this message, renumbering all following messages.
    1.57 -Also, any trailing text of the digest will be lost, though,
    1.58 -in practice, it usually consists of an end-of-digest marker only.
    1.59 +.sp \n(PDu
    1.60 +.LP
    1.61  The decision to drop the
    1.62  .Sw -inplace
    1.63 -behavior was supported by the complexity and possible data loss
    1.64 -it introduced.
    1.65 +behavior was supported by the code complexity and the possible data loss
    1.66 +it caused.
    1.67  .Sw -noinplace
    1.68 -was the default behavior already and is the chosen behavior now.
    1.69 +was chosen to be the definitive behavior.
    1.70  
    1.71 -.U3 "mbox and MMDF
    1.72 +
    1.73 +.U3 "Forms and Format Strings
    1.74  .P
    1.75 -packf: file mbox mmdf
    1.76 -rcvpack: mbox mmdf
    1.77 +Historically, the tools that had
    1.78 +.Sw -form
    1.79 +switches to supply a form file had
    1.80 +.Sw -format
    1.81 +switches as well to supply the contents of a form file as a string
    1.82 +on the command line directly.
    1.83 +In consequence, the following two lines equaled:
    1.84 +.VS
    1.85 +scan -form scan.mailx
    1.86 +scan -format "`cat .../scan.mailx`"
    1.87 +VE
    1.88 +The
    1.89 +.Sw -format
    1.90 +switches were dropped in favor for extending the
    1.91 +.Sw -form
    1.92 +switches.
    1.93 +If their argument starts with an equal sign (`='),
    1.94 +then the rest of the argument is taken as a format string,
    1.95 +otherwise the arguments is treated as the name of a format file.
    1.96 +Thus, now the following two lines equal:
    1.97 +.VS
    1.98 +scan -form scan.mailx
    1.99 +scan -form "=`cat .../scan.mailx`"
   1.100 +VE
   1.101 +This rework removed the prefix collision between
   1.102 +.Sw -form
   1.103 +and
   1.104 +.Sw -format .
   1.105 +Now, typing
   1.106 +.Sw -fo
   1.107 +suffices to specify form or format string.
   1.108 +.P
   1.109 +The different meaning of
   1.110 +.Sw -format
   1.111 +for
   1.112 +.Pn repl
   1.113 +and
   1.114 +.Pn forw
   1.115 +was removed in mmh.
   1.116 +.Pn forw
   1.117 +was completely switched to MIME-type forwarding, thus removing the
   1.118 +.Sw -[no]format .
   1.119 +For
   1.120 +.Pn repl ,
   1.121 +the
   1.122 +.Sw -[no]format
   1.123 +switches were reworked to
   1.124 +.Sw -[no]filter
   1.125 +switches.
   1.126 +The
   1.127 +.Sw -format
   1.128 +switches of
   1.129 +.Pn send
   1.130 +and
   1.131 +.Pn post ,
   1.132 +which had a third meaning,
   1.133 +were removed likewise.
   1.134 +Eventually, the ambiguity of the
   1.135 +.Sw -format
   1.136 +switches was resolved by not anymore having any such switch in mmh.
   1.137 +
   1.138 +
   1.139 +.U3 "MIME Tools
   1.140 +.P
   1.141 +The MIME tools, which were once part of
   1.142 +.Pn mhn ,
   1.143 +had several switches that added little practical value to the programs.
   1.144 +The
   1.145 +.Sw -[no]realsize
   1.146 +switches of
   1.147 +.Pn mhbuild
   1.148 +and
   1.149 +.Pn mhlist
   1.150 +were removed, doing real size calculations always now, as
   1.151 +``This provides an accurate count at the expense of a small delay.''
   1.152 +This small delay is not noticable on modern systems.
   1.153 +.P
   1.154 +The
   1.155 +.Sw -[no]check
   1.156 +switches were removed together with the support for
   1.157 +.Hd Content-MD5
   1.158 +header fields.
   1.159 +.[
   1.160 +rfc 1864
   1.161 +.]
   1.162 +(See Sec. XXX)
   1.163 +.P
   1.164 +The
   1.165 +.Sw -[no]ebcdicsafe
   1.166 +and
   1.167 +.Sw -[no]rfc934mode
   1.168 +switches of
   1.169 +.Pn mhbuild
   1.170 +were removed because they are considered obsolete.
   1.171 +.P
   1.172 +Content caching of external MIME parts, activated with the
   1.173 +.Sw -rcache
   1.174 +and
   1.175 +.Sw -wcache
   1.176 +switches was completely removed.
   1.177 +External MIME parts are truly rare today, having a caching facility
   1.178 +for them is appeares to be unnecessary.
   1.179 +.P
   1.180 +In pre-MIME times,
   1.181 +.Pn mhl
   1.182 +had covered many tasks that are part of MIME handling today.
   1.183 +Therefore,
   1.184 +.Pn mhl
   1.185 +could be simplified to a large extend, reducing the number of its
   1.186 +switches from 21 to 6.
   1.187 +
   1.188 +
   1.189 +.U3 "Mail Transfer Switches
   1.190 +.P
   1.191 +With the removal of the mail transfer facilities, a lot of switches
   1.192 +vanished automatically.
   1.193 +.Pn inc
   1.194 +lost 9 switches, namely
   1.195 +.Sw -host ,
   1.196 +.Sw -port ,
   1.197 +.Sw -user ,
   1.198 +.Sw -proxy ,
   1.199 +.Sw -snoop ,
   1.200 +.Sw -[no]pack ,
   1.201 +as well as
   1.202 +.Sw -sasl
   1.203 +and
   1.204 +.Sw -saslmech .
   1.205 +.Pn send
   1.206 +and
   1.207 +.Pn post 
   1.208 +lost 11 switches each, namely
   1.209 +.Sw -server ,
   1.210 +.Sw -port ,
   1.211 +.Sw -client ,
   1.212 +.Sw -user ,
   1.213 +.Sw -mail ,
   1.214 +.Sw -saml ,
   1.215 +.Sw -send ,
   1.216 +.Sw -soml ,
   1.217 +.Sw -snoop ,
   1.218 +as well as
   1.219 +.Sw -sasl ,
   1.220 +.Sw -saslmech ,
   1.221 +and
   1.222 +.Sw -tls .
   1.223 +.Pn send
   1.224 +had the switches only to pass them further to
   1.225 +.Pn post ,
   1.226 +because the user would invoke
   1.227 +.Pn post
   1.228 +not directly, but through
   1.229 +.Pn send .
   1.230 +All these switches, except
   1.231 +.Sw -snoop
   1.232 +were usually defined as default switches in the user's profile,
   1.233 +but hardly given in interactive usage.
   1.234 +.P
   1.235 +Of course, those switches did not really ``vanish'', but the configuration
   1.236 +they did was handed over to external MSAs and MRAs.
   1.237 +Instead of setting up the mail transfer in mmh, it is set up in
   1.238 +external tools.
   1.239 +Yet, this simplifies mmh.
   1.240 +Specialized external tools will likely have simple configuration files.
   1.241 +Hence, instead of having one complicated central configuration file,
   1.242 +the configuration of each domain is separate.
   1.243 +Although the user needs to learn to configure each of the tools,
   1.244 +each configuration is likely much simpler.
   1.245 +
   1.246 +
   1.247 +.U3 "Maildrop Formats
   1.248 +.P
   1.249 +With the removal of MMDF maildrop format support,
   1.250 +.Pn packf
   1.251 +and
   1.252 +.Pn rcvpack
   1.253 +no longer needed their
   1.254 +.Sw -mbox
   1.255 +and
   1.256 +.Sw -mmdf
   1.257 +switches.
   1.258 +.Sw -mbox
   1.259 +is the sole  behavior now.
   1.260 +In the same go,
   1.261 +.Pn packf
   1.262 +was reworked (see Sec. XXX) and its
   1.263 +.Sw -file
   1.264 +switch became unnecessary.
   1.265 +
   1.266 +
   1.267 +.U3 "Terminal Magic
   1.268 +.P
   1.269 +Mmh's tools will no longer clear the screen (\c
   1.270 +.Pn scan 's
   1.271 +and
   1.272 +.Pn mhl 's
   1.273 +.Sw -[no]clear
   1.274 +switches).
   1.275 +Neither will
   1.276 +.Pn mhl
   1.277 +ring the bell (\c
   1.278 +.Sw -[no]bell )
   1.279 +nor page the output itself (\c
   1.280 +.Sw -length ).
   1.281 +.P
   1.282 +Generally, the pager to use is no longer specified with the
   1.283 +.Sw -[no]moreproc
   1.284 +command line switches for
   1.285 +.Pn mhl
   1.286 +and
   1.287 +.Pn show /\c
   1.288 +.Pn mhshow .
   1.289 +.P
   1.290 +.Pn prompter
   1.291 +lost its
   1.292 +.Sw -erase
   1.293 +and
   1.294 +.Sw -kill
   1.295 +switches because today the terminal cares for the line editing keys.
   1.296 +
   1.297 +
   1.298 +.U3 "Header Printing
   1.299 +.P
   1.300 +.Pn folder 's
   1.301 +data output is self-explaining enough that
   1.302 +displaying the header line makes few sense.
   1.303 +Hence, the
   1.304 +.Sw -[no]header
   1.305 +switch was removed and headers are never printed.
   1.306 +.P
   1.307 +In
   1.308 +.Pn mhlist ,
   1.309 +the
   1.310 +.Sw -[no]header
   1.311 +switches were removed, too.
   1.312 +But in this case headers are always printed,
   1.313 +because the output is not self-explaining.
   1.314 +.P
   1.315 +.Pn scan
   1.316 +also had
   1.317 +.Sw -[no]header
   1.318 +switches.
   1.319 +Printing the header had been sensible until the introduction of
   1.320 +format strings made it impossible to display the column headings.
   1.321 +Only the folder name and the current date remained to be printed.
   1.322 +As this information can be perfectly retrieved by
   1.323 +.Pn folder
   1.324 +and
   1.325 +.Pn date ,
   1.326 +consequently, the switches were removed.
   1.327 +.P
   1.328 +By removing all
   1.329 +.Sw -header
   1.330 +switches, the collision with
   1.331 +.Sw -help
   1.332 +on the first two letters was resolved.
   1.333 +Currently,
   1.334 +.Sw -h
   1.335 +evaluates to
   1.336 +.Sw -help
   1.337 +for all tools of mmh.
   1.338 +
   1.339 +
   1.340 +.U3 "Suppressing Edits or the WhatNow Shell
   1.341 +.P
   1.342 +The
   1.343 +.Sw -noedit
   1.344 +switches of
   1.345 +.Pn comp ,
   1.346 +.Pn repl ,
   1.347 +.Pn forw ,
   1.348 +.Pn dist ,
   1.349 +and
   1.350 +.Pn whatnow
   1.351 +was removed, but it can now be replaced by specifying
   1.352 +.Sw -editor
   1.353 +with an empty argument.
   1.354 +(Specifying
   1.355 +.Cl "-editor true
   1.356 +is nearly the same, only differing by the previous editor being set.)
   1.357 +.P
   1.358 +The more important change is the removal of the
   1.359 +.Sw -nowhatnowproc
   1.360 +switch.
   1.361 +This switch had introduced an awkward behavior, as explained in nmh's
   1.362 +man page for
   1.363 +.Mp comp (1):
   1.364 +.QP
   1.365 +The \-editor editor switch indicates the editor  to  use  for
   1.366 +the  initial  edit.  Upon exiting from the editor, comp will
   1.367 +invoke the whatnow program.  See whatnow(1) for a discussion
   1.368 +of available options.  The invocation of this program can be
   1.369 +inhibited by using the \-nowhatnowproc switch.  (In truth  of
   1.370 +fact,  it  is  the  whatnow program which starts the initial
   1.371 +edit.  Hence, \-nowhatnowproc  will  prevent  any  edit  from
   1.372 +occurring.)
   1.373 +.P
   1.374 +Effectively, the
   1.375 +.Sw -nowhatnowproc
   1.376 +switch stored a copy of the form file into the draft folder.
   1.377 +As
   1.378 +.Cl "-whatnowproc true
   1.379 +causes the same behavior, the
   1.380 +.Sw -nowhatnowproc
   1.381 +switch was removed for being redundant.
   1.382 +Likely, however, the intention for specifying
   1.383 +.Sw -nowhatnowproc
   1.384 +is sending a fully prepared form file at once.
   1.385 +This can be done with
   1.386 +.Cl "-whatnowproc send" .
   1.387 +
   1.388 +
   1.389 +.U3 "Compatibility Switches
   1.390 +.BU
   1.391 +The hidden
   1.392 +.Sw -[no]total
   1.393 +switches of
   1.394 +.Pn flist .
   1.395 +They were simply the inverse of the visible
   1.396 +.Sw -[no]fast
   1.397 +switches:
   1.398 +.Sw -total
   1.399 +was
   1.400 +.Sw -nofast
   1.401 +and
   1.402 +.Sw -nototal
   1.403 +was
   1.404 +.Sw -fast .
   1.405 +I removed the
   1.406 +.Sw -[no]total
   1.407 +legacy.
   1.408 +.BU
   1.409 +The
   1.410 +.Sw -subject
   1.411 +switch of
   1.412 +.Pn sortm
   1.413 +existed for compatibility only.
   1.414 +It can be fully replaced by
   1.415 +.Cl "-textfield subject
   1.416 +thus it was removed.
   1.417 +
   1.418 +
   1.419 +.U3 "Various
   1.420 +.BU
   1.421 +In order to avoid prefix collisions amoung switch names, the
   1.422 +.Sw -version
   1.423 +switch was renamed to
   1.424 +.Sw -Version
   1.425 +(with capital `V').
   1.426 +Every program has the
   1.427 +.Sw -version
   1.428 +switch but its first three letters collided with the
   1.429 +.Sw -verbose
   1.430 +switch, present in many programs.
   1.431 +The rename solved this problem once for all.
   1.432 +Although this rename breaks a basic interface, having the
   1.433 +.Sw -V
   1.434 +abbreviation to display the version information, isn't all too bad.
   1.435 +.BU
   1.436 +.Sw -[no]preserve
   1.437 +of
   1.438 +.Pn refile
   1.439 +was removed because what use was it anyway?
   1.440 +.QP
   1.441 +Normally when a message is refiled, for each destination
   1.442 +folder it is assigned the number which is one above the current
   1.443 +highest message number in that folder. Use of the
   1.444 +\-preserv [sic!] switch will override this message renaming, and try
   1.445 +to preserve the number of the message. If a conflict for a
   1.446 +particular folder occurs when using the \-preserve switch,
   1.447 +then refile will use the next available message number which
   1.448 +is above the message number you wish to preserve.
   1.449 +.BU
   1.450 +The removal of the
   1.451 +.Sw -[no]reverse
   1.452 +switches of
   1.453 +.Pn scan
   1.454 +is a bug fix, supported by the comments
   1.455 +``\-[no]reverse under #ifdef BERK (I really HATE this)''
   1.456 +by Rose and
   1.457 +``Lists messages in reverse order with the `\-reverse' switch.
   1.458 +This should be considered a bug.'' by Romine in the documentation.
   1.459 +The question remaining is why neither Rose and Romine had fixed this
   1.460 +bug in the Eighties when they wrote these comments nor has anyone
   1.461 +thereafter.
   1.462  
   1.463  
   1.464  .ig
   1.465  
   1.466 -ap: width
   1.467 -dp: width
   1.468 -burst: [no]quiet
   1.469 -flist: [no]total
   1.470 -folder: [no]header
   1.471 +forw: [no]dashstuffing(mhl)
   1.472  
   1.473 -comp: file
   1.474 -dist: file(msh)
   1.475 -forw: filter, [no]mime, [no]dashstuffing(mhl)
   1.476 -repl: [no]format/filter width
   1.477 +mhshow: [no]pause [no]serialonly
   1.478  
   1.479  mhmail: resent queued
   1.480  inc: snoop, (pop)
   1.481 -mhbuild: [no]check, [no]ebcdicsafe, [no]headers, [no]list, [no]realsize
   1.482 -	[no]rfc934mode, [no]contentid (caching)
   1.483 -mhlist: [no]check [no]headers [no]realsize (caching)
   1.484 -mhstore: [no]check [no]verbose (caching)
   1.485  
   1.486 -scan: [no]clear [no]header [no]reverse
   1.487 +mhl: [no]faceproc folder sleep
   1.488 +	[no]dashstuffing(forw) digest list volume number issue number
   1.489  
   1.490 -mhl: [no]bell [no]clear [no]faceproc folder [no]moreproc length sleep
   1.491 -	[no]dashstuffing(forw) digest list volume number issue number
   1.492 -mhshow: [no]check [no]pause [no]serialonly (caching) [no]moreproc
   1.493 -	length width
   1.494 -
   1.495 -prompter: erase kill [no]doteof
   1.496 +prompter: [no]doteof
   1.497  
   1.498  refile: [no]preserve [no]unlink [no]rmmproc
   1.499  
   1.500 -send: filter [no]format [no]forward [no]mime [no]msgid
   1.501 +send: [no]forward [no]mime [no]msgid
   1.502  	[no]push split [no]unique (sasl) width snoop [no]dashstuffing
   1.503  	attach attachformat
   1.504  whatnow: (noedit) attach
   1.505  
   1.506  slocal: [no]suppressdups
   1.507  
   1.508 -sortm: subject
   1.509 -
   1.510 -spost: [no]filter [no]format [no]remove [no]backup width [no]push idanno
   1.511 +spost: [no]filter [no]backup width [no]push idanno
   1.512  	[no]check(whom) whom(whom)
   1.513  
   1.514  whom: ???
   1.515  
   1.516 +..
   1.517  
   1.518 -(pop) host, port, user, [no]pack, proxy
   1.519 -(smtp) mail saml send soml client server user port
   1.520 -(sasl) sasl, saslmech
   1.521 -(tls)
   1.522 -(caching) rcache wcache
   1.523 -
   1.524 -noedit
   1.525 -nowhatnowproc
   1.526 -
   1.527 -
   1.528 -format -> form
   1.529 -
   1.530 -version -> Version
   1.531 -
   1.532 -..
   1.533  
   1.534  .ig
   1.535  
   1.536 @@ -1233,6 +1599,9 @@
   1.537  
   1.538  ..
   1.539  
   1.540 +
   1.541 +
   1.542 +
   1.543  .H1 "Modernizing
   1.544  
   1.545