Mercurial > docs > master

comparison discussion.roff @ 134:edf46861132b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Wrote about path conversion; Dropped the idea to write about scan listings
author markus schnalke <meillo@marmaro.de>
date Tue, 03 Jul 2012 22:30:20 +0200
parents 02660c14f6a8
children 470d5db0c06c
comparison
equal deleted inserted replaced
133:02660c14f6a8 134:edf46861132b
424 .Pn slocal 424 .Pn slocal
425 is unrelated to the rest of the project. 425 is unrelated to the rest of the project.
426 426
427 427
428 428
429 .H2 "\fLshow\fP and \fPmhshow\fP 429 .H2 "Displaying Messages
430 .P 430 .P
431 Since the very beginning, already in the first concept paper, 431 Since the very beginning, already in the first concept paper,
432 .Pn show 432 .Pn show
433 had been MH's message display program. 433 had been MH's message display program.
434 .Pn show 434 .Pn show
562 Its lean elegance is missing to the new 562 Its lean elegance is missing to the new
563 .Pn show . 563 .Pn show .
564 But there is no chance; 564 But there is no chance;
565 supporting MIME demands for higher essential complexity. 565 supporting MIME demands for higher essential complexity.
566 566
567 567 .ig
568 .H2 "Scan Listings 568 XXX
569 .P 569 Consider including text on scan listings here
570 FIXME XXX 570
571 571 Scan listings shall not contain body content. Hence, removed this feature.
572 .P 572 Scan listings shall operator on message headers and non-message information
573 commit c20e315f9fb9f0f0955749726dbf4fd897cd9f48 573 only. Displaying the beginning of the body complicates everything too much.
574 Author: markus schnalke <meillo@marmaro.de> 574 That's no surprise, because it's something completely different. If you
575 Date: Fri Dec 9 21:56:44 2011 +0100 575 want to examine the body, then use show(1)/mhshow(1).
576 576 Changed the default scan formats accordingly.
577 Adjusted the default scan listing: remove the body preview 577 .Ci 70b2643e0da8485174480c644ad9785c84f5bff4
578 The original listing is still available as etc/scan.nmh 578 ..
579
580 commit 70b2643e0da8485174480c644ad9785c84f5bff4
581 Author: markus schnalke <meillo@marmaro.de>
582 Date: Mon Jan 30 16:16:26 2012 +0100
583
584 Scan listings shall not contain body content. Hence, removed this feature.
585 Scan listings shall operator on message headers and non-message information
586 only. Displaying the beginning of the body complicates everything too much.
587 That's no surprise, because it's something completely different. If you
588 want to examine the body, then use show(1)/mhshow(1).
589 Changed the default scan formats accordingly.
590 579
591 580
592 581
593 582
594 .H2 "Configure Options 583 .H2 "Configure Options
3106 3095
3107 3096
3108 3097
3109 .U3 "Path Conversion 3098 .U3 "Path Conversion
3110 .P 3099 .P
3111 FIXME! XXX 3100 Four kinds of path names can appear in MH:
3112 3101 .IP (1)
3113 3102 Absolute Unix directory paths, like
3114 commit d39e2c447b0d163a5a63f480b23d06edb7a73aa0 3103 .Fn /etc/passwd .
3115 Author: markus schnalke <meillo@marmaro.de> 3104 .IP (2)
3116 Date: Fri Dec 9 16:34:57 2011 +0100 3105 Relative Unix directory paths, like
3117 3106 .Fn ./foo/bar .
3118 Completely reworked the path convertion functions 3107 .IP (3)
3119 Moved everything (from sbr/getfolder.c and sbr/m_maildir.c) into 3108 Absolute MH folder paths, like
3120 sbr/path.c, but actually replaced the code almost completely. 3109 .Fn +friends/phil .
3121 See h/prototypes.h for the function changes. 3110 .IP (4)
3122 sbr/path.c provides explaining comments on the functions. 3111 Relative MH folder paths, like
3123 None of them allocates memory automatically. 3112 .Fn @subfolder .
3124 3113 .P
3125 Additionally: 3114 The last type, relative MH folder paths, are hardly documented.
3126 - Like for other ``files'', `inc -audit file' places file relative 3115 Nonetheless, they are useful for large mail storages.
3127 to the cwd, not relative to the mh-dir. This is for consistency. 3116 The current mail folder is specified as `\c
3128 - Replaced add(foo, NULL) with getcpy(foo), which ist clearer. 3117 .Fn @ ',
3129 3118 just like the current directory is specified as `\c
3119 .Fn . '.
3120 .P
3121 To allow MH tools to understand all four notations,
3122 they need to convert between them.
3123 In nmh, these path name conversion functions were located in the files
3124 .Fn sbr/path.c
3125 (``return a pathname'') and
3126 .Fn sbr/m_maildir.c
3127 (``get the path for the mail directory'').
3128 The seven functions in the two files were documented with no more
3129 than two comments, which described obvious information.
3130 The function signatures were neither explaining:
3131 .VS
3132 char *path(char *, int);
3133 char *pluspath(char *);
3134 char *m_mailpath(char *);
3135 char *m_maildir(char *);
3136 VE
3137 .P
3138 My investigation provides the following description:
3139 .BU
3140 The second parameter of
3141 .Fu path()
3142 defines the type of path given as first parameter.
3143 Directory paths are converted to absolute directory paths.
3144 Folder paths are converted to absolute folder paths.
3145 Folder paths must not include a leading `@' character.
3146 Leading plus characters are preserved.
3147 The result is a pointer to newly allocated memory.
3148 .BU
3149 .Fu pluspath()
3150 is a convenience-wrapper to
3151 .Fu path() ,
3152 to convert folder paths only.
3153 This function can not be used for directory paths.
3154 An empty string parameter causes a buffer overflow.
3155 .BU
3156 .Fu m_mailpath()
3157 converts directory paths to absolute directory paths.
3158 The characters `+' or `@' at the beginning of the path name are
3159 treated literal, i.e. as the first character of a relative directory path.
3160 Hence, this function can not be used for folder paths.
3161 In any case, the result is an absolute directory path.
3162 The result is a pointer to newly allocated memory.
3163 .BU
3164 .Fu m_maildir()
3165 returns the parameter unchanged if it is an absolute directory path
3166 or begins with the entry `.' or `..'.
3167 All other strings are prepended with the current working directory.
3168 Hence, this functions can not be used for folder paths.
3169 The result is either an absolute directory path or a relative
3170 directory path, starting with a dot.
3171 In contrast to the other functions, the result is a pointer to
3172 static memory.
3173 .P
3174 The situation was obscure, irritating, error-prone, and non-orthogonal.
3175 No clear terminology was used to name the different kinds of path names.
3176 The first argument of
3177 .Fu m_mailpath() ,
3178 for instance, was named
3179 .Ar folder ,
3180 though
3181 .Fu m_mailpath()
3182 can not be used for MH folders.
3183 .P
3184 I reworked the path name conversion completely, introducing clarity.
3185 First of all, the terminology needed to be defined.
3186 A path name is either in the Unix domain, then it is called
3187 \fIdirectory path\fP, `dirpath' for short, or it is in the MH domain,
3188 then it is called \fIfolder path\fP, `folpath' for short.
3189 The two terms need to be used with strict distinction.
3190 Having a clear terminology is often an indicator of having understood
3191 the problem itself.
3192 Second, I exploited the concept of path type indicators.
3193 By requesting every path name to start with a clear type identifier,
3194 conversion between the types can be fully automated.
3195 Thus the tools can accept paths of any type from the user.
3196 Therefore, it was necessary to require relative directory paths to be
3197 prefixed with a dot character.
3198 In consequence, the dot character could no longer be an alias for the
3199 current message.
3200 .Ci cff0e16925e7edbd25b8b9d6d4fbdf03e0e60c01
3201 Third, I created three new functions to replace the previous mess:
3202 .BU
3203 .Fu expandfol()
3204 converts folder paths to absolute folder paths,
3205 without the leading plus character.
3206 Directory paths are simply passed through.
3207 This function is to be used for folder paths only, thus the name.
3208 The result is a pointer to static memory.
3209 .BU
3210 .Fu expanddir()
3211 converts directory paths to absolute directory paths.
3212 Folder paths are treated as relative directory paths.
3213 This function is to be used for directory paths only, thus the name.
3214 The result is a pointer to static memory.
3215 .BU
3216 .Fu toabsdir()
3217 converts any type of path to an absolute directory path.
3218 This is the function of choice for path conversion.
3219 Absolute directory paths are the most general representation of a
3220 path name.
3221 The result is a pointer to static memory.
3222 .P
3223 The new functions have names that indicate their use.
3224 Two of the functions convert relative to absolute path names of the
3225 same type.
3226 The third function converts any path name type to the most general one,
3227 the absolute directory path.
3228 All of the functions return pointers to static memory.
3229 All three functions are implemented in
3230 .Fn sbr/path.c .
3231 .Fn sbr/m_maildir.c
3232 is removed.
3233 .P
3234 Along with the path conversion rework, I also replaced
3235 .Fu getfolder(FDEF)
3236 with
3237 .Fu getdeffol()
3238 and
3239 .Fu getfolder(FCUR)
3240 with
3241 .Fu getcurfol() ,
3242 which is only a convenience wrapper for
3243 .Fu expandfol("@") .
3244 This code was moved from
3245 .Fn sbr/getfolder.c
3246 to
3247 .Fn sbr/path.c .
3248 .P
3249 The related function
3250 .Fu etcpath()
3251 was moved to
3252 .Fn sbr/path.c ,
3253 too.
3254 Previously, it had been located in
3255 .Fn config/config.c ,
3256 for whatever reasons.
3257 .P
3258 .Fn sbr/path.c
3259 now contains all path handling code.
3260 Only 173 lines of code were needed to replace the previous 252 lines.
3261 The readability of the code is highly improved.
3262 Additionally, each of the six exported and one static functions
3263 is introduced by an explaining comment.
3264 .Ci d39e2c447b0d163a5a63f480b23d06edb7a73aa0
3130 3265
3131 3266
3132 3267
3133 3268
3134 .H2 "Profile Reading 3269 .H2 "Profile Reading