The start of some User docs (microsoft#1577)

* Start User docs * Fix typos * Addded some more TODO * Update doc/user-docs/index.md Co-Authored-By: Michael Niksa <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Michael Niksa <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Michael Niksa <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Michael Niksa <[email protected]> * 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 <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/UsingJsonSettings.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * Update doc/user-docs/index.md Co-Authored-By: Kayla Cinnamon <[email protected]> * 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
mcpiroman · Jul 23, 2019 · e933123 · e933123
1 parent 046f04e
commit e933123
Show file tree

Hide file tree

Showing 2 changed files with 216 additions and 0 deletions.
diff --git a/doc/user-docs/UsingJsonSettings.md 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_<randomString>\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_<randomString>\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
@@ -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 `<ctrl>+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_<randomString>/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