# HG changeset patch # User markus schnalke # Date 1335279145 -7200 # Node ID db3567c9cc3f6e053306dc8e9918e5f4646e7c1b # Parent b3c37947764eeea72aeeec7007308543711ee4b3 style: Added format macros for files, functions, switches, etc. Converted the existing text. diff -r b3c37947764e -r db3567c9cc3f ch03.roff --- a/ch03.roff Sun Apr 22 17:16:30 2012 +0200 +++ b/ch03.roff Tue Apr 24 16:52:25 2012 +0200 @@ -52,7 +52,7 @@ I did drop any support for the MMDF maildrop format. This type of format is conceptionally similar to the mbox format, but uses four bytes with value 1 (\fL^A^A^A^A\fP) as message delimiter, -instead of the string ``\fLFrom\0\fP''. +instead of the string ``\fLFrom\ \fP''. Due to the similarity and mbox being the de-facto standard maildrop format on Unix, but also due to the larger influence of Sendmail than MMDF, the MMDF maildrop format had vanished. @@ -67,7 +67,9 @@ The direct MMDF code had been removed, but as now only one packed mailbox format is left, code structure simplifications are likely possible. The reason why they are still outstanding is the heavily optimized code -of \fLm_getfld()\fP. Changes beyond a small local scope \(en +of +.Fu m_getfld() . +Changes beyond a small local scope \(en which restructuring in its core is \(en cause a high risk of damaging the intricate workings of the optimized code. This problem is know to the developers of nmh, too. They also avoid touching this minefield @@ -93,8 +95,12 @@ actually being able to work on it, but I fear my chances are null. .P The check only prevented a pager to be placed between the outputting -program (\fLmhl\fP) and the terminal. This could have been ensured with -the \fL-nomoreproc\fP at the command line statically, too. +program (\c +.Pn mhl ) +and the terminal. This could have been ensured with +the +.Sw \-nomoreproc +at the command line statically, too. .U2 "Removed support for header fields .P @@ -120,7 +126,9 @@ .H1 "Draft and Trash Folders .U2 "Draft Folder .P -Historically, MH provided exactly one draft message, named `\fLdraft\fP' and +Historically, MH provided exactly one draft message, named +.Fn draft +and being located in the MH directory. When starting to compose another message before the former one was sent, the user had been questioned wether to use, refile or replace the old draft. Working on multiple drafts at the same time @@ -133,7 +141,9 @@ draft folder facility exists. It had been introduced already in July 1984 by Marshall T. Rose. The facility was deactivated by default. Even in nmh, the draft folder facility remained deactivated by default. -At least, Richard Coleman added the man page \fImh-draft(5)\fP to document +At least, Richard Coleman added the man page +.Mp mh-draft(5) +to document the feature well. .P The only advantage of not using the draft folder facility is the static @@ -145,28 +155,45 @@ On the other hand, a draft folder is the much more natural concept than a draft message. MH's mail storage consists of folders and messages, the messages named with ascending numbers. A draft message breaks with this -concept by introducing a message in a file named ``\fLdraft\fP''. This draft +concept by introducing a message in a file named +.Fn draft . +This draft message is special. It can not be simply listed with the available tools, but instead requires special switches. I.e. corner-cases were introduced. A draft folder, in contrast, does not introduce such corner-cases. The available tools can operate on the messages within that folder like on any messages within any mail folders. The only difference -is the fact that the default folder for \fLsend\fP is the draft folder, +is the fact that the default folder for +.Pn send +is the draft folder, instead of the current folder, like for all other tools. .P The trivial part of the change was activating the draft folder facility by default and setting a default name for this folder. Obviously, I chose -the name ``\fL+drafts\fP''. This made the \fL\-draftfolder\fP and -\fL\-draftmessage\fP switches useless, and I could remove them. +the name +.Fn +drafts . +This made the +.Sw \-draftfolder +and +.Sw \-draftmessage +switches useless, and I could remove them. The more difficult but also the part that showed the real improvement, -was updating the tools to the new concept. \fL\-draft\fP switches could +was updating the tools to the new concept. +.Sw \-draft +switches could be dropped, as operating on a draft message became indistinguishable to -operating on any other message for the tools. \fLcomp\fP still has its -\fL\-use\fP switch for switching between its two modes: (1) Compose a new +operating on any other message for the tools. +.Pn comp +still has its +.Sw \-use +switch for switching between its two modes: (1) Compose a new draft, possibly by taking some existing message as a form. (2) Modify -an existing draft. In either case, the behavior of \fLcomp\fP is +an existing draft. In either case, the behavior of +.Pn comp is deterministic. There is no more need to query the user. I consider this -a major improvement. By making \fLsend\fP simply operate on the current +a major improvement. By making +.Pn send +simply operate on the current message in the draft folder by default, with message and folder both overridable by specifying them on the command line, it is now possible to send a draft anywhere within the storage by simply specifying its folder @@ -179,7 +206,10 @@ .P Similar to the situation for drafts is the situation for removed messages. Historically, a message was deleted by renaming. A specific -\fIbackup prefix\fP, often comma (\fL,\fP) or hash (\fL#\fP), +\fIbackup prefix\fP, often comma (\c +.Fn , ) +or hash (\c +.Fn # ), being prepended to the file name. Thus, MH wouldn't recognize the file as a message anymore, as only files whose name consists of digits only are treated as messages. The removed messages remained as files in the @@ -191,9 +221,14 @@ in a cron job. Within the grace time interval the original message could be restored by stripping the the backup prefix from the file name. If however, the last message of -a folder is been removed \(en say message `\fL6\fP' becomes file -`\fL,6\fP' \(en and a new message enters the same folder, thus the same -numbered being given again \(en in our case `\fL6\fP' \(en, if that one +a folder is been removed \(en say message +.Fn 6 +becomes file +.Fn ,6 +\(en and a new message enters the same folder, thus the same +numbered being given again \(en in our case +.Fn 6 +\(en, if that one is removed too, then the backup of the former message gets overwritten. Thus, the ability to restore removed messages does not only depend on the ``sweeping cron job'' but also on the removing of further messages. @@ -202,40 +237,62 @@ Further more, the backup files are scattered within the whole mail storage, instead of being collected at one place. .P -To improve the situation, the profile entry \fIrmmproc\fP -(previously named \fIDelete-Prog\fP) was introduced, very early. +To improve the situation, the profile entry +.Pe rmmproc +(previously named +.Pe Delete-Prog ) +was introduced, very early. It could be set to any command, which would care for the mail removal instead of taking the default action, described above. Refiling the to-be-removed files to some wastebin folder was a common -example. Nmh's man page for \fLrmm(1)\fP proposes `\fLrefile +d\fP' -to move messages to the wastebin and `\fLrm `mhpath +d all`\fP' +example. Nmh's man page +.Mp rmm(1) +proposes +.Cl "refile +d +to move messages to the wastebin and +.Cl "rm `mhpath +d all` the empty the wastebin. Managing the message removal this way is a sane approach. It keeps the removed messages in one place, makes it easy to remove the backup files, and, most important, enables the user to use the tools of MH -itself to operate on the removed messages. One can \fLscan\fP them, -\fLshow\fP them, and restore them with \fLrefile(1)\fP. There's no more -need to use \fLmhpath\fP to switch over from MH tools to Unix tools -\(en MH can do it all itself. +itself to operate on the removed messages. One can +.Pn scan +them, +.Pn show +them, and restore them with +.Pn refile . +There's no more +need to use +.Pn mhpath +to switch over from MH tools to Unix tools \(en MH can do it all itself. .P -This apporach is matches perfect with the concepts of MH, thus making +This apporach matches perfect with the concepts of MH, thus making it powerful. Hence, I made it the default. And even more, I also removed the old backup prefix approach, as it is clearly less powerful. Keeping unused alternative in the code is a bad choice as they likely gather bugs, by not being constantly tested. Also, the increased code size and more conditions crease the maintenance costs. By strictly converting to the trash folder approach, I simplified the code base. -\fLrmm(1)\fP calls \fLrefile(1)\fP internally to move the to-be-removed -message to the trash folder (`\fL+trash\fP' by default). Messages +.Pn rmm +calls +.Pn refile +internally to move the to-be-removed +message to the trash folder (\c +.Fn +trash +by default). Messages there can be operated on like on any other message in the storage. -The sweep clean, one can use `\fLrmm \-unlink +trash a\fP', where -the `\fL\-unlink\fP' switch causes the files to be truly unliked instead +The sweep clean, one can use +.Cl "rmm \-unlink +trash a" , +where the +.Sw \-unlink +switch causes the files to be truly unliked instead of moved to the trash folder. .H1 "MH Directory Split .P - +Historically, a personal MH setup had consisted of two things: +the .H1 "Path Notations diff -r b3c37947764e -r db3567c9cc3f style --- a/style Sun Apr 22 17:16:30 2012 +0200 +++ b/style Tue Apr 24 16:52:25 2012 +0200 @@ -221,3 +221,26 @@ .ps 8 .vs 9 .. + +.de Fn \" file name +.CW "\\$1" "\\$2 +.. +.de Pn \" program name +.CW "\\$1" "\\$2 +.. +.de Fu \" function +.CW "\\$1" "\\$2 +.. +.de Cl \" command line +`\c +.CW "\\$1" "'\\$2 +.. +.de Sw \" switch +.CW "\\$1" "\\$2 +.. +.de Mp \" man page +.I "\\$1" "\\$2 +.. +.de Pe \" profile entry +.CW "\\$1" "\\$2 +..