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.

Viewing Pages

By default, zoi man opens the manual in your system's man viewer (falling back to info, then plain output when neither is installed). If a package provides multiple manual pages, the one matching the package name in section 1 (e.g. zbsdiff.1) is shown.

Selecting a Page

Use the --page flag to open a specific page by file name, e.g. a library page in another section:

zoi man zbsdiff --page zbsdiff.3
zoi man zbsdiff --page zbspatch.1

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

The output stays in its original format (e.g. raw ROFF), so it can be piped into other tools:

zoi man @zillowe/zbsdiff --raw | man

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.

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.
• "has no manual page": The package ships several pages but none matches the default <name>.1 pick. List them via the error message and open one with --page.