From f494fe73afbdad708e37b0e269a315be98d0e1f2 Mon Sep 17 00:00:00 2001 From: Ethan Kinnear <51250849+superatomic@users.noreply.github.com> Date: Mon, 24 Jul 2023 23:16:50 -0500 Subject: [PATCH] Add manpage for tldr-man --- pyproject.toml | 2 +- tldr-man.1 | 269 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 270 insertions(+), 1 deletion(-) create mode 100644 tldr-man.1 diff --git a/pyproject.toml b/pyproject.toml index 906cc4f..89f3dc8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,7 +27,7 @@ classifiers = [ 'Topic :: Text Processing :: Markup :: Markdown', 'Topic :: Utilities', ] -include = ["generate_completions.sh"] +include = ["generate_completions.sh", "tldr-man.1"] [tool.poetry.urls] "Bug Tracker" = "https://github.com/superatomic/tldr-man-client/issues" diff --git a/tldr-man.1 b/tldr-man.1 new file mode 100644 index 0000000..2afdac3 --- /dev/null +++ b/tldr-man.1 @@ -0,0 +1,269 @@ +.\" 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 . +.SH "FILES" +.TP +.BR $XDG_CACHE_HOME/tldr_man +The location that the tldr\-pages (in +.BR roff (7) +format) are stored. +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 . +.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-client +.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-client +.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.2.0