docs/master: discussion.roff comparison

comparison discussion.roff @ 180:731e747a805b

Applied corrections by Lydi.

author	markus schnalke <meillo@marmaro.de>
date	Wed, 11 Jul 2012 00:00:34 +0200
parents	b59201e345e5
children	eb6eeb10afd5

comparison

equal deleted inserted replaced

-:b59201e345e5
+:731e747a805b
 .Sw -delete ,
 but not with
 .Sw -list .
 .P
 Trying to fix these problems on the surface would not have solved
-them truly, as they originate from a discrepance between the semantic
+them truly, as they originate from a discrepance between the
 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
 .Sw -delete
 introduce modes of operation.
 Historically,
 .Pn anno
 had only one operation mode: adding header fields.
-With the extension, it got two more modes:
+With the extension it got two more modes:
+.\" XXX got
 listing and deleting header fields.
 The structure of the code changes did not pay respect to this
 fundamental change to
 .Pn anno 's
 behavior.
 just like the current directory is specified as `\c
 .Fn . '.
 .P
 To allow MH tools to understand all four notations,
 they need to convert between them.
+.\" XXX between?
 In nmh, these path name conversion functions were located in the files
 .Fn sbr/path.c
 (``return a pathname'') and
 .Fn sbr/m_maildir.c
 (``get the path for the mail directory'').
 This is the function of choice for path conversion.
 Absolute directory paths are the most general representation of a
 path name.
 The result is a pointer to static memory.
 .P
+.\" XXX ueberfluessig?
 The new functions have names that indicate their use.
 Two of the functions convert relative to absolute path names of the
 same type.
 The third function converts any path name type to the most general one,
 the absolute directory path.
 .Fn config/config.c ,
 for whatever reasons.
 .P
 .Fn sbr/path.c
 now contains all path handling code.
+.\" XXX naechste zeile weg?
 Only 173 lines of code were needed to replace the previous 252 lines.
 The readability of the code is highly improved.
 Additionally, each of the six exported and one static functions
 is introduced by an explaining comment.
 does not behave as expected.
 But all programs should behave as expected.
 Clear and simple concepts are a precondition for this.
 Hence, the real solution is having all MH tools read the profile.
 .P
-Yet, the problem has a further aspect.
+The problem has a further aspect.
 It mainly originates in
 .Pn mhmail .
 .Pn mhmail
 was intended to be a replacement for
 .Pn mailx
 Instead it should have been treated accordingly to its foreign style.
 The solution is not to prevent the tools reading the profile but
 to instruct them reading a different profile.
 .Pn mhmail
 could have set up a well-defined profile and caused all MH tools
-in the session use it by exporting an environment variable.
+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
 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.
+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 pike practice of programming
 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
+The 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 do not 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
+.\" XXX kuerzen und mit dem naechsten Absatz vereinen
+I am still in my twenties 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.
+This puts 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
 put a load on mmh.
 .Ci b067ff5c465a5d243ce5a19e562085a9a1a97215
 .P
 The
 .Fu copy()
-function copies the string in argument one to the location in two.
+function copies the string in parameter one to the location in
+parameter 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()
 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.
+.\" XXX bad ... inapropriate?
 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
 .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 name of the command.
+Each tool has a source file with the name of the command.
 For example,
 .Pn rmm
 is built from
 .Fn uip/rmm.c .
 Some source files are used for multiple programs.
 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.)
+.\" XXX graph
 .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.
+.\" XXX however?
+Most of the mmh tools are simple and straight-forward programs.
 With the exception of the MIME handling tools,
 .Pn pick
 is the largest tool.
-It contains 1\|037 lines of source code (measured with
+It contains 1\|037 lines of source code, excluding the MH library.
-.Pn sloccount ), excluding the MH library.
 Only the MIME handling tools (\c
 .Pn mhbuild ,
 .Pn mhstore ,
 .Pn show ,
 etc.)
 .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.
+.\" 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

Mercurial > docs > master

comparison discussion.roff @ 180:731e747a805b