docs/master: discussion.roff comparison

comparison discussion.roff @ 220:95257474a123

Further improvements in the discussion; added build dependency graphs.

author	markus schnalke <meillo@marmaro.de>
date	Sun, 15 Jul 2012 18:41:35 +0200
parents	8c537982d718
children	1fa5a74bf138

comparison

equal deleted inserted replaced

-:8c537982d718
+:95257474a123
 is not related to the mail client, and
 .Pn msh
 conflicts with the basic concept of MH.
 These two tools might still be useful, but they should not be part of mmh.
 .P
+.Id slocal
 Finally, there is
 .Pn slocal ,
 which is an MDA and thus not directly MUA-related.
 It should be removed from mmh because including it conflicts with
 the idea that mmh is an MUA only.
 .H2 "Profile Reading
 .P
-The MH profile contains the configuration for the user-specific MH setup.
+The MH profile contains the configuration of a user-specific MH setup.
-MH tools read the profile right after starting up,
+MH tools read the profile right after starting up
-as it contains the location of the user's mail storage
+because it contains the location of the user's mail storage
 and similar settings that influence the whole setup.
-Furthermore, the profile contains the default switches for the tools,
+Furthermore, the profile contains the default switches for the tools
-hence, it must be read before the command line switches are processed.
+as well.
+The context file is read along with the profile.
 .P
 For historic reasons, some MH tools did not read the profile and context.
 Among them were
 .Pn post /\c
 .Pn spost ,
 .Pn mhmail ,
 and
 .Pn slocal .
 The reason why these tools ignored the profile were not clearly stated.
-During the discussion on the nmh-workers mailing list,
+During a discussion on the nmh-workers mailing list,
 David Levine posted an explanation, quoting John Romine:
 .[
 nmh-workers levine post profile
 .]
 .QS
 I asked John Romine and here's what he had to say, which
 agrees and provides an example that convinces me:
 .QS
 My take on this is that
 use an environment variable (I think
 .Pn send /\c
 .Pn whatnow
 do this).
 .QE
+.sp \n(PDu
 I think that's the way to go.
 My personal preference is to use a command line option,
 not an environment variable.
 .QE
-.P
-To solve the problem of
+.P
+To solve the problem that
 .Pn post
-not honoring the
+does not honor the
 .Pe fileproc
 profile entry,
 the community roughly agreed that a switch
 .Sw -fileproc
 should be added to
 .Pn post
 to be able to pass a different fileproc.
 I strongly disagree with this approach because it does not solve
 the problem; it only removes a single symptom.
-The problem is that
+The actual problem is that
 .Pn post
-does not behave as expected.
+does not behave as expected,
-But all programs should behave as expected.
+though all programs should behave as expected.
-Clear and simple concepts are a precondition for this.
+Clear and general concepts are a precondition for this.
-Hence, the real solution is having all MH tools read the profile.
+Thus, there should be no separation into ``front-end UI programs''
-.P
+and ones that ``should not be called by users directly''.
-The problem has a further aspect.
+The real solution is having all MH tools read the profile.
-It mainly originates in
+.P
-.Pn mhmail .
+But the problem has a further aspect,
+which originates from
+.Pn mhmail
+mainly.
 .Pn mhmail
 was intended to be a replacement for
 .Pn mailx
 on systems with MH installations.
+In difference to
+.Pn mailx ,
 .Pn mhmail
-should have been able to use just like
+used MH's
-.Pn mailx ,
-but sending the message via MH's
 .Pn post
-instead of
+to send the message.
-.Pn sendmail .
+The idea was that using
-Using
 .Pn mhmail
-should not be influenced by the question whether the user had
+should not be influenced whether the user had
 MH set up for himself or not.
+Therefore
 .Pn mhmail
-did not read the profile as this requests the user to set up MH
+had not read the profile.
-if not done yet.
 As
 .Pn mhmail
 used
 .Pn post ,
 .Pn post
-could not read the profile neither.
+was not allowed to read the profile neither.
-This is the reason why
-.Pn post
-does not read the profile.
 This is the reason for the actual problem.
-It was not much of a problem because
+Yet, this was not considered much of a problem because
 .Pn post
 was not intended to be used by users directly.
+To invoke
+.Pn post ,
 .Pn send
-is the interactive front-end to
+was used an a front-end.
-.Pn post .
 .Pn send
 read the profile and passed all relevant values on the command line to
 .Pn post
 \(en an awkward solution.
 .P
 The important insight is that
 .Pn mhmail
-is no true MH tool.
+is a wolf in sheep's clothing.
-The concepts broke because this outlandish tool was treated as any other
+This alien tool broke the concepts because it was treated like
-MH tool.
+a normal MH tool.
 Instead it should have been treated accordingly to its foreign style.
-The solution is not to prevent the tools reading the profile but
+.P
-to instruct them reading a different profile.
+The solution is not to prevent the tools from reading the profile but
+to instruct them to read a different profile.
 .Pn mhmail
-could have set up a well-defined profile and caused all MH tools
+could have set up a well-defined profile and caused the following
-in the session to use it by exporting an environment variable.
-With this approach, no special cases would have been introduced,
-no surprises would have been caused.
-By writing a clean-profile-wrapper, the concept could have been
-generalized orthogonally to the whole MH tool chest.
-Then Rose's motivation behind the decision that
 .Pn post
-ignores the profile, as quoted by Jeffrey Honig,
+to use this profile by exporting an environment variable.
-would have become possible:
+With this approach, no special cases would have been introduced
+and no surprises would have been caused.
+By writing a wrapper program to provide a clean temporary profile,
+the concept could have been generalized orthogonally to the whole
+MH tool chest.
+.P
+In mmh, the wish to have
+.Pn mhmail
+as a replacement for
+.Pn mailx
+is considered obsolete.
+Mmh's
+.Pn mhmail
+does no longer cover this use-case
+.Ci d36e56e695fe1c482c7920644bfbb6386ac9edb0 .
+Currently,
+.Pn mhmail
+is in a transition state
+.Ci 32d4f9daaa70519be3072479232ff7be0500d009 .
+It may become a front-end to
+.Pn comp ,
+which provides an alternative interface which can be more convenient
+in some cases.
+This would convert
+.Pn mhmail
+into an ordinary MH tool.
+If, however, this idea does not convince, then
+.Pn mhmail
+will be removed.
+.P
+In the mmh tool chest, every program reads the profile.
+(\c
+.Pn slocal
+is not considered part of the mmh tool chest (cf. Sec.
+.Cf slocal ).)
+Mmh has no
+.Pn post
+program, but it has
+.Pn spost ,
+which now does read the profile
+.Ci 3e017a7abbdf69bf0dff7a4073275961eda1ded8 .
+Following this change,
+.Pn send
+and
+.Pn spost
+can be considered for merging.
+Besides
+.Pn send ,
+.Pn spost
+is only invoked directly by the to-be-changed
+.Pn mhmail
+implementation and by
+.Pn rcvdist ,
+which requires rework anyway.
+.P
+Jeffrey Honig quoted Marshall T. Rose explaining the decision that
+.Pn post
+ignores the profile:
 .[
 nmh-workers honig post profile
 .]
 .QS
 when you run mh commands in a script, you want all the defaults to be
 what the man page says.
 when you run a command by hand, then you want your own defaults...
 .QE
 .LP
-Yet, I consider this explanation shortsighted.
+The explanation neither matches the problem concered exactly
-We should rather regard theses two cases as just two different MH setups,
+nor is the interpretation clear.
-based on two different profiles.
+If the described desire addresses the technical level,
-Mapping such problems on the concepts of switching between different
+then it conflicts fundametally with the Unix philosophy,
-profiles, solves them once for all.
+precisely because the indistinquishability of human and script
-.P
+input is the main reason for the huge software leverage in Unix.
-In mmh, the wish to have
+If, however, the described desire addresses the user's view,
-.Pn mhmail
+then different technical solutions are more appropriate.
-as a replacement for
+The two cases can be regarded simply as two different MH setups.
-.Pn mailx
+Hence, mapping the problem of different behavior between interactive and
-is considered obsolete.
+automated use on the concept of switching between different profiles,
-Mmh's
+marks it already solved.
-.Pn mhmail
-does no longer cover this use-case.
-Currently,
-.Pn mhmail
-is in a transition state.
-.Ci 32d4f9daaa70519be3072479232ff7be0500d009
-It may become a front-end to
-.Pn comp ,
-which provides an interface more convenient in some cases.
-In this case,
-.Pn mhmail
-will become an ordinary MH tool, reading the profile.
-If, however, this idea will not convince, then
-.Pn mhmail
-will be removed.
-.P
-Every program in the mmh tool chest reads the profile.
-The only exception is
-.Pn slocal ,
-which is not considered part of the mmh tool chest.
-This MDA is only distributed with mmh, currently.
-Mmh has no
-.Pn post
-program, but
-.Pn spost ,
-which now reads the profile.
-.Ci 3e017a7abbdf69bf0dff7a4073275961eda1ded8
-With this change,
-.Pn send
-and
-.Pn spost
-can be considered to be merged.
-.Pn spost
-is only invoked directly by the to-be-changed
-.Pn mhmail
-implementation and by
-.Pn rcvdist ,
-which will require rework.
-.P
-The
-.Fu context_foil()
-function to pretend to have read an empty profile was removed.
-.Ci 68af8da96bea87a5541988870130b6209ce396f6
-All mmh tools read the profile.
 .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,
+that were neither standardized nor widely available, back then.
-but were not back then.
+Today, twenty years after POSIX and ANSI C were published,
-Today, twenty years after the POSIX and ANSI C were published,
+developers can expect that systems comply with these standards.
-developers can expect systems 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 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.
+but it had not adjusted to more recent changes in this field.
 The
 .Fu snprintf()
 function, for instance, was standardized with C99 and is available
 almost everywhere because of its high usefulness.
-The project's own implementation of
+Thus, the project's own implementation of
 .Fu snprintf()
 was dropped in March 2012 in favor for using the one of the
-standard library.
+standard library
-.Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32
+.Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 .
 Such decisions limit the portability of mmh
 if systems do not support these standardized and widespread functions.
 This compromise is made because mmh focuses on the future.
 .P
 .\" XXX kuerzen und mit dem naechsten Absatz vereinen
-I am still in my twenties and my C and Unix experience comprises
+As I am still in my twenties, have no programming experience from
-only half a dozen years.
+past decades.
-Hence, I need to learn about the history in retrospective.
+I have not followed the evolution of C through time.
-I have not used those ancient constructs myself.
+I have not suffered from the the Unix wars.
-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.
+Thus, I needed to learn about the history in retrospective.
 I have only read a lot of books about the (good) old times.
-This puts me in a difficult position when working with old code.
+This put me in a difficult position 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.
+experience do the transition from ancient code constructs to
+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.
+Ken Hornstein and David Levine had their part in this work, as well.
-Often, I only needed to pull over changes from nmh into mmh.
+Often, I only pulled the changes over from nmh into mmh.
-These changes include many commits; these are among them:
+These changes include many commits, among them:
 .Ci 768b5edd9623b7238e12ec8dfc409b82a1ed9e2d
 .Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 .
 .P
-During my own work, I tidied up the \fIMH standard library\fP,
+Nevertheless, I worked on the task as well, tidying up the
-.Fn libmh.a ,
+\fIMH standard library\fP,
-which is located in the
+.Fn libmh.a .
+It is located in the
 .Fn sbr
-(``subroutines'') directory in the source tree.
+(``subroutines'') directory in the source tree and
-The MH library includes functions that mmh tools usually need.
+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
+.BU
 I have replaced the
 .Fu atooi()
 function with calls to
+.Fu strtoul() ,
+setting the third parameter, the base, to eight.
 .Fu strtoul()
-with the third parameter, the base, set to eight.
+is part of C89 and thus considered safe to use
-.Fu strtoul()
+.Ci c490c51b3c0f8871b6953bd0c74551404f840a74 .
-is part of C89 and thus considered safe to use.
+.BU
-.Ci c490c51b3c0f8871b6953bd0c74551404f840a74
-.P
 I did remove project-included fallback implementations of
 .Fu memmove()
 and
-.Fu strerror() ,
+.Fu strerror()
+.Ci b067ff5c465a5d243ce5a19e562085a9a1a97215 ,
 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
+.BU
-.P
 The
 .Fu copy()
 function copies the string in parameter one to the location in
 parameter two.
 In contrast to
 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.
+and its visibility it limited to that
-.Ci 552fd7253e5ee9e554c5c7a8248a6322aa4363bb
+.Ci 552fd7253e5ee9e554c5c7a8248a6322aa4363bb .
-.P
+.BU
 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,
+had the slash (`\fL/\fP') as delimiter anyway,
 replacing
 .Fu r1bindex()
 with the more specific and better-named function
 .Fu basename()
 became desirable.
 .Fu basename() .
 Hence,
 .Fu r1bindex()
 was kept but renamed to
 .Fu mhbasename() ,
-fixing the delimiter to the slash.
+setting the delimiter to the slash
-.Ci 240013872c392fe644bd4f79382d9f5314b4ea60
+.Ci 240013872c392fe644bd4f79382d9f5314b4ea60 .
 For possible uses of
 .Fu r1bindex()
 with a different delimiter,
 the ANSI C function
 .Fu strrchr()
 provides the core functionality.
-.P
+.BU
 The
 .Fu ssequal()
 function \(en apparently for ``substring equal'' \(en
 was renamed to
 .Fu isprefix() ,
-because this is what it actually checks.
+because this is what it actually checked
-.Ci c20b4fa14515c7ab388ce35411d89a7a92300711
+.Ci c20b4fa14515c7ab388ce35411d89a7a92300711.
-Its source file had included the following comments, no joke.
+Its source file had included both of the following comments, no joke.
+.in -\n(PIu
 .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
 /*
 * 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
+.in +\n(PIu
-.Fu strncmp() .
+Eventually, the function was completely replaced with calls to
-.Ci b0b1dd37ff515578cf7cba51625189eb34a196cb
+.Fu strncmp()
+.Ci b0b1dd37ff515578cf7cba51625189eb34a196cb .
 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
+place to search for form files, 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
+The usual name is a directory named
 .Fn Mail
-in the home directory.
+in the user's home directory.
 .P
 The way MH data is split 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:
+They are of different kind:
-The data to be operated on and the configuration to change how
+One kind is the data to be operated on and the other kind is
-tools operate.
+the configuration to change how tools operate.
-.\" XXX bad ... inapropriate?
 Splitting the configuration between the profile and the MH directory
-is bad.
+is inappropriate, as well.
-Merging the mail storage and the configuration in one directory is bad
+I improved the situation by breaking compatibility.
-as well.
+.P
-As the mail storage and the configuration were not separated sensibly
+In mmh, personal data is grouped by type.
-in the first place, I did it now.
+This results in two distinct parts:
-.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,
+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.
+but the user's \fImail storage\fP.
 Its location is still user-chosen, with the default name
-.Fn Mail ,
+.Fn Mail
 in the user's home directory.
-In mmh, the configuration is grouped together in
+The configuration is grouped together in the hidden directory
-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
+The path to the profile is no longer
 .Fn $HOME/.mh_profile
-but to
+but
 .Fn $HOME/.mmh/profile .
-Having both the file
+(The alternative of having file
 .Fn $HOME/.mh_profile
-and the configuration directory
+and a configuration directory
 .Fn $HOME/.mmh
-appeared to be inconsistent.
+appeared to be inconsistent.)
+.P
 The approach chosen for mmh is consistent, simple, and familiar to
 Unix users.
+The main achievement of the change is the clear and sensible separation
+of the mail storage and the configuration.
 .Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
 .P
-MH allows users to have multiple MH setups.
+As MH allows users to have multiple MH setups,
-Therefore, it is necessary to select a different profile.
+it is necessary to switch the 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 specify a different profile.
+is used to specify a different profile.
-To operate in the same MH setup with a separate context,
+To operate in the same MH setup with a separate context, the
-the
 .Ev MHCONTEXT
-environment variable could be used.
+environment variable is used.
-This allows having own current folders and current messages in
+This allows having a separate current folder in each terminal at
-each terminal, for instance.
+the same time, for instance.
-In mmh, three environment variables are used.
+In mmh, three environment variables replace the two of nmh.
 .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.
+override the paths to the profile and context file, respectively.
 This approach allows the set of personal configuration files to be chosen
-independently from the profile, context, and mail storage.
+independently of the profile, context, and mail storage.
-.Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
-.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.
+possibly even easier with the new one.
-The main achievement of the change is the clear and sensible split
+.Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
-between mail storage and configuration.
 .H2 "Modularization
+.Id modularization
 .P
 The source code of the mmh tools is located in the
 .Fn uip
 (``user interface programs'') directory.
 Each tool has a source file with the name of the command.
 (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.)
 .\" XXX graph
 .P
 Splitting the source code of a large program into multiple files can
-increase the readability of its source code.
+increase the readability of its source code,
-.\" XXX however?
+but most of the mmh tools are small and straight-forward programs.
-Most of the mmh tools are simple and straight-forward programs.
+In exception of the MIME handling tools (i.e.
-With the exception of the MIME handling tools,
-.Pn pick
-is the largest tool.
-It contains 1\|037 lines of source code, excluding the MH library.
-Only the MIME handling tools (\c
 .Pn mhbuild ,
 .Pn mhstore ,
 .Pn show ,
-etc.)
+etc.),
-are larger.
+.Pn pick
-Splitting programs with less than 1\|000 lines of code into multiple
+is the only tool with more than one thousand lines of source code.
-source files seldom leads to better readability.
+Splitting programs with less than one thousand lines of code into
-For such tools, splitting makes sense
+multiple source files leads seldom to better readability.
-when parts of the code are reused in other programs,
+For such tools, splitting still makes sense
+when parts of the code are reused in other programs
 and the reused code fragment is (1) not general enough
 for including it in the MH library
 or (2) has dependencies on a library that only few programs need.
 .Fn uip/packsbr.c ,
 for instance, provides the core program logic for the
 .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
+accesses terminal properties, which requires linking with the
-curses library.
+\fItermcap\fP or a \fIcurses\fP library.
-Including
+If
 .Fn uip/termsbr.c
-into the MH library would require every program to be linked with
+is included in the MH library, then every program needs to be linked
-termcap or curses, although only few of the programs require it.
+with termcap or curses, although only few of the programs use
+the library.
 .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
+consists of 800 lines; the other 1\|700 lines are code 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.
+This is left to be done.
 .P
 The work already accomplished 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,
 the core function of
 .Pn whatnow ,
 .Pn send ,
 and
 .Pn anno
-were compiled into
+were all compiled into
 .Pn comp .
 This saved the need to execute these programs with
+the expensive system calls
 .Fu fork()
 and
-.Fu exec() ,
+.Fu exec() .
-two expensive system calls.
 Whereas this approach improved the time performance,
 it interwove the source code.
 Core functionalities were not encapsulated into programs but into
 function, which were then wrapped by programs.
 For example,
 .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.
+to the function
-.Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f
+.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.
+together 210 lines of code,
-In nmh,
+whereas in nmh,
 .Pn comp
 comprises six files with 2\|450 lines.
-Not all of the code in these six files was actually used by
+Not all of the code in these six files is actually used by
 .Pn comp ,
-but the code reader needed to read all of the code first to know which
+but the reader needed to read it all to know which parts are relevant.
-parts were used.
+Understanding nmh's
-.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 the influenced code area is small
-and its boundaries are strictly defined.
-Furthermore, the code needs to solve the problem in a straight-forward way.
-.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
-.\" XXX kate fragen: more vs. as much
-requires to read 210 lines of code in mmh, but ten times more 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
+Here, it should be recalled that information passed in obscure ways
-clearly visible and technically enforced.
+through the program's source base, due to the aforementioned hack
-The interfaces are calls to
+to save an additional parameter in nmh's
+.Pn anno .
+.P
+In mmh, understanding
+.Pn comp
+requires to read only 210 lines of code to read, whereas the amount
+is ten times more for nmh's
+.Pn comp .
+.P
+By separating the tools on the program-level,
+the boundaries are clearly visible, as the interfaces are calls to
 .Fu exec()
 rather than arbitrary function calls.
-.P
+Additionally, this kind of separation is more strict because
-But the real problem is another:
+it is technically enforced by the operating system;
+it can not be simply bypassed with global variables.
+Good separation simplifies the understanding of program code
+because the area influenced by any particular statement is small.
+As I have read a lot in nmh's code base during the last two years,
+I have learned about the easy and the difficult parts.
+In my observation, the understanding of code is enormously eased
+if the influenced area is small and clearly bounded.
+.P
+Yet, the real problem is another:
 Nmh violates the golden ``one tool, one job'' rule of the Unix philosophy.
-.\" XXX ref
 Understanding
 .Pn comp
 requires understanding
 .Fn uip/annosbr.c
 and
 .Fn uip/sendsbr.c
 because
 .Pn comp
-does annotate and send messages.
+annotates and sends messages.
-In nmh, there surely exists the tool
+In nmh, there surely exist the tools
+.Pn anno
+and
 .Pn send ,
-which does mainly send messages.
+which cover these jobs,
-But
+but
 .Pn comp
 and
 .Pn repl
 and
 .Pn forw
 and
 .Pn dist
 and
 .Pn whatnow
 and
-.Pn viamail ,
+.Pn viamail
-they all (!) have the same message sending function included, as well.
+\(en they all (!) \(en
-In result,
+have the same annotating and sending functions included, once more.
+As a result,
 .Pn comp
 sends messages without using
 .Pn send .
 The situation is the same as if
 .Pn grep
-would page without
+would page its output without using
 .Pn more
 just because both programs are part of the same code base.
 .P
-The clear separation on the surface \(en the tool chest approach \(en
+The clear separation on the surface of nmh
+\(en the tool chest approach \(en
 is violated on the level below.
 This violation is for the sake of time performance.
-On systems where
+Decades ago, sacrificing readability and conceptional beauty
-.Fu fork()
+for speed might have been necessary to prevent MH from being
-and
+unusably slow, but today this is not the case anymore.
-.Fu exec()
+No longer should speed improvements that became unnecessary be kept.
-are expensive, the quicker response might be noticable.
+No longer should readability or conceptional beauty be sacrificed.
-In the old times, sacrificing readability and conceptional beauty for
+No longer should the Unix philosophy's ``one tool, one job''
-speed might even have been a must to prevent MH from being unusably slow.
+guideline be violated.
-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.
-.\" XXX ref
-No longer should we keep speed improvements that became unnecessary.
-.P
 Therefore, mmh's
 .Pn comp
-does no longer send messages.
+no longer sends messages.
+.P
 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 .
+.Pn send
 .Ci 3df5ab3c116e6d4a2fb4bb5cc9dfc5f781825815
-.Ci c73c00bfccd22ec77e9593f47462aeca4a8cd9c0
+.Ci c73c00bfccd22ec77e9593f47462aeca4a8cd9c0 .
 The clear separation on the surface is maintained on the level below.
-Human users and the tools use the same interface \(en
+Human users and other 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.
+no matter if requested by programs or by human beings
 .Ci 469a4163c2a1a43731d412eaa5d9cae7d670c48b
 .Ci aed384169af5204b8002d06e7a22f89197963d2d
-.Ci 3caf9e298a8861729ca8b8a84f57022b6f3ea742
+.Ci 3caf9e298a8861729ca8b8a84f57022b6f3ea742 .
 The decrease of tools built from multiple source files and thus
 the decrease of
 .Fn uip/*sbr.c
-files confirm the improvement.
+files confirm the improvement
 .Ci 9e6d91313f01c96b4058d6bf419a8ca9a207bc33
 .ci 81744a46ac9f845d6c2b9908074d269275178d2e
 .Ci f0f858069d21111f0dbea510044593f89c9b0829
 .Ci 0503a6e9be34f24858b55b555a5c948182b9f24b
 .Ci 27826f9353e0f0b04590b7d0f8f83e60462b90f0
 .Ci d1da1f94ce62160aebb30df4063ccbc53768656b
-.Ci c42222869e318fff5dec395eca3e776db3075455
+.Ci c42222869e318fff5dec395eca3e776db3075455 .
-.P
+This is also visible in the complexity of the build dependency graphs:
-.\" XXX move this paragraph up somewhere
-One disadvantage needs to be taken with this change:
+.sp
-The compiler can no longer check the integrity of the interfaces.
+Nmh:
-By changing the command line interfaces of tools, it is
+.BP input/deps-nmh.eps .5i
-the developer's job to adjust the invocations of these tools as well.
+.EP
-As this is a manual task and regression tests, which could detect such
+.sp
-problems, are not available yet, it is prone to errors.
+Mmh:
-These errors will not be detected at compile time but at run time.
+.BP input/deps-mmh.eps .8i
-Installing regression tests is a pending task.
+.EP
-In the best case, a uniform way of invoking tools from other tools
-can be developed to allow automated testing at compile time.
+The figures display all program to source file relationships
+that are not one-to-one,
+i.e. all programs that are built from multiple source files.
-.ig
+The primary source file of each program is omited from the graph.
-XXX consider writing about mhl vs. mhlproc
-sbr/showfile.c
-23          /*
-24          ** If you have your lproc listed as "mhl",
-25          ** then really invoked the mhlproc instead
-26          ** (which is usually mhl anyway).
-27          */
-Sat Nov 24 19:09:14 1984  /mtr (agent: Marshall Rose) <uci@udel-dewey>
-sbr/showfile.c: if lproc is "mhl", use mhlproc for consistency
-(Actually, user should use "lproc: show", "showproc: mhl".)
-..

Mercurial > docs > master

comparison discussion.roff @ 220:95257474a123