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.