id       = "man-db"
name     = "man-db"
homepage = "https://man-db.gitlab.io/man-db/"
description = "man-db is an implementation of the standard Unix documentation system accessed using the man command."
# The `man` binary is man-db's on Linux, but the same name is BSD man on macOS
# and mandoc elsewhere; neither of those has a per-user configuration file. The
# entry is named for the project, not for the binary.
executables   = ["man", "manpath", "mandb", "apropos", "whatis"]
# man-db is the man implementation on essentially every Linux distribution and
# also builds on macOS (its home page points at a Homebrew tap). It has no
# Windows build.
platforms = ["linux", "macos"]

[dotfiles]

# man(1): "-C file, --config-file=file  Use this user configuration file rather
# than the default of ~/.manpath." manpath(5) describes the format, and says of
# it: "When used in the per-user configuration file .manpath, it indicates
# which manual page hierarchies to access as the setuid user and which as the
# invoking user."
paths = ["~/.manpath"]

exclude = []

# A search path and a section order. Nothing here is a credential.
secret = []

# Read once per man invocation.
side_effect = false

# manpath(5) FORMAT: MANDATORY_MANPATH "specifies a manpath element that should
# always be in the resulting manpath" and MANPATH_MAP "sets up a PATH to
# MANPATH mapping", both written as absolute directories — /usr/local/share/man
# on one machine, a Homebrew prefix on the next — and MANDB_MAP additionally
# names the directory this machine stores its cat pages in. The SECTION and
# NOCACHE lines around them are preferences and stay. Where a package manager
# installs its man pages follows from the kind of machine, not from this one,
# so these values hold across every box of the same OS and architecture.
[[dotfiles.machine_lines]]
file  = "~/.manpath"
match = { prefix = ["MANDATORY_MANPATH", "MANPATH_MAP", "MANDB_MAP"] }
scope = "platform"

[commands]
format = 1
label = "Read manual page"
description = "Show or locate manual pages. Config file, browser, preprocessor and troff options are left out."
quality = "ai-draft"
base = "fig:man"
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/man.ts"
license = "MIT"

[[commands.field]]
id = "page"
label = "Page names"
type = "string"
position = 0
multiple = true
sources = ["fig"]

[[commands.field]]
id = "sections"
label = "Sections to search"
description = "Colon-separated list, for example 1:3."
type = "string"
option = ["-S"]
sources = ["fig"]

[[commands.field]]
id = "all"
label = "Open every matching page"
type = "boolean"
option = ["-a"]
sources = ["fig"]

[[commands.field]]
id = "path"
label = "Print file location only"
type = "boolean"
option = ["-w", "--path"]
sources = ["fig"]

[[commands.field]]
id = "whatis"
label = "Short description (whatis)"
type = "boolean"
option = ["-f"]
sources = ["fig"]

[[commands.field]]
id = "apropos"
label = "Search descriptions (apropos)"
type = "boolean"
option = ["-k"]
sources = ["fig"]

[[commands.field]]
id = "pager"
label = "Pager program"
type = "string"
option = ["-P"]
sources = ["fig"]

[[commands.task]]
id = "read"
label = "Read a page"
fields = ["page", "sections"]
required = ["page"]

[[commands.task]]
id = "search"
label = "Search descriptions"
fields = ["page", "apropos"]
required = ["page"]
set = { apropos = [true] }

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["page", "sections", "all", "path"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["whatis", "apropos", "pager"]