ceos/tealdeer
1
0
Fork 0
mirror of https://github.com/tealdeer-rs/tealdeer.git synced 2026-08-24 17:14:18 +02:00
Code Issues Projects Releases Packages Wiki Activity
tealdeer/print.html
dbrgn 17d3d394d9 deploy: 7c371a6852
2022-10-24 13:02:14 +00:00

501 lines
25 KiB
HTML
Raw Blame History

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Tealdeer User Manual</title>
<meta name="robots" content="noindex" />
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded affix "><a href="intro.html">Introduction</a></li><li class="chapter-item expanded "><a href="installing.html"><strong aria-hidden="true">1.</strong> Installing</a></li><li class="chapter-item expanded "><a href="usage.html"><strong aria-hidden="true">2.</strong> Usage</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage_custom_pages.html"><strong aria-hidden="true">2.1.</strong> Custom Pages and Patches</a></li></ol></li><li class="chapter-item expanded "><a href="config.html"><strong aria-hidden="true">3.</strong> Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="config_display.html"><strong aria-hidden="true">3.1.</strong> Section: [display]</a></li><li class="chapter-item expanded "><a href="config_style.html"><strong aria-hidden="true">3.2.</strong> Section: [style]</a></li><li class="chapter-item expanded "><a href="config_updates.html"><strong aria-hidden="true">3.3.</strong> Section: [updates]</a></li><li class="chapter-item expanded "><a href="config_directories.html"><strong aria-hidden="true">3.4.</strong> Section: [directories]</a></li></ol></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Tealdeer User Manual</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1><a class="header" href="#tealdeer-introduction" id="tealdeer-introduction">Tealdeer: Introduction</a></h1>
<p>Tealdeer is a very fast implementation of
<a href="https://github.com/tldr-pages/tldr">tldr</a> in Rust: Simplified, example based
and community-driven man pages.</p>
<p><img src="screenshot-default.png" alt="Screenshot" /></p>
<p>This documentation shows how to install, use and configure Tealdeer.</p>
<h2><a class="header" href="#links" id="links">Links</a></h2>
<ul>
<li><a href="https://github.com/dbrgn/tealdeer">GitHub Project Page</a></li>
<li><a href="https://tldr.sh/">TLDR Pages Project</a></li>
</ul>
<h1><a class="header" href="#installing" id="installing">Installing</a></h1>
<p>There are a few different ways to install Tealdeer:</p>
<ul>
<li>Through <a href="installing.html#package-managers">package managers</a></li>
<li>Through <a href="installing.html#static-binaries-linux">static binaries</a></li>
<li>Through <a href="installing.html#through-cargo-install">cargo install</a></li>
<li>By <a href="installing.html#build-from-source">building from source</a></li>
</ul>
<p>Additionally, when not using system packages, you can <a href="installing.html#autocompletion">manually install
autocompletions</a>.</p>
<h2><a class="header" href="#package-managers" id="package-managers">Package Managers</a></h2>
<p>Tealdeer has been added to a few package managers:</p>
<ul>
<li>Arch Linux: <a href="https://archlinux.org/packages/community/x86_64/tealdeer/"><code>tealdeer</code></a></li>
<li>Fedora: <a href="https://src.fedoraproject.org/rpms/rust-tealdeer"><code>tealdeer</code></a></li>
<li>FreeBSD: <a href="https://www.freshports.org/sysutils/tealdeer/"><code>sysutils/tealdeer</code></a></li>
<li>Funtoo: <a href="https://github.com/funtoo/core-kit/tree/1.4-release/app-misc/tealdeer"><code>app-misc/tealdeer</code></a></li>
<li>Homebrew: <a href="https://formulae.brew.sh/formula/tealdeer"><code>tealdeer</code></a></li>
<li>MacPorts: <a href="https://ports.macports.org/port/tealdeer/"><code>tealdeer</code></a></li>
<li>NetBSD: <a href="https://pkgsrc.se/sysutils/tealdeer"><code>sysutils/tealdeer</code></a></li>
<li>Nix: <a href="https://nixos.org/nixos/packages.html#tealdeer"><code>tealdeer</code></a></li>
<li>openSUSE: <a href="https://software.opensuse.org/package/tealdeer?search_term=tealdeer"><code>tealdeer</code></a></li>
<li>Solus: <a href="https://packages.getsol.us/shannon/t/tealdeer/"><code>tealdeer</code></a></li>
<li>Void Linux: <a href="https://github.com/void-linux/void-packages/tree/master/srcpkgs/tealdeer"><code>tealdeer</code></a></li>
</ul>
<h2><a class="header" href="#static-binaries-linux" id="static-binaries-linux">Static Binaries (Linux)</a></h2>
<p>Static binary builds (currently for Linux only) are available on the
<a href="https://github.com/dbrgn/tealdeer/releases">GitHub releases page</a>.
Simply download the binary for your platform and run it!</p>
<h2><a class="header" href="#through-cargo-install" id="through-cargo-install">Through <code>cargo install</code></a></h2>
<p>Build and install the tool via cargo...</p>
<pre><code>$ cargo install tealdeer
</code></pre>
<p><em>(Note: You might need to install OpenSSL development headers, otherwise you get
a &quot;failed to run custom build command for openssl-sys&quot; error message. The
package is called <code>libssl-dev</code> on Ubuntu.)</em></p>
<h2><a class="header" href="#build-from-source" id="build-from-source">Build From Source</a></h2>
<p>Debug build with logging enabled:</p>
<pre><code>$ cargo build --features logging
</code></pre>
<p>Release build without logging:</p>
<pre><code>$ cargo build --release
</code></pre>
<p>To enable the log output, set the <code>RUST_LOG</code> env variable:</p>
<pre><code>$ export RUST_LOG=tldr=debug
</code></pre>
<h2><a class="header" href="#autocompletion" id="autocompletion">Autocompletion</a></h2>
<p>Shell completion scripts are located in the folder <code>completion</code>.
Just copy them to their designated location:</p>
<ul>
<li><em>Bash</em>: <code>cp completion/bash_tealdeer /usr/share/bash-completion/completions/tldr</code></li>
<li><em>Fish</em>: <code>cp completion/fish_tealdeer ~/.config/fish/completions/tldr.fish</code></li>
<li><em>Zsh</em>: <code>cp completion/zsh_tealdeer /usr/share/zsh/site-functions/_tldr</code></li>
</ul>
<h1><a class="header" href="#usage" id="usage">Usage</a></h1>
<p>Tealdeer is straightforward to use, through the binary named <code>tldr</code>.</p>
<p>You can view the available options using <code>tldr --help</code>:</p>
<!-- Note: To update the file below, run `cargo run -- --help > docs/src/usage.txt`. -->
<pre><code>tealdeer 1.6.1
Danilo Bargen &lt;mail@dbrgn.ch&gt;, Niklas Mohrin &lt;dev@niklasmohrin.de&gt;
A fast TLDR client
USAGE:
tldr [OPTIONS] [COMMAND]...
ARGS:
&lt;COMMAND&gt;... The command to show (e.g. `tar` or `git log`)
OPTIONS:
-l, --list List all commands in the cache
-f, --render &lt;FILE&gt; Render a specific markdown file
-p, --platform &lt;PLATFORM&gt; Override the operating system [possible values: linux, macos,
windows, sunos, osx, android]
-L, --language &lt;LANGUAGE&gt; Override the language
-u, --update Update the local cache
--no-auto-update If auto update is configured, disable it for this run
-c, --clear-cache Clear the local cache
--pager Use a pager to page output
-r, --raw Display the raw markdown instead of rendering it
-q, --quiet Suppress informational messages
--show-paths Show file and directory paths used by tealdeer
--seed-config Create a basic config
--color &lt;WHEN&gt; Control whether to use color [possible values: always, auto, never]
-v, --version Print the version
-h, --help Print help information
To view the user documentation, please visit https://dbrgn.github.io/tealdeer/.
</code></pre>
<h1><a class="header" href="#custom-pages-and-patches" id="custom-pages-and-patches">Custom Pages and Patches</a></h1>
<p>Tealdeer allows creating new custom pages, overriding existing pages as well as
extending existing pages.</p>
<p>The directory, where these custom pages and patches can be placed, follows OS
conventions. On Linux for instance, the default location is
<code>~/.local/share/tealdeer/pages/</code>. To print the path used on your system, simply
run <code>tldr --show-paths</code>.</p>
<p>The custom pages directory can be <a href="config_directories.html">overridden by the config
file</a>.</p>
<h2><a class="header" href="#custom-pages" id="custom-pages">Custom Pages</a></h2>
<p>To document internal command line tools, or if you want to replace an existing
tldr page with one that's better suited for you, place a file with the name
<code>&lt;command&gt;.page</code> in the custom pages directory. When calling <code>tldr &lt;command&gt;</code>,
your custom page will be shown instead of the upstream version in the cache.</p>
<p>Path:</p>
<pre><code>$CUSTOM_PAGES_DIR/&lt;command&gt;.page
</code></pre>
<p>Example:</p>
<pre><code>~/.local/share/tealdeer/pages/ufw.page
</code></pre>
<h2><a class="header" href="#custom-patches" id="custom-patches">Custom Patches</a></h2>
<p>Sometimes you don't want to fully replace an existing upstream page, but just
want to extend it with your own examples that you frequently need. In this
case, use a file called <code>&lt;command&gt;.patch</code>, it will be appended to existing
pages.</p>
<p>Path:</p>
<pre><code>$CUSTOM_PAGES_DIR/&lt;command&gt;.patch
</code></pre>
<p>Example:</p>
<pre><code>~/.local/share/tealdeer/pages/ufw.patch
</code></pre>
<h1><a class="header" href="#configuration" id="configuration">Configuration</a></h1>
<p>Tealdeer can be customized with a config file in <a href="https://toml.io/">TOML
format</a> called <code>config.toml</code>.</p>
<h2><a class="header" href="#configfile-path" id="configfile-path">Configfile Path</a></h2>
<p>The configuration file path follows OS conventions (e.g.
<code>$XDG_CONFIG_HOME/tealdeer/config.toml</code> on Linux). The paths can be queried
with the following command:</p>
<pre><code>$ tldr --show-paths
</code></pre>
<p>Creating the config file can be done manually or with the help of <code>tldr</code>:</p>
<pre><code>$ tldr --seed-config
</code></pre>
<p>On Linux, this will usually be <code>~/.config/tealdeer/config.toml</code>.</p>
<h2><a class="header" href="#config-example" id="config-example">Config Example</a></h2>
<p>Here's an example configuration file. Note that this example does not contain
all possible config options. For details on the things that can be configured,
please refer to the subsections of this documentation page
(<a href="config_display.html">display</a>, <a href="config_style.html">style</a>,
<a href="config_updates.html">updates</a> or <a href="config_directories.html">directories</a>).</p>
<pre><code class="language-toml">[display]
compact = false
use_pager = true
[style.command_name]
foreground = &quot;red&quot;
[style.example_text]
foreground = &quot;green&quot;
[style.example_code]
foreground = &quot;blue&quot;
[style.example_variable]
foreground = &quot;blue&quot;
underline = true
[updates]
auto_update = true
</code></pre>
<h2><a class="header" href="#override-config-directory" id="override-config-directory">Override Config Directory</a></h2>
<p>The directory where the configuration file resides may be overwritten by the
environment variable <code>TEALDEER_CONFIG_DIR</code>. Remember to use an absolute path.
Variable expansion will not be performed on the path.</p>
<h2><a class="header" href="#override-cache-directory" id="override-cache-directory">Override Cache Directory</a></h2>
<p>Similarly, the cache directory where the pages are downloaded to, also follows
OS conventions. On Linux, it will usually be at <code>~/.cache/tealdeer/</code>. The path
can be overwritten using the environment variable <code>TEALDEER_CACHE_DIR</code>.
Remember to use an absolute path. Variable expansion will not be performed on
the path.</p>
<h1><a class="header" href="#section-display" id="section-display">Section: [display]</a></h1>
<p>In the <code>display</code> section you can configure the output format.</p>
<h2><a class="header" href="#use_pager" id="use_pager"><code>use_pager</code></a></h2>
<p>Specifies whether the pager should be used by default or not (default <code>false</code>).</p>
<pre><code>[display]
use_pager = true
</code></pre>
<p>When enabled, <code>less -R</code> is used as pager. To override the pager command used,
set the <code>PAGER</code> environment variable.</p>
<p>NOTE: This feature is not available on Windows.</p>
<h2><a class="header" href="#compact" id="compact"><code>compact</code></a></h2>
<p>Set this to enforce more compact output, where empty lines are stripped out
(default <code>false</code>).</p>
<pre><code>[display]
compact = true
</code></pre>
<h1><a class="header" href="#section-style" id="section-style">Section: [style]</a></h1>
<p>Using the config file, the style (e.g. colors or underlines) can be customized.</p>
<img src="screenshot-custom.png" alt="Screenshot of customized version" width="600">
<h2><a class="header" href="#style-targets" id="style-targets">Style Targets</a></h2>
<ul>
<li><code>description</code>: The initial description text</li>
<li><code>command_name</code>: The command name as part of the example code</li>
<li><code>example_text</code>: The text that describes an example</li>
<li><code>example_code</code>: The example itself (except the <code>command_name</code> and <code>example_variable</code>)</li>
<li><code>example_variable</code>: The variables in the example</li>
</ul>
<h2><a class="header" href="#attributes" id="attributes">Attributes</a></h2>
<ul>
<li><code>foreground</code> (color string, ANSI code, or RGB, see below)</li>
<li><code>background</code> (color string, ANSI code, or RGB, see below)</li>
<li><code>underline</code> (<code>true</code> or <code>false</code>)</li>
<li><code>bold</code> (<code>true</code> or <code>false</code>)</li>
<li><code>italic</code> (<code>true</code> or <code>false</code>)</li>
</ul>
<p>Colors can be specified in one of three ways:</p>
<ul>
<li>
<p>Color string (<code>black</code>, <code>red</code>, <code>green</code>, <code>yellow</code>, <code>blue</code>, <code>magenta</code>, <code>cyan</code>, <code>white</code>):</p>
<p>Example:</p>
<pre><code>foreground = &quot;green&quot;
</code></pre>
</li>
<li>
<p>256 color ANSI code (<em>Tealdeer v1.5.0+</em>)</p>
<p>Example:</p>
<pre><code>foreground = { ansi = 4 }
</code></pre>
</li>
<li>
<p>24-bit RGB color (<em>Tealdeer v1.5.0+</em>)</p>
<p>Example:</p>
<pre><code>background = { rgb = { r = 255, g = 255, b = 255 } }
</code></pre>
</li>
</ul>
<h1><a class="header" href="#section-updates" id="section-updates">Section: [updates]</a></h1>
<h2><a class="header" href="#automatic-updates" id="automatic-updates">Automatic updates</a></h2>
<p>tealdeer can refresh the cache automatically when it is outdated. This
behavior can be configured in the <code>updates</code> section and is disabled by
default.</p>
<h3><a class="header" href="#auto_update" id="auto_update"><code>auto_update</code></a></h3>
<p>Specifies whether the auto-update feature should be enabled (defaults to
<code>false</code>).</p>
<pre><code>[updates]
auto_update = true
</code></pre>
<h3><a class="header" href="#auto_update_interval_hours" id="auto_update_interval_hours"><code>auto_update_interval_hours</code></a></h3>
<p>Duration, since the last cache update, after which the cache will be
refreshed (defaults to 720 hours). This parameter is ignored if <code>auto_update</code>
is set to <code>false</code>.</p>
<pre><code>[updates]
auto_update = true
auto_update_interval_hours = 24
</code></pre>
<h1><a class="header" href="#section-directories" id="section-directories">Section: [directories]</a></h1>
<p>This section allows overriding some directory paths.</p>
<h2><a class="header" href="#cache_dir" id="cache_dir"><code>cache_dir</code></a></h2>
<p>Override the cache directory. Remember to use an absolute path. Variable
expansion will not be performed on the path. If the directory does not yet
exist, it will be created.</p>
<pre><code>[directories]
cache_dir = &quot;/home/myuser/.tealdeer-cache/&quot;
</code></pre>
<p>If no <code>cache_dir</code> is specified, tealdeer will fall back to a location that
follows OS conventions. On Linux, it will usually be at <code>~/.cache/tealdeer/</code>.
Use <code>tldr --show-paths</code> to show the path that is being used.</p>
<h2><a class="header" href="#custom_pages_dir" id="custom_pages_dir"><code>custom_pages_dir</code></a></h2>
<p>Set the directory to be used to look up <a href="usage_custom_pages.html">custom
pages</a>. Remember to use an absolute path. Variable
expansion will not be performed on the path.</p>
<pre><code>[directories]
custom_pages_dir = &quot;/home/myuser/custom-tldr-pages/&quot;
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</nav>
</div>
<script type="text/javascript">
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
<script type="text/javascript">
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
</script>
</body>
</html>
Reference in a new issue View git blame Copy permalink