vscode-docs Review performance and update integrated terminal topic

https://code.visualstudio.com/docs/editor/integrated-terminal August CSAT FY21Q4 32% Several product issues and new features during May and June.

Sep 03 '21 18:09 gregvanl

AFAIK the reason for this was the introduction of some links to the page into the settings, using a query param to indicate it came from VS Code would allow us to segment access via troubleshooting links vs organic.

Sep 07 '21 15:09 Tyriar

Next to do pull content out of docs/terminal/basics into advanced and reference

Aug 03 '22 23:08 gregvanl

Current full ToC of basics page:

Terminal Basics
- Terminal shells
- Managing terminals
  - Grouping
  - Customizing Tabs
- Terminal profiles
  - Configuring profiles
  - Removing built-in profiles
  - Configuring the task/debug profile
- Working directory
- Terminal process reconnection
- Links
- Local echo
- Terminal appearance
- Copy & Paste
- Using the mouse
  - Right-click behavior
  - Alt click
- Keybindings and the shell
  - Chord keybindings in the terminal
  - Send text via a keybinding
- Find
- Run selected text
- Automating launching of terminals
- Next steps
- Common questions
  - I'm having problems launching the terminal
  - Can I use the integrated terminal with the Windows Subsystem for Linux?
  - Why is VS Code shortcut X not working when the terminal has focus?
  - Can I use Cmder's shell with the terminal on Windows?
  - Why is Cmd+k/Ctrl+k not clearing the terminal?
  - Why is nvm complaining about a prefix option when the integrated terminal is launched?
  - Can I use Powerline fonts in the integrated terminal?
  - How do I configure zsh on macOS to jump words with Ctrl+Left/Right arrow?
  - Why does macOS make a ding sound when I resize terminal split panes?
  - Why is my terminal showing a multi-colored triangle or a completely black rectangle?
  - Why are there duplicate paths in the terminal's $PATH environment variable and/or why are they reversed?
  - I'm having problems with the terminal rendering. What can I do?
  - Git Bash isn't saving history when I close the terminal
  - I see 1~ or [201~ when I paste something
  - Ctrl+A, Ctrl+R output ^A, ^R on zsh
  - Why are the colors in the terminal not correct?

Aug 04 '22 17:08 Tyriar

Proposed new structure below:

Legend

:open_hands: Usage
:gear: Config
:art: Appearance
:zap: Advanced
:thinking: Troubleshooting
:no_entry: Stale/remove/mentioned elsewhere
:arrow_right: Move/consolidate
:question: Unknown/open question

New table of contents

Basics - Simple usage and high level overview of features, minimal configuration
Terminal Profiles - Profiles are one of the most important features
Shell Integration
Appearance - All appearance related customizations and gpu acceleration
Advanced - Catch all for advanced topics, mostly for at power users. keybinding complications, auto replies, local echo, etc.
Reference (later) - Technical specs, supported escape sequences, protocol extensions, etc.

Top-level sections

Settings/commands also added under sections to consider covering

Basics Just explain simple usage and high level overview of features, only config should be in tip callouts
- (no header) Intro to terminal similar to today but with updated/fancier screenshot, also briefly about philosophy?
- :open_hands: Managing terminals
  - :open_hands: Split panes
    - terminal.integrated.splitCwd
- :new: :open_hands: Terminals in editor area (better name?)
  - terminal.integrated.defaultLocation
- :new: :open_hands: Navigating the buffer Mention keybindings to navigate around the buffer
  - :gear: Tip: Increasing the buffer size
    - terminal.integrated.scrollback
  - terminal.integrated.smoothScrolling
- :open_hands: Links
  - terminal.integrated.wordSeparators Not sure this does anything anymore?
  - terminal.integrated.showLinkHover Not worth mentioning?
  - workbench.action.terminal.openDetectedLink
  - workbench.action.terminal.openWordLink
  - workbench.action.terminal.openFileLink
  - workbench.action.terminal.openUrlLink
- :open_hands: Copy & Paste
  - terminal.integrated.copyOnSelection
  - terminal.integrated.enableMultiLinePasteWarning
- :open_hands: :gear: Using the mouse
  - :open_hands: :gear: Right-click behavior
    - terminal.integrated.rightClickBehavior
  - :open_hands: Alt click
    - terminal.integrated.altClickMovesCursor
  - :new: terminal.integrated.macOptionClickForcesSelection
- :open_hands: Find The Ctrl+F thing mentioned is more of a tip
- :open_hands: Run selected text
- :open_hands: Maximizing the terminal
- :open_hands: :gear: Select all
- :open_hands: Drag and drop file paths
- :zap: :open_hands: :gear: Automating launching of terminals This just points at the tasks page Rephrase title?
- terminal.integrated.macOptionIsMeta
- :zap: :gear: Working directory This was way too high in the basics doc
- :new: Fixed dimension terminals
  - workbench.action.terminal.setDimensions
- :new: Drag and drop terminals between windows
  - workbench.action.terminal.attachToSession
  - workbench.action.terminal.detachSession
- Common questions
  - :thinking: I'm having problems launching the terminal
  - :thinking: Why is nvm complaining about a prefix option when the integrated terminal is launched?
  - :thinking: I see 1~ or [201~ when I paste something
  - :thinking: Ctrl+A, Ctrl+R output ^A, ^R on zsh
Terminal Profiles ("terminal" prefix to disambiguate with settings profiles) Dedicated section as this is arguably one of the most important features? We could have sections on individual shells instead of hiding in common questions
- :gear: Configuring profiles
  - terminal.integrated.profiles.windows
  - terminal.integrated.profiles.osx
  - terminal.integrated.profiles.linux
  - terminal.integrated.defaultProfile.linux
  - terminal.integrated.defaultProfile.osx
  - terminal.integrated.defaultProfile.windows
- :gear: Removing built-in profiles
- :gear: Configuring the task/debug profile
  - terminal.integrated.automationProfile.linux
  - terminal.integrated.automationProfile.osx
  - terminal.integrated.automationProfile.windows
- :open_hands: Can I use the integrated terminal with the Windows Subsystem for Linux? This is obvious now because of built-in profile and remote-wsl extension Make sure WSL is mentioned on profiles page
  - terminal.integrated.useWslProfiles
- :arrow_right: Can I use Cmder's shell with the terminal on Windows? Merge into profiles section
- :thinking: Why are there duplicate paths in the terminal's $PATH environment variable and/or why are they reversed? This one's frequently referred to
- :question: Git Bash isn't saving history when I close the terminal Should there be a page for tips on configuring various shells?
- terminal.integrated.env.osx
- terminal.integrated.env.linux
- terminal.integrated.env.windows
Shell integration Existing section dedicated to shell integration and its features
- terminal.integrated.shellIntegration.enabled
- terminal.integrated.shellIntegration.showWelcome
- terminal.integrated.shellIntegration.decorationsEnabled
- terminal.integrated.shellIntegration.decorationIcon
- terminal.integrated.shellIntegration.decorationIconError
- terminal.integrated.shellIntegration.decorationIconSuccess
- terminal.integrated.shellIntegration.history
Appearance All appearance related customizations and gpu acceleration
- :gear: Customizing Tabs
  - terminal.integrated.tabs.defaultColor
  - terminal.integrated.tabs.defaultIcon
  - terminal.integrated.tabs.enabled
  - terminal.integrated.tabs.enableAnimation
  - terminal.integrated.tabs.hideCondition
  - terminal.integrated.tabs.showActiveTerminal
  - terminal.integrated.tabs.showActions
  - terminal.integrated.tabs.location
  - terminal.integrated.enableBell
  - terminal.integrated.bellDuration
  - terminal.integrated.tabs.separator
  - terminal.integrated.tabs.title
  - terminal.integrated.tabs.description
  - terminal.integrated.ignoreProcessNames Validate how this interacts with shell type
- :new: :art: Text style
  - terminal.integrated.fontFamily
  - terminal.integrated.fontSize
  - terminal.integrated.letterSpacing
  - terminal.integrated.lineHeight
  - terminal.integrated.fontWeight
  - terminal.integrated.fontWeightBold
- :art: Terminal colors
  - terminal.integrated.drawBoldTextInBrightColors
- :art: Terminal cursor
  - terminal.integrated.cursorBlinking
  - terminal.integrated.cursorStyle
  - terminal.integrated.cursorWidth
- :new: :art: Minimum contrast ratio
  - terminal.integrated.minimumContrastRatio
- :arrow_right: :gear: Can I use Powerline fonts in the integrated terminal? Move to its own customization section
- :new: GPU Acceleration
  - terminal.integrated.gpuAcceleration
- :new: Custom glyphs
  - terminal.integrated.customGlyphs
- :new: Customizing your prompt Brief explanation of how you can customize the prompt in various shells
- Common questions
  - :thinking: Why is my terminal showing a multi-colored triangle or a completely black rectangle? Probably good to keep this, though we get less and less reports
  - :arrow_right: I'm having problems with the terminal rendering. What can I do? Merge into gpu acceleration section
  - :thinking: Why are the colors in the terminal not correct? Link back to min contrast section, this is mainly for SEO
Advanced (alt: input and behavior?) Catch all for advanced topics, mostly targeted at power users. Things like keybinding complications, auto replies, local echo, etc.
- :zap: :open_hands: :gear: Terminal process reconnection
  - terminal.integrated.enablePersistentSessions
  - terminal.integrated.persistentSessionReviveProcess
  - terminal.integrated.persistentSessionScrollback
- :zap: :open_hands: :gear: Local echo Name should be more descriptive like "Reducing input latency"?
  - terminal.integrated.localEchoLatencyThreshold
  - terminal.integrated.localEchoEnabled
  - terminal.integrated.localEchoExcludePrograms
  - terminal.integrated.localEchoStyle
- :zap: :gear: Keybindings and the shell This section's a little sparse, explain how to passthrough clicks to the pty
  - :zap: :open_hands: :gear: Chord keybindings in the terminal
  - :zap: :gear: Send text via a keybinding
  - :arrow_right: Why is Cmd+k/Ctrl+k not clearing the terminal? Merge into keybindings section
  - :arrow_right: Why is VS Code shortcut X not working when the terminal has focus? Merge into keybindings section
  - :arrow_right: :gear: How do I configure zsh on macOS to jump words with Ctrl+Left/Right arrow? Include example in keybindings section
  - terminal.integrated.sendKeybindingsToShell
  - terminal.integrated.commandsToSkipShell
  - terminal.integrated.allowChords
  - terminal.integrated.allowMnemonics
- :question: :gear: Confirm when exiting VS Code with active terminal sessions Basics instead?
  - terminal.integrated.confirmOnExit
  - terminal.integrated.confirmOnKill
  - terminal.integrated.showExitAlert
- :new: Auto replies
  - terminal.integrated.autoReplies
- :new: $LANG interaction
  - terminal.integrated.detectLocale
- :new: Unicode and emoji support
  - terminal.integrated.unicodeVersion
- :new: Extension environment contributions
  - terminal.integrated.environmentChangesRelaunch
- :new: Windows and Conpty
  - terminal.integrated.windowsEnableConpty
- terminal.integrated.inheritEnv Not sure if this deserves a section
- :new: Remote Windows (bad title?)
  - workbench.action.terminal.newLocal
Reference (later)
- Area to put technical specs, supported escape sequences, protocol extensions, etc.

Accessibility page

:new: Run recent command Mention here as an accessible alternative to ctrl+r?

No home:

terminal.integrated.tabs.focusMode Expected usage too low?
terminal.integrated.fastScrollSensitivity Expected usage too low?
terminal.integrated.mouseWheelScrollSensitivity Expected usage too low?

No docs intentionally:

terminal.integrated.environmentChangesIndicator Will probably remove eventually
terminal.integrated.enableFileLinks Bad solution to the problem
terminal.integrated.shell.linux
terminal.integrated.shell.osx
terminal.integrated.shell.windows
terminal.integrated.automationShell.linux
terminal.integrated.automationShell.osx
terminal.integrated.automationShell.windows
terminal.integrated.shellArgs.linux
terminal.integrated.shellArgs.osx
terminal.integrated.shellArgs.windows
:gear: Focus when already open

Aug 09 '22 13:08 Tyriar