documentation: consistent format for actions help

src/cli/action.zig

@@ -45,12 +45,12 @@ pub const Action = enum {
     // Validate passed config file
     @"validate-config",
 
-    // List, (eventually) view, and (eventually) send crash reports.
-    @"crash-report",
-
     // Show which font face Ghostty loads a codepoint from.
     @"show-face",
 
+    // List, (eventually) view, and (eventually) send crash reports.
+    @"crash-report",
+
     pub const Error = error{
         /// Multiple actions were detected. You can specify at most one
         /// action on the CLI otherwise the behavior desired is ambiguous.

src/cli/help.zig

@@ -15,9 +15,11 @@ pub const Options = struct {
     }
 };
 
-/// The `help` command shows general help about Ghostty. You can also specify
-/// `--help` or `-h` along with any action such as `+list-themes` to see help
-/// for a specific action.
+/// The `help` command shows general help about Ghostty. Recognized as either
+/// `-h, `--help`, or like other actions `+help`.
+///
+/// You can also specify `--help` or `-h` along with any action such as
+/// `+list-themes` to see help for a specific action.
 pub fn run(alloc: Allocator) !u8 {
     var opts: Options = .{};
     defer opts.deinit();

src/cli/list_actions.zig

@@ -24,7 +24,9 @@ pub const Options = struct {
 /// actions for Ghostty. These are distinct from the CLI Actions which can
 /// be listed via `+help`
 ///
-/// The `--docs` argument will print out the documentation for each action.
+/// Flags:
+///
+///   * `--docs`: will print out the documentation for each action.
 pub fn run(alloc: Allocator) !u8 {
     var opts: Options = .{};
     defer opts.deinit();

src/cli/list_fonts.zig

@@ -44,14 +44,21 @@ pub const Options = struct {
 /// the sorting will be disabled and the results instead will be shown in the
 /// same priority order Ghostty would use to pick a font.
 ///
-/// The `--family` argument can be used to filter results to a specific family.
-/// The family handling is identical to the `font-family` set of Ghostty
-/// configuration values, so this can be used to debug why your desired font may
-/// not be loading.
+/// Flags:
 ///
-/// The `--bold` and `--italic` arguments can be used to filter results to
-/// specific styles. It is not guaranteed that only those styles are returned,
-/// it will just prioritize fonts that match those styles.
+///   * `--bold`: Filter results to specific bold styles. It is not guaranteed
+///     that only those styles are returned. They are only prioritized.
+///
+///   * `--italic`: Filter results to specific italic styles. It is not guaranteed
+///     that only those styles are returned. They are only prioritized.
+///
+///   * `--style`: Filter results based on the style string advertised by a font.
+///     It is not guaranteed that only those styles are returned. They are only
+///     prioritized.
+///
+///   * `--family`: Filter results to a specific font family. The family handling
+///     is identical to the `font-family` set of Ghostty configuration values, so
+///     this can be used to debug why your desired font may not be loading.
 pub fn run(alloc: Allocator) !u8 {
     var iter = try args.argsIterator(alloc);
     defer iter.deinit();

src/cli/list_keybinds.zig

@@ -42,11 +42,15 @@ pub const Options = struct {
 /// changes to the keybinds it will print out the default ones configured for
 /// Ghostty
 ///
-/// The `--default` argument will print out all the default keybinds configured
-/// for Ghostty
+/// Flags:
 ///
-/// The `--plain` flag will disable formatting and make the output more
-/// friendly for Unix tooling. This is default when not printing to a tty.
+///   * `--default`: will print out all the default keybinds
+///
+///   * `--docs`: currently does nothing, intended to print out documentation
+///     about the action associated with the keybinds
+///
+///   * `--plain`: will disable formatting and make the output more
+///     friendly for Unix tooling. This is default when not printing to a tty.
 pub fn run(alloc: Allocator) !u8 {
     var opts: Options = .{};
     defer opts.deinit();

src/cli/list_themes.zig

@@ -91,6 +91,7 @@ const ThemeListElement = struct {
 /// Flags:
 ///
 ///   * `--path`: Show the full path to the theme.
+///
 ///   * `--plain`: Force a plain listing of themes.
 pub fn run(gpa_alloc: std.mem.Allocator) !u8 {
     var opts: Options = .{};

src/cli/validate_config.zig

@@ -23,10 +23,13 @@ pub const Options = struct {
 
 /// The `validate-config` command is used to validate a Ghostty config file.
 ///
-/// When executed without any arguments, this will load the config from the default location.
+/// When executed without any arguments, this will load the config from the default
+/// location.
 ///
-/// The `--config-file` argument can be passed to validate a specific target config
-/// file in a non-default location.
+/// Flags:
+///
+///   * `--config-file`: can be passed to validate a specific target config file in
+///     a non-default location
 pub fn run(alloc: std.mem.Allocator) !u8 {
     var opts: Options = .{};
     defer opts.deinit();

src/cli/version.zig

@@ -10,7 +10,8 @@ const gtk = if (build_config.app_runtime == .gtk) @import("../apprt/gtk/c.zig").
 
 pub const Options = struct {};
 
-/// The `version` command is used to display information about Ghostty.
+/// The `version` command is used to display information about Ghostty. Recognized as
+/// either `+version` or `--version`.
 pub fn run(alloc: Allocator) !u8 {
     _ = alloc;
 

src/shell-integration/README.md

@@ -6,7 +6,7 @@ supports.
 
 This README is meant as developer documentation and not as
 user documentation. For user documentation, see the main
-README.
+README or [ghostty.org](https://ghostty.org/docs)
 
 ## Implementation Details