Lang guide refactor

[NotTheDr01ds]

Based on a discussion in the Website/Doc Discord channel yesterday. This is an extensive refactor of the monolithic Language Guide into smaller, individual files that can be more easily edited and merged.

This has the added advantage of properly styling headings in the sub-files.

During this refactor, I did make a few other tweaks along the way:

• The existing file had highly inconsistent heading levels, resulting in some topics appearing as subheadings of other topics they aren't. Fixed all heading levels to be consistent across all files.

• Changed dataframe example for Custom Value to Polars Plugin

• Added a deprecation notice to lazy make

• Added some additional conversion/casting to/from path

• Added a conversion example for range->list (i.e., 1..5 | each {||})

• Tweaked wording on the headings for data types that can't be "used by scripts" and can't be used to declare variables.

• Fixed minor typos (e.g., "A syntactic. form used by some Nushell keywords.")

• When explaining the return value of a block, described if/else/try as expressions rather than statements (this terminology was used elsewhere in the doc as well).

• Renamed "Numbers and Arithmetic" to "Operators" to more accurately reflect its contents

• Added intro/overview for "Flow Control", mainly to note that "Filters" should be considered as an alternative in many cases.

• Moved filters like each from "Flow Control" to a new section on Filters. Added new (since the guide was initially written) flow control statements like loop, break, continue, while, etc.

• Moved "Brackets" to "Operators" - I don't have a strong opinion on this and can move it to its own file if needed, it just seems better grouped here.

• Ommited "Nu as a shell" for now. These topics are probably best covered in "The Book" rather than the language guide, but since they were empty placeholders anyway, we can add them back in when/if created.

• Removed the "Literals" section as the only literal discussed was String, which has its own section. Additional literal forms are defined in the "Types" section, so this looks to be potentially redundant.

I can back out any of these if there's disagreement - They just felt fairly safe and needed while I was creating the sub-files.

[fdncred]

What does this look like rendered. I don't see a TOC but maybe it's not supposed to have one?

[NotTheDr01ds]

What does this look like rendered. I don't see a TOC but maybe it's not supposed to have one?

Index/TOC is definitely on the TODO list. The sidebar looks great rendered - better than the existing, along with collapsibility for most sections.

I'd love to be able to enumerate subsections into the "overview" for each section, as well as a master index like we talked about.

I'm guessing there's some Vuepress support to automate this, but I haven't gone too deep yet.

If we're going to switch doc engines (since Vuepress is in maintenance mode) soon, it might make sense to wait until that decision is made. The more manually linking we do, the more chance for things to get out of sync, of course.

[NotTheDr01ds]

Also TODO (reminder to self) - more previous/next linking to aid with navigation/flow. I did a few that needed manual insertion of the YAML front-matter, but not all.

[fdncred]

Maybe this should be draft until it's finished?

[NotTheDr01ds]

Maybe this should be draft until it's finished?

It's already an improvement over what what was there, so I'd recommend going ahead with it so that we can do future merges on top of it. If anyone else wants to submit to the Guide in the meantime, it's going to be a very manual (copy/paste) merge process.

Once this refactor is in place, additional updates become much easier.

[fdncred]

ok, let's move forward with this. if we don't like it we can always roll back.

[NotTheDr01ds]

@fdncred Thanks! I'll try to keep close watch on any issues raised over the next few days. Feel free to ping me in Discord (better notifications) if you see anything.