nushell
Replace Pipelines "Behind the Scenes" with "Result Display Rendering"
The previous "Behind the Scenes" docs has some problems:
- The title is not descriptive
- Confusing context reference: The "You may have wondered" references
lsoutput despite no applicable example in front of it - and is not stable against other docs section changes either way - Confusing false equivalence: Claims "one and the same" and then explains how they are not in fact the same
The section is being replaced with "Result Display Rendering", which
- Mentions and explains the existence of a display output hook
- Begins with establishing context: The section is about interactive shell pipeline result display output
I kept the section small so as not to duplicate content from the Hooks documentation page.
Adding examples for current, different, or simplified displaying may be reasonable here, but would duplicate the hooks "Changing how Output is Displayed" and "Filtering or Diverting Command Output" sections.
This looks like a good, straightforward simplification to me - Thanks!
As noted in https://github.com/nushell/nushell/pull/14361, display_output is actually not what runs table, but instead table is automatically appended to printed pipelines. I think this should be mentioned in the docs if we maintain this behavior, and shouldn't imply that display_output does everything.
You're probably right - When I look at it in light of that, it may be an over-simplification. Does my suggested edit about look more accurate?
@132ikl thank you for raising that concern. Although I tested with null or empty setting the hook, I assumed Nushell fell back to table in such cases. Both concepts behave practically the same, but of course it'd be better to document it as it is implemented.
Shall this PR wait for the discussion in https://github.com/nushell/nushell/pull/14361 then, or make adjustments like @NotTheDr01ds suggested so the improvements can land? I don't know how long or not the referenced discussion may take?
@Kissaki https://github.com/nushell/nushell/pull/14361 was landed, so I think your original explanation is good. Technically, if the hook is not set (or set to null), the table command is used as well, but I don't think that's really necessary to mention in the docs.
It could be useful to show what happens if you set $env.config.hooks.display_output = {||} and say something to the effect of "you can see that without the call to table, tables are really just a list of records," but feel free to take it whatever direction you want.
It seemed to me like there was nothing open here but nothing happened anymore. Anyway, I applied the suggested headline change, and added examples including behavior with an empty closure as suggested.
PTAL
this one fell between the cracks, but looks good. thanks, I'll merge it finally 😄