[asdf-devel] patch for component-relative-pathname

[Faré]

On 19 February 2010 10:50, Robert Goldman <rpgoldman at sift.info> wrote:
> Would anyone object to augmenting the docstring for
> COMPONENT-RELATIVE-PATHNAME?
>
> Currently it's:
>
> "Extracts the relative pathname applicable for a particular component."
>
> How about something like:
>
> "Returns a pathname for the component argument relative to the pathname
> of that component's parent."
>
> ?
>
> I think the most important thing for the reader to know is what the
> return value is relative to.
>
> The above isn't ideal, either, because sometimes what this returns is
> NOT a relative pathname (at least as far as I can tell by reading the
> source) --- it extracts the value that the system definer sets using
> :pathname so that the "relative" pathname may well be absolute!
>
> Perhaps:
>
> "Returns a pathname for the component argument intended to be
> interpreted relative to the pathname of that component's parent.
> Despite the function's name, the return value may be an absolute
> pathname, because an absolute pathname may be interpreted relative to
> another pathname in a degenerate way."
>
> A little long-winded.  I'm open to suggestions for improvement.
>
> What about adding a docstring for SPLIT-PATH-STRING, too --- any
> function that returns three values is worth a docstring!
>
>  "Splits the path string S, returning three values:
> A flag that is either :absolute or :relative, indicating
>   how the rest of the values are to be interpreted.
> A directory path --- a list of strings, suitable for
>   use with MAKE-PATHNAME when prepended with the flag
>   value.
> A filename with type extension, possibly NIL in the
>   case of a directory pathname.
> FORCE-DIRECTORY forces S to be interpreted as a directory
> pathname \(third return value will be NIL, final component
> of S will be treated as part of the directory path."
>
> By the way, is there any danger that SPLIT-PATH-STRING will be called on
> a logical pathname string?  I don't see anything to keep it from
> happening.  If so, it looks like it will lose badly; split-path-string
> assumes that the pathname separator is "/".
>
Split path string will be called on a what is provided as :name to
ASDF. In these circumstances, we get to define what is the pathname
separator convention (if any) and I think that having one is better
than having none, and "/" is a pretty unsurprising one. Yes, that
needs to be documented.

> If you all agree with me, this looks like a job for a launchpad ticket.
>
No! This looks like a job for someone willing to write the damn doc
strings and get their patch committed. Ahem, don't you have commit
priviledge?

[ François-René ÐVB Rideau | Reflection&Cybernethics | http://fare.tunes.org ]
Resentment is like taking poison and waiting for the other person to die.
        — Malachy McCourt