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 tldr usage screenshot ## 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) tldr customize screenshot @@ -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+ tldr new markdown screenshot 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