id       = "tldr"
name     = "tldr pages"
homepage = "https://tldr.sh"
description = "A collection of community-maintained help pages for command-line tools."
# The project's own icon, from tldr.sh.
icon     = "https://tldr.sh/assets/img/icon.png"
executables   = ["tldr"]

[dotfiles]

# `tldr` is one command name shared by several independent clients, so every
# client that keeps a per-user file is listed here and the consumer syncs
# whichever exists. Each path is cited with the client it belongs to.
#
# tealdeer (Rust, https://docs.tealdeer.org/config.html): "The configuration
# file path follows OS conventions (e.g. $XDG_CONFIG_HOME/tealdeer/config.toml
# on Linux) ... On Linux, this will usually be ~/.config/tealdeer/config.toml".
# src/config.rs takes etcetera's `choose_app_strategy` (XDG on Linux *and*
# macOS) with app_name = NAME = "tealdeer", and falls back to the native
# strategy — ~/Library/Preferences/<bundle-id> on macOS — when only that one
# exists, which is where tealdeer wrote before 1.9. The Windows spelling is
# not listed: etcetera's Windows app strategy composes
# %APPDATA%\<author>\<app_name>\config and tealdeer passes an empty author, so
# the resulting path is an inference rather than something documented.
#
# tldr-node-client (Node, lib/config.js): `const CUSTOM =
# path.join(osHomedir(), '.tldrrc')`, parsed as JSON, with the cache defaulting
# to `path.join(osHomedir(), '.tldr')`.
#
# py-tldr (Python, README): "Config file should be located as
# ~/.config/tldr/config.toml".
paths = [
  "~/.config/tealdeer/config.toml",
  "~/Library/Preferences/tealdeer/config.toml",
  "~/.tldrrc",
  "~/.config/tldr/config.toml",
]

# Downloaded page archives, re-fetched by `tldr --update`. tealdeer's cache
# directory comes from the same two strategies as its config directory
# (src/config.rs: `fallback(app_dirs.cache_dir(), native_dirs.cache_dir())`),
# so the app-strategy one is `[xdgCache]` — XDG on macOS as well as Linux, and
# a variable tealdeer reads rather than a default it assumes, since etcetera's
# XDG base strategy resolves the directory as
# `env_var_or_default("XDG_CACHE_HOME", ".cache/")` — and the native-strategy
# one, ~/Library/Caches, is a second directory rather than another spelling of the
# first: it is what tealdeer used before 1.9 and still prefers when only it
# exists. As with the config directory, the Windows spelling is left unlisted
# rather than inferred.
exclude = [
  "[xdgCache]/tealdeer/",
  "~/Library/Caches/tealdeer/",
  "~/.tldr/",
]

# Themes, page source URLs and language preferences. None of these clients
# authenticates to anything.
secret = []

# Read at the start of a lookup by a process that then exits.
side_effect = false

# No machine_lines: these files hold colour themes, the preferred platform and
# language, and the pages repository — the preferences a user wants on every
# machine.

[commands]
format = 1
label = "tldr pages"
description = "Look up a simplified man page, search, or refresh the page cache."
quality = "ai-draft"
base = "fig:tldr"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = true }

[[commands.source]]
id = "fig"
kind = "completion"
url = "https://github.com/withfig/autocomplete/blob/master/src/tldr.ts"
license = "MIT"

[[commands.field]]
id = "command"
label = "Command"
type = "string"
position = 0
sources = ["fig"]

[[commands.field]]
id = "platform"
label = "Platform"
type = "enum"
option = ["-p", "--platform"]
choices = [{ value = "linux", label = "Linux" }, { value = "osx", label = "macOS" }, { value = "sunos", label = "SunOS" }, { value = "windows", label = "Windows" }, { value = "common", label = "Common" }]
sources = ["fig"]

[[commands.field]]
id = "search"
label = "Search all pages"
type = "string"
option = ["-s", "--search"]
sources = ["fig"]

[[commands.field]]
id = "list"
label = "List pages"
type = "boolean"
option = ["-l", "--list"]
sources = ["fig"]

[[commands.field]]
id = "update"
label = "Update page cache"
type = "boolean"
option = ["-u", "--update"]
sources = ["fig"]

[[commands.field]]
id = "clear_cache"
label = "Clear local cache"
type = "boolean"
option = ["-c", "--clear-cache"]
effect = "delete"
sources = ["fig"]

[[commands.task]]
id = "lookup"
label = "Look up a command"
fields = ["command", "platform"]
required = ["command"]

[[commands.task]]
id = "update"
label = "Update pages"
fields = ["update"]
required = ["update"]
set = { update = [true] }

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["command", "platform", "search", "list", "update", "clear_cache"]