normalize_lexically should mention other functions that do basic normalization

[lolbinarycat]

Location

https://doc.rust-lang.org/nightly/std/path/struct.Path.html#method.normalize_lexically

Summary

both the PartialEq impl for Path and Path::components will normalize away non-leading . and duplicate/trailing slashes. This is "good enough" for many applications, such as choosing a specific file in a tarball to extract.

[the8472]

But why? And why only for normalize_lexically? canonicalize doesn't point to it. components doesn't point to canonicalize... we in general don't have a forest of methods explaining what all the other methods do.

components() calls what it does "a small amount of normalization", it seems barely worth a mention. And afaik the tar format permits .., so this bit of normalization isn't always sufficient for that either.

I guess we could have a section on path normalization on top that that mentions all 3 approaches?

[lolbinarycat]

normalize_lexically already lists 2 different alternatives. I believe the rationale is that it is frequently the wrong operation to perform, as it does not handle symlinks correctly, so it makes sense to list functions that don't have this interaction with symlinks.

[the8472]

All the options have upsides and downsides. I don't think it makes sense to have normalize_lexically be the central point to collect them.

[lolbinarycat]

I mean, I would be all for a dedicated section on path normalization, then having all the relevant functions just link link to that. That's basically what I did with the pointer to reference conversion section.

[ChrisDenton]

normalize_lexically is "special" in that it's currently the only one that removes .. components on Unix without resolving them, which may be a security concern. This should be given due attention. Contrasting it with what components() does makes sense to me because path functions are typically written in terms of components() (even if they don't literally call components then they still work as-if components was used).

I agree this isn't the place to have a full overview of normalisation functions but it would indeed be good to have that overview somewhere. Though it's kind of tricky with unstable functions because we have to be careful mentioning them in otherwise stable documentation.