Release version 0.3
- More extensive colour customization, also help - Use $XDG_DATA_HOME if it exists - Bug: display pagename on linting errors
This commit is contained in:
pepa65
parent
0cd34e48cf
commit
a08bd77bd0
40
README.md
40
README.md
|
|
@ -1,6 +1,6 @@
|
|||
# tldr-bash-client
|
||||
|
||||
* version 0.2
|
||||
* version 0.3
|
||||
* https://github.com/pepa65/tldr-bash-client
|
||||
|
||||
### Bash client for tldr: community driven man-by-example
|
||||
|
|
@ -22,7 +22,6 @@ sudo chmod +x $location
|
|||
```
|
||||
|
||||
If the location is not in $PATH, you need to specify the path to run it.
|
||||
|
||||
Alternately, you can do `sudo bpkg-install pepa65/tldr` if you have
|
||||
[bpkg](https://github.com/bpkg/bpkg) installed.
|
||||
|
||||
|
|
@ -35,18 +34,36 @@ coreutils, less, grep, unzip, curl / wget
|
|||
<img alt="tldr usage screenshot" src="tldr-usage.jpg" title="tldr usage" width="600" />
|
||||
|
||||
## Customisation
|
||||
The colors and other styling of the 5 elements of tldr pages can be modified
|
||||
either by editing the first few lines of the scipt, or by setting the following
|
||||
environment variables:
|
||||
|
||||
The 5 elements in TLDR markup that can be styled with these colors and
|
||||
backgrounds (last one specified will be used) and modes (more can apply):
|
||||
* Colors: Black, Red, Green, Yellow, Blue, Magenta, Cyan, White
|
||||
* BG: BlackBG, RedBG, GreenBG, YellowBG, BlueBG, MagentaBG, CyanBG, WhiteBG
|
||||
* Modes: Bold, Underline, Italic, Inverse
|
||||
'Newline' can be added to the style list to add a newline before the element
|
||||
and 'Space' to add a space at the start of the line
|
||||
(style items are separated by space, lower/uppercase mixed allowed)
|
||||
* TLDR_TITLE_STYLE (defaults to: Newline Space Bold Yellow)
|
||||
* TLDR_DESCRIPTION_STYLE (defaults to: Space Yellow)
|
||||
* TLDR_EXAMPLE_STYLE (defaults to: Newline Bold Green)
|
||||
* TLDR_EXAMPLE_STYLE (defaults to: Newline Space Bold Green)
|
||||
* TLDR_CODE_STYLE (defaults to: Space Bold Blue)
|
||||
* TLDR_VALUE_STYLE (defaults to: Bold Cyan)
|
||||
|
||||
Also the error color and page expiry can easily be set:
|
||||
* TLDR_ERROR_COLOR (defaults to: Red)
|
||||
* TLDR_VALUE_ISTYLE (defaults to: Space Bold Cyan)
|
||||
The Value style (above) is an Inline style: doesn't take Newline or Space
|
||||
Inline styles for help text: default, URL, option, platform, command, header
|
||||
* TLDR_DEFAULT_ISTYLE (defaults to: White)
|
||||
* TLDR_URL_ISTYLE (defaults to: Yellow)
|
||||
* TLDR_HEADER_ISTYLE (defaults to: Bold)
|
||||
* TLDR_OPTION_ISTYLE (defaults to: Bold Yellow)
|
||||
* TLDR_PLATFORM_ISTYLE (defaults to: Bold Blue)
|
||||
* TLDR_COMMAND_ISTYLE (defaults to: Bold Cyan)
|
||||
* TLDR_FILE_ISTYLE (defaults to: Bold Magenta)
|
||||
Color/BG (Newline and Space also allowed) for error and info messages
|
||||
* TLDR_ERROR_COLOR (defaults to: Newline Space Red)
|
||||
* TLDR_INFO_COLOR (defaults to: Newline Space Green)
|
||||
How many days before freshly downloading a potentially stale page
|
||||
* TLDR_EXPIRY (defaults to: 60)
|
||||
Alternative location of pages cache
|
||||
* TLDR_CACHE (not set by default)
|
||||
|
||||
<img alt="tldr customize screenshot" src="tldr-customize.jpg" title="tldr customize" width="600" />
|
||||
|
||||
|
|
@ -61,6 +78,7 @@ Or even better, send a pull request!
|
|||
|
||||
### License
|
||||
|
||||
Relicensed under GPL v3+
|
||||
Original client by Ray Lee http://github.com/raylee/tldr (MIT license)
|
||||
Re-licensed under GPL v3+
|
||||
|
||||
<img alt="tldr new markdown screenshot" src="tldr-markdown-new.jpg" title="tldr new markdown" width="600" />
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"name": "tldr-bash-client",
|
||||
"version": "0.2",
|
||||
"version": "0.3",
|
||||
"description": "Bash client for tldr: community driven man-by-example",
|
||||
"global": "true",
|
||||
"install": "make install",
|
||||
|
|
|
|||
133
tldr
133
tldr
|
|
@ -1,8 +1,8 @@
|
|||
#!/bin/bash
|
||||
set +vx -o pipefail
|
||||
[[ $- = *i* ]] && echo "Don't source this script!" && return 1
|
||||
version='0.2'
|
||||
# tldr-bash-client version 0.2
|
||||
version='0.3'
|
||||
# tldr-bash-client version 0.3
|
||||
# Bash client for tldr: community driven man-by-example
|
||||
# - forked from Ray Lee, http://github.com/raylee/tldr
|
||||
# - modified and expanded by pepa65: http://github.com/pepa65/tldr-bash-client
|
||||
|
|
@ -14,53 +14,69 @@ version='0.2'
|
|||
# BG: BlackBG, RedBG, GreenBG, YellowBG, BlueBG, MagentaBG, CyanBG, WhiteBG
|
||||
# Modes: Bold, Underline, Italic, Inverse
|
||||
# 'Newline' can be added to the style list to add a newline before the element
|
||||
# and 'Space' to add a space at the start of the line (not for Value element)
|
||||
# (The style items are separated by space, lower or uppercase mixed allowed.)
|
||||
# and 'Space' to add a space at the start of the line
|
||||
# (style items are separated by space, lower/uppercase mixed allowed)
|
||||
: "${TLDR_TITLE_STYLE:= Newline Space Bold Yellow }"
|
||||
: "${TLDR_DESCRIPTION_STYLE:= Space Yellow }"
|
||||
: "${TLDR_EXAMPLE_STYLE:= Newline Space Bold Green }"
|
||||
: "${TLDR_CODE_STYLE:= Space Bold Blue }"
|
||||
: "${TLDR_VALUE_STYLE:= Space Bold Cyan }"
|
||||
# Color and/or background (Newline and Space also allowed) for error messages
|
||||
: "${TLDR_VALUE_ISTYLE:= Space Bold Cyan }"
|
||||
# The Value style (above) is an Inline style: doesn't take Newline or Space
|
||||
# Inline styles for help text: default, URL, option, platform, command, header
|
||||
: "${TLDR_DEFAULT_ISTYLE:= White }"
|
||||
: "${TLDR_URL_ISTYLE:= Yellow }"
|
||||
: "${TLDR_HEADER_ISTYLE:= Bold }"
|
||||
: "${TLDR_OPTION_ISTYLE:= Bold Yellow }"
|
||||
: "${TLDR_PLATFORM_ISTYLE:= Bold Blue }"
|
||||
: "${TLDR_COMMAND_ISTYLE:= Bold Cyan }"
|
||||
: "${TLDR_FILE_ISTYLE:= Bold Magenta }"
|
||||
# Color/BG (Newline and Space also allowed) for error and info messages
|
||||
: "${TLDR_ERROR_COLOR:= Newline Space Red }"
|
||||
: "${TLDR_INFO_COLOR:= Newline Space Green }"
|
||||
|
||||
# How long before an attempt will be made to re-download a page
|
||||
# How many days before freshly downloading a potentially stale page
|
||||
: "${TLDR_EXPIRY:= 60 }"
|
||||
|
||||
# Alternative location of pages cache
|
||||
: "${TLDR_CACHE:= }"
|
||||
|
||||
# $1: [optional] exit code; Uses: version cachedir
|
||||
Usage(){
|
||||
Out "$(cat <<-EOF
|
||||
$version
|
||||
$HHE $version
|
||||
|
||||
USAGE: $GRE$B$(basename "$0")$XB$DEF [$YEL${B}option$XB$DEF] [$BLU${B}platform$XB/$DEF]$CYA$B<command>$XB$DEF
|
||||
$HDE USAGE: $HHE$(basename "$0")$XHHE [${HOP}option$XHOP] [${HPL}platform$XHPL/]${HCO}command$XHCO
|
||||
|
||||
$BLU$B platform$XB/$CYA${B}command$XB$DEF: Show page for$CYA$B command$XB$DEF (from$BLU$B platform$XB$DEF)
|
||||
$HDE [${HPL}platform$XHPL/]${HCO}command$XHCO: Show page for$HCO command$XHCO (from$HPL platform$XHPL)
|
||||
|
||||
$BLU$B platform$XB$DEF is optionally one of:$YEL common$DEF,$YEL linux$DEF,$YEL osx$DEF,$YEL sunos$DEF
|
||||
$HPL platform$XHPL is optionally one of:$HPL common$XHPL,$HPL linux$XHPL,$HPL osx$XHPL,$HPL sunos$XHPL
|
||||
|
||||
$YEL$B option$XB$DEF is optionally one of:
|
||||
$B$YEL-l$DEF,$YEL --list$DEF $BLU[platform]$DEF$XB: Show all available pages (from$BLU$B platform$XB$DEF)
|
||||
$B$YEL-r$DEF,$YEL --render$DEF$XB $MAG$B<file>$XB$DEF: Render a local$B$MAG file$DEF$XB as tldr markdown
|
||||
$B$YEL-m$DEF,$YEL --markdown$DEF$XB $CYA$B<command>$XB$DEF: Show the markdown source for$B$CYA command$DEF$XB
|
||||
$B$YEL-c$DEF,$YEL --cache$DEF$XB: Cache all pages by downloading archive from repo
|
||||
$B$YEL-u$DEF,$YEL --update$DEF$XB: Re-download index file from repo
|
||||
$B$YEL-v$DEF,$YEL --version$DEF$XB: Version number and repo location
|
||||
[$B$YEL-h$DEF,$YEL -?$DEF,$YEL --help$DEF$XB]: This help overview
|
||||
$HOP option$XHOP is optionally one of:
|
||||
$HOP-l$XHOP,$HOP --list$XHOP [${HPL}platform$XHPL]: Show all available pages (from$HPL platform$XHPL)
|
||||
$HOP-r$XHOP,$HOP --render$XHOP ${HFI}file$XHFI: Render a local$HFI file$XHFI as tldr markdown
|
||||
$HOP-m$XHOP,$HOP --markdown$XHOP ${HCO}command$XHCO: Show the markdown source for$HCO command$XHCO
|
||||
$HOP-c$XHOP,$HOP --cache$XHOP: Cache all pages by downloading archive from repo
|
||||
$HOP-u$XHOP,$HOP --update$XHOP: Re-download index file from repo
|
||||
$HOP-v$XHOP,$HOP --version$XHOP: Version number and repo location
|
||||
$HDE[$HOP-h$XHOP,$HOP -?$XHOP,$HOP --help$XHOP]: This help overview
|
||||
|
||||
Element styling:$T Title$XT$D Description$XD$E Example$XD$C Code$XC$V Value$XV
|
||||
All pages and the index are cached locally under $YEL$cachedir$DEF.
|
||||
By default, the cached copies will be re-downloaded after $YEL${TLDR_EXPIRY// /}$DEF days.
|
||||
$HDE Element styling:$XHDE$T Title$XT$D Description$XD$E Example$XD$C Code$XC$V Value$XV
|
||||
$HDE All pages and the index are cached locally under $HUR$cachedir$XHUR.
|
||||
$HDE By default, the cached copies will be freshly downloaded after $HUR${TLDR_EXPIRY// /}$XHUR days.
|
||||
EOF
|
||||
)"
|
||||
exit "${1:-0}"
|
||||
}
|
||||
|
||||
# $1: keep error messages; Uses/Sets: stderr
|
||||
Err(){ stderr+=$ERRNL$ERRSP$ERR$B$1$XB$XERR$N;}
|
||||
|
||||
# $1: keep output; Uses/Sets: stdout
|
||||
Out(){ stdout+=$1$N;}
|
||||
|
||||
# $1: keep error messages
|
||||
Err(){ Out "$ERRNL$ERRSP$ERR$B$1$XB$XERR";}
|
||||
|
||||
# $1: keep info messages
|
||||
Inf(){ Out "$INFNL$INFSP$INF$B$1$XB$XINF";}
|
||||
|
||||
# $1: Style specification; Uses: color xcolor bg xbg mode xmode
|
||||
Style(){
|
||||
local -l style
|
||||
|
|
@ -131,10 +147,27 @@ Init_term(){
|
|||
E=$STYLES XE=$XSTYLES ENL=$NL ESP=$SP
|
||||
Style "$TLDR_CODE_STYLE"
|
||||
C=$STYLES XC=$XSTYLES CNL=$NL CSP=$SP
|
||||
Style "$TLDR_VALUE_STYLE"
|
||||
Style "$TLDR_VALUE_ISTYLE"
|
||||
V=$STYLES XV=$XSTYLES
|
||||
Style "$TLDR_DEFAULT_ISTYLE"
|
||||
HDE=$STYLES XHDE=$XSTYLES
|
||||
Style "$TLDR_URL_ISTYLE"
|
||||
URL=$STYLES XURL=$XSTYLES
|
||||
HUR=$XHDE$STYLES XHUR=$XSTYLES$HDE
|
||||
Style "$TLDR_OPTION_ISTYLE"
|
||||
HOP=$XHDE$STYLES XHOP=$XSTYLES$HDE
|
||||
Style "$TLDR_PLATFORM_ISTYLE"
|
||||
HPL=$XHDE$STYLES XHPL=$XSTYLES$HDE
|
||||
Style "$TLDR_COMMAND_ISTYLE"
|
||||
HCO=$XHDE$STYLES XHCO=$XSTYLES$HDE
|
||||
Style "$TLDR_FILE_ISTYLE"
|
||||
HFI=$XHDE$STYLES XHFI=$XSTYLES$HDE
|
||||
Style "$TLDR_HEADER_ISTYLE"
|
||||
HHE=$XHDE$STYLES XHHE=$XSTYLES$HDE
|
||||
Style "$TLDR_ERROR_COLOR"
|
||||
ERR=$COLOR XERR=$XCOLOR ERRNL=$NL ERRSP=$SP
|
||||
Style "$TLDR_INFO_COLOR"
|
||||
INF=$COLOR XINF=$XCOLOR INFNL=$NL INFSP=$SP
|
||||
}
|
||||
|
||||
# $1: page
|
||||
|
|
@ -142,25 +175,25 @@ Recent(){ find "$1" -mtime -"${TLDR_EXPIRY// /}" >/dev/null 2>&1;}
|
|||
|
||||
# Download index.json; Uses: index index_url base_url zip_url dl
|
||||
Update_index(){
|
||||
$dl "$index" "$index_url" && Out "${GRE}Index file $I$index$XI re-downloaded$DEF" || {
|
||||
$dl "$index" "$index_url" && Inf "Index file $I$index$XI freshly downloaded" || {
|
||||
Err "Could not download index from $I$index_url$XI"
|
||||
exit 2
|
||||
}
|
||||
}
|
||||
|
||||
# Initialize globals, check the environment; Uses: config cachedir version
|
||||
# Sets: stdout stderr os version dl
|
||||
# Sets: stdout os version dl
|
||||
Config(){
|
||||
os=common stdout='' stderr='' Q='"' N=$'\n'
|
||||
os=common stdout='' Q='"' N=$'\n'
|
||||
case "$(uname -s)" in
|
||||
Darwin) os='osx' ;;
|
||||
Linux) os='linux' ;;
|
||||
SunOS) os='sunos' ;;
|
||||
esac
|
||||
Init_term
|
||||
trap 'less -~RXQFP"Press Q to exit " <<<"$stdout$stderr"' EXIT
|
||||
trap 'less -~RXQFP"Browse up/down, press Q to exit " <<<"$stdout"' EXIT
|
||||
|
||||
version="$GRE$B tldr-bash-client version $version$XB $YEL http://github.com/pepa65/tldr-bash-client$DEF"
|
||||
version="tldr-bash-client version $version $XB$URL http://github.com/pepa65/tldr-bash-client$XURL"
|
||||
|
||||
# Select download method
|
||||
dl="$(type -p curl) -sfo" || {
|
||||
|
|
@ -174,8 +207,15 @@ Config(){
|
|||
zip_url='http://tldr-pages.github.io/assets/tldr.zip'
|
||||
index_url='http://tldr-pages.github.io/assets/index.json'
|
||||
|
||||
[[ -d ~/.config ]] && cachedir=~/.config/tldr || cachedir=~/.tldr
|
||||
[[ -d "$cachedir" ]] || mkdir -p "$cachedir"
|
||||
read cachedir <<<$TLDR_CACHE
|
||||
[[ $cachedir ]] || {
|
||||
[[ $XDG_DATA_HOME ]] && cachedir=$XDG_DATA_HOME/tldr \
|
||||
|| cachedir=$HOME/.local/share/tldr
|
||||
}
|
||||
[[ -d "$cachedir" ]] || mkdir -p "$cachedir" || {
|
||||
Err "Can't create the pages cache location $cachedir"
|
||||
exit 4
|
||||
}
|
||||
index=$cachedir/index.json
|
||||
# update if the file doesn't exists, or if it's older than $TLDR_EXPIRY
|
||||
[[ -f $index ]] && Recent "$index" || Update_index
|
||||
|
|
@ -183,7 +223,7 @@ Config(){
|
|||
|
||||
# $1: error message; Uses: md line ln
|
||||
Unlinted(){
|
||||
Err "Page $I$md$XI not properly linted!\nLine $I$ln$XI:[$U$line$XU]$N$ERR$B$1"
|
||||
Err "Page $I$md$XI not properly linted!$N${ERRSP}${ERR}Line $I$ln$XI [$XERR$U$line$XU$ERR]$N$ERRSP$ERR$1"
|
||||
exit 4
|
||||
}
|
||||
|
||||
|
|
@ -217,7 +257,7 @@ Get_tldr(){
|
|||
}
|
||||
# if still no page found, get the first entry in index
|
||||
[[ $md ]] || md=$(cut -d "$Q" -f 8 <<<"$desc")/"$1.md"
|
||||
((err)) && Err "tldr page $I$1$XI not found in $notfound, page from platform $U${md%/*}$XU instead"
|
||||
((err)) && Err "tldr page $I$1$XI not found in $notfound, from platform $U${md%/*}$XU instead"
|
||||
|
||||
# return the local cached copy of the tldrpage, or retrieve and cache from github
|
||||
cached=$cachedir/$md
|
||||
|
|
@ -227,10 +267,11 @@ Get_tldr(){
|
|||
}
|
||||
}
|
||||
|
||||
# Uses: page stdout stderr; Sets: ln line
|
||||
# $1: text; Uses: page stdout; Sets: ln line
|
||||
Display_tldr(){
|
||||
local newfmt len val
|
||||
ln=0 line=''
|
||||
[[ $md ]] || md=$1
|
||||
# Read full lines, and process even when no newline at the end
|
||||
while read -r line || [[ $line ]]
|
||||
do
|
||||
|
|
@ -282,15 +323,15 @@ Display_tldr(){
|
|||
[[ -z $line ]] && Unlinted "No example content"
|
||||
Out "$ENL$EPS$E$line$XE" ;;
|
||||
esac
|
||||
done
|
||||
trap 'less +Gg -~RXQFP"%pB\% tldr $I$page$XI - press Q to exit" <<<"$stdout$stderr"' EXIT
|
||||
done <"$1"
|
||||
trap 'less +Gg -~RXQFP"%pB\% tldr $I$page$XI - browse up/down, press Q to exit" <<<"$stdout"' EXIT
|
||||
}
|
||||
|
||||
# $1: exit code; Uses: platform index
|
||||
List_pages(){
|
||||
local platformtext c1 c2 c3
|
||||
[[ $platform ]] && platformtext=" from platform $I$platform$XI"
|
||||
Out "${GRE}Known tldr pages$platformtext:"
|
||||
Inf "Known tldr pages$platformtext:"
|
||||
Out "$(while read -r c1 c2 c3; do printf "%-19s %-19s %-19s %-19s$N" $c1 $c2 $c3; done \
|
||||
<<<$(tr '{' '\n' <$index |grep "$platform" |cut -d "$Q" -f4))"
|
||||
exit "$1"
|
||||
|
|
@ -314,7 +355,7 @@ Cache_fill(){
|
|||
rm -rf -- "${cachedir:?}/"*
|
||||
mv -- "$tmp/pages/"* "${cachedir:?}/"
|
||||
rm -rf -- "$tmp"
|
||||
Out "${GRE}Pages cached in $U$cachedir$XU$DEF"
|
||||
Inf "Pages cached in $U$cachedir$XU"
|
||||
exit "$1"
|
||||
}
|
||||
|
||||
|
|
@ -336,7 +377,7 @@ Main(){
|
|||
-c|--cache) [[ $2 ]] && Err "No more command line arguments allowed" && err=10
|
||||
Cache_fill "$err" ;;
|
||||
-v|--version) [[ $2 ]] && Err "No more command line arguments allowed" && err=11
|
||||
Out "$version"
|
||||
Inf "$version"
|
||||
exit "$err" ;;
|
||||
-u|--update) [[ $2 ]] && Err "No more command line arguments allowed" && err=12
|
||||
Update_index
|
||||
|
|
@ -344,7 +385,7 @@ Main(){
|
|||
-r|--render) [[ -z $2 ]] && Err "Specify a file to render" && Usage 13
|
||||
[[ $3 ]] && Err "No more command line arguments allowed" && err=14
|
||||
[[ -f "$2" ]] && {
|
||||
Display_tldr <"$2" && exit "$err"
|
||||
Display_tldr "$2" && exit "$err"
|
||||
Err "A file error occured"
|
||||
exit 15
|
||||
} || Err "No file:$I $2$XI" && exit 16 ;;
|
||||
|
|
@ -368,11 +409,11 @@ Main(){
|
|||
}
|
||||
|
||||
Get_tldr "${page// /-}"
|
||||
[[ ! -s $cached ]] && Err "tldr page for command $I$page$XI not found" && exit 23
|
||||
|
||||
((markdown)) && Out "$(cat "$cached")" || Display_tldr <"$cached"
|
||||
[[ ! -s $cached ]] && Err "tldr page for command $I$page$XI not found" \
|
||||
&& Inf "Contribute new pages at:$XB$URL https://github.com/tldr-pages/tldr$XURL" && exit 23
|
||||
((markdown)) && Out "$(cat "$cached")" || Display_tldr "$cached"
|
||||
}
|
||||
|
||||
Main "$@"
|
||||
# The error trap will output the accumulated stdout and stderr
|
||||
# The error trap will output the accumulated stdout
|
||||
exit 0
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 79 KiB |
BIN
tldr-usage.jpg
BIN
tldr-usage.jpg
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 65 KiB |
Loading…
Reference in New Issue