docs/master: discussion.roff comparison

comparison discussion.roff @ 133:02660c14f6a8

Further re-ordering of the sections.

author	markus schnalke <meillo@marmaro.de>
date	Tue, 03 Jul 2012 16:50:41 +0200
parents	7c741bc8f719
children	edf46861132b

comparison

equal deleted inserted replaced

-:8c56dac46efe
+:02660c14f6a8
 Current changes of nmh will be mentioned only as side notes.
 .\" XXX where do I discuss the parallel development of nmh?
+.\" --------------------------------------------------------------
 .H1 "Streamlining
 .P
 MH had been considered an all-in-one system for mail handling.
 The community around nmh has a similar understanding.
 That does not hurt because
 .Pn slocal
 is unrelated to the rest of the project.
-.H3 "Profile Reading
-.P
+.H2 "\fLshow\fP and \fPmhshow\fP
-FIXME XXX
+.P
+Since the very beginning, already in the first concept paper,
-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
 mapped message numbers and sequences to files and invoked
 .Pn mhl
 .Pn show .
 But there is no chance;
 supporting MIME demands for higher essential complexity.
-.U3 "Scan Listings
+.H2 "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
 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
 .P
 Eventually, however, the new trash folder concept
 .Cf "Sec. XXX
 obsoleted the concept of the backup prefix completely.
 .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
-.\" (Well, there still are corner-cases to remove until the backup
+.Ci ca0b3e830b86700d9e5e31b1784de2bdcaf58fc5
-.\" prefix can be laid to rest, eventually.)
-.\" FIXME: Do this work in the code!
 .U3 "Editor and Pager
 .P
 The two configure options
 .CW --with-editor=EDITOR
 .\" XXX: whatnow prompt commands
+.\" --------------------------------------------------------------
 .H1 "Modernizing
 .P
 In the over thirty years of MH's existence, its code base was
 extended more and more.
 New features entered the project and became alternatives to the
 .P
 FIXME
-.H2 "Modern Defaults
+.H2 "Draft and Trash Folder
-.P
-Nmh has a bunch of convenience-improving features inactive by default,
-although one can expect every new user wanting to have them active.
-The reason they are inactive by default is the wish to stay compatible
-with old versions.
-But what is the definition for old versions.
-Still, the highly useful draft folder facility is not active by default
-although it had been introduced over twenty-five years ago
-.[
-rose romine real work
-.]
-\(en the community seems not to care.
-This is one of several examples that require new users to build up
-their profile before they can access the modern features of nmh.
-Without an extensively built-up profile, the setup is hardly usable
-for modern emailing.
-The point is not the customization of the setup,
-but the activating of generally useful facilities.
-.P
-Yet, the real problem lies less in enabling the features, as this is
-straight forward as soon as one knows what he wants.
-The real problem is that new users need deep insights into the project
-before they find out what they are missing and that nmh actually
-provides it already, it just was not activated.
-To give an example, I needed one year of using nmh
-before I became aware of the existence of the attachment system.
-One could argue that this fact disqualifies my reading of the
-documentation.
-If I would have installed nmh from source back then, I could agree.
-Yet, I had used a prepackaged version and had expected that it would
-just work.
-Nevertheless, I had been convinced by the concepts of MH already
-and I am a software developer,
-still I required a lot of time to discover the cool features.
-How can we expect users to be even more advanced than me,
-just to allow them use MH in a convenient and modern way?
-Unless they are strongly convinced of the concepts, they will fail.
-I have seen friends of me giving up disappointed
-before they truly used the system,
-although they had been motivated in the beginning.
-They suffer hard enough to get used to the toolchest approach,
-we should spare them further inconveniences.
-.P
-Maintaining compatibility for its own sake is for no good.
-If any MH implementation would be the back-end of widespread
-email clients with large user bases, compatibility would be more
-important.
-Yet, it appears as if this is not the case.
-Hence, compatibility is hardly important for technical reasons.
-Its importance originates rather from personal reasons.
-Nmh's user base is small and old.
-Changing the interfaces would cause inconvenience to long-term users of MH.
-It would force them to change their many years old MH configurations.
-I do understand this aspect, but it keeps new users from using MH.
-By sticking to the old users, new users are kept away.
-Yet, the future lies in new users.
-Hence, mmh invites new users by providing a convenient and modern setup,
-readily usable out-of-the-box.
-.P
-In mmh, all modern features are active by default.
-In consequence, a setup with a profile that defines only the path to the
-mail storage, is already convenient to use.
-Again, Paul Vixie's ``edginess'' appeal supports the direction I took:
-``the `main branch' should just be modern''.
-.[
-paul vixie edginess nmh-workers
-.]
-.P
-Modern features that are active in mmh by default include:
-.BU
-The attachment system (\c
-.Hd Attach ).
-.Ci 8ff284ff9167eff8f5349481529332d59ed913b1
-.BU
-The draft folder facility (\c
-.Fn +drafts ).
-.Ci 337338b404931f06f0db2119c9e145e8ca5a9860
-.BU
-The unseen sequence (`u')
-.Ci c2360569e1d8d3678e294eb7c1354cb8bf7501c1
-and the sequence negation prefix (`!').
-.Ci db74c2bd004b2dc9bf8086a6d8bf773ac051f3cc
-.BU
-Quoting the original message in the reply.
-.Ci 67411b1f95d6ec987b4c732459e1ba8a8ac192c6
-.BU
-Forwarding messages using MIME.
-.Ci 6e271608b7b9c23771523f88d23a4d3593010cf1
-.H2 "Drafts and Trash Folder
 .P
 .U3 "Draft Folder
 .P
 In the beginning, MH had the concept of a draft message.
 Dropping the draft message concept in favor for the draft folder concept,
 removed special cases with regular cases.
 This simplified the source code of the tools, as well as the concepts.
 In mmh, draft management does not break with the MH concepts
 but applies them.
+.Cl "scan +drafts" ,
+for instance, is a truly natural request.
 Most of the work was already done by Rose in the eighties.
-The original improvement in mmh is dropping the draft message approach
+The original improvement of mmh is dropping the old draft message approach
-completely and thus simplifying the tools, the documentation and the
+and thus simplifying the tools, the documentation and the system as a whole.
-system as a whole.
 Although my part in the draft handling improvement was small,
-it was important.
+it was an important one.
 .U3 "Trash Folder
 .P
 Similar to the situation for drafts is the situation for removed messages.
 by the MH concepts makes the whole system more powerful.
+.H2 "Modern Defaults
+.P
+Nmh has a bunch of convenience-improving features inactive by default,
+although one can expect every new user wanting to have them active.
+The reason they are inactive by default is the wish to stay compatible
+with old versions.
+But what is the definition for old versions.
+Still, the highly useful draft folder facility is not active by default
+although it had been introduced over twenty-five years ago
+.[
+rose romine real work
+.]
+\(en the community seems not to care.
+This is one of several examples that require new users to build up
+their profile before they can access the modern features of nmh.
+Without an extensively built-up profile, the setup is hardly usable
+for modern emailing.
+The point is not the customization of the setup,
+but the activating of generally useful facilities.
+.P
+Yet, the real problem lies less in enabling the features, as this is
+straight forward as soon as one knows what he wants.
+The real problem is that new users need deep insights into the project
+before they find out what they are missing and that nmh actually
+provides it already, it just was not activated.
+To give an example, I needed one year of using nmh
+before I became aware of the existence of the attachment system.
+One could argue that this fact disqualifies my reading of the
+documentation.
+If I would have installed nmh from source back then, I could agree.
+Yet, I had used a prepackaged version and had expected that it would
+just work.
+Nevertheless, I had been convinced by the concepts of MH already
+and I am a software developer,
+still I required a lot of time to discover the cool features.
+How can we expect users to be even more advanced than me,
+just to allow them use MH in a convenient and modern way?
+Unless they are strongly convinced of the concepts, they will fail.
+I have seen friends of me giving up disappointed
+before they truly used the system,
+although they had been motivated in the beginning.
+They suffer hard enough to get used to the toolchest approach,
+we should spare them further inconveniences.
+.P
+Maintaining compatibility for its own sake is for no good.
+If any MH implementation would be the back-end of widespread
+email clients with large user bases, compatibility would be more
+important.
+Yet, it appears as if this is not the case.
+Hence, compatibility is hardly important for technical reasons.
+Its importance originates rather from personal reasons.
+Nmh's user base is small and old.
+Changing the interfaces would cause inconvenience to long-term users of MH.
+It would force them to change their many years old MH configurations.
+I do understand this aspect, but it keeps new users from using MH.
+By sticking to the old users, new users are kept away.
+Yet, the future lies in new users.
+Hence, mmh invites new users by providing a convenient and modern setup,
+readily usable out-of-the-box.
+.P
+In mmh, all modern features are active by default.
+In consequence, a setup with a profile that defines only the path to the
+mail storage, is already convenient to use.
+Again, Paul Vixie's ``edginess'' appeal supports the direction I took:
+``the `main branch' should just be modern''.
+.[
+paul vixie edginess nmh-workers
+.]
+.P
+Modern features that are active in mmh by default include:
+.BU
+The attachment system (\c
+.Hd Attach ).
+.Ci 8ff284ff9167eff8f5349481529332d59ed913b1
+.BU
+The draft folder facility (\c
+.Fn +drafts ).
+.Ci 337338b404931f06f0db2119c9e145e8ca5a9860
+.BU
+The unseen sequence (`u')
+.Ci c2360569e1d8d3678e294eb7c1354cb8bf7501c1
+and the sequence negation prefix (`!').
+.Ci db74c2bd004b2dc9bf8086a6d8bf773ac051f3cc
+.BU
+Quoting the original message in the reply.
+.Ci 67411b1f95d6ec987b4c732459e1ba8a8ac192c6
+.BU
+Forwarding messages using MIME.
+.Ci 6e271608b7b9c23771523f88d23a4d3593010cf1
+.\" --------------------------------------------------------------
 .H1 "Styling
 .P
 Kernighan and Pike have emphasized the importance of style in the
 preface of their book:
 .[ [
 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
+.H2 "Structural Rework
+.P
 .U3 "Rework of \f(CWanno\fP
 .P
 At the end of their chapter on style,
 Kernighan and Pike ask: ``But why worry about style?''
 VE
 .\" XXX think about explaining the -preserve rework?
+.U3 "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.
+.H2 "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 "Standard Libraries
 .P
 MH is one decade older than the POSIX and ANSI C standards.
 Hence, MH included own implementations of functions
 .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
 The main achievement of the change is the clear and sensible split
 between mail storage and configuration.
-.H2 "Path Conversion
-.P
-FIXME! XXX
+.H2 "Modularization
+.P
+The source code of the mmh tools is located in the
-commit d39e2c447b0d163a5a63f480b23d06edb7a73aa0
+.Fn uip
-Author: markus schnalke <meillo@marmaro.de>
+(``user interface programs'') directory.
-Date:   Fri Dec 9 16:34:57 2011 +0100
+Each tools has a source file with the same name.
+For example,
-Completely reworked the path convertion functions
+.Pn rmm
-Moved everything (from sbr/getfolder.c and sbr/m_maildir.c) into
+is built from
-sbr/path.c, but actually replaced the code almost completely.
+.Fn uip/rmm.c .
-See h/prototypes.h for the function changes.
+Some source files are used for multiple programs.
-sbr/path.c provides explaining comments on the functions.
+For example
-None of them allocates memory automatically.
+.Fn uip/scansbr.c
+is used for both,
-Additionally:
+.Pn scan
-- Like for other ``files'', `inc -audit file' places file relative
+and
-to the cwd, not relative to the mh-dir. This is for consistency.
+.Pn inc .
-- Replaced add(foo, NULL) with getcpy(foo), which ist clearer.
+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.

Mercurial > docs > master

comparison discussion.roff @ 133:02660c14f6a8