`:h[elp]` command and documentation

[Omnikar]

Addresses #668.

Each command will have its documentation as a file at runtime/help/command_name.txt. I'm going for an example-driven documentation style (though not all commands need/can have examples).

Todos

• [x] :h <command> where command is a static command will open documentation for the static command.

• [x] :h :<command> where command is a typable command will open documentation for the typable command.

• [x] :h <keybind> where keybind is bound to a specific command will open documentation for the command. Keybind keys will be parsed like a macro.

• [ ] :h <keybind> where keybind branches to multiple other keybinds — like g or z — will collect the sub-keys, their associated commands, and said commands' descriptions into a list which is opened in a buffer for the user.

• [x] :h topics will open a fuzzy picker with non-command-related help topics.

• [ ] Document static commands

  Command list

  • [x] no_op
  • [x] move_char_left
  • [x] move_char_right
  • [x] move_line_up
  • [x] move_line_down
  • [x] extend_char_left
  • [x] extend_char_right
  • [x] extend_line_up
  • [x] extend_line_down
  • [x] copy_selection_on_next_line
  • [x] copy_selection_on_prev_line
  • [x] move_next_word_start
  • [x] move_prev_word_start
  • [x] move_next_word_end
  • [x] move_next_long_word_start
  • [x] move_prev_long_word_start
  • [x] move_next_long_word_end
  • [x] extend_next_word_start
  • [x] extend_prev_word_start
  • [x] extend_next_word_end
  • [x] extend_next_long_word_start
  • [x] extend_prev_long_word_start
  • [x] extend_next_long_word_end
  • [x] find_till_char
  • [x] find_next_char
  • [x] extend_till_char
  • [x] extend_next_char
  • [x] till_prev_char
  • [x] find_prev_char
  • [x] extend_till_prev_char
  • [x] extend_prev_char
  • [ ] repeat_last_motion
  • [x] replace
  • [x] switch_case
  • [x] switch_to_uppercase
  • [x] switch_to_lowercase
  • [x] page_up
  • [x] page_down
  • [x] half_page_up
  • [x] half_page_down
  • [x] select_all
  • [ ] select_regex
  • [ ] split_selection
  • [ ] split_selection_on_newline
  • [ ] search
  • [ ] rsearch
  • [ ] search_next
  • [ ] search_prev
  • [ ] extend_search_next
  • [ ] extend_search_prev
  • [ ] search_selection
  • [ ] global_search
  • [ ] extend_line
  • [ ] extend_to_line_bounds
  • [ ] delete_selection
  • [ ] change_selection
  • [ ] collapse_selection
  • [ ] flip_selections
  • [ ] insert_mode
  • [ ] append_mode
  • [ ] command_mode
  • [ ] file_picker
  • [ ] code_action
  • [ ] buffer_picker
  • [ ] symbol_picker
  • [ ] last_picker
  • [ ] prepend_to_line
  • [ ] append_to_line
  • [ ] open_below
  • [ ] open_above
  • [ ] normal_mode
  • [ ] select_mode
  • [ ] exit_select_mode
  • [ ] goto_definition
  • [ ] add_newline_above
  • [ ] add_newline_below
  • [ ] goto_type_definition
  • [ ] goto_implementation
  • [ ] goto_file_start
  • [ ] goto_file_end
  • [ ] goto_reference
  • [ ] goto_window_top
  • [ ] goto_window_middle
  • [ ] goto_window_bottom
  • [ ] goto_last_accessed_file
  • [ ] goto_line
  • [ ] goto_last_line
  • [ ] goto_first_diag
  • [ ] goto_last_diag
  • [ ] goto_next_diag
  • [ ] goto_prev_diag
  • [ ] goto_line_start
  • [ ] goto_line_end
  • [ ] goto_next_buffer
  • [ ] goto_previous_buffer
  • [ ] goto_line_end_newline
  • [ ] goto_first_nonwhitespace
  • [ ] extend_to_line_start
  • [ ] extend_to_line_end
  • [ ] extend_to_line_end_newline
  • [ ] signature_help
  • [ ] insert_tab
  • [ ] insert_newline
  • [ ] delete_char_backward
  • [ ] delete_char_forward
  • [ ] delete_word_backward
  • [ ] undo
  • [ ] redo
  • [ ] yank
  • [ ] yank_joined_to_clipboard
  • [ ] yank_main_selection_to_clipboard
  • [ ] yank_joined_to_primary_clipboard
  • [ ] yank_main_selection_to_primary_clipboard
  • [ ] replace_with_yanked
  • [ ] replace_selections_with_clipboard
  • [ ] replace_selections_with_primary_clipboard
  • [ ] paste_after
  • [ ] paste_before
  • [ ] paste_clipboard_after
  • [ ] paste_clipboard_before
  • [ ] paste_primary_clipboard_after
  • [ ] paste_primary_clipboard_before
  • [ ] indent
  • [ ] unindent
  • [ ] format_selections
  • [ ] join_selections
  • [ ] keep_selections
  • [ ] keep_primary_selection
  • [ ] remove_primary_selection
  • [ ] completion
  • [ ] hover
  • [ ] toggle_comments
  • [ ] rotate_selections_forward
  • [ ] rotate_selections_backward
  • [ ] rotate_selection_contents_forward
  • [ ] rotate_selection_contents_backward
  • [ ] expand_selection
  • [ ] jump_forward
  • [ ] jump_backward
  • [ ] jump_view_right
  • [ ] jump_view_left
  • [ ] jump_view_up
  • [ ] jump_view_down
  • [ ] rotate_view
  • [ ] hsplit
  • [ ] vsplit
  • [ ] wclose
  • [ ] select_register
  • [ ] align_view_middle
  • [ ] align_view_top
  • [ ] align_view_center
  • [ ] align_view_bottom
  • [ ] scroll_up
  • [ ] scroll_down
  • [ ] match_brackets
  • [ ] surround_add
  • [ ] surround_replace
  • [ ] surround_delete
  • [ ] select_textobject_around
  • [ ] select_textobject_inner
  • [ ] shell_pipe
  • [ ] shell_pipe_to
  • [ ] shell_insert_output
  • [ ] shell_append_output
  • [ ] shell_keep_pipe
  • [ ] suspend
  • [ ] rename_symbol
  • [ ] increment
  • [ ] decrement
  • [ ] record_macro
  • [ ] replay_macro

• [ ] Document typable commands

  Command list

  • [x] :quit
  • [x] :quit!
  • [x] :open
  • [x] :buffer-close
  • [x] :buffer-close!
  • [x] :write
  • [x] :new
  • [ ] :format
  • [ ] :indent-style
  • [ ] :line-ending
  • [ ] :earlier
  • [ ] :later
  • [x] :write-quit
  • [x] :write-quit!
  • [x] :write-all
  • [x] :write-quit-all
  • [x] :write-quit-all!
  • [x] :quit-all
  • [x] :quit-all!
  • [ ] :cquit
  • [ ] :cquit!
  • [ ] :theme
  • [ ] :clipboard-yank
  • [ ] :clipboard-yank-join
  • [ ] :primary-clipboard-yank
  • [ ] :primary-clipboard-yank-join
  • [ ] :clipboard-paste-after
  • [ ] :clipboard-paste-before
  • [ ] :clipboard-paste-replace
  • [ ] :primary-clipboard-paste-after
  • [ ] :primary-clipboard-paste-before
  • [ ] :primary-clipboard-paste-replace
  • [ ] :show-clipboard-provider
  • [ ] :change-current-directory
  • [ ] :show-directory
  • [ ] :encoding
  • [ ] :reload
  • [ ] :tree-sitter-scopes
  • [ ] :vsplit
  • [ ] :hsplit
  • [ ] :tutor
  • [ ] :goto
  • [ ] :set-option
  • [ ] :sort
  • [ ] :rsort
  • [ ] :help

[archseer]

I was thinking we could use markdown since it would be possible to highlight it with a tree-sitter grammar. We could also render it using the markdown components we use for LSP docs.

[Omnikar]

I was thinking we could use markdown since it would be possible to highlight it with a tree-sitter grammar. We could also render it using the markdown components we use for LSP docs.

Would that allow for, in the examples, showing the selections without making the text wider by adding []? Cause that's been bothering me.

[Omnikar]

Would that allow for, in the examples, showing the selections without making the text wider by adding []? Cause that's been bothering me.

I had an idea to solve this; from Matrix:

What if we were to make some custom tree-sitter grammar solely for Helix help files, and use it to represent selections in examples by actually rendering a selection? It would remove the aforementioned ambiguity, and would be more clear about the fact that they are selections.

"Aforementioned ambiguity" referring to the fact that using brackets to show selections in examples makes no distinction between selection and cursor, and no distinction between primary and non-primary.

One issue I can see with this approach is getting the file to somehow let tree-sitter know what to parse as text that should have a selection displayed on it. Delimiting the example selections with invisible characters won't work since Helix just displays them as 1-column spaces.

Thoughts?

[matoous]

Late to the party but just out of curiosity (and whether it even makes sense): would it be possible to have the docs as a comments for the rust functions and then extract it from there? It would mean that there's only single source of truth that is close to the implementation and it could be easier to keep it up to date. On the other hand, it could get quite messy and maybe harder to write the docs.

[Omnikar]

Late to the party but just out of curiosity (and whether it even makes sense): would it be possible to have the docs as a comments for the rust functions and then extract it from there? It would mean that there's only single source of truth that is close to the implementation and it could be easier to keep it up to date. On the other hand, it could get quite messy and maybe harder to write the docs.

Hm, interesting idea… but I'm not sure how we'd go about extracting the doc comments into runtime files. Does rustdoc provide an API of some sort that can be used to access the doc comments from build code?

[Omnikar]

Why is it claiming that typable-cmd.md is conflicted?

[Omnikar]

OK… I guess I was able to fix it through Github's GUI

[sudormrfbin]

would it be possible to have the docs as a comments for the rust functions and then extract it from there?

I wanted to do the same for config options and automatically updating the online docs at https://docs.helix-editor.com/configuration.html as a followup to #1119, but couldn't find a way to do it. rustdoc is not available as a separate crate, which would have solved the problem quite neatly.

[dead10ck]

Maybe this would be doable with tree-sitter once https://github.com/tree-sitter/tree-sitter-rust/pull/99 finally gets merged.

[Omnikar]

Maybe this would be doable with tree-sitter once tree-sitter/tree-sitter-rust#99 finally gets merged.

What do you mean? How does that relate to the help system?

[dead10ck]

Maybe this would be doable with tree-sitter once tree-sitter/tree-sitter-rust#99 finally gets merged.

What do you mean? How does that relate to the help system?

Generating docs from doc comments. Read the last few comments.

[Omnikar]

So you're proposing using tree-sitter for compile time documentation generation?

I do want to add that I am honestly not particularly fond of the idea of moving all the help file documentation into doc comments in the source file; they'll add a lot of non-code to the commands.rs file, which is already very long as it is now.
Additionally, doc comments are generally meant to be markdown, right? The help files I'm creating are not formatted as markdown, but are meant to be viewed as monospace plaintext in the editor.

[dead10ck]

I do want to add that I am honestly not particularly fond of the idea of moving all the help file documentation into doc comments in the source file; they'll add a lot of non-code to the commands.rs file, which is already very long as it is now.

Is that so bad? Having all the intended behavior sitting right alongside the code would be a good thing in my opinion. I'm also not seeing what the length of the current manifestation of the file has to do with anything. It'll also get thrice as long or more when more testing code is added. It's honestly overdue for a refactor. There's so much going on in there, it's in sore need of being split up.

Additionally, doc comments are generally meant to be markdown, right? The help files I'm creating are not formatted as markdown, but are meant to be viewed as monospace plaintext in the editor.

Don't we already render doc comments in the "show docs" view? This is a solved problem right now. And additionally, it would give users a way to view docs in a nicely rendered web page outside of the editor, something that kakoune offers and vim does not.

[Omnikar]

Exactly what change is being asked for here? Is it just to copy all the documentation as-is from the files into doc comments, or is it to do that in addition to reformatting it to allow it to be displayed "in a nicely rendered web page" as well?

[dead10ck]

Exactly what change is being asked for here? Is it just to copy all the documentation as-is from the files into doc comments, or is it to do that in addition to reformatting it to allow it to be displayed "in a nicely rendered web page" as well?

I suppose the long term goal would be the latter. Nothing has to happen all at once of course. And besides, without the PR I linked to being merged, this is all hypothetical anyway. And any help command at all is better than none.

[glyh]

@Omnikar maybe your problem here(hiding brackets) will be workaround by virtual text(#417), though this is not yet merged.

[Omnikar]

Hm, I suppose virtual text could be used to re-render the text without the brackets, but that'd be a bit of an odd thing to do. Also, something I've realized is that currently, the help is opened as a scratch buffer, so the editor can't currently differentiate between a help buffer and any other scratch buffer, so this sort of special behaviour will only be possible once scratch buffers have additional state, as per #1237. There is of course the alternative of opening the help files as any other files, but I don't want to do that for the same reason as with runtime/tutor.txt; I don't want the user to be able to potentially accidentally save edits and then have to restore their runtime files.

[Omnikar]

Actually, no, we couldn't use virtual text to remove the brackets, since that'd mess with the cursor position in the actual text and visually. However, we could instead completely remove the brackets from the help files and instead load a separate file containing data for where virtual text should be used to render selections in the help file.

[Omnikar]

:h <keybind> is now implemented for non-branching keybinds. I also made it work without <> delimiters around multichar keypresses if it's only one, so :h C-o can be done instead of :h <C-o>, for example.

[langston-barrett]

This is really great - Anything I can do to help move it forward?

[archseer]

@Omnikar could we merge this as is? I think partial documentation is still better than no documentation, and it would make it possible for others to contribute via follow-up PRs.

[6lj6]

The API need to be design comprehensive. Also the default keymaps need to be selected carefully by the factors of general usage, high frequency, finger pains, etc...

The behavior should be separated as an independent level. It should be hard coded and rely on implementation. Instead, the codes serve for middle-abstraction level. e.g.: the difference between i and a is mainly on with/without selection, but this behavior shouldn't be hard coded, instead it should be customizable by user to decide which one is with/without selection. Also gh/gl will work on \n or not? on space or not? (Right now, gh works on CHAR, gl works on CHARwithout\n, gs works on CHARwithoutSPACE&TAB, they are so weird and not changeable!)

[shaleh]

merge conflicts resolved in shaleh/help-command.