Clarify pipeline arguments/output in book

[Gremious]

Added an example for PowerShell users showing that you have to explicitly provide pipeline output sometimes, because it confused me when I was switching to Nushell (https://github.com/nushell/nushell/issues/12074).

[rgwood]

Hey, thank you for the contribution!

I am a little reluctant to add this section as-is; I think it implies that Nu users should not pipe data between commands. Many Nushell commands do take "arguments" as piped input. For example, if we run help save we can see that the save command can be piped input of any type:

In the case of sleep, Nu decided to take the same approach as coreutils sleep and specify the sleep duration as an argument (sleep 1sec) as opposed to piped input (1sec | sleep) like PowerShell. I can appreciate that this might be confusing for people with muscle memory from PowerShell, but I don't know if this 1 command warrants a new section in the documentation. I'm open to other ideas for documenting $in better though!

I'd also note that the use of echo is not very idiomatic in Nu; I think Nu users would typically write sleep 1sec instead of sleep (echo 1sec).

[Gremious]

I think it implies that Nu users should not pipe data between commands.

Yeah I can see that, I think that's deffinetely worth rewriting a bit then

I think Nu users would typically write sleep 1sec instead of sleep (echo 1sec).

I admit, I struggled a bit to provide a good example that wasn't superflous. I just wanted to show that you can parenthesise arguments in that sectio as well as piping.

---

But, I think my confusion lies with the fact that it's not just sleep. You can't pipe e.g. dirname some_file to start or echo, like in PowerShell.

And so - between start, echo, sleep all not accepting raw stdout, but pipes being the expected way to move data, the question becomes - who else? How do I know?

Perhaps I could instead rewrite this section to clarify that you need to run help to see what each command expects, if you get a pipe error like the example I showed?

But then also ,help start says it accepts input string and pwd | start does not work, so I guess the output of pwd is not a string..?

Though I will go to sleep now, I would deffinetely appreciate some clarification as to what the rules are/how I am supposed to confirm whether I need to provide a $in or not.

[rgwood]

How do I know?

I think help (or browsing the equivalent command reference online) is usually the best way to check how a given command works.

But then also ,help start says it accepts input string and pwd | start does not work

That's a good catch. I think that's a mistake in the signature of start and it does not actually use the input string, I will confirm that and fix the signature.

I would deffinetely appreciate some clarification as to what the rules are

Me too! 😅

This is something I wondered about a lot when I was more actively contributing to Nushell. I wasn't able to find any great guidelines for whether to prefer foo | bar or bar foo. In practice I think we usually try to copy established conventions (i.e. sleep in coreutils probably has a lot more users than PowerShell's sleep functionality) or do whatever "feels right".

In the absence of reliable rules/guidelines for that, I suspect the best we can do is make it easy+intuitive for people to look up how any given Nushell command works.

[Gremious]

Oh the the start bug just hella caught me off guard then. Thank you, I appreciate it!

I think I will instead rewrite this to briefly mention that people can do help <command> if one doesn't behave like they expect.

[Gremious]

I got around to it and updated the text, clearing up that sometimes you should use help. Hopefully that is better now? :)