1.1 --- a/discussion.roff	Tue Jul 03 16:50:41 2012 +0200
     1.2 +++ b/discussion.roff	Tue Jul 03 22:30:20 2012 +0200
     1.3 @@ -426,7 +426,7 @@
     1.4  
     1.5  
     1.6  
     1.7 -.H2 "\fLshow\fP and \fPmhshow\fP
     1.8 +.H2 "Displaying Messages
     1.9  .P
    1.10  Since the very beginning, already in the first concept paper,
    1.11  .Pn show
    1.12 @@ -564,29 +564,18 @@
    1.13  But there is no chance;
    1.14  supporting MIME demands for higher essential complexity.
    1.15  
    1.16 +.ig
    1.17 +XXX
    1.18 +Consider including text on scan listings here
    1.19  
    1.20 -.H2 "Scan Listings
    1.21 -.P
    1.22 -FIXME XXX
    1.23 -
    1.24 -.P
    1.25 -commit c20e315f9fb9f0f0955749726dbf4fd897cd9f48
    1.26 -Author: markus schnalke <meillo@marmaro.de>
    1.27 -Date:   Fri Dec 9 21:56:44 2011 +0100
    1.28 -
    1.29 -    Adjusted the default scan listing: remove the body preview
    1.30 -    The original listing is still available as etc/scan.nmh
    1.31 -
    1.32 -commit 70b2643e0da8485174480c644ad9785c84f5bff4
    1.33 -Author: markus schnalke <meillo@marmaro.de>
    1.34 -Date:   Mon Jan 30 16:16:26 2012 +0100
    1.35 -
    1.36 -    Scan listings shall not contain body content. Hence, removed this feature.
    1.37 -    Scan listings shall operator on message headers and non-message information
    1.38 -    only. Displaying the beginning of the body complicates everything too much.
    1.39 -    That's no surprise, because it's something completely different. If you
    1.40 -    want to examine the body, then use show(1)/mhshow(1).
    1.41 -    Changed the default scan formats accordingly.
    1.42 +Scan listings shall not contain body content. Hence, removed this feature.
    1.43 +Scan listings shall operator on message headers and non-message information
    1.44 +only. Displaying the beginning of the body complicates everything too much.
    1.45 +That's no surprise, because it's something completely different. If you
    1.46 +want to examine the body, then use show(1)/mhshow(1).
    1.47 +Changed the default scan formats accordingly.
    1.48 +.Ci 70b2643e0da8485174480c644ad9785c84f5bff4
    1.49 +..
    1.50  
    1.51  
    1.52  
    1.53 @@ -3108,25 +3097,171 @@
    1.54  
    1.55  .U3 "Path Conversion
    1.56  .P
    1.57 -FIXME! XXX
    1.58 -
    1.59 -
    1.60 -commit d39e2c447b0d163a5a63f480b23d06edb7a73aa0
    1.61 -Author: markus schnalke <meillo@marmaro.de>
    1.62 -Date:   Fri Dec 9 16:34:57 2011 +0100
    1.63 -
    1.64 -    Completely reworked the path convertion functions
    1.65 -    Moved everything (from sbr/getfolder.c and sbr/m_maildir.c) into
    1.66 -    sbr/path.c, but actually replaced the code almost completely.
    1.67 -    See h/prototypes.h for the function changes.
    1.68 -    sbr/path.c provides explaining comments on the functions.
    1.69 -    None of them allocates memory automatically.
    1.70 -    
    1.71 -    Additionally:
    1.72 -    - Like for other ``files'', `inc -audit file' places file relative
    1.73 -      to the cwd, not relative to the mh-dir. This is for consistency.
    1.74 -    - Replaced add(foo, NULL) with getcpy(foo), which ist clearer.
    1.75 -
    1.76 +Four kinds of path names can appear in MH:
    1.77 +.IP (1)
    1.78 +Absolute Unix directory paths, like
    1.79 +.Fn /etc/passwd .
    1.80 +.IP (2)
    1.81 +Relative Unix directory paths, like
    1.82 +.Fn ./foo/bar .
    1.83 +.IP (3)
    1.84 +Absolute MH folder paths, like
    1.85 +.Fn +friends/phil .
    1.86 +.IP (4)
    1.87 +Relative MH folder paths, like
    1.88 +.Fn @subfolder .
    1.89 +.P
    1.90 +The last type, relative MH folder paths, are hardly documented.
    1.91 +Nonetheless, they are useful for large mail storages.
    1.92 +The current mail folder is specified as `\c
    1.93 +.Fn @ ',
    1.94 +just like the current directory is specified as `\c
    1.95 +.Fn . '.
    1.96 +.P
    1.97 +To allow MH tools to understand all four notations,
    1.98 +they need to convert between them.
    1.99 +In nmh, these path name conversion functions were located in the files
   1.100 +.Fn sbr/path.c
   1.101 +(``return a pathname'') and
   1.102 +.Fn sbr/m_maildir.c
   1.103 +(``get the path for the mail directory'').
   1.104 +The seven functions in the two files were documented with no more
   1.105 +than two comments, which described obvious information.
   1.106 +The function signatures were neither explaining:
   1.107 +.VS
   1.108 +char *path(char *, int);
   1.109 +char *pluspath(char *);
   1.110 +char *m_mailpath(char *);
   1.111 +char *m_maildir(char *);
   1.112 +VE
   1.113 +.P
   1.114 +My investigation provides the following description:
   1.115 +.BU
   1.116 +The second parameter of
   1.117 +.Fu path()
   1.118 +defines the type of path given as first parameter.
   1.119 +Directory paths are converted to absolute directory paths.
   1.120 +Folder paths are converted to absolute folder paths.
   1.121 +Folder paths must not include a leading `@' character.
   1.122 +Leading plus characters are preserved.
   1.123 +The result is a pointer to newly allocated memory.
   1.124 +.BU
   1.125 +.Fu pluspath()
   1.126 +is a convenience-wrapper to
   1.127 +.Fu path() ,
   1.128 +to convert folder paths only.
   1.129 +This function can not be used for directory paths.
   1.130 +An empty string parameter causes a buffer overflow.
   1.131 +.BU
   1.132 +.Fu m_mailpath()
   1.133 +converts directory paths to absolute directory paths.
   1.134 +The characters `+' or `@' at the beginning of the path name are
   1.135 +treated literal, i.e. as the first character of a relative directory path.
   1.136 +Hence, this function can not be used for folder paths.
   1.137 +In any case, the result is an absolute directory path.
   1.138 +The result is a pointer to newly allocated memory.
   1.139 +.BU
   1.140 +.Fu m_maildir()
   1.141 +returns the parameter unchanged if it is an absolute directory path
   1.142 +or begins with the entry `.' or `..'.
   1.143 +All other strings are prepended with the current working directory.
   1.144 +Hence, this functions can not be used for folder paths.
   1.145 +The result is either an absolute directory path or a relative
   1.146 +directory path, starting with a dot.
   1.147 +In contrast to the other functions, the result is a pointer to
   1.148 +static memory.
   1.149 +.P
   1.150 +The situation was obscure, irritating, error-prone, and non-orthogonal.
   1.151 +No clear terminology was used to name the different kinds of path names.
   1.152 +The first argument of
   1.153 +.Fu m_mailpath() ,
   1.154 +for instance, was named
   1.155 +.Ar folder ,
   1.156 +though
   1.157 +.Fu m_mailpath()
   1.158 +can not be used for MH folders.
   1.159 +.P
   1.160 +I reworked the path name conversion completely, introducing clarity.
   1.161 +First of all, the terminology needed to be defined.
   1.162 +A path name is either in the Unix domain, then it is called
   1.163 +\fIdirectory path\fP, `dirpath' for short, or it is in the MH domain,
   1.164 +then it is called \fIfolder path\fP, `folpath' for short.
   1.165 +The two terms need to be used with strict distinction.
   1.166 +Having a clear terminology is often an indicator of having understood
   1.167 +the problem itself.
   1.168 +Second, I exploited the concept of path type indicators.
   1.169 +By requesting every path name to start with a clear type identifier,
   1.170 +conversion between the types can be fully automated.
   1.171 +Thus the tools can accept paths of any type from the user.
   1.172 +Therefore, it was necessary to require relative directory paths to be
   1.173 +prefixed with a dot character.
   1.174 +In consequence, the dot character could no longer be an alias for the
   1.175 +current message.
   1.176 +.Ci cff0e16925e7edbd25b8b9d6d4fbdf03e0e60c01
   1.177 +Third, I created three new functions to replace the previous mess:
   1.178 +.BU
   1.179 +.Fu expandfol()
   1.180 +converts folder paths to absolute folder paths,
   1.181 +without the leading plus character.
   1.182 +Directory paths are simply passed through.
   1.183 +This function is to be used for folder paths only, thus the name.
   1.184 +The result is a pointer to static memory.
   1.185 +.BU
   1.186 +.Fu expanddir()
   1.187 +converts directory paths to absolute directory paths.
   1.188 +Folder paths are treated as relative directory paths.
   1.189 +This function is to be used for directory paths only, thus the name.
   1.190 +The result is a pointer to static memory.
   1.191 +.BU
   1.192 +.Fu toabsdir()
   1.193 +converts any type of path to an absolute directory path.
   1.194 +This is the function of choice for path conversion.
   1.195 +Absolute directory paths are the most general representation of a
   1.196 +path name.
   1.197 +The result is a pointer to static memory.
   1.198 +.P
   1.199 +The new functions have names that indicate their use.
   1.200 +Two of the functions convert relative to absolute path names of the
   1.201 +same type.
   1.202 +The third function converts any path name type to the most general one,
   1.203 +the absolute directory path.
   1.204 +All of the functions return pointers to static memory.
   1.205 +All three functions are implemented in
   1.206 +.Fn sbr/path.c .
   1.207 +.Fn sbr/m_maildir.c
   1.208 +is removed.
   1.209 +.P
   1.210 +Along with the path conversion rework, I also replaced
   1.211 +.Fu getfolder(FDEF)
   1.212 +with
   1.213 +.Fu getdeffol()
   1.214 +and
   1.215 +.Fu getfolder(FCUR)
   1.216 +with
   1.217 +.Fu getcurfol() ,
   1.218 +which is only a convenience wrapper for
   1.219 +.Fu expandfol("@") .
   1.220 +This code was moved from
   1.221 +.Fn sbr/getfolder.c
   1.222 +to
   1.223 +.Fn sbr/path.c .
   1.224 +.P
   1.225 +The related function
   1.226 +.Fu etcpath()
   1.227 +was moved to
   1.228 +.Fn sbr/path.c ,
   1.229 +too.
   1.230 +Previously, it had been located in
   1.231 +.Fn config/config.c ,
   1.232 +for whatever reasons.
   1.233 +.P
   1.234 +.Fn sbr/path.c
   1.235 +now contains all path handling code.
   1.236 +Only 173 lines of code were needed to replace the previous 252 lines.
   1.237 +The readability of the code is highly improved.
   1.238 +Additionally, each of the six exported and one static functions
   1.239 +is introduced by an explaining comment.
   1.240 +.Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
   1.241  
   1.242  
   1.243