feat: add support for placeholder escaping, prep for release, misc (#247)

* feat: add support for placeholder escaping, prep for release, misc

* docs: update CHANGELOG

* chore: update README screenshot

* docs: update README usage to align with actual usage (#248)

---------

Signed-off-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
Co-authored-by: Patrice Denis <patricedenis@users.noreply.github.com>

Author: kbdharun

.gitignore

@@ -70,7 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/man
+docs/man/.doctrees
 
 # PyBuilder
 .pybuilder/

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 3.3.0 (06/29/2023)
+
+## Breaking
+
+* Drop support for EOL versions Python 3.6 and Python 3.7.
+
+### Bugfixes
+
+* Return `str` instead of `list` when executing `tldr -l` (thanks [@uunnxx](https://github.com/uunnxx))
+* Use pathlib instead of os.path (thanks [@vitorhcl](https://github.com/vitorhcl))
+* Respect language settings when geting a list of commands (thanks [@frenzymadness](https://github.com/frenzymadness))
+* Fix `--search` option (thanks [@CleanMachine1](https://github.com/CleanMachine1))
+
+### Features
+
+* Add support for BSD platform directories (thanks [@vitorhcl](https://github.com/vitorhcl))
+* Add `--update` long option (thanks [@owenvoke](https://github.com/owenvoke))
+* Add support for fetching individual translation archives for cache (thanks [@SaurabhDRao](https://github.com/SaurabhDRao))
+* Add support to show message for other versions of the same page in other platforms (thanks [@Jaimepas77](https://github.com/Jaimepas77))
+* Update `DOWNLOAD_CACHE_LOCATION` to use GitHub Releases (thanks [@vitorhcl](https://github.com/vitorhcl))
+* Add `macos` alias for `osx` directory and update `--platform` option (thanks [@patricedenis](https://github.com/patricedenis))
+* Add support for escaping placeholders for special pages (thanks [@kbdharun](https://github.com/kbdharun))
+* Add support for Python 3.11 and Python 3.12 (thanks [@kbdharun](https://github.com/kbdharun))
+* Add support for [Client Specification v2.2](https://github.com/tldr-pages/tldr/releases/tag/v2.2)
+
 ## 3.2.0 (05/09/2023)
 
 ### Bugfixes

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Felix Yan
+Copyright (c) 2014 Felix Yan and 2014-present tldr-pages contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,10 +2,11 @@
 
 [![PyPI Release](https://img.shields.io/pypi/v/tldr.svg)](https://pypi.python.org/pypi/tldr)
 [![Build](https://github.com/tldr-pages/tldr-python-client/workflows/Test/badge.svg?branch=main)](https://github.com/tldr-pages/tldr-python-client/actions?query=branch%3Amain)
+[![Snap Release](https://snapcraft.io/tldr/badge.svg)](https://snapcraft.io/tldr)
 
 Python command-line client for [tldr pages](https://github.com/tldr-pages/tldr).
 
-![tldr pages example](https://raw.github.com/tldr-pages/tldr/main/images/tldr-dark.png)
+![Tldr Python client displaying the tar page](https://raw.github.com/tldr-pages/tldr-python-client/main/images/tldr-dark.png)
 
 ## Installation
 
@@ -42,7 +43,7 @@ sudo snap install tldr
 
 ## Usage
 
-```
+```txt
 usage: tldr command [options]
 
 Python command line client for tldr
@@ -57,7 +58,7 @@ options:
   -u, --update, --update_cache
                         Update the local cache of pages and exit
   -p PLATFORM, --platform PLATFORM
-                        Override the operating system [linux, osx, sunos, windows, common]
+                        Override the operating system [android, freebsd, linux, netbsd, openbsd, osx, sunos, windows, common]
   -l, --list            List all available commands for operating system
   -s SOURCE, --source SOURCE
                         Override the default page source
@@ -92,13 +93,14 @@ export TLDR_DOWNLOAD_CACHE_LOCATION="https://tldr-pages.github.io/assets/tldr.zi
 Cache is downloaded from `TLDR_DOWNLOAD_CACHE_LOCATION` (defaults to the one described in [the client specification](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md#caching)), unzipped and extracted into the [local cache directory](#cache-location). Pages are loaded directly from `TLDR_PAGES_SOURCE_LOCATION` if `tldr <command>` is used.
 
 - `TLDR_CACHE_ENABLED` (default is `1`):
-    - If set to `1`, the client will first try to load from cache, and fall back to fetching from the internet if the cache doesn't exist or is too old.
-    - If set to `0`, the client will fetch from the internet, and fall back to the cache if the page cannot be fetched from the internet.
+  - If set to `1`, the client will first try to load from cache, and fall back to fetching from the internet if the cache doesn't exist or is too old.
+  - If set to `0`, the client will fetch from the internet, and fall back to the cache if the page cannot be fetched from the internet.
 - `TLDR_CACHE_MAX_AGE` (default is `168` hours, which is equivalent to a week): maximum age of the cache in hours to be considered as valid when `TLDR_CACHE_ENABLED` is set to `1`.
 
 #### Cache location
 
 In order of precedence:
+
 - `$XDG_CACHE_HOME/tldr`
 - `$HOME/.cache/tldr`
 - `~/.cache/tldr`
@@ -130,7 +132,7 @@ an autocomplete for `tldr` for `fish`.
 
 For networks that sit behind a proxy, it may be necessary to disable SSL verification for the client to function. Setting the following:
 
-- `TLDR_ALLOW_INSECURE=1` 
+- `TLDR_ALLOW_INSECURE=1`
 
 will disable SSL certificate inspection. This __should be avoided__ unless absolutely necessary.
 

docs/conf.py

@@ -17,8 +17,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'tldr'
-copyright = '2014, Felix Yan'
-author = 'Felix Yan'
+copyright = '2014, Felix Yan and 2014-present, tldr-pages contributors'
+author = 'Felix Yan and tldr-pages contributors'
 from tldr import __version__  # noqa: E402
 release = __version__
 

docs/man/tldr.1

@@ -0,0 +1,105 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "TLDR" "1" "Jun 29, 2024" "" "tldr"
+.SH NAME
+tldr \- tldr 3.3.0
+.sp
+Python command line client for tldr
+
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+usage: tldr command [options]
+.EE
+.UNINDENT
+.UNINDENT
+.SH POSITIONAL ARGUMENTS
+.INDENT 0.0
+.TP
+.B command
+command to lookup
+.UNINDENT
+.SH NAMED ARGUMENTS
+.INDENT 0.0
+.TP
+.B \-v, \-\-version
+show program\(aqs version number and exit
+.TP
+.B \-\-search
+Search for a specific command from a query
+.TP
+.B \-u, \-\-update, \-\-update_cache
+Update the local cache of pages and exit
+.sp
+Default: False
+.TP
+.B \-p, \-\-platform
+Possible choices: android, freebsd, linux, netbsd, openbsd, osx, sunos, windows, common
+.sp
+Override the operating system [android, freebsd, linux, netbsd, openbsd, osx, sunos, windows, common]
+.TP
+.B \-l, \-\-list
+List all available commands for operating system
+.sp
+Default: False
+.TP
+.B \-s, \-\-source
+Override the default page source
+.sp
+Default: \(dq\X'tty: link https://raw.githubusercontent.com/tldr-pages/tldr/main/pages'\fI\%https://raw.githubusercontent.com/tldr\-pages/tldr/main/pages\fP\X'tty: link'\(dq
+.TP
+.B \-c, \-\-color
+Override color stripping
+.TP
+.B \-r, \-\-render
+Render local markdown files
+.sp
+Default: False
+.TP
+.B \-L, \-\-language
+Override the default language
+.TP
+.B \-m, \-\-markdown
+Just print the plain page file.
+.sp
+Default: False
+.TP
+.B \-\-print\-completion
+Possible choices: bash, zsh, tcsh
+.sp
+print shell completion script
+.UNINDENT
+.SH AUTHOR
+Felix Yan and tldr-pages contributors
+.SH COPYRIGHT
+2014, Felix Yan and 2014-present, tldr-pages contributors
+.\" Generated by docutils manpage writer.
+.

images/tldr-dark.png

@@ -16,8 +16,7 @@
 
 setup(
     name='tldr',
-    author='Felix Yan',
-    author_email='felixonmars@gmail.com',
+    author='Felix Yan and tldr-pages contributors',
     url='https://github.com/tldr-pages/tldr-python-client',
     description='command line client for tldr',
     long_description=Path(setup_dir, 'README.md').open().read(),
@@ -45,12 +44,16 @@
         "Natural Language :: English",
         "Operating System :: POSIX :: Linux",
         "Operating System :: POSIX :: SunOS/Solaris",
+        "Operating System :: POSIX :: BSD :: FreeBSD",
+        "Operating System :: POSIX :: BSD :: NetBSD",
+        "Operating System :: POSIX :: BSD :: OpenBSD",
         "Operating System :: MacOS :: MacOS X",
         "Operating System :: Microsoft :: Windows",
         "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
         "Topic :: Utilities",
         "Topic :: System"
     ]

setup.py

@@ -1,22 +1,20 @@
-name: tldr # you probably want to 'snapcraft register <name>'
-base: core22 # the base snap is the execution environment for this snap
-version: '3.2.0' # just for humans, typically '1.2+git' or '1.3.2'
-summary: tldr python client # 79 char long summary
+name: tldr
+base: core24
+version: '3.2.0'
+summary: tldr python client
 description: Python command-line client for tldr pages.
 
-grade: stable # must be 'stable' to release into candidate/stable channels
-confinement: strict # use 'strict' once you have the right plugs and slots
+grade: stable
+confinement: strict
 
 parts:
   tldr:
-    # See 'snapcraft plugins'
     plugin: python
     source: https://github.com/tldr-pages/tldr-python-client.git
     source-tag: $SNAPCRAFT_PROJECT_VERSION
     build-environment:
-      # WORKAROUND: The python plugin is broken with gnome extension
       - PATH: ${CRAFT_PART_INSTALL}/bin:${PATH}
-      - PYTHONPATH: ${CRAFT_PART_INSTALL}/lib/python3.10/site-packages
+      - PYTHONPATH: ${CRAFT_PART_INSTALL}/lib/python3.12/site-packages
     override-pull: |
       craftctl default
       sed -i "/data_files=\[('share\/man\/man1', \['docs\/man\/tldr\.1'\])\],/d" setup.py
@@ -37,14 +35,14 @@ parts:
       - -bin/Activate.ps1
       - -bin/python
       - -bin/python3
-      - -bin/python3.10
+      - -bin/python3.12
       - -lib/*/*/sphinx*
       - -lib/*/*/setuptools*
       - -lib/*/*/pip*
       - -lib/*/*/pkg_resources
       - -bin/pip
       - -bin/pip3
-      - -bin/pip3.10
+      - -bin/pip3.12
       - -bin/[a-s, u-z, _]*
       - -pyvenv.cfg
       - -lib/*/*/[a-b, d-r, u-z, A-B, D-R, U-Z, _]*
@@ -56,8 +54,7 @@ apps:
   tldr:
     command: bin/tldr
     environment:
-      PYTHONPATH: $SNAP/lib/python3.10/site-packages:$PYTHONPATH
-      #LD_LIBRARY_PATH: $SNAP/lib/man-db:$SNAP/lib:$SNAP/lib/$CRAFT_ARCH_TRIPLET
+      PYTHONPATH: $SNAP/lib/python3.12/site-packages:$PYTHONPATH
     plugs:
       - network
       - home

snap/snapcraft.yaml

@@ -18,8 +18,8 @@
 import colorama  # Required for Windows
 import shtab
 
-__version__ = "3.2.0"
-__client_specification__ = "1.5"
+__version__ = "3.3.0"
+__client_specification__ = "2.2"
 
 REQUEST_HEADERS = {'User-Agent': 'tldr-python-client'}
 PAGES_SOURCE_LOCATION = os.environ.get(
@@ -433,24 +433,35 @@ def output(page: str, plain: bool = False) -> None:
                 colored(
                     line.replace('>', '').replace('<', ''),
                     *colors_of('description')
-            )
+                )
             sys.stdout.buffer.write(line.encode('utf-8'))
         elif line[0] == '-':
             line = '\n' + ' ' * LEADING_SPACES_NUM + \
                 colored(line, *colors_of('example'))
             sys.stdout.buffer.write(line.encode('utf-8'))
         elif line[0] == '`':
-            line = line[1:-1]  # need to actually parse ``
+            line = line[1:-1]  # Remove backticks for parsing
+
+            # Handle escaped placeholders first
+            line = line.replace(r'\{\{', '__ESCAPED_OPEN__')
+            line = line.replace(r'\}\}', '__ESCAPED_CLOSE__')
+
             elements = [' ' * 2 * LEADING_SPACES_NUM]
             for item in COMMAND_SPLIT_REGEX.split(line):
                 item, replaced = PARAM_REGEX.subn(
-                    lambda x: colored(
-                        x.group('param'), *colors_of('parameter')),
+                    lambda x: colored(x.group('param'), *colors_of('parameter')),
                     item)
                 if not replaced:
                     item = colored(item, *colors_of('command'))
                 elements.append(item)
-            sys.stdout.buffer.write(''.join(elements).encode('utf-8'))
+
+            line = ''.join(elements)
+
+            # Restore escaped placeholders
+            line = line.replace('__ESCAPED_OPEN__', '{{')
+            line = line.replace('__ESCAPED_CLOSE__', '}}')
+
+            sys.stdout.buffer.write(line.encode('utf-8'))
         print()
     print()