Skip to content

Conversation

EjPlatzer
Copy link
Contributor

I found two minor typos in the beginning of the book.

Also, I wanted to try to clarify the Parsing and evaluation... section of Thinking in Nu because I think this is by far the most confusing section for people coming to Nu. I know there have been discussions of how to clarify it on Discord, but I figured I'd submit some minor changes as a first effort.


Personally, I think that the given example is more confusing than is necessary. This is especially true because if you run each line as a separate command in the shell, it will work perfectly - and this is how most people will think to try the script.

Instead, I would highlight the second example and use that to explain the overall concept. It's much more clear (to me, at least) that sourcing a dynamic path doesn't work because the source command tries to parse the contents of the path before the dynamic expression has been evaluated. We could, for example, give this self-contained example:

> source $nu.config-path

This has the added benefit that it would fail even if run from the shell, unlike the current primary example. Also, I think this is a familiar command to people coming from other shells, because sourcing the [.bashrc/.zshrc/...] is the normal way to reload the configuration values. I think that isn't best practice in Nushell, but this section is just about explaining the concepts, not instructing in the proper use of Nu.

The book referred to `save` as a file, saying "you pipe to a file that has the job of saving content". This is confusing and potentially misleading - files don't have any job. Instead, we pipe to a command that has the job of saving content and give that command a path argument for the file that the content should be saved to.
I think this is by far the most confusing section for many people coming to Nu. I know there have been discussions of how to clarify it on Discord, but I figured I'd submit some minor changes as a first effort.

Personally, I think that the given example is more confusing than is necessary. This is especially true because if you run each line as a separate command in the shell, it will work perfectly - and this is how most people will think to try the script. 

Instead, I would highlight the second example and use that to explain the overall concept. It's much more clear (to me, at least) that sourcing a dynamic path doesn't work because the source command tries to parse the contents of the path before the dynamic expression has been evaluated. This example has the added benefit that it would fail even if run from the shell. We could, for example, give this self-contained example:

```bash
> source $nu.config-path
```
@tikue
Copy link

tikue commented Mar 24, 2022

This is especially true because if you run each line as a separate command in the shell, it will work perfectly - and this is how most people will think to try the script.

Thank you! I was banging my head against this for a few minutes trying to understand what I was missing.

@fdncred
Copy link
Contributor

fdncred commented Mar 24, 2022

Thanks!

@fdncred fdncred merged commit 8766042 into nushell:main Mar 24, 2022
ayax79 pushed a commit to ayax79/nushell.github.io that referenced this pull request Jun 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants