docs: start adding a reference section for Config

.gitignore

@@ -12,6 +12,7 @@
 /docs/installation.md
 /docs/install/*.md
 /docs/colorschemes/**/index.md
+/docs/config/lua/config/index.md
 /docs/config/lua/wezterm/index.md
 /docs/config/lua/pane/index.md
 /docs/config/lua/window/index.md

ci/generate-docs.py

@@ -170,6 +170,22 @@ local wezterm = require 'wezterm';
 at the top of your configuration file to enable it.
 
 ## Available functions, constants
+""",
+                    ),
+                    Gen(
+                        "struct: Config",
+                        "config/lua/config",
+                        index="""
+# `Config` struct
+
+The `return` statement at the end of your `wezterm.lua` file returns
+a table that is interpreted as the internal `Config` struct type.
+
+This section documents the various available fields in the config
+struct.
+
+At the time of writing, it is not a complete list!
+
 """,
                     ),
                     Gen(

docs/config/lua/config/bold_brightens_ansi_colors.md

@@ -0,0 +1,5 @@
+# `bold_brightens_ansi_colors = true`
+
+When true (the default), PaletteIndex 0-7 are shifted to bright when the font
+intensity is bold.  The brightening doesn't apply to text that is the default
+color.

docs/config/lua/config/color_schemes.md

@@ -0,0 +1,5 @@
+# `color_schemes`
+
+Specifies various named color schemes in your configuration file.
+
+Described in more detail in [Colors & Appearance](../../appearance.html#defining-a-color-scheme-in-your-weztermlua)

docs/config/lua/config/colors.md

@@ -0,0 +1,5 @@
+# `colors`
+
+Specifies the color palette.
+
+Described in more detail in [Colors & Appearance](../../appearance.md#defining-your-own-colors)

docs/config/lua/config/default_prog.md

@@ -0,0 +1,19 @@
+# `default_prog`
+
+If no `prog` is specified on the command line, use this
+instead of running the user's shell.
+
+For example, to have `wezterm` always run `top` by default,
+you'd use this:
+
+```lua
+return {
+  default_prog = {"top"}
+}
+```
+
+`default_prog` is implemented as an array where the 0th element
+is the command to run and the rest of the elements are passed
+as the positional arguments to that command.
+
+See also: [Launching Programs](../../launch.html)

docs/config/lua/config/font.md

@@ -0,0 +1,6 @@
+# `font`
+
+Configures the font to use by default.  The `font` setting can specify
+a set of fallbacks and other options, and is described in more detail
+in the [Fonts](../../fonts.md) section.
+

docs/config/lua/config/font_antialias.md

@@ -0,0 +1,8 @@
+# `font_antialias = "Greyscale"`
+
+Adjusts the anti-aliasing portion of the font rasterizer.
+
+Possible values are `None`, `Greyscale`, `Subpixel`.
+
+The default value is `Greyscale`.
+

docs/config/lua/config/font_hinting.md

@@ -0,0 +1,8 @@
+# `font_hinting = "Full"`
+
+Adjust the hinting portion of the font rasterizer.
+
+Possible values are `None`, `Vertical`, `VerticalSubpixel`, `Full`.
+
+
+

docs/config/lua/config/font_locator.md

@@ -0,0 +1,8 @@
+# `font_locator`
+
+specifies the method by which system fonts are located and loaded.  You may
+specify `ConfigDirsOnly` to disable loading system fonts and use only the fonts
+found in the directories that you specify in your `font_dirs` configuration
+option.
+
+Otherwise, it is recommended to omit this setting.

docs/config/lua/config/font_rasterizer.md

@@ -0,0 +1,4 @@
+# `font_rasterizer`
+
+Specifies the method by which fonts are rendered on screen.  The only available
+implementation is `FreeType`.

docs/config/lua/config/font_rules.md

@@ -0,0 +1,6 @@
+# `font_rules`
+
+An optional set of style rules that can be used to specify alternative
+fonts to be used for text matching various styles.
+
+This option is described in more detail in the [Fonts](../../fonts.md) section.

docs/config/lua/config/font_shaper.md

@@ -0,0 +1,7 @@
+# `font_shaper`
+
+specifies the method by which text is mapped to glyphs in the available fonts.
+The shaper is responsible for handling kerning, ligatures and emoji
+composition.  The default is `Harfbuzz` and we have very preliminary support
+for `Allsorts`.
+

docs/config/lua/config/font_size.md

@@ -0,0 +1,9 @@
+# `font_size = 10.0`
+
+Specifies the size of the font, measured in points.
+
+The default font size is 10 points.
+
+You may use fractional point sizes, such as `13.3`, to fine tune the size.
+
+

docs/config/lua/config/freetype_interpreter_version.md

@@ -0,0 +1,5 @@
+# `freetype_interpreter_version`
+
+Selects the freetype interpret version to use.  Possible values are `35`, `38`
+and `40` which have different characteristics with respective to subpixel
+hinting.  See <https://freetype.org/freetype2/docs/subpixel-hinting.html>

docs/config/lua/config/front_end.md

@@ -0,0 +1,14 @@
+# `front_end = "OpenGL"`
+
+Specifies which render front-end to use.  This option used to have
+more scope in earlier versions of wezterm, but today it allows two
+possible values:
+
+* `OpenGL` - use GPU accelerated rasterization (this is the default)
+* `Software` - use CPU-based rasterization.
+
+You may wish (or need!) to select `Software` if there are issues with your
+GPU/OpenGL drivers.
+
+WezTerm will automatically select `Software` if it detects that it is
+being started in a Remote Desktop environment on Windows.

docs/config/lua/config/harfbuzz_features.md

@@ -0,0 +1,8 @@
+# `harfbuzz_features`
+
+When `font_shaper = "Harfbuzz"`, this setting affects how font shaping
+takes place.
+
+See [Font Shaping](../../font-shaping.html) for more information
+and examples.
+

docs/config/lua/config/hyperlink_rules.md

@@ -0,0 +1,7 @@
+# `hyperlink_rules`
+
+Defines rules to match text from the terminal output and generate
+clickable links.
+
+See [Hyperlinks](../../../hyperlinks.md) for more information and
+examples.

docs/config/lua/config/initial_cols.md

@@ -0,0 +1,3 @@
+# `initial_cols = 80`
+
+Specifies the width of a new window, expressed in character cells.

docs/config/lua/config/initial_rows.md

@@ -0,0 +1,3 @@
+# `initial_rows = 24`
+
+Specifies the height of a new window, expressed in character cells.

docs/config/lua/config/line_height.md

@@ -0,0 +1,10 @@
+# `line_height = 1.0`
+
+Scales the computed line height to adjust the spacing between successive rows
+of text.  The default line height is controlled by the
+[font_size](font_size.md) configuration option.  If you feel that your chosen
+font feels too vertically cramped then you can set `line_height = 1.2` to
+increase the vertical spacing by 20%.  Conversely, setting `line_height = 0.9`
+will decrease the vertical spacing by 10%.
+
+

docs/config/lua/config/scrollback_lines.md

@@ -0,0 +1,5 @@
+# `scrollback_lines = 3500`
+
+How many lines of scrollback you want to retain.
+
+[Learn more about scrollback](../../../scrollback.md)

docs/config/lua/config/set_environment_variables.md

@@ -0,0 +1,7 @@
+# `set_environment_variables`
+
+Specifies a map of environment variables that should be set when spawning
+commands in the local domain.  This is not used when working with remote
+domains.
+
+See also: [Launching Programs](../../launch.html#passing-environment-variables-to-the-spawned-program)

docs/config/lua/config/term.md

@@ -0,0 +1,24 @@
+# `term = "xterm-256color"`
+
+What to set the `TERM` environment variable to.  The default is
+`xterm-256color`, which should provide a good level of feature
+support without requiring the installation of additional terminfo
+data.
+
+If you want to get the most application support out of wezterm, then you may
+wish to install a copy of the `wezterm` TERM definition:
+
+```
+tempfile=$(mktemp) \
+  && curl -o $tempfile https://raw.githubusercontent.com/wez/wezterm/master/termwiz/data/wezterm.terminfo \
+  && tic -x -o ~/.terminfo $tempfile \
+  && rm $tempfile
+```
+
+You can then set `term = "wezterm"` in your `.wezterm.lua` config file.
+
+Doing this will inform some software of newer, more advanced features such
+as colored underlines, styled underlines (eg: undercurl).  If the system
+you are using has a relatively outdated ncurses installation, the `wezterm`
+terminfo will also enable italics and true color support.
+

docs/config/lua/general.md

@@ -1,8 +1,8 @@
 ## Lua Reference
 
-This section documents the various lua functions that are provided to
+This section documents the various lua functions and types that are provided to
-the configuration file.  These are provided by the `wezterm` module that
+the configuration file.  These are provided by the `wezterm` module that must
-must be imported into your configuration file:
+be imported into your configuration file:
 
 ```lua
 local wezterm = require 'wezterm';