diff --git a/README.md b/README.md
index 0bf7add..43c1c81 100644
--- a/README.md
+++ b/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
## 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)
@@ -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+
diff --git a/package.json b/package.json
index 2808db4..7acc8fd 100644
--- a/package.json
+++ b/package.json
@@ -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",
diff --git a/tldr b/tldr
index 2a2a8e4..7934924 100755
--- a/tldr
+++ b/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$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$XB$DEF: Render a local$B$MAG file$DEF$XB as tldr markdown
- $B$YEL-m$DEF,$YEL --markdown$DEF$XB $CYA$B$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
diff --git a/tldr-customization.jpg b/tldr-customization.jpg
new file mode 100644
index 0000000..4f6a570
Binary files /dev/null and b/tldr-customization.jpg differ
diff --git a/tldr-usage.jpg b/tldr-usage.jpg
index 31a40e1..30e9b29 100644
Binary files a/tldr-usage.jpg and b/tldr-usage.jpg differ