docs: incorrect/misleading instructions on PATH importing

[mwichmann]

This came up during a Discord discussion on #scons-help

https://discord.com/channels/571796279483564041/571796280146133047/1006057851858452510

Both the man page and User Guide give examples of importing the external PATH variable into the SCons build, but the way it is demonstrated is not ideal. This is the first example in both places:

import os
env = Environment(ENV={'PATH': os.environ['PATH']})

The problem with this and the other examples is they overwrite the platform-default value of the ENV dictionary, rather than adding to or updating it. It turns out this is actually potentially fatal on modern Windows, where a variety of things don't work if %USERPROFILE% is not set, and this clobbers it, as well as %SystemRoot% (apparently needed for socket operations). On a Mac, this would clobber the setting of PATHOSX (which SCons itself uses, though possibly only in the TeX tool).

In the case of the Discord discussion, following this recommendation did in fact break a build on Windows.

It seems we should not make this approach a primary recommendation, or at the very least, include a warning. Explaining how to do it "correctly" may be a little tricky, though.... the basic model could be something like:

env.AppendENVPath('PATH', os.environ['PATH'])

But because that has to happen after the Environment creation, it may run into problems of tools needing the imported path to initialize themselves.