Initial `$in` language reference

[NotTheDr01ds]

Here's a first pass at $in documentation for the Language Reference Guide. Let me know if I missed any nuances or use-cases.

[NotTheDr01ds]

@amtoine ping as requested

[kubouch]

I think this is a great addition, but I would split it a bit. The language guide is meant as a concise reference for the language. There should be only a short mention of what $in is and where it appears. The rest of your text is more of a tutorial style which is better fit for the book, possibly under https://www.nushell.sh/book/variables.html.

[NotTheDr01ds]

I think this is a great addition, but I would split it a bit. The language guide is meant as a concise reference for the language. There should be only a short mention of what $in is and where it appears. The rest of your text is more of a tutorial style which is better fit for the book, possibly under https://www.nushell.sh/book/variables.html.

Thanks! And certainly open to seeing how we can split it out. Regardless, I think The Book needs more discussion of $in than is currently there.

Keep in mind, though, that the README for the Language Guide says the goal is:

to provide a little bit of documentation text for context and then many examples of usage

I know it "looks" like a tutorial at first glance, but it's really just 10 examples of usage of $in, along with the explanation of those examples. In that light, doesn't it pretty much fit the criteria for the "many examples" of the Language Guide?

I also think it's a bit overkill for The Book, which it seems should be the intro/tutorial/digest version, right?

[kubouch]

The goal of the reference is to have a concise overview of Nushell's syntax, kind of like https://doc.rust-lang.org/reference. The readme probably should be reworded to reflect that better. The goal of the book is to teach users how to use the language which can include examples. If we don't keep this distinction strict, we'll end up with two books.

I believe you can take most of your text, put it under a new section in https://www.nushell.sh/book/variables.html and in the language reference just add a short enumeration of where $in can appear. It can include examples, but just for showcasing the syntax, it doesn't need to showcase all the possible use cases for $in (like the let day = $in example, doesn't need to be in the language guide). Formulations like "Imagine that ..." are better suited for the tutorial-style book as well.

[NotTheDr01ds]

Thanks for the feedback, and apologies for the delay getting back around to this.

• @kubouch - I've moved it to The Book as requested - I agree this is more "essentials" than "language reference" for the most part. I think it fits better in the "Pipelines" section than "Variables", though.

  I still have some questions on what belongs in each doc, though, but I'll take those up on a separate issue. I plan to do a lot more work around this, and I'd like to make sure it's clear where things go.

• @sholderbach I've removed the reference to the "implicit $in".

[fdncred]

I think we can move ahead with this. Thanks for taking the time to update based on our feedback. We can continue to tweak as time goes by, but this is 100% better than what we had. Thanks.