tldr-man.1

.\" Copyright 2023 Olivia Kinnear
.\"
.\" Licensed under the Apache License, Version 2.0 (the "License");
.\" you may not use this file except in compliance with the License.
.\" You may obtain a copy of the License at
.\"
.\" http://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS,
.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.\" See the License for the specific language governing permissions and
.\" limitations under the License.
.TH "tldr\-man" 1
.SH "NAME"
tldr\-man \- display simple help pages for command\-line tools from the tldr\-pages project as manpages
.SH "SYNOPSIS"
.SY tldr
.RB [ \-L | \-\-language
.IR LANGUAGE ]
.RB [ \-p | \-\-platform
.IR PLATFORM ]
.IR PAGE ...
.SY tldr
.RB [ \-L | \-\-language
.IR LANGUAGE ]
.RB [ \-p | \-\-platform
.IR PLATFORM ]
.BR \-l | \-\-list
.SY tldr
.RB [ \-L | \-\-language
.IR LANGUAGE ]
.RB [ \-p | \-\-platform
.IR PLATFORM ]
.BR \-M | \-\-manpath
.SY tldr
.BR \-r | \-\-render
.IR FILE
.SY tldr
.BR \-u | \-\-update
.SY tldr
.BR \-v | \-\-version
.SY tldr
.BR \-h | \-\-help
.YS
.SH "DESCRIPTION"
.PP
.B tldr\-man
is a command\-line client for \f[B]tldr\-pages\f[R],
a collection of community\-maintained help pages for command\-line tools.
It differs from other clients because it displays its pages as
.BR man (1)
pages.
.PP
This client is able to integrate with the
.BR man (1)
command to fall back to displaying a tldr\-page for a command when no manpage exists.
.PP
The
.BR pandoc (1)
tool must be installed and present on
.B $PATH
for tldr\-man to function. Instructions for installing pandoc can be found at
.UR https://pandoc.org/installing.html
.UE .
.SH "OPTIONS"
.SS Arguments
.TP
.IR PAGE ...
The name of the tldr\-page to display.
.TP
.BR \-l ", " \-\-list
List all available tldr\-pages for the current platform and language with one page name per line.
.TP
.BR \-M ", " \-\-manpage
Prints a colon\-separated list of manpaths to be appended to
.BR $MANPATH .
See the
.B MAN INTEGRATION
section for more information.
.TP
.BR \-r " " \f[I]FILE\f[R] ", " \-\-render = \f[I]FILE\f[R]
Instead of displaying a page, render
.I FILE
(in the tldr\-pages markdown format) in the
.BR roff (7)
format and display it.
.TP
.BR \-u ", " \-\-update
Update the local cache of rendered
.BR 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.
.TP
.BR \-v ", " \-\-version
Print this command\[aq]s version and exit.
.TP
.BR \-h ", " \-\-help
Print this command\[aq]s help and exit.
.SS General Options
.TP
.BR \-L " " \f[I]LANGUAGE\f[R] ", " \-\-language = \f[I]LANGUAGE\f[R]
Set the language to display. Overrides any languages specified by environment variables.
.I LANGUAGE
must be a country code, such as
.BR en ", " es ", " fr ", " zh ", or " zh_TW .
.TP
.BR \-p " " \f[I]PLATFORM\f[R] ", " \-\-platform = \f[I]PLATFORM\f[R]
Set the platform to display.
.I PLATFORM
must be one of
.BR android ", " linux ", " macos ", " osx ", " sunos ", and " windows .
.SH "EXIT STATUS"
.PP
If tldr\-man completes successfully, it will return exit code \f[B]0\f[R].
Nonzero exit codes have the following meanings:
.TP
.B 1
General error
.TP
.B 2
Invalid usage
.TP
.B 3
Page cache does not exist
.TP
.B 127
The external commands
.BR man (1)
or
.BR pandoc (1)
were not found on
.B $PATH
.SH "ENVIRONMENT"
.TP
.BR TLDR_LANGUAGE ", " LANGUAGE ", " LANG
If the
.RB [ \-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,
.B en:fr:zh_TW
is a valid value for each of these variables.
The order of priority is
.BR TLDR_LANGUAGE ", " LANGUAGE ", " LANG ,
with the values of
.B TLDR_LANGUAGE
being checked first and
.B 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
.BR en .
.TP
.BR TLDR_MAN_ARCHIVE_URL
The URL to download pages from when running the
.B tldr \-\-update
command. If this variable is not set, the default
.UR https://tldr.sh/assets/tldr.zip
official archive URL
.UE
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.
.TP
.BR TLDR_MAN_CACHE_DIR
The location of the page cache directory. This directory is created by the
.B 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
.BR $XDG_CACHE_HOME/tldr-man .
.TP
.BR TLDR_MAN_NO_COLOR ", " NO_COLOR
When present and not an empty string (regardless of its value), prevents the usage of ANSI color.
.SH "FILES"
.TP
.BR $XDG_CACHE_HOME/tldr_man
The location that the tldr\-pages (in
.BR roff (7)
format) are stored if the environment variable
.B $TLDR_MAN_CACHE_DIR
is not set or not an absolute path.
This directory is created by running the
.B tldr \-\-update
.R command, and the cache is accessed by
.B tldr
.IR PAGE ,
.BR "tldr \-\-list" ", and"
.BR "tldr \-\-manpath" " commands."
.SH "CONFORMING TO"
.PP
.UR https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md
TLDR\-Pages Client Specification
.UE .
.PP
.UR https://standards.freedesktop.org/basedir-spec/basedir-spec-latest
XDG Base Directory Specification
.UE .
.PP
.UR https://no-color.org/
NO_COLOR
.UE .
.SH "EXAMPLES"
.PP
Display the tldr\-page for
.BR git (1):
.PP
.nf
.RS
.B tldr \f[I]git\f[B]
.RE
.fi
.PP
Update the local page cache:
.PP
.nf
.RS
.B tldr \-\-update
.RE
.fi
.PP
Render a page locally:
.PP
.nf
.RS
.B tldr \-\-render \f[I]path/to/page.md\f[B]
.RE
.fi
.PP
Print manpage paths as a colon\-separated list:
.PP
.nf
.RS
.B tldr \-\-manpath
.RE
.fi
.SH "SHELL COMPLETION"
The file
.B generate_completion.sh
that is distributed along with this software can be used to generate shell completions for tldr\-man.
.SH "MAN INTEGRATION"
.PP
The
.BR man (1)
command can be set up to fall back to displaying tldr\-pages if no manpages are found.
.PP
For
.BR bash (1)
place the following line in
.BR ~/.bash_profile ,
and for
.BR zsh (1)
place the following line in
.BR ~/.zshenv :
.PP
.nf
.RS
export MANPATH=\[dq]${MANPATH}:$(tldr \-\-manpath)\[dq]
.RE
.fi
.PP
For
.BR fish (1),
place the following line in
.BR $XDG_CONFIG_HOME/fish/config.fish :
.PP
.nf
.RS
set \-gxa MANPATH (tldr \-\-manpath)
.RE
.fi
.SH "HOMEPAGE"
.PP
This software is available at
.UR https://github.com/superatomic/tldr-man
.UE ,
and can be found on PyPI at
.UR https://pypi.org/project/tldr-man
.UE .
.SH "REPORTING BUGS"
.PP
Please report bugs and feature requests in the issue tracker at
.UR https://github.com/superatomic/tldr-man
.UE .
Please do your best to provide a reproducible test case for bugs.
.SH "COPYRIGHT"
Copyright 2023 Olivia Kinnear
.br
Licensed under the Apache License, Version 2.0
.SH "SEE ALSO"
.BR man (1),
.BR pandoc (1),
.BR man\-pages (7)
.SH "VERSION"
1.5.2