Example formats: Make it easier to copy paste examples

[RobbingDaHood]

Example taken from https://www.nushell.sh/book/pipelines.html#when-does-in-change-and-when-can-it-be-reused but are many places in the documentation:

  > ls / | get name; $in | describe
  nothing

Should be split in two and the prefixed > should be removed:

  ls / | get name; $in | describe

  nothing

Because many readers allow copying a code block and that is practical for pasting and executing: Like it does here in gitlab PR reader.

Now I have to manually select the code I want executed and that is tedious.

PS: It seems like the documentation is not consistent on this, some places it looks as I suggest.

[fdncred]

Agreed. This would make it easier. We'd accept a PR for this.

[NotTheDr01ds]

In general, we're trying to converge on a "commented return result" so that copy/paste works:

ls / | get name; $in | describe
# => nothing

Return results are indicated by # => before them. Also works for multiline:

ls | table -a 3
# => ╭───┬────────────────────┬──────┬──────────┬──────────────╮
# => │ # │        name        │ type │   size   │   modified   │
# => ├───┼────────────────────┼──────┼──────────┼──────────────┤
# => │ 0 │ CITATION.cff       │ file │    812 B │ 2 months ago │
# => │ 1 │ CODE_OF_CONDUCT.md │ file │  3.4 KiB │ 9 months ago │
# => │ 2 │ CONTRIBUTING.md    │ file │ 11.0 KiB │ 5 months ago │
# => │ 3 │ ...                │ ...  │ ...      │ ...          │
# => │ 4 │ toolkit.nu         │ file │ 20.0 KiB │ 2 weeks ago  │
# => │ 5 │ typos.toml         │ file │    513 B │ 2 months ago │
# => │ 6 │ wix                │ dir  │  4.0 KiB │ 5 months ago │
# => ╰───┴────────────────────┴──────┴──────────┴──────────────╯

I'll take the blame for the ones you mention being in the current state that makes copy/paste difficult - I read somewhere about the format above, but I didn't understand the reason behind it when I first started submitting doc PR's here.

[NotTheDr01ds]

There sure are a lot of them. Looks like close to 500:

grep -ri '^\w*>'

It would be nice to get the majority into the "copyable" format so that new contributors don't make the same mistake I did and follow the "bad examples.'

[0x4D5352]

I'd be happy to take some time and clean this up!

[0x4D5352]

A few quick points as I'm getting into this:

1. I'm not entirely sure what the best approach would be for some examples - e.g. the shells command in https://github.com/nushell/nushell.github.io/blob/main/blog/2019-08-23-introducing-nushell.md#shells-plural has the example of /home/sophia/Source/rhai(master)> shells. For now I'm splitting them onto separate lines and putting the path on a new line inside the comment format described above.
2. How comprehensive should this be for things like blogs, and for older content with deprecated features like the example in the previous question?
3. Should I keep the prompt indicator in this section? https://github.com/nushell/nushell.github.io/blob/main/book/how_nushell_code_gets_run.md#the-nushell-repl Could/should it be rewritten to keep with the rest of the documentation?

[NotTheDr01ds]

@0x4D5352 Great questions.

1. Here's what I've done for similar scenarios:

   enter ../rhai/
   # enters a new shell in the specified directory
   shells
   # => ---+---+------------+-----------------------------
   # =>  # |   | name       | path
   # => ---+---+------------+-----------------------------
   # =>  0 |   | filesystem | /home/sophia/Source/nushell
   # =>  1 | X | filesystem | /home/sophia/Source/rhai
   # => ---+---+------------+-----------------------------

2. Don't worry about blogs, because they very often have outdated content. They've been removed from the site search index, but we should probably add warning heads to older ones. It's something we've discussed.

3. That's a fairly unique one, yes. I specifically left the prompt (and explained it) in that case because of the unique aspect of explaining the REPL. That said, I'm not tied to it -- If you have a suggestion on how to improve it here, I'm definitely open to changing it.

[0x4D5352]

@NotTheDr01ds Sounds good! Pedagogically, I like the idea of keeping the prompt in for these types of sections. The code snippets in those sections feel less like examples you can plug-and-play with and more like concepts to be aware of.

I kept them in when submitting the PR for the book changes; will likely do the same for the rest of the changes.