Update and simplify NaN-safe mode instructions #747
Conversation
| @@ -151,7 +151,7 @@ the `nansafe_mode` preference to true, for example via: | |||
| ```julia | |||
| julia> using Preferences | |||
|
|
|||
There was a problem hiding this comment.
This is also necessary for it to work, I believe:
| julia> import Pkg; Pkg.add("ForwardDiff") |
There was a problem hiding this comment.
Only if you don't have installed ForwardDiff yet. I (and the previous authors I suppose) assume that that's already case - given that this is the documentation of ForwardDiff, installation of ForwardDiff is the first thing you have to do if you want to follow or apply anything from the docs.
There was a problem hiding this comment.
No, it's not enough to have ForwardDiff installed. It has to be specifically installed in this environment. Not just visible from a lower-level one.
There was a problem hiding this comment.
Sure, that's what I assumed. Does anyone actually install ForwardDiff in e.g. the global environment? I assumed everyone working with the docs would have ForwardDiff installed in their current environment.
There was a problem hiding this comment.
I do. But also, the obvious way to try out this thing is ] activate --temp, so that you can compare to your other session & not mess anything up. (Especially since there's no way to reverse this change clearly described.)
Why make instructions for which this fails? Why not make instructions which work when copy-pasted 100% of the time?
There was a problem hiding this comment.
But also, the obvious way to try out this thing is ] activate --temp, so that you can compare to your other session & not mess anything up.
Exactly, and in that case everyone who wants to try something ForwardDiff-docs-related surely has installed ForwardDiff already in that temporary environment? That's at least my typical use case...
In any case, my intention was mostly to not clutter the docs with redundant information. We surely do not want to add Pkg.add("ForwardDiff") to every code block?
There was a problem hiding this comment.
Exactly, and in that case everyone who wants to try something ForwardDiff-docs-related surely has installed
No, they made this environment 5 seconds ago, just before pasting in the presumably complete doc example. Which fails with a mysterious error, even though ForwardDiff can load just fine. You are really assuming everyone will be on your golden path here. And I am telling you experimentally that someone who knows a fair bit about these things was completely baffled by this not just working.
We surely do not want to add Pkg.add("ForwardDiff") to every code block?
Right. Normally you type in using ForwardDiff, and it either just works, or prompts you to install. It "just works" even if ForwardDiff is not in this specific environment, it only has to be visible from it.
Co-authored-by: Michael Abbott <[email protected]>
I just learnt that since Preferences 1.4.3,
Preferences.set_preferences!accepts package names in addition to modules and UUIDs. This PR updates the docs accordingly, I think most users would prefer not having to copy or memorize ForwardDiff's UUID. Moreover, since in my experience most users expect the preference to become active right after setting the preference, I removed the example that required restarting the Julia session (which was also not applicable when working in a temporary environment).