tldr-man(1)

NAME
tldr-man - display simple help pages for command-line tools from the tldr-pages project as manpages

SYNOPSIS
tldr [-L|--language LANGUAGE] [-p|--platform PLATFORM] PAGE...
tldr [-L|--language LANGUAGE] [-p|--platform PLATFORM] -l|--list
tldr [-L|--language LANGUAGE] [-p|--platform PLATFORM] -M|--manpath
tldr -r|--render FILE
tldr -u|--update
tldr -v|--version
tldr -h|--help

DESCRIPTION

tldr-man is a command-line client for tldr-pages, a collection of community-maintained help pages for command-line tools. It differs from other clients because it displays its pages as man(1) pages.

This client is able to integrate with the man(1) command to fall back to displaying a tldr-page for a command when no manpage exists.

The pandoc(1) tool must be installed and present on $PATH for tldr-man to function. Instructions for installing pandoc can be found at https://pandoc.org/installing.html.

OPTIONS

  Arguments

PAGE...
    The name of the tldr-page to display.

-l, --list
    List all available tldr-pages for the current platform and language with one page name per line.

-M, --manpage
    Prints a colon-separated list of manpaths to be appended to $MANPATH. See the MAN INTEGRATION section for more information.

-r FILE, --render=FILE
    Instead of displaying a page, render FILE (in the tldr-pages markdown format) in the roff(7) format and display it.

-u, --update
    Update the local cache of rendered man(1) pages by getting the updated list of pages from the internet and rendering them. This command must be run before any pages are displayed.

-v, --version
    Print this command's version and exit.

-h, --help
    Print this command's help and exit.

  General Options

-L LANGUAGE, --language=LANGUAGE
    Set the language to display. Overrides any languages specified by environment variables. LANGUAGE must be a country code, such as en, es, fr, zh, or zh_TW.

-p PLATFORM, --platform=PLATFORM
    Set the platform to display. PLATFORM must be one of android, linux, macos, osx, sunos, and windows.

EXIT STATUS

If tldr-man completes successfully, it will return exit code 0. Nonzero exit codes have the following meanings:

1   General error

2   Invalid usage

3   Page cache does not exist

127 The external commands man(1) or pandoc(1) were not found on $PATH

ENVIRONMENT

TLDR_LANGUAGE, LANGUAGE, LANG
    If the [-L|--language] option is not set, these environment variables determine the languages that are displayed. Each variable must contain a colon-separated list of languages, which will be checked in order until an existing page is found. For example, en:fr:zh_TW is a valid value for each of these variables. The order of priority is TLDR_LANGUAGE, LANGUAGE, LANG, with the values of TLDR_LANGUAGE being checked first and LANG being checked last. If none of these environment variables are set or if no valid pages exist for any of the languages, this defaults back to en.

TLDR_MAN_ARCHIVE_URL
    The URL to download pages from when running the tldr --update command. If this variable is not set, the default official archive URL (https://tldr.sh/assets/tldr.zip) is used. The file located at the provided URL must be a well-formed ZIP file with contents which match the directory structure specified in the TLDR-Pages Client Specification.

TLDR_MAN_CACHE_DIR
    The location of the page cache directory. This directory is created by the tldr --update command and is accessed by other commands. If this variable is not set or is not an absolute path, this defaults back to the value of $XDG_CACHE_HOME/tldr-man.

TLDR_MAN_NO_COLOR, NO_COLOR
    When present and not an empty string (regardless of its value), prevents the usage of ANSI color.

FILES

$XDG_CACHE_HOME/tldr_man
    The location that the tldr-pages (in roff(7) format) are stored if the environment variable $TLDR_MAN_CACHE_DIR is not set or not an absolute path. This directory is created by running the tldr --update command, and the cache is accessed by tldr PAGE, tldr --list, and tldr --manpath commands.

CONFORMING TO

TLDR-Pages Client Specification (https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md).

XDG Base Directory Specification (https://standards.freedesktop.org/basedir-spec/basedir-spec-latest).

NO_COLOR (https://no-color.org/).

EXAMPLES

Display the tldr-page for git(1):

    tldr git

Update the local page cache:

    tldr --update

Render a page locally:

    tldr --render path/to/page.md

Print manpage paths as a colon-separated list:

    tldr --manpath

SHELL COMPLETION
The file generate_completion.sh that is distributed along with this software can be used to generate shell completions for tldr-man.

MAN INTEGRATION

The man(1) command can be set up to fall back to displaying tldr-pages if no manpages are found.

For bash(1) place the following line in ~/.bash_profile, and for zsh(1) place the following line in ~/.zshenv:

    export MANPATH="${MANPATH}:$(tldr --manpath)"

For fish(1), place the following line in $XDG_CONFIG_HOME/fish/config.fish:

    set -gxa MANPATH (tldr --manpath)

HOMEPAGE

This software is available at https://github.com/superatomic/tldr-man, and can be found on PyPI at https://pypi.org/project/tldr-man.

REPORTING BUGS

Please report bugs and feature requests in the issue tracker at https://github.com/superatomic/tldr-man. Please do your best to provide a reproducible test case for bugs.

COPYRIGHT
Copyright 2023 Olivia Kinnear
Licensed under the Apache License, Version 2.0

SEE ALSO
man(1), pandoc(1), man-pages(7)

VERSION
1.5.2