docs/master: discussion.roff comparison

comparison discussion.roff @ 131:7c741bc8f719

Reorganized: Converted 4-parted discussion into 3-parted discussion.

author	markus schnalke <meillo@marmaro.de>
date	Tue, 03 Jul 2012 11:11:12 +0200
parents	0b9aa74ced4d
children	02660c14f6a8

comparison

equal deleted inserted replaced

-:0b9aa74ced4d
+:7c741bc8f719
 That does not hurt because
 .Pn slocal
 is unrelated to the rest of the project.
-.H2 "\fLshow\fP and \fPmhshow\fP
+.H3 "Profile Reading
+.P
+FIXME XXX
+commit 3e017a7abbdf69bf0dff7a4073275961eda1ded8
+Author: markus schnalke <meillo@marmaro.de>
+Date:   Wed Jun 27 14:23:35 2012 +0200
+spost: Read profile and context now. Removed -library switch.
+spost is a full part of the mmh toolchest, hence, it shall read the
+profile/context. This will remove the need to pass profile information
+from send to spost via command line switches.
+In January 2012, there had been a discussion on the nmh-workers ML
+whether post should read the profile/context. There wasn't a clear
+answer. It behavior was mainly motivated by the historic situation,
+it seems. My opinion on the topic goes into the direction that every
+tool that is part of the mmh toolchest should read the profile. That
+is a clear and simple concept. Using MH tools without wanting to
+interact with MH (like mhmail had been) is no more a practical problem.
+commit 32d4f9daaa70519be3072479232ff7be0500d009
+Author: markus schnalke <meillo@marmaro.de>
+Date:   Wed Jun 27 13:15:47 2012 +0200
+mhmail: Read the context!
+mhmail will change from a mailx-replacment to an alternative to
+`comp -ed prompter', thus being a send front-end. Hence, mhmail
+should not stay outside the profile/context respecting mmh toolchest.
+slocal
+.H2 "Displaying Messages
+.P
+FIXME XXX
+.U3 "\fLshow\fP and \fPmhshow\fP
 .P
 Since the very beginning \(en already in the first concept paper \(en
 .Pn show
 had been MH's message display program.
 .Pn show
 hurts in one regard: It had been such a simple program.
 Its lean elegance is missing to the new
 .Pn show .
 But there is no chance;
 supporting MIME demands for higher essential complexity.
+.U3 "Scan Listings
+.P
+FIXME XXX
+.P
+commit c20e315f9fb9f0f0955749726dbf4fd897cd9f48
+Author: markus schnalke <meillo@marmaro.de>
+Date:   Fri Dec 9 21:56:44 2011 +0100
+Adjusted the default scan listing: remove the body preview
+The original listing is still available as etc/scan.nmh
+commit 70b2643e0da8485174480c644ad9785c84f5bff4
+Author: markus schnalke <meillo@marmaro.de>
+Date:   Mon Jan 30 16:16:26 2012 +0100
+Scan listings shall not contain body content. Hence, removed this feature.
+Scan listings shall operator on message headers and non-message information
+only. Displaying the beginning of the body complicates everything too much.
+That's no surprise, because it's something completely different. If you
+want to examine the body, then use show(1)/mhshow(1).
+Changed the default scan formats accordingly.
 .H2 "Configure Options
 .P
 Customization is a double-edged sword.
 Forwarding messages using MIME.
 .Ci 6e271608b7b9c23771523f88d23a4d3593010cf1
+.H2 "Drafts and Trash Folder
-.H1 "Style
+.P
-.P
-Kernighan and Pike have emphasized the importance of style in the
+.U3 "Draft Folder
-preface of their book:
-.[ [
-kernighan pike practice of programming
-.], p. x]
-.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
-to improve on style.
-Many of them follow the rules given in the quoted book.
-.[
-kernighan pike practice of programming
-.]
-.H2 "Code Style
-.P
-.U3 "Indentation Style
-.P
-Indentation styles are the holy cow of programmers.
-Again Kernighan and Pike:
-.[ [
-kernighan pike practice of programming
-.], p. 10]
-.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
-time arguing.
-.QE
-.P
-I agree that the constant application is most important,
-but I believe that some styles have advantages over others.
-For instance the indentation with tab characters only.
-Tab characters directly map to the nesting level \(en
-one tab, one level.
-Tab characters are flexible because developers can adjust them to
-whatever width they like to have.
-There is no more need to run
-.Pn unexpand
-or
-.Pn entab
-programs to ensure the correct mixture of leading tabs and spaces.
-The simple rules are: (1) Leading whitespace must consist of tabs only.
-(2) Any other whitespace should consist of spaces.
-These two rules ensure the integrity of the visual appearance.
-Although reformatting existing code should be avoided, I did it.
-I did not waste time arguing; I just did it.
-.Ci a485ed478abbd599d8c9aab48934e7a26733ecb1
-.U3 "Comments
-.P
-Section 1.6 of
-.[ [
-kernighan pike practice of programming
-.], p. 23]
-demands: ``Don't belabor the obvious.''
-Hence, I simply removed all the comments in the following code excerpt:
-.VS
-context_replace(curfolder, folder);  /* update current folder  */
-seq_setcur(mp, mp->lowsel);  /* update current message */
-seq_save(mp);  /* synchronize message sequences */
-folder_free(mp);  /* free folder/message structure */
-context_save();  /* save the context file */
-[...]
-int c;  /* current character */
-char *cp;  /* miscellaneous character pointer */
-[...]
-/* NUL-terminate the field */
-*cp = '\0';
-VE
-.Ci 426543622b377fc5d091455cba685e114b6df674
-.P
-The names of the functions explain enough already.
-.U3 "Names
-.P
-Kernighan and Pike suggest:
-``Use active names for functions''.
-.[ [
-kernighan pike practice of programming
-.], p. 4]
-One application of this rule was the rename of
-.Fu check_charset()
-to
-.Fu is_native_charset() .
-.Ci 8d77b48284c58c135a6b2787e721597346ab056d
-The same change fixed a violation of ``Be accurate'' as well.
-The code did not match the expectation the function suggested,
-as it, for whatever reason, only compared the first ten characters
-of the charset name.
-.P
-More important than using active names is using descriptive names.
-Renaming the obscure function
-.Fu m_unknown()
-was a delightful event.
-.Ci 611d68d19204d7cbf5bd585391249cb5bafca846
-.P
-Magic numbers are generally considered bad style.
-Obviously, Kernighan and Pike agree:
-``Give names to magic numbers''.
-.[ [
-kernighan pike practice of programming
-.], p. 19]
-One such change was naming the type of input \(en mbox or mail folder \(en
-to be scanned:
-.VS
-#define SCN_MBOX (-1)
-#define SCN_FOLD 0
-VE
-.Ci 7ffb36d28e517a6f3a10272056fc127592ab1c19
-.P
-The argument
-.Ar outnum
-of the function
-.Fu scan()
-in
-.Fn uip/scansbr.c
-defines the number of the message to be created.
-If no message is to be created, the argument is misused to transport
-program logic.
-This lead to obscure code.
-I improved the clarity of the code by introducing two variables:
-.VS
-int incing = (outnum > 0);
-int ismbox = (outnum != 0);
-VE
-They cover the magic values and are used for conditions.
-The variable
-.Ar outnum
-is only used when it holds an ordinary message number.
-.Ci b8b075c77be7794f3ae9ff0e8cedb12b48fd139f
-The clarity improvement of the change showed detours in the program logic
-of related code parts.
-Having the new variables with descriptive names, a more
-straight forward implementation became apparent.
-Before the clarification was done,
-the possibility to improve had not be seen.
-.Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723
-.U3 "Rework of \f(CWanno\fP
-.P
-At the end of their chapter on style,
-Kernighan and Pike ask: ``But why worry about style?''
-The following example of my rework of
-.Pn anno
-provides an answer why style is important in the first place.
-.P
-Until 2002,
-.Pn anno
-had six functional command line switches,
-.Sw -component
-and
-.Sw -text ,
-which took 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.
-In need for more advanced annotation handling, he extended
-.Pn anno .
-He added five more switches:
-.Sw -draft ,
-.Sw -list ,
-.Sw -delete ,
-.Sw -append ,
-and
-.Sw -number ,
-the last one taking an argument.
-.Ci 7480dbc14bc90f2d872d434205c0784704213252
-Later,
-.Sw -[no]preserve
-was added.
-.Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f
-Then, the Synopsis section of the man page
-.Mp anno (1)
-read:
-.VS
-anno [+folder] [msgs] [-component field] [-inplace | -noinplace]
-	[-date | -nodate] [-draft] [-append] [-list] [-delete]
-	[-number [num|all]] [-preserve | -nopreserve] [-version]
-	[-help] [-text body]
-VE
-.LP
-The implementation followed the same structure.
-Problems became visible when
-.Cl "anno -list -number 42
-worked on the current message instead on message number 42,
-and
-.Cl "anno -list -number l:5
-did not work on the last five messages but failed with the mysterious
-error message: ``anno: missing argument to -list''.
-Yet, the invocation matched the specification in the man page.
-There, the correct use of
-.Sw -number
-was defined as being
-.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
-header fields with names matching the specified component,
-one per line. The listing is numbered, starting at 1, if
-the -number option is also used.
-.QE
-.LP
-The problem was manifold.
-The code required a numeric argument to the
-.Sw -number
-switch.
-If it was missing or non-numeric,
-.Pn anno
-aborted with an error message that had an off-by-one error,
-printing the switch one before the failing one.
-Semantically, the argument to the
-.Sw -number
-switch is only necessary in combination with
-.Sw -delete ,
-but not with
-.Sw -list .
-In the former case it is even necessary.
-.P
-Trying to fix these problems on the surface would not have solved it truly.
-The problems discovered originate from a discrepance between the semantic
-structure of the problem and the structure implemented in the program.
-Such structural differences can not be cured on the surface.
-They need to be solved by adjusting the structure of the implementation
-to the structure of the problem.
-.P
-In 2002, the new switches
-.Sw -list
-and
-.Sw -delete
-were added in the same way, the
-.Sw -number
-switch for instance had been added.
-Yet, they are of structural different type.
-Semantically,
-.Sw -list
-and
-.Sw -delete
-introduce modes of operation.
-Historically,
-.Pn anno
-had only one operation mode: adding header fields.
-With the extension, it got two moder modes:
-listing and deleting header fields.
-The structure of the code changes did not pay respect to this
-fundamental change to
-.Pn anno 's
-behavior.
-Neither the implementation nor the documentation did clearly
-define them as being exclusive modes of operation.
-Having identified the problem, I solved it by putting structure into
-.Pn anno
-and its documentation.
-.Ci d54c8db8bdf01e8381890f7729bc0ef4a055ea11
-.P
-The difference is visible in both, the code and the documentation.
-The following code excerpt:
-.VS
-int delete = -2;  /* delete header element if set */
-int list = 0;  /* list header elements if set */
-[...]
-	case DELETESW:  /* delete annotations */
-		delete = 0;
-		continue;
-	case LISTSW:  /* produce a listing */
-		list = 1;
-		continue;
-VE
-.LP
-was replaced by:
-.VS
-static enum { MODE_ADD, MODE_DEL, MODE_LIST } mode = MODE_ADD;
-[...]
-	case DELETESW:  /* delete annotations */
-		mode = MODE_DEL;
-		continue;
-	case LISTSW:  /* produce a listing */
-		mode = MODE_LIST;
-		continue;
-VE
-.LP
-The replacement code does not only reflect the problem's structure better,
-it is easier to understand as well.
-The same applies to the documentation.
-The man page was completely reorganized to propagate the same structure.
-This is visible in the Synopsis section:
-.VS
-anno [+folder] [msgs] [-component field] [-text body]
-	[-append] [-date | -nodate] [-preserve | -nopreserve]
-	[-Version] [-help]
-anno -delete [+folder] [msgs] [-component field] [-text
-	body] [-number num | all ] [-preserve | -nopreserve]
-	[-Version] [-help]
-anno -list [+folder] [msgs] [-component field] [-number]
-	[-Version] [-help]
-VE
-.\" XXX think about explaining the -preserve rework?
-.H2 "Standard Libraries
-.P
-MH is one decade older than the POSIX and ANSI C standards.
-Hence, MH included own implementations of functions
-that are standardized and thus widely available today,
-but were not back then.
-Today, twenty years after the POSIX and ANSI C were published,
-developers can expect system to comply with these standards.
-In consequence, MH-specific replacements for standard functions
-can and should be dropped.
-Kernighan and Pike advise: ``Use standard libraries.''
-.[ [
-kernighan pike practice of programming
-.], p. 196]
-Actually, MH had followed this advice in history,
-but it had not adjusted to the changes in this field.
-The
-.Fu snprintf()
-function, for instance, was standardized with C99 and is available
-almost everywhere because of its high usefulness.
-In project's own implementation of
-.Fu snprintf()
-was dropped in March 2012 in favor for using the one of the
-standard library.
-.Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32
-Such decisions limit the portability of mmh
-if systems don't support these standardized and widespread functions.
-This compromise is made because mmh focuses on the future.
-.P
-I am not yet thirty years old and my C and Unix experience comprises
-only half a dozen years.
-Hence, I need to learn about the history in retrospective.
-I have not used those ancient constructs myself.
-I have not suffered from their incompatibilities.
-I have not longed for standardization.
-All my programming experience is from a time when ANSI C and POSIX
-were well established already.
-I have only read a lot of books about the (good) old times.
-This puts me in a difficult positions when working with old code.
-I need to freshly acquire knowledge about old code constructs and ancient
-programming styles, whereas older programmers know these things by
-heart from their own experience.
-.P
-Being aware of the situation, I rather let people with more historic
-experience replace ancient code constructs with standardized ones.
-Lyndon Nerenberg covered large parts of this task for the nmh project.
-He converted project-specific functions to POSIX replacements,
-also removing the conditionals compilation of now standardized features.
-Ken Hornstein and David Levine had their part in the work, too.
-Often, I only needed to pull over changes from nmh into mmh.
-These changes include many commits; these are among them:
-.Ci 768b5edd9623b7238e12ec8dfc409b82a1ed9e2d
-.Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 .
-.P
-During my own work, I tidied up the \fIMH standard library\fP,
-.Fn libmh.a ,
-which is located in the
-.Fn sbr
-(``subroutines'') directory in the source tree.
-The MH library includes functions that mmh tools usually need.
-Among them are MH-specific functions for profile, context, sequence,
-and folder handling, but as well
-MH-independent functions, such as auxiliary string functions,
-portability interfaces and error-checking wrappers for critical
-functions of the standard library.
-.P
-I have replaced the
-.Fu atooi()
-function with calls to
-.Fu strtoul()
-with the third parameter \(en the base \(en set to eight.
-.Fu strtoul()
-is part of C89 and thus considered safe to use.
-.Ci c490c51b3c0f8871b6953bd0c74551404f840a74
-.P
-I did remove project-included fallback implementations of
-.Fu memmove()
-and
-.Fu strerror() ,
-although Peter Maydell had re-included them into nmh in 2008
-to support SunOS 4.
-Nevertheless, these functions are part of ANSI C.
-Systems that do not even provide full ANSI C support should not
-put a load on mmh.
-.Ci b067ff5c465a5d243ce5a19e562085a9a1a97215
-.P
-The
-.Fu copy()
-function copies the string in argument one to the location in two.
-In contrast to
-.Fu strcpy() ,
-it returns a pointer to the terminating null-byte in the destination area.
-The code was adjusted to replace
-.Fu copy()
-with
-.Fu strcpy() ,
-except within
-.Fu concat() ,
-where
-.Fu copy()
-was more convenient.
-Therefore, the definition of
-.Fu copy()
-was moved into the source file of
-.Fu concat()
-and its visibility is now limited to it.
-.Ci 552fd7253e5ee9e554c5c7a8248a6322aa4363bb
-.P
-The function
-.Fu r1bindex()
-had been a generalized version of
-.Fu basename()
-with minor differences.
-As all calls to
-.Fu r1bindex()
-had the slash (`/') as delimiter anyway,
-replacing
-.Fu r1bindex()
-with the more specific and better-named function
-.Fu basename()
-became desirable.
-Unfortunately, many of the 54 calls to
-.Fu r1bindex()
-depended on a special behavior,
-which differed from the POSIX specification for
-.Fu basename() .
-Hence,
-.Fu r1bindex()
-was kept but renamed to
-.Fu mhbasename() ,
-fixing the delimiter to the slash.
-.Ci 240013872c392fe644bd4f79382d9f5314b4ea60
-For possible uses of
-.Fu r1bindex()
-with a different delimiter,
-the ANSI C function
-.Fu strrchr()
-provides the core functionality.
-.P
-The
-.Fu ssequal()
-function \(en apparently for ``substring equal'' \(en
-was renamed to
-.Fu isprefix() ,
-because this is what it actually checks.
-.Ci c20b4fa14515c7ab388ce35411d89a7a92300711
-Its source file had included the following comments, no joke.
-.VS
-/*
-* THIS CODE DOES NOT WORK AS ADVERTISED.
-* It is actually checking if s1 is a PREFIX of s2.
-* All calls to this function need to be checked to see
-* if that needs to be changed. Prefix checking is cheaper, so
-* should be kept if it's sufficient.
-*/
-/*
-* Check if s1 is a substring of s2.
-* If yes, then return 1, else return 0.
-*/
-VE
-Two months later, it was completely removed by replacing it with
-.Fu strncmp() .
-.Ci b0b1dd37ff515578cf7cba51625189eb34a196cb
-.H2 "Modularization
-.P
-The source code of the mmh tools is located in the
-.Fn uip
-(``user interface programs'') directory.
-Each tools has a source file with the same name.
-For example,
-.Pn rmm
-is built from
-.Fn uip/rmm.c .
-Some source files are used for multiple programs.
-For example
-.Fn uip/scansbr.c
-is used for both,
-.Pn scan
-and
-.Pn inc .
-In nmh, 49 tools were built from 76 source files.
-This is a ratio of 1.6 source files per program.
-32 programs depended on multiple source files;
-17 programs depended on one source file only.
-In mmh, 39 tools are built from 51 source files.
-This is a ratio of 1.3 source files per program.
-18 programs depend on multiple source files;
-21 programs depend on one source file only.
-(These numbers and the ones in the following text ignore the MH library
-as well as shell scripts and multiple names for the same program.)
-.P
-Splitting the source code of a large program into multiple files can
-increase the readability of its source code.
-Most of the mmh tools, however, are simple and straight-forward programs.
-With the exception of the MIME handling tools,
-.Pn pick
-is the largest tools.
-It contains 1\|037 lines of source code (measured with
-.Pn sloccount ), excluding the MH library.
-Only the MIME handling tools (\c
-.Pn mhbuild ,
-.Pn mhstore ,
-.Pn show ,
-etc.)
-are larger.
-Splitting programs with less than 1\|000 lines of code into multiple
-source files seldom leads to better readability.
-For such tools, splitting makes sense
-when parts of the code are reused in other programs,
-and the reused code fragment is not general enough
-for including it in the MH library,
-or, if the code has dependencies on a library that only few programs need.
-.Fn uip/packsbr.c ,
-for instance, provides the core program logic for the
-.Pn packf
-and
-.Pn rcvpack
-programs.
-.Fn uip/packf.c
-and
-.Fn uip/rcvpack.c
-mainly wrap the core function appropriately.
-No other tools use the folder packing functions.
-As another example,
-.Fn uip/termsbr.c
-provides termcap support, which requires linking with a termcap or
-curses library.
-Including
-.Fn uip/termsbr.c
-into the MH library would require every program to be linked with
-termcap or curses, although only few of the programs require it.
-.P
-The task of MIME handling is complex enough that splitting its code
-into multiple source files improves the readability.
-The program
-.Pn mhstore ,
-for instance, is compiled out of seven source files with 2\|500
-lines of code in summary.
-The main code file
-.Fn uip/mhstore.c
-consists of 800 lines; the other 1\|700 lines of code are reused in
-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 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:
-.Fn comp.c ,
-.Fn whatnowproc.c ,
-.Fn whatnowsbr.c ,
-.Fn sendsbr.c ,
-.Fn annosbr.c ,
-and
-.Fn distsbr.c .
-In mmh, it builds from only two:
-.Fn comp.c
-and
-.Fn whatnowproc.c .
-In nmh's
-.Pn comp ,
-the core function of
-.Pn whatnow ,
-.Pn send ,
-and
-.Pn anno
-were compiled into
-.Pn comp .
-This saved the need to execute these programs with
-.Fu fork()
-and
-.Fu exec() ,
-two expensive system calls.
-Whereis this approach improved the time performance,
-it interweaved the source code.
-Core functionalities were not encapsulated into programs but into
-function, which were then wrapped by programs.
-For example,
-.Fn uip/annosbr.c
-included the function
-.Fu annotate() .
-Each program that wanted to annotate messages, included the source file
-.Fn uip/annosbr.c
-and called
-.Fu annotate() .
-Because the function
-.Fu annotate()
-was used like the tool
-.Pn anno ,
-it had seven parameters, reflecting the command line switches of the tool.
-When another pair of command line switches was added to
-.Pn anno ,
-a rather ugly hack was implemented to avoid adding another parameter
-to the function.
-.Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f
-.P
-Separation simplifies the understanding of program code
-because the area influenced by any particular statement is smaller.
-The separating on the program-level is more strict than the separation
-on the function level.
-In mmh, the relevant code of
-.Pn comp
-comprises the two files
-.Fn uip/comp.c
-and
-.Fn uip/whatnowproc.c ,
-together 210 lines of code.
-In nmh,
-.Pn comp
-comprises six files with 2\|450 lines.
-Not all of the code in these six files was actually used by
-.Pn comp ,
-but the code reader needed to read all of the code first to know which
-parts were used.
-.P
-As I have read a lot in the code base during the last two years,
-I learned about the easy and the difficult parts.
-Code is easy to understand if:
-.BU
-The influenced code area is small
-.BU
-The boundaries are strictly defined
-.BU
-The code is written straight-forward
-.P
-.\" XXX move this paragraph somewhere else?
-Reading
-.Pn rmm 's
-source code in
-.Fn uip/rmm.c
-is my recommendation for a beginner's entry point into the code base of nmh.
-The reasons are that the task of
-.Pn rmm
-is straight forward and it consists of one small source code file only,
-yet its source includes code constructs typical for MH tools.
-With the introduction of the trash folder in mmh,
-.Pn rmm
-became a bit more complex, because it invokes
-.Pn refile .
-Still, it is a good example for a simple tool with clear sources.
-.P
-Understanding
-.Pn comp
-requires to read 210 lines of code in mmh, but ten times as much in nmh.
-Due to the aforementioned hack in
-.Pn anno
-to save the additional parameter, information passed through the program's
-source base in obscure ways.
-Thus, understanding
-.Pn comp ,
-required understanding the inner workings of
-.Fn uip/annosbr.c
-first.
-To be sure to fully understand a program, its whole source code needs
-to be examined.
-Not doing so is a leap of faith, assuming that the developers
-have avoided obscure programming techniques.
-By separating the tools on the program-level, the boundaries are
-clearly visible and technically enforced.
-The interfaces are calls to
-.Fu exec()
-rather than arbitrary function calls.
-.P
-But the real problem is another:
-Nmh violates the golden ``one tool, one job'' rule of the Unix philosophy.
-Understanding
-.Pn comp
-requires understanding
-.Fn uip/annosbr.c
-and
-.Fn uip/sendsbr.c
-because
-.Pn comp
-does annotate and send messages.
-In nmh, there surely exists the tool
-.Pn send ,
-which does (almost) only send messages.
-But
-.Pn comp
-and
-.Pn repl
-and
-.Pn forw
-and
-.Pn dist
-and
-.Pn whatnow
-and
-.Pn viamail ,
-they all (!) have the same message sending function included, too.
-In result,
-.Pn comp
-sends messages without using
-.Pn send .
-The situation is the same as if
-.Pn grep
-would page without
-.Pn more
-just because both programs are part of the same code base.
-.P
-The clear separation on the surface \(en the toolchest approach \(en
-is violated on the level below.
-This violation is for the sake of time performance.
-On systems where
-.Fu fork()
-and
-.Fu exec()
-are expensive, the quicker response might be noticable.
-In the old times, sacrificing readability and conceptional beauty for
-speed might even have been a must to prevent MH from being unusably slow.
-Whatever the reasons had been, today they are gone.
-No longer should we sacrifice readability or conceptional beauty.
-No longer should we violate the Unix philosophy's ``one tool, one job''
-guideline.
-No longer should we keep speed improvements that became unnecessary.
-.P
-Therefore, mmh's
-.Pn comp
-does no longer send messages.
-In mmh, different jobs are divided among separate programs that
-invoke each other as needed.
-In consequence,
-.Pn comp
-invokes
-.Pn whatnow
-which thereafter invokes
-.Pn send .
-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.
-The decrease of tools built from multiple source files and thus
-the decrease of
-.Fn uip/*sbr.c
-files confirm the improvement.
-.P
-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
-the developer's job to adjust the invocations of these tools as well.
-As this is a manual task and regression tests, which could detect such
-problems, are not available yet, it is prone to errors.
-These errors will not be detected at compile time but at run time.
-Installing regression tests is a task left to do.
-In the best case, a uniform way of invoking tools from other tools
-can be developed to allow automated testing at compile time.
-.H2 "User Data Locations
-.P
-In nmh, a personal setup consists of the MH profile and the MH directory.
-The profile is a file named
-.Fn \&.mh_profile
-in the user's home directory.
-It contains the static configuration.
-It also contains the location of the MH directory in the profile entry
-.Pe Path .
-The MH directory contains the mail storage and is the first
-place to search for personal forms, scan formats, and similar
-configuration files.
-The location of the MH directory can be chosen freely by the user.
-The default and usual name is a directory named
-.Fn Mail
-in the home directory.
-.P
-The way MH data is splitted between profile and MH directory is a legacy.
-It is only sensible in a situation where the profile is the only
-configuration file.
-Why else should the mail storage and the configuration files be intermixed?
-They are different kinds of data:
-The data to be operated on and the configuration to change how
-tools operate.
-Splitting the configuration between the profile and the MH directory
-is bad.
-Merging the mail storage and the configuration in one directory is bad
-as well.
-As the mail storage and the configuration were not separated sensibly
-in the first place, I did it now.
-.P
-Personal mmh data is grouped by type, resulting in two distinct parts:
-The mail storage and the configuration.
-In mmh, the mail storage directory still contains all the messages,
-but, in exception of public sequences files, nothing else.
-In difference to nmh, the auxiliary configuration files are no longer
-located there.
-Therefore, the directory is no longer called the user's \fIMH directory\fP
-but his \fImail storage\fP.
-Its location is still user-chosen, with the default name
-.Fn Mail ,
-in the user's home directory.
-In mmh, the configuration is grouped together in
-the hidden directory
-.Fn \&.mmh
-in the user's home directory.
-This \fImmh directory\fP contains the context file, personal forms,
-scan formats, and the like, but also the user's profile, now named
-.Fn profile .
-The location of the profile is no longer fixed to
-.Fn $HOME/.mh_profile
-but to
-.Fn $HOME/.mmh/profile .
-Having both, the file
-.Fn $HOME/.mh_profile
-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
-MH allows users to have multiiple 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
-could be used to specifiy a different profile.
-To operate in the same MH setup with a separate context,
-the
-.Ev MHCONTEXT
-environment variable could be used.
-This allows having own current folders and current messages in
-each terminal, for instance.
-In mmh, three environment variables are used.
-.Ev MMH
-overrides the default location of the mmh directory (\c
-.Fn .mmh ).
-.Ev MMHP
-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.
-.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.
-The main achievement of the change is the clear and sensible split
-between mail storage and configuration.
-.H1 "Concept Exploitation \"Homogeneity
-.H2 "Draft Folder
 .P
 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.
 system as a whole.
 Although my part in the draft handling improvement was small,
 it was important.
+.U3 "Trash Folder
-.H2 "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,
 to the file name.
 By generalizing the message removal in a way that it becomes covered
 by the MH concepts makes the whole system more powerful.
-.H2 "Path Notations
-.P
-FIXME! TODO
+.H1 "Styling
+.P
+Kernighan and Pike have emphasized the importance of style in the
+preface of their book:
-.H2 "Of One Cast
+.[ [
-.P
+kernighan pike practice of programming
+.], p. x]
+.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
+to improve on style.
+Many of them follow the rules given in the quoted book.
+.[
+kernighan pike practice of programming
+.]
+.H2 "Code Style
+.P
+.U3 "Indentation Style
+.P
+Indentation styles are the holy cow of programmers.
+Again Kernighan and Pike:
+.[ [
+kernighan pike practice of programming
+.], p. 10]
+.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
+time arguing.
+.QE
+.P
+I agree that the constant application is most important,
+but I believe that some styles have advantages over others.
+For instance the indentation with tab characters only.
+Tab characters directly map to the nesting level \(en
+one tab, one level.
+Tab characters are flexible because developers can adjust them to
+whatever width they like to have.
+There is no more need to run
+.Pn unexpand
+or
+.Pn entab
+programs to ensure the correct mixture of leading tabs and spaces.
+The simple rules are: (1) Leading whitespace must consist of tabs only.
+(2) Any other whitespace should consist of spaces.
+These two rules ensure the integrity of the visual appearance.
+Although reformatting existing code should be avoided, I did it.
+I did not waste time arguing; I just did it.
+.Ci a485ed478abbd599d8c9aab48934e7a26733ecb1
+.U3 "Comments
+.P
+Section 1.6 of
+.[ [
+kernighan pike practice of programming
+.], p. 23]
+demands: ``Don't belabor the obvious.''
+Hence, I simply removed all the comments in the following code excerpt:
+.VS
+context_replace(curfolder, folder);  /* update current folder  */
+seq_setcur(mp, mp->lowsel);  /* update current message */
+seq_save(mp);  /* synchronize message sequences */
+folder_free(mp);  /* free folder/message structure */
+context_save();  /* save the context file */
+[...]
+int c;  /* current character */
+char *cp;  /* miscellaneous character pointer */
+[...]
+/* NUL-terminate the field */
+*cp = '\0';
+VE
+.Ci 426543622b377fc5d091455cba685e114b6df674
+.P
+The names of the functions explain enough already.
+.U3 "Names
+.P
+Kernighan and Pike suggest:
+``Use active names for functions''.
+.[ [
+kernighan pike practice of programming
+.], p. 4]
+One application of this rule was the rename of
+.Fu check_charset()
+to
+.Fu is_native_charset() .
+.Ci 8d77b48284c58c135a6b2787e721597346ab056d
+The same change fixed a violation of ``Be accurate'' as well.
+The code did not match the expectation the function suggested,
+as it, for whatever reason, only compared the first ten characters
+of the charset name.
+.P
+More important than using active names is using descriptive names.
+Renaming the obscure function
+.Fu m_unknown()
+was a delightful event.
+.Ci 611d68d19204d7cbf5bd585391249cb5bafca846
+.P
+Magic numbers are generally considered bad style.
+Obviously, Kernighan and Pike agree:
+``Give names to magic numbers''.
+.[ [
+kernighan pike practice of programming
+.], p. 19]
+One such change was naming the type of input \(en mbox or mail folder \(en
+to be scanned:
+.VS
+#define SCN_MBOX (-1)
+#define SCN_FOLD 0
+VE
+.Ci 7ffb36d28e517a6f3a10272056fc127592ab1c19
+.P
+The argument
+.Ar outnum
+of the function
+.Fu scan()
+in
+.Fn uip/scansbr.c
+defines the number of the message to be created.
+If no message is to be created, the argument is misused to transport
+program logic.
+This lead to obscure code.
+I improved the clarity of the code by introducing two variables:
+.VS
+int incing = (outnum > 0);
+int ismbox = (outnum != 0);
+VE
+They cover the magic values and are used for conditions.
+The variable
+.Ar outnum
+is only used when it holds an ordinary message number.
+.Ci b8b075c77be7794f3ae9ff0e8cedb12b48fd139f
+The clarity improvement of the change showed detours in the program logic
+of related code parts.
+Having the new variables with descriptive names, a more
+straight forward implementation became apparent.
+Before the clarification was done,
+the possibility to improve had not be seen.
+.Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723
+.U3 "Rework of \f(CWanno\fP
+.P
+At the end of their chapter on style,
+Kernighan and Pike ask: ``But why worry about style?''
+The following example of my rework of
+.Pn anno
+provides an answer why style is important in the first place.
+.P
+Until 2002,
+.Pn anno
+had six functional command line switches,
+.Sw -component
+and
+.Sw -text ,
+which took 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.
+In need for more advanced annotation handling, he extended
+.Pn anno .
+He added five more switches:
+.Sw -draft ,
+.Sw -list ,
+.Sw -delete ,
+.Sw -append ,
+and
+.Sw -number ,
+the last one taking an argument.
+.Ci 7480dbc14bc90f2d872d434205c0784704213252
+Later,
+.Sw -[no]preserve
+was added.
+.Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f
+Then, the Synopsis section of the man page
+.Mp anno (1)
+read:
+.VS
+anno [+folder] [msgs] [-component field] [-inplace | -noinplace]
+	[-date | -nodate] [-draft] [-append] [-list] [-delete]
+	[-number [num|all]] [-preserve | -nopreserve] [-version]
+	[-help] [-text body]
+VE
+.LP
+The implementation followed the same structure.
+Problems became visible when
+.Cl "anno -list -number 42
+worked on the current message instead on message number 42,
+and
+.Cl "anno -list -number l:5
+did not work on the last five messages but failed with the mysterious
+error message: ``anno: missing argument to -list''.
+Yet, the invocation matched the specification in the man page.
+There, the correct use of
+.Sw -number
+was defined as being
+.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
+header fields with names matching the specified component,
+one per line. The listing is numbered, starting at 1, if
+the -number option is also used.
+.QE
+.LP
+The problem was manifold.
+The code required a numeric argument to the
+.Sw -number
+switch.
+If it was missing or non-numeric,
+.Pn anno
+aborted with an error message that had an off-by-one error,
+printing the switch one before the failing one.
+Semantically, the argument to the
+.Sw -number
+switch is only necessary in combination with
+.Sw -delete ,
+but not with
+.Sw -list .
+In the former case it is even necessary.
+.P
+Trying to fix these problems on the surface would not have solved it truly.
+The problems discovered originate from a discrepance between the semantic
+structure of the problem and the structure implemented in the program.
+Such structural differences can not be cured on the surface.
+They need to be solved by adjusting the structure of the implementation
+to the structure of the problem.
+.P
+In 2002, the new switches
+.Sw -list
+and
+.Sw -delete
+were added in the same way, the
+.Sw -number
+switch for instance had been added.
+Yet, they are of structural different type.
+Semantically,
+.Sw -list
+and
+.Sw -delete
+introduce modes of operation.
+Historically,
+.Pn anno
+had only one operation mode: adding header fields.
+With the extension, it got two moder modes:
+listing and deleting header fields.
+The structure of the code changes did not pay respect to this
+fundamental change to
+.Pn anno 's
+behavior.
+Neither the implementation nor the documentation did clearly
+define them as being exclusive modes of operation.
+Having identified the problem, I solved it by putting structure into
+.Pn anno
+and its documentation.
+.Ci d54c8db8bdf01e8381890f7729bc0ef4a055ea11
+.P
+The difference is visible in both, the code and the documentation.
+The following code excerpt:
+.VS
+int delete = -2;  /* delete header element if set */
+int list = 0;  /* list header elements if set */
+[...]
+	case DELETESW:  /* delete annotations */
+		delete = 0;
+		continue;
+	case LISTSW:  /* produce a listing */
+		list = 1;
+		continue;
+VE
+.LP
+was replaced by:
+.VS
+static enum { MODE_ADD, MODE_DEL, MODE_LIST } mode = MODE_ADD;
+[...]
+	case DELETESW:  /* delete annotations */
+		mode = MODE_DEL;
+		continue;
+	case LISTSW:  /* produce a listing */
+		mode = MODE_LIST;
+		continue;
+VE
+.LP
+The replacement code does not only reflect the problem's structure better,
+it is easier to understand as well.
+The same applies to the documentation.
+The man page was completely reorganized to propagate the same structure.
+This is visible in the Synopsis section:
+.VS
+anno [+folder] [msgs] [-component field] [-text body]
+	[-append] [-date | -nodate] [-preserve | -nopreserve]
+	[-Version] [-help]
+anno -delete [+folder] [msgs] [-component field] [-text
+	body] [-number num | all ] [-preserve | -nopreserve]
+	[-Version] [-help]
+anno -list [+folder] [msgs] [-component field] [-number]
+	[-Version] [-help]
+VE
+.\" XXX think about explaining the -preserve rework?
+.H2 "Standard Libraries
+.P
+MH is one decade older than the POSIX and ANSI C standards.
+Hence, MH included own implementations of functions
+that are standardized and thus widely available today,
+but were not back then.
+Today, twenty years after the POSIX and ANSI C were published,
+developers can expect system to comply with these standards.
+In consequence, MH-specific replacements for standard functions
+can and should be dropped.
+Kernighan and Pike advise: ``Use standard libraries.''
+.[ [
+kernighan pike practice of programming
+.], p. 196]
+Actually, MH had followed this advice in history,
+but it had not adjusted to the changes in this field.
+The
+.Fu snprintf()
+function, for instance, was standardized with C99 and is available
+almost everywhere because of its high usefulness.
+In project's own implementation of
+.Fu snprintf()
+was dropped in March 2012 in favor for using the one of the
+standard library.
+.Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32
+Such decisions limit the portability of mmh
+if systems don't support these standardized and widespread functions.
+This compromise is made because mmh focuses on the future.
+.P
+I am not yet thirty years old and my C and Unix experience comprises
+only half a dozen years.
+Hence, I need to learn about the history in retrospective.
+I have not used those ancient constructs myself.
+I have not suffered from their incompatibilities.
+I have not longed for standardization.
+All my programming experience is from a time when ANSI C and POSIX
+were well established already.
+I have only read a lot of books about the (good) old times.
+This puts me in a difficult positions when working with old code.
+I need to freshly acquire knowledge about old code constructs and ancient
+programming styles, whereas older programmers know these things by
+heart from their own experience.
+.P
+Being aware of the situation, I rather let people with more historic
+experience replace ancient code constructs with standardized ones.
+Lyndon Nerenberg covered large parts of this task for the nmh project.
+He converted project-specific functions to POSIX replacements,
+also removing the conditionals compilation of now standardized features.
+Ken Hornstein and David Levine had their part in the work, too.
+Often, I only needed to pull over changes from nmh into mmh.
+These changes include many commits; these are among them:
+.Ci 768b5edd9623b7238e12ec8dfc409b82a1ed9e2d
+.Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 .
+.P
+During my own work, I tidied up the \fIMH standard library\fP,
+.Fn libmh.a ,
+which is located in the
+.Fn sbr
+(``subroutines'') directory in the source tree.
+The MH library includes functions that mmh tools usually need.
+Among them are MH-specific functions for profile, context, sequence,
+and folder handling, but as well
+MH-independent functions, such as auxiliary string functions,
+portability interfaces and error-checking wrappers for critical
+functions of the standard library.
+.P
+I have replaced the
+.Fu atooi()
+function with calls to
+.Fu strtoul()
+with the third parameter \(en the base \(en set to eight.
+.Fu strtoul()
+is part of C89 and thus considered safe to use.
+.Ci c490c51b3c0f8871b6953bd0c74551404f840a74
+.P
+I did remove project-included fallback implementations of
+.Fu memmove()
+and
+.Fu strerror() ,
+although Peter Maydell had re-included them into nmh in 2008
+to support SunOS 4.
+Nevertheless, these functions are part of ANSI C.
+Systems that do not even provide full ANSI C support should not
+put a load on mmh.
+.Ci b067ff5c465a5d243ce5a19e562085a9a1a97215
+.P
+The
+.Fu copy()
+function copies the string in argument one to the location in two.
+In contrast to
+.Fu strcpy() ,
+it returns a pointer to the terminating null-byte in the destination area.
+The code was adjusted to replace
+.Fu copy()
+with
+.Fu strcpy() ,
+except within
+.Fu concat() ,
+where
+.Fu copy()
+was more convenient.
+Therefore, the definition of
+.Fu copy()
+was moved into the source file of
+.Fu concat()
+and its visibility is now limited to it.
+.Ci 552fd7253e5ee9e554c5c7a8248a6322aa4363bb
+.P
+The function
+.Fu r1bindex()
+had been a generalized version of
+.Fu basename()
+with minor differences.
+As all calls to
+.Fu r1bindex()
+had the slash (`/') as delimiter anyway,
+replacing
+.Fu r1bindex()
+with the more specific and better-named function
+.Fu basename()
+became desirable.
+Unfortunately, many of the 54 calls to
+.Fu r1bindex()
+depended on a special behavior,
+which differed from the POSIX specification for
+.Fu basename() .
+Hence,
+.Fu r1bindex()
+was kept but renamed to
+.Fu mhbasename() ,
+fixing the delimiter to the slash.
+.Ci 240013872c392fe644bd4f79382d9f5314b4ea60
+For possible uses of
+.Fu r1bindex()
+with a different delimiter,
+the ANSI C function
+.Fu strrchr()
+provides the core functionality.
+.P
+The
+.Fu ssequal()
+function \(en apparently for ``substring equal'' \(en
+was renamed to
+.Fu isprefix() ,
+because this is what it actually checks.
+.Ci c20b4fa14515c7ab388ce35411d89a7a92300711
+Its source file had included the following comments, no joke.
+.VS
+/*
+* THIS CODE DOES NOT WORK AS ADVERTISED.
+* It is actually checking if s1 is a PREFIX of s2.
+* All calls to this function need to be checked to see
+* if that needs to be changed. Prefix checking is cheaper, so
+* should be kept if it's sufficient.
+*/
+/*
+* Check if s1 is a substring of s2.
+* If yes, then return 1, else return 0.
+*/
+VE
+Two months later, it was completely removed by replacing it with
+.Fu strncmp() .
+.Ci b0b1dd37ff515578cf7cba51625189eb34a196cb
+.H2 "Modularization
+.P
+The source code of the mmh tools is located in the
+.Fn uip
+(``user interface programs'') directory.
+Each tools has a source file with the same name.
+For example,
+.Pn rmm
+is built from
+.Fn uip/rmm.c .
+Some source files are used for multiple programs.
+For example
+.Fn uip/scansbr.c
+is used for both,
+.Pn scan
+and
+.Pn inc .
+In nmh, 49 tools were built from 76 source files.
+This is a ratio of 1.6 source files per program.
+32 programs depended on multiple source files;
+17 programs depended on one source file only.
+In mmh, 39 tools are built from 51 source files.
+This is a ratio of 1.3 source files per program.
+18 programs depend on multiple source files;
+21 programs depend on one source file only.
+(These numbers and the ones in the following text ignore the MH library
+as well as shell scripts and multiple names for the same program.)
+.P
+Splitting the source code of a large program into multiple files can
+increase the readability of its source code.
+Most of the mmh tools, however, are simple and straight-forward programs.
+With the exception of the MIME handling tools,
+.Pn pick
+is the largest tools.
+It contains 1\|037 lines of source code (measured with
+.Pn sloccount ), excluding the MH library.
+Only the MIME handling tools (\c
+.Pn mhbuild ,
+.Pn mhstore ,
+.Pn show ,
+etc.)
+are larger.
+Splitting programs with less than 1\|000 lines of code into multiple
+source files seldom leads to better readability.
+For such tools, splitting makes sense
+when parts of the code are reused in other programs,
+and the reused code fragment is not general enough
+for including it in the MH library,
+or, if the code has dependencies on a library that only few programs need.
+.Fn uip/packsbr.c ,
+for instance, provides the core program logic for the
+.Pn packf
+and
+.Pn rcvpack
+programs.
+.Fn uip/packf.c
+and
+.Fn uip/rcvpack.c
+mainly wrap the core function appropriately.
+No other tools use the folder packing functions.
+As another example,
+.Fn uip/termsbr.c
+provides termcap support, which requires linking with a termcap or
+curses library.
+Including
+.Fn uip/termsbr.c
+into the MH library would require every program to be linked with
+termcap or curses, although only few of the programs require it.
+.P
+The task of MIME handling is complex enough that splitting its code
+into multiple source files improves the readability.
+The program
+.Pn mhstore ,
+for instance, is compiled out of seven source files with 2\|500
+lines of code in summary.
+The main code file
+.Fn uip/mhstore.c
+consists of 800 lines; the other 1\|700 lines of code are reused in
+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 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:
+.Fn comp.c ,
+.Fn whatnowproc.c ,
+.Fn whatnowsbr.c ,
+.Fn sendsbr.c ,
+.Fn annosbr.c ,
+and
+.Fn distsbr.c .
+In mmh, it builds from only two:
+.Fn comp.c
+and
+.Fn whatnowproc.c .
+In nmh's
+.Pn comp ,
+the core function of
+.Pn whatnow ,
+.Pn send ,
+and
+.Pn anno
+were compiled into
+.Pn comp .
+This saved the need to execute these programs with
+.Fu fork()
+and
+.Fu exec() ,
+two expensive system calls.
+Whereis this approach improved the time performance,
+it interweaved the source code.
+Core functionalities were not encapsulated into programs but into
+function, which were then wrapped by programs.
+For example,
+.Fn uip/annosbr.c
+included the function
+.Fu annotate() .
+Each program that wanted to annotate messages, included the source file
+.Fn uip/annosbr.c
+and called
+.Fu annotate() .
+Because the function
+.Fu annotate()
+was used like the tool
+.Pn anno ,
+it had seven parameters, reflecting the command line switches of the tool.
+When another pair of command line switches was added to
+.Pn anno ,
+a rather ugly hack was implemented to avoid adding another parameter
+to the function.
+.Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f
+.P
+Separation simplifies the understanding of program code
+because the area influenced by any particular statement is smaller.
+The separating on the program-level is more strict than the separation
+on the function level.
+In mmh, the relevant code of
+.Pn comp
+comprises the two files
+.Fn uip/comp.c
+and
+.Fn uip/whatnowproc.c ,
+together 210 lines of code.
+In nmh,
+.Pn comp
+comprises six files with 2\|450 lines.
+Not all of the code in these six files was actually used by
+.Pn comp ,
+but the code reader needed to read all of the code first to know which
+parts were used.
+.P
+As I have read a lot in the code base during the last two years,
+I learned about the easy and the difficult parts.
+Code is easy to understand if:
+.BU
+The influenced code area is small
+.BU
+The boundaries are strictly defined
+.BU
+The code is written straight-forward
+.P
+.\" XXX move this paragraph somewhere else?
+Reading
+.Pn rmm 's
+source code in
+.Fn uip/rmm.c
+is my recommendation for a beginner's entry point into the code base of nmh.
+The reasons are that the task of
+.Pn rmm
+is straight forward and it consists of one small source code file only,
+yet its source includes code constructs typical for MH tools.
+With the introduction of the trash folder in mmh,
+.Pn rmm
+became a bit more complex, because it invokes
+.Pn refile .
+Still, it is a good example for a simple tool with clear sources.
+.P
+Understanding
+.Pn comp
+requires to read 210 lines of code in mmh, but ten times as much in nmh.
+Due to the aforementioned hack in
+.Pn anno
+to save the additional parameter, information passed through the program's
+source base in obscure ways.
+Thus, understanding
+.Pn comp ,
+required understanding the inner workings of
+.Fn uip/annosbr.c
+first.
+To be sure to fully understand a program, its whole source code needs
+to be examined.
+Not doing so is a leap of faith, assuming that the developers
+have avoided obscure programming techniques.
+By separating the tools on the program-level, the boundaries are
+clearly visible and technically enforced.
+The interfaces are calls to
+.Fu exec()
+rather than arbitrary function calls.
+.P
+But the real problem is another:
+Nmh violates the golden ``one tool, one job'' rule of the Unix philosophy.
+Understanding
+.Pn comp
+requires understanding
+.Fn uip/annosbr.c
+and
+.Fn uip/sendsbr.c
+because
+.Pn comp
+does annotate and send messages.
+In nmh, there surely exists the tool
+.Pn send ,
+which does (almost) only send messages.
+But
+.Pn comp
+and
+.Pn repl
+and
+.Pn forw
+and
+.Pn dist
+and
+.Pn whatnow
+and
+.Pn viamail ,
+they all (!) have the same message sending function included, too.
+In result,
+.Pn comp
+sends messages without using
+.Pn send .
+The situation is the same as if
+.Pn grep
+would page without
+.Pn more
+just because both programs are part of the same code base.
+.P
+The clear separation on the surface \(en the toolchest approach \(en
+is violated on the level below.
+This violation is for the sake of time performance.
+On systems where
+.Fu fork()
+and
+.Fu exec()
+are expensive, the quicker response might be noticable.
+In the old times, sacrificing readability and conceptional beauty for
+speed might even have been a must to prevent MH from being unusably slow.
+Whatever the reasons had been, today they are gone.
+No longer should we sacrifice readability or conceptional beauty.
+No longer should we violate the Unix philosophy's ``one tool, one job''
+guideline.
+No longer should we keep speed improvements that became unnecessary.
+.P
+Therefore, mmh's
+.Pn comp
+does no longer send messages.
+In mmh, different jobs are divided among separate programs that
+invoke each other as needed.
+In consequence,
+.Pn comp
+invokes
+.Pn whatnow
+which thereafter invokes
+.Pn send .
+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.
+The decrease of tools built from multiple source files and thus
+the decrease of
+.Fn uip/*sbr.c
+files confirm the improvement.
+.P
+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
+the developer's job to adjust the invocations of these tools as well.
+As this is a manual task and regression tests, which could detect such
+problems, are not available yet, it is prone to errors.
+These errors will not be detected at compile time but at run time.
+Installing regression tests is a task left to do.
+In the best case, a uniform way of invoking tools from other tools
+can be developed to allow automated testing at compile time.
+.H2 "User Data Locations
+.P
+In nmh, a personal setup consists of the MH profile and the MH directory.
+The profile is a file named
+.Fn \&.mh_profile
+in the user's home directory.
+It contains the static configuration.
+It also contains the location of the MH directory in the profile entry
+.Pe Path .
+The MH directory contains the mail storage and is the first
+place to search for personal forms, scan formats, and similar
+configuration files.
+The location of the MH directory can be chosen freely by the user.
+The default and usual name is a directory named
+.Fn Mail
+in the home directory.
+.P
+The way MH data is splitted between profile and MH directory is a legacy.
+It is only sensible in a situation where the profile is the only
+configuration file.
+Why else should the mail storage and the configuration files be intermixed?
+They are different kinds of data:
+The data to be operated on and the configuration to change how
+tools operate.
+Splitting the configuration between the profile and the MH directory
+is bad.
+Merging the mail storage and the configuration in one directory is bad
+as well.
+As the mail storage and the configuration were not separated sensibly
+in the first place, I did it now.
+.P
+Personal mmh data is grouped by type, resulting in two distinct parts:
+The mail storage and the configuration.
+In mmh, the mail storage directory still contains all the messages,
+but, in exception of public sequences files, nothing else.
+In difference to nmh, the auxiliary configuration files are no longer
+located there.
+Therefore, the directory is no longer called the user's \fIMH directory\fP
+but his \fImail storage\fP.
+Its location is still user-chosen, with the default name
+.Fn Mail ,
+in the user's home directory.
+In mmh, the configuration is grouped together in
+the hidden directory
+.Fn \&.mmh
+in the user's home directory.
+This \fImmh directory\fP contains the context file, personal forms,
+scan formats, and the like, but also the user's profile, now named
+.Fn profile .
+The location of the profile is no longer fixed to
+.Fn $HOME/.mh_profile
+but to
+.Fn $HOME/.mmh/profile .
+Having both, the file
+.Fn $HOME/.mh_profile
+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
+MH allows users to have multiiple 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
+could be used to specifiy a different profile.
+To operate in the same MH setup with a separate context,
+the
+.Ev MHCONTEXT
+environment variable could be used.
+This allows having own current folders and current messages in
+each terminal, for instance.
+In mmh, three environment variables are used.
+.Ev MMH
+overrides the default location of the mmh directory (\c
+.Fn .mmh ).
+.Ev MMHP
+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.
+.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.
+The main achievement of the change is the clear and sensible split
+between mail storage and configuration.
+.H2 "Path Conversion
+.P
+FIXME! XXX
+commit d39e2c447b0d163a5a63f480b23d06edb7a73aa0
+Author: markus schnalke <meillo@marmaro.de>
+Date:   Fri Dec 9 16:34:57 2011 +0100
+Completely reworked the path convertion functions
+Moved everything (from sbr/getfolder.c and sbr/m_maildir.c) into
+sbr/path.c, but actually replaced the code almost completely.
+See h/prototypes.h for the function changes.
+sbr/path.c provides explaining comments on the functions.
+None of them allocates memory automatically.
+Additionally:
+- Like for other ``files'', `inc -audit file' places file relative
+to the cwd, not relative to the mh-dir. This is for consistency.
+- Replaced add(foo, NULL) with getcpy(foo), which ist clearer.

Mercurial > docs > master

comparison discussion.roff @ 131:7c741bc8f719