From e9331233c36f170aa8c6ad9acc854cdece655a0d Mon Sep 17 00:00:00 2001 From: Alec Clews Date: Tue, 9 Jul 2019 04:17:19 +1000 Subject: [PATCH] The start of some User docs (#1577) * Start User docs * Fix typos * Addded some more TODO * Update doc/user-docs/index.md Co-Authored-By: Michael Niksa * Update doc/user-docs/index.md Co-Authored-By: Michael Niksa * Update doc/user-docs/index.md Co-Authored-By: Michael Niksa * Update doc/user-docs/index.md Co-Authored-By: Michael Niksa * Updated from suggestions in the PR * Improve path to profiles.json * Added some details about Json settings * Example Json settings, and a #TODO * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <48369326+cinnamon-msft@users.noreply.github.com> * After review and make colour US. 1. Merged in comments from PR 2. Made colour color :-( 3. Other tidy ups * Added more detais about background images * Remove some TODO comments and minot tidy up * Get rid of TODO 1. Some notes abouet cut and paste -- needs more work 2. Get rid of TODO -- replace with links to issues 3. Add some extra notes about URI for background images --- doc/user-docs/UsingJsonSettings.md | 128 +++++++++++++++++++++++++++++ doc/user-docs/index.md | 88 ++++++++++++++++++++ 2 files changed, 216 insertions(+) create mode 100644 doc/user-docs/UsingJsonSettings.md create mode 100644 doc/user-docs/index.md diff --git a/doc/user-docs/UsingJsonSettings.md b/doc/user-docs/UsingJsonSettings.md new file mode 100644 index 00000000000..a616d5c5ab7 --- /dev/null +++ b/doc/user-docs/UsingJsonSettings.md @@ -0,0 +1,128 @@ +# Editing Windows Terminal JSON Settings + +One way (currently the only way) to configure Windows Terminal is by editing the profiles.json settings file. At +the time of writing you can open the settings file in your default editor by selecting +`Settings` from the WT pull down menu. + +The settings are stored in the file `$env:LocalAppData\Packages\Microsoft.WindowsTerminal_\RoamingState\profiles.json` + +Details of specific settings can be found [here](../cascadia/SettingsSchema.md). A general introduction is provided below. + +The settings are grouped under four headings: + +1. Global: Settings that apply to the whole application e.g. Default profile, initial size etc. +2. Key Bindings: Actually a sub field of the global settings, but worth discussing separately +3. Profiles: A group of settings to be applied to a tab when it is opened using that profile. E.g. shell to use, cursor shape etc. +4. Schemes: Sets of colors for background, text etc. that can be used by profiles + +## Global Settings + +These settings define startup defaults. + +* Theme +* Title Bar options +* Initial size +* Default profile used when WT is started + +Example settings include + +```json + "defaultProfile" : "{58ad8b0c-3ef8-5f4d-bc6f-13e4c00f2530}", + "initialCols" : 120, + "initialRows" : 50, + "requestedTheme" : "system", + "keybinding" : [] + ... +``` + +## Key Bindings + +This is an array of key chords and shortcuts to invoke various commands. +Each command can have more than one key binding. + +NOTE: Key bindings is a subfield of the global settings and +key bindings apply to all profiles in the same manner. + +## Profiles + +A profile contains the settings applied when a new WT tab is opened. Each profile is identified by a GUID and contains +a number of other fields. + +* Which command to execute on startup - this can include arguments. +* Starting directory +* Which color scheme to use (see Schemes below) +* Font face and size +* Various settings to control appearance. E.g. Opacity, icon, cursor appearance, display name etc. +* Other behavioural settings. E.g. Close on exit, snap on input, ..... + +Example settings include + +```json + "closeOnExit" : true, + "colorScheme" : "Campbell", + "commandline" : "wsl.exe -d Debian", + "cursorColor" : "#FFFFFF", + "cursorShape" : "bar", + "fontFace" : "Hack", + "fontSize" : 9, + "guid" : "{58ad8b0c-3ef8-5f4d-bc6f-13e4c00f2530}", + "name" : "Debian", + "startingDirectory" : "%USERPROFILE%/wslhome" + .... +``` + +The profile GUID is used to reference the default profile in the global settings. + +The values for background image stretch mode are documented [here](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.media.stretch) + +## color Schemes + +Each scheme defines the color values to be used for various terminal escape sequences. +Each schema is identified by the name field. Examples include + +```json + "name" : "Campbell", + "background" : "#0C0C0C", + "black" : "#0C0C0C", + "blue" : "#0037DA", + "foreground" : "#F2F2F2", + "green" : "#13A10E", + "red" : "#C50F1F", + "white" : "#CCCCCC", + "yellow" : "#C19C00" + ... +``` + +The schema name can then be referenced in one or more profiles. + +## Configuration Examples: + +### Add a custom background to the WSL Debian terminal profile + +1. Download the Debian SVG logo https://www.debian.org/logos/openlogo.svg +2. Put the image in the + `$env:LocalAppData\Packages\Microsoft.WindowsTerminal_\RoamingState\` + directory (same directory as your `profiles.json` file). + + __NOTE__: You can put the image anywhere you like, the above suggestion happens to be convenient. +3. Open your WT json properties file. +4. Under the Debian Linux profile, add the following fields: +```json + "backgroundImage": "ms-appdata:///Roaming/openlogo.jpg", + "backgroundImageOpacity": 0.3, + "backgroundImageStretchMode": "Fill", +``` +5. Make sure that `useAcrylic` is `false`. +6. Save the file. +7. Jump over to WT and verify your changes. + +Notes: +1. You will need to experiment with different color settings +and schemes to make your terminal text visible on top of your image +2. If you store the image in the UWP directory (the same directory as your profiles.json file), +then you should use the URI style path name given in the above example. +More information about UWP URI schemes [here](https://docs.microsoft.com/en-us/windows/uwp/app-resources/uri-schemes). +3. Instead of using a UWP URI you can use a: + 1. URL such as +`http://open.esa.int/files/2017/03/Mayer_and_Bond_craters_seen_by_SMART-1-350x346.jpg` + 2. Local file location such as `C:\Users\Public\Pictures\openlogo.jpg` diff --git a/doc/user-docs/index.md b/doc/user-docs/index.md new file mode 100644 index 00000000000..17f35113056 --- /dev/null +++ b/doc/user-docs/index.md @@ -0,0 +1,88 @@ +# Windows Terminal User Documentation + +NOTE: At the time of writing Windows Terminal is still under active development and many things will +change. If you notice an error in the docs, please raise an issue. Or better yet, please file a PR with an appropriate update! + +## Installing Windows Terminal + +### From Source Code + +Follow the instructions in this repo's [README](/README.md#developer-guidance). + +### From the Microsoft Store + +1. Make sure you have upgraded to the current Windows 10 release (at least 1903) +2. Search for Windows Terminal in the Store +3. Review the minimum system settings to ensure you can successfully install Windows Terminal +4. Install in the normal fashion + +## Starting Windows Terminal + +From the Windows Start menu, select Windows Terminal and run the application. + +Note: You can right click on the application item and run with Windows Administrator privilege if required. + +The default shell is PowerShell. + + +### Command line options + +None at this time. See issue [#607](https://github.com/microsoft/terminal/issues/607) + +## Multiple Tabs + +Additional shells can be started by hitting the `+` button from the tab bar -- a new instance of the +default shell is displayed (default shortcut `Ctrl+Shift+1`). + +## Running a Different Shell + +Note: The following text assumes you have WSL installed. + +To choose a different shell (e.g. `cmd.exe` or WSL `bash`) then + +1. Select the `down` button next to the `+` in the tab bar +2. Choose your new shell from the list (more on how to extend the list in the config section) + +## Starting a new PowerShell tab with admin privilege + +There is no current plan to support this feature for security reaons. See issue [#623](https://github.com/microsoft/terminal/issues/632) + +## Using cut and paste in the Terminal window + +### With PowerShell + +* Copy - Select the text with mouse (default left button), then right click with mouse +* Paste - by default use `+v`>, or right click with mouse + +### With Bash + +* Copy - Select the text with mouse (default left button), then right click with mouse +* Paste - Right click with mouse + +## Add a "Open Windows Terminal Here" to File Explorer + +Not currently supported "out of the box". See issue [#1060](https://github.com/microsoft/terminal/issues/1060) + +## Configuring Windows Terminal + +At the time of writing all Windows Terminal settings are managed via a json file. + +From the `down` button in the top bar select Settings (default shortcut `Ctrl+,`). + +Your default json editor will open up the Terminal settings file. The file can be found +at `$env:LocalAppData\Packages\Microsoft.WindowsTerminal_/RoamingState` + +An introduction to the the various settings can be found [here](UsingJsonSettings.md). + +The list of valid settings can be found in the [Profiles.json Documentation](../cascadia/SettingsSchema.md) doc. + +## Tips and Tricks: + +1. In PowerShell you can discover if the Windows Terminal is being used by checking for the existence of the environment variable `WT_SESSION`. + + Under pwsh you can also use +`(Get-Process -Id $pid).Parent.Parent.ProcessName -eq 'WindowsTerminal'` + + (ref https://twitter.com/r_keith_hill/status/1142871145852440576) + +2. Please add more Tips and Tricks