Documentation #3023
Documentation #3023
Conversation
exastone
commented
Jan 28, 2023
exastone
commented
- added table of contents to Key Bindings doc and Color & Appearances doc
- additional information and example on key bindings doc
- some restructuring of Key Bindings doc and Color & Appearances doc to group related info into more focused sections, where before there was some ambiguity where one section ended and another started making it difficult to quickly find info on a particular topic
- added screenshot showing 2 options of tab bar style; fancy, retro.
- general formatting touch-up, linkage to relevant docs pages where they were previous missing,
added table of contents and updated Key Binding doc with cleaner formatting, added examples, links to other doc pages where appropriate and improved structuring
…creen shot of the 2 tab bar options available and reformatting to better fit logical layout
added table of contents and updated Key Binding doc with cleaner formatting, added examples, links to other doc pages where appropriate and improved structuring
docs/config/appearance.md
Outdated
| @@ -1,4 +1,27 @@ | |||
| ### Color Scheme | |||
| - [Colors \& Appearance](#colors--appearance) | |||
There was a problem hiding this comment.
Hmm, I have mixed feelings about this. I can see the utility.
My train of thought is:
- Manually updating this TOC is a PITA, and extra PITA when considering the other page you added a TOC to.
- I wonder if mdbook has a thing to help with this?
- Perhaps this page should just get split into multiple pages anyway, so that the existing TOC on the left can be used to navigate it?
If you'd like to take a crack at splitting this into separate pages, you can play around with the structure over here:
https://github.com/wez/wezterm/blob/main/ci/generate-docs.py#L319-L335
There was a problem hiding this comment.
I looked into breaking it up into a separate page, I think the content on the page works well being grouped on the same page together since it's all under the category of appearance/styling.
I didn't consider being an issue because i assumed that docs wouldn't change much but I recognize it could creates extra work down the road. I'll remove it from the revised PR.
Here's a screen shot of what it looks like incase it's something you want to revisit in the future.
|
|
||
| Combining the 3 fields togeather, we can construct a key assignment structs in our config e.g. | ||
|
|
||
| ```lua |
There was a problem hiding this comment.
FWIW, I think this will fail validation in the doc build because this isn't a complete syntactically valid block of lua code.
You can run the doc build yourself; the setup step is:
cargo install --vers "^0.4" mdbook
cargo install mdbook-linkcheck
cargo install mdbook-mermaid
cargo install gelatyx --version "^0.2"
Then:
./ci/build-docs.sh
open gh_pages/html/index.html
One of the things that the build does is format all of the lua fragments for consistency in style, so be sure to run it and add in any formatting changes to your PR!
There was a problem hiding this comment.
this seems to fail at ci/subst-release-info.py with
Error {
"documentation_url":"https://docs.github.com/rest",
"message":"Bad credentials"
}
Work around: commenting this step from build-docs.sh
additionally, mdbook build docs fails to generate because it's expecting to find the chapters:
install/freebsd.md
install/linux.md
install/macos.md
install/source.md
install/windows.md
Line 310 in 691ec18
but the files are named:
install/freebsd.markdown
install/linux.markdown
install/macos.markdown
install/source.markdown
install/windows.markdown
Work around: change the files endings from .markdown to .md
idk if this is intentionally done another reason but i figured it's worth a mention
docs/config/keys.md
Outdated
|
|
||
| Alternatively, a single unicode character can be specified to indicate | ||
| pressing the corresponding key. | ||
|
|
||
| Pay attention to the case of the text that you use and the state of the `SHIFT` modifier, as `key="A"` will match | ||
| Pay attention to the case of the text that you assign to `key = '<some key>'` if your modifier contains `SHIFT` as this is a common mistake. |
There was a problem hiding this comment.
Thanks for fixing this up; looks like a casualty of a vim piloting error :-p
Might be worth also summarizing and linking to #1906
There was a problem hiding this comment.
added example to clarify the issue of not being able to discern non-alphabetic keys when shift is used as a modifier key (@kaddkaka caught the original example was bad)
Ran ./ci/build-docs.sh and made changes as necessary pass build-docs check.
updated keycode identifiers table in keys.md to remove excessive horizontal scroll on reg. width window.
| will trigger the current pane to be split. | ||
| In this configuration, | ||
| pressing `CTRL-A` activates the leader key for up to 1 second (1000 milliseconds).<br> | ||
| While `LEADER` is active, the `'|'` key (with no other modifiers) will trigger the current pane to be split. |
There was a problem hiding this comment.
This text says that no modifier is needed, but the configuration says mods = 'LEADER|SHIFT' why is that? Is it because many keyboard layouts need shift to produce | ?
| milliseconds). While `LEADER` is active, the `|` key (with no other modifiers) | ||
| will trigger the current pane to be split. | ||
| In this configuration, | ||
| pressing `CTRL-A` activates the leader key for up to 1 second (1000 milliseconds).<br> |
| local wezterm = require 'wezterm' | ||
| return { | ||
| keys = { | ||
| -- This will not be abled to be triggered |
There was a problem hiding this comment.
I'm able to trigger keybinding such as { key = "h", mods = "ALT|SHIFT", ... }, is this documentation only half true?
There was a problem hiding this comment.
i think you're right, this should be better clarified as to what the issue actually is. I believe this should be given a better example since to my knowledge the issue only effects non alphabetic characters.
There was a problem hiding this comment.
this should provide clarity. I had to do a sanity check on it myself.
Updated keys.md with screenshot with example of debug key-events to find raw keycodes.
| local wezterm = require 'wezterm' | ||
| return { | ||
| keys = { | ||
| -- These are the same key assignments |
There was a problem hiding this comment.
... on a ... keyboard under ...? (above there is Raw codes are hardware and windowing system dependent,...)
There was a problem hiding this comment.
the point wasn't to convey 45 = n but rather raw code = key.
perhaps this creates more confusion then it resolves. this can be removed or a line can be added to clarify, have an opinion?
