nushell.github.io icon indicating copy to clipboard operation
nushell.github.io copied to clipboard

Explain the role and rules for `where` row conditions.

Open sholderbach opened this issue 3 years ago • 2 comments

where (~~, any and all~~) uses the Expr::RowCondition internally, we should probably have a small section on what rules are valid for those. E.g. mention the $it special variable (#401) and that columns of tables can be accessed by their bare name (or the quoted string of their name if they are not valid variable names). Then we can refer to those from the command documentation (@hustcer is there a good way we could allow commands to link to pages in the book?)

sholderbach avatar Sep 08 '22 11:09 sholderbach

@sholderbach As for adding links in the command docs:

  • For the built-in doc that is accessed via help <command>/<command> --help the problem is that links to the book can be quite long. We can add them, but we have to do so as the fully-qualified URL, so that terminals (that support the feature) can make them clickable links.

    So a link to the closure type would look like:

    See also https://nushell.sh/book/types_of_data.md#closures

    I have a proof of concept URL shortener (redirect) for Vuepress that we could use to make this:

    See also https://nushell.sh/type-closures.md

    We'd just need to set up any "short-links" we wanted for particular topics.

  • Alternatively, we could have an "Additional info" section that the gets added only to the online Command Reference by the make_docs.nu. That could add either a link or as much info to each command as we need, of course.

NotTheDr01ds avatar Aug 18 '24 00:08 NotTheDr01ds

Yeah, if we want to liberally use links in the command docs we should probably have some form of markup/markdown parser in our internal help logic to manage intra-doc links differently.

Re the row conditions https://github.com/nushell/nushell/issues/9140 points to potential confusion there.

Now its just where remaining so maybe the documentation of this command needs the extra attention.

sholderbach avatar Aug 18 '24 13:08 sholderbach