# HG changeset patch # User markus schnalke # Date 1341347420 -7200 # Node ID edf46861132b2c8d08d011faa073425892e9637d # Parent 02660c14f6a857f3cf3877f0cc6273c48c7fb001 Wrote about path conversion; Dropped the idea to write about scan listings diff -r 02660c14f6a8 -r edf46861132b discussion.roff --- a/discussion.roff Tue Jul 03 16:50:41 2012 +0200 +++ b/discussion.roff Tue Jul 03 22:30:20 2012 +0200 @@ -426,7 +426,7 @@ -.H2 "\fLshow\fP and \fPmhshow\fP +.H2 "Displaying Messages .P Since the very beginning, already in the first concept paper, .Pn show @@ -564,29 +564,18 @@ But there is no chance; supporting MIME demands for higher essential complexity. +.ig +XXX +Consider including text on scan listings here -.H2 "Scan Listings -.P -FIXME XXX - -.P -commit c20e315f9fb9f0f0955749726dbf4fd897cd9f48 -Author: markus schnalke -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 -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. +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. +.Ci 70b2643e0da8485174480c644ad9785c84f5bff4 +.. @@ -3108,25 +3097,171 @@ .U3 "Path Conversion .P -FIXME! XXX - - -commit d39e2c447b0d163a5a63f480b23d06edb7a73aa0 -Author: markus schnalke -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. - +Four kinds of path names can appear in MH: +.IP (1) +Absolute Unix directory paths, like +.Fn /etc/passwd . +.IP (2) +Relative Unix directory paths, like +.Fn ./foo/bar . +.IP (3) +Absolute MH folder paths, like +.Fn +friends/phil . +.IP (4) +Relative MH folder paths, like +.Fn @subfolder . +.P +The last type, relative MH folder paths, are hardly documented. +Nonetheless, they are useful for large mail storages. +The current mail folder is specified as `\c +.Fn @ ', +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. +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''). +The seven functions in the two files were documented with no more +than two comments, which described obvious information. +The function signatures were neither explaining: +.VS +char *path(char *, int); +char *pluspath(char *); +char *m_mailpath(char *); +char *m_maildir(char *); +VE +.P +My investigation provides the following description: +.BU +The second parameter of +.Fu path() +defines the type of path given as first parameter. +Directory paths are converted to absolute directory paths. +Folder paths are converted to absolute folder paths. +Folder paths must not include a leading `@' character. +Leading plus characters are preserved. +The result is a pointer to newly allocated memory. +.BU +.Fu pluspath() +is a convenience-wrapper to +.Fu path() , +to convert folder paths only. +This function can not be used for directory paths. +An empty string parameter causes a buffer overflow. +.BU +.Fu m_mailpath() +converts directory paths to absolute directory paths. +The characters `+' or `@' at the beginning of the path name are +treated literal, i.e. as the first character of a relative directory path. +Hence, this function can not be used for folder paths. +In any case, the result is an absolute directory path. +The result is a pointer to newly allocated memory. +.BU +.Fu m_maildir() +returns the parameter unchanged if it is an absolute directory path +or begins with the entry `.' or `..'. +All other strings are prepended with the current working directory. +Hence, this functions can not be used for folder paths. +The result is either an absolute directory path or a relative +directory path, starting with a dot. +In contrast to the other functions, the result is a pointer to +static memory. +.P +The situation was obscure, irritating, error-prone, and non-orthogonal. +No clear terminology was used to name the different kinds of path names. +The first argument of +.Fu m_mailpath() , +for instance, was named +.Ar folder , +though +.Fu m_mailpath() +can not be used for MH folders. +.P +I reworked the path name conversion completely, introducing clarity. +First of all, the terminology needed to be defined. +A path name is either in the Unix domain, then it is called +\fIdirectory path\fP, `dirpath' for short, or it is in the MH domain, +then it is called \fIfolder path\fP, `folpath' for short. +The two terms need to be used with strict distinction. +Having a clear terminology is often an indicator of having understood +the problem itself. +Second, I exploited the concept of path type indicators. +By requesting every path name to start with a clear type identifier, +conversion between the types can be fully automated. +Thus the tools can accept paths of any type from the user. +Therefore, it was necessary to require relative directory paths to be +prefixed with a dot character. +In consequence, the dot character could no longer be an alias for the +current message. +.Ci cff0e16925e7edbd25b8b9d6d4fbdf03e0e60c01 +Third, I created three new functions to replace the previous mess: +.BU +.Fu expandfol() +converts folder paths to absolute folder paths, +without the leading plus character. +Directory paths are simply passed through. +This function is to be used for folder paths only, thus the name. +The result is a pointer to static memory. +.BU +.Fu expanddir() +converts directory paths to absolute directory paths. +Folder paths are treated as relative directory paths. +This function is to be used for directory paths only, thus the name. +The result is a pointer to static memory. +.BU +.Fu toabsdir() +converts any type of path to an absolute directory path. +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 +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. +All of the functions return pointers to static memory. +All three functions are implemented in +.Fn sbr/path.c . +.Fn sbr/m_maildir.c +is removed. +.P +Along with the path conversion rework, I also replaced +.Fu getfolder(FDEF) +with +.Fu getdeffol() +and +.Fu getfolder(FCUR) +with +.Fu getcurfol() , +which is only a convenience wrapper for +.Fu expandfol("@") . +This code was moved from +.Fn sbr/getfolder.c +to +.Fn sbr/path.c . +.P +The related function +.Fu etcpath() +was moved to +.Fn sbr/path.c , +too. +Previously, it had been located in +.Fn config/config.c , +for whatever reasons. +.P +.Fn sbr/path.c +now contains all path handling code. +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. +.Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0