Package Manuals

Zoi provides a built-in man command to view manuals for Zoi-managed packages. It supports Markdown, ROFF (traditional man pages), and plain text formats.

Viewing Manuals

To view the manual for a package or a command it provides, use:

zoi man <package_or_binary>

Zoi will automatically resolve the binary name to its providing package and display the relevant manual pages.

TUI Navigation

By default, zoi man opens an interactive TUI (Terminal User Interface). If a package provides multiple manual pages (e.g. for different binaries or sections), you can navigate between them using the sidebar.

• Up/Down / j/k: Scroll content
• Tab / Shift+Tab: Switch between manual pages
• q / Esc: Exit the manual viewer

Using a Pager

If you prefer to use your system's default pager (like less or more) instead of the TUI, use the --no-tui flag:

zoi man <package_name> --no-tui

This will concatenate all manual pages and pipe them to your $PAGER.

Raw Output

To print the manual content directly to your terminal without any paging or interactive interface, use the --raw flag:

zoi man <package_name> --raw

Providing Manuals in Packages

Package authors can provide manual pages using the zman() helper function within their .pkg.lua definitions. This is the recommended way to ensure manuals are correctly placed for both system-wide and user-scoped installations.

Using zman(source, section)

The zman() function stages a manual file to the appropriate location based on the installation scope.

• source: Path to the manual file (Markdown, ROFF, or Text), relative to BUILD_DIR or ${pkgluadir}.
• section: (Optional) The manual section (e.g. "1" for commands, "5" for config files). If omitted, Zoi automatically infers the section from the file extension.

Example: Staging a traditional ROFF Page

function package()
  -- Stage a traditional ROFF man page (section 1)
  -- If source is 'man/mytool.1', Zoi infers section 1 automatically.
  zman("man/mytool.1")
end

Example: Staging a Markdown Page

function package()
  -- Stage a Markdown manual and explicitly set section 7 (Miscellaneous)
  zman("docs/guide.md", "7")
end

Installation Locations

Zoi places manuals in standard locations to ensure they are discoverable:

Viewing Manuals for Uninstalled Packages

One of Zoi's advanced features is the ability to view manuals for packages that are not yet installed on your system.

When you run zoi man <package_name> for an uninstalled package:

1. Zoi resolves the package from your active registries.
2. It downloads or builds the package archive into a temporary cache.
3. It extracts the archive to a temporary directory.
4. It gathers the manual pages from the extracted contents and displays them.

This allows you to research a tool's capabilities and configuration before deciding to install it globally.

ROFF Parsing

Zoi includes a cross-platform ROFF-to-Markdown parser. This allows traditional man pages to be rendered with syntax highlighting and styling in Zoi's TUI, even on systems without man-db or groff installed (like Windows).

Troubleshooting

• "No manual pages found": Ensure the package maintainer has used zman() to stage files in the package.
• Upstream Manuals: If the local manual is missing or you want the latest version from the registry (including uninstalled ones), use zoi man <pkg> --upstream.
• Formatting Issues: While Zoi's ROFF parser handles common macros, complex man pages might display better with --raw if you have a local man command.