From b9433515688e1fcb99cc7ad55de9882b19b776aa Mon Sep 17 00:00:00 2001 From: CoeJoder Date: Sat, 15 Jun 2024 20:00:03 -0700 Subject: [PATCH] Update installation instructions --- README.md | 50 ++++++++------ main.py | 33 +++++++-- templates/template.README.md | 69 +++++++++++++++++++ .../template.lessfilter.sh | 0 4 files changed, 126 insertions(+), 26 deletions(-) create mode 100644 templates/template.README.md rename template.lessfilter.sh => templates/template.lessfilter.sh (100%) diff --git a/README.md b/README.md index 195d32f..c3c95de 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,27 @@ # Syntax highlighter for `less` -Uses [Pygments](https://pygments.org/) to provide syntax highlighting -for supported file types. The `.lessfilter` is generated by parsing the Pygments documentation website. +Adds syntax highlighting to everyone's favorite terminal pager, `less`. ![screenshot](screenshot.png) ## Installation +These instructions assume an Ubuntu-based distro; modify as needed. -### 1. Install Pygments & awk -Ensure that you have the latest version of Pygments installed by using [pip](https://pypi.org/project/pip/), as your -distro's packaged version is likely outdated. You'll also need `awk`. +### 1. Install `pygmentize` & `awk` +[Pygments](https://pygments.org/) provides `pygmentize`. Your system may already have an outdated version of Pygments installed. If so, leave that alone and install the latest Pygments locally, giving it priority in your `$PATH`. [Pipx](https://pipx.pypa.io/stable/) can facilitate these two tasks. + +You'll also need `awk`: ```shell -# remove any installed packaged versions -sudo apt autoremove python-pygments python3-pygments +# install pipx if needed +sudo apt install pipx -# install latest version -sudo pip install Pygments --upgrade +# add pipx-installed binaries to `$PATH` if not already +pipx ensurepath -# install some implementation of `awk` +# install Pygments and GNU awk +pipx install Pygments sudo apt install gawk ``` -### 2. Install lesspipe (recommended) +### 2. Install `lesspipe` (optional, recommended) Most Linux distros already have `lesspipe` enabled, but you can check for certain by running: ```shell echo $LESSOPEN @@ -27,7 +29,7 @@ echo $LESSOPEN If you don't see `lesspipe` or `lessfile` in the output, install [lesspipe](https://github.com/wofr06/lesspipe). ### 3. Configure Environment Variables -Add the following to `~/.bashrc` +Add the following to `~/.bashrc`: ```shell # sets LESSOPEN and LESSCLOSE variables eval "$(SHELL=/bin/sh lesspipe)" @@ -35,25 +37,33 @@ eval "$(SHELL=/bin/sh lesspipe)" # interpret color characters export LESS='-R' -# to list available styles: `pygmentize -L styles` +# more styles available, see: `pygmentize -L styles` export PYGMENTIZE_STYLE='paraiso-dark' # optional alias ls='ls --color=always' alias grep='grep --color=always' ``` -If you don't have or want `lesspipe`, replace the above `eval` statement with: +If you opted out of `lesspipe` in the previous step, replace the above `eval` statement with: ```shell export LESSOPEN='|~/.lessfilter %s' ``` -### 4. Create ~/.lessfilter -Run [main.py](main.py) to generate the latest `.lessfilter` file and place it in your home directory. -Or you can download a pre-generated [.lessfilter](.lessfilter) which is currently at version `2.15.1`. -Check your program version by running `pygmentize -V` to ensure that it is this version or newer. +### 4. Generate `~/.lessfilter` (optional) +This repo contains a pre-generated [.lessfilter](.lessfilter) which is currently at version `2.18.0` and is updated occasionally. You could use that and skip to the next step, even if its version lags behind that of Pygments (any unsupported file types would fallback to plain-text). -### 5. Make ~/.lessfilter executable +You could also generate a `.lessfilter` yourself by running [main.py](main.py), which scrapes the Pygments lexer documentation website and produces a `.lessfilter` in this directory which corresponds to the latest published version: ```shell +git clone https://github.com/CoeJoder/lessfilter-pygmentize.git +cd lessfilter-pygmentize/ +pipenv install +pipenv run python main.py >/dev/null +``` + +### 5. Copy `~/.lessfilter` to `$HOME` and make it executable +```shell +cp ./.lessfilter ~ chmod +x ~/.lessfilter ``` -Done. Test it out by running `less ~/.lessfilter` + +That's it. Test it out by running `less ~/.lessfilter`. \ No newline at end of file diff --git a/main.py b/main.py index 1cca53f..b7b33b5 100644 --- a/main.py +++ b/main.py @@ -1,5 +1,6 @@ from typing import List, Iterable +import argparse import re import requests from lxml import html @@ -17,8 +18,11 @@ SELECT_LEXER_NAME = CSSSelector('.sig-name') SELECT_HOMEPAGE_VERSION = CSSSelector('.sphinxsidebarwrapper b') REGEXP_FILENAMES = re.compile(r'.*?Filenames:\s+?(.+?)$', re.MULTILINE | re.DOTALL) PATH_PROJECT = Path(__file__).parent -TEMPLATE_LESSFILTER = 'template.lessfilter.sh' -TEMPLATE_OUTPUT = '.lessfilter' +TEMPLATE_DIR = PATH_PROJECT.joinpath('templates') +TEMPLATE_OUTPUT_LESSFILTER = '.lessfilter' +TEMPLATE_OUTPUT_README = 'README.md' +TEMPLATE_LESSFILTER = f'template{TEMPLATE_OUTPUT_LESSFILTER}.sh' +TEMPLATE_README = f'template.{TEMPLATE_OUTPUT_README}' INDENT = 4 INDENT_DOUBLE = INDENT * 2 MAX_COL_SIZE = 80 @@ -67,13 +71,21 @@ recognized_filenames = {} def main(): + parser = argparse.ArgumentParser() + parser.add_argument('--lessfilter_only', action='store_true') + args = parser.parse_args() + print("Fetching Pygments version number from homepage...", end='') version = fetch_version() print(f'v{version}') print('Fetching lexers from documentation page...') fetch_lexers() print(f' Supported filenames:\n {recognized_filenames}') - render_template(version) + + env = Environment(loader=FileSystemLoader(TEMPLATE_DIR)) + render_template(env, version) + if not args.lessfilter_only: + render_readme(env, version) print(f'Done.') @@ -111,9 +123,18 @@ def fetch_lexers(): else: raise Exception(f'Aborted due to an unrecognized "{name}" lexer description format: {description}') +def render_readme(env: Environment, version: str): + template = env.get_template(TEMPLATE_README) + template_vars = { + 'pygments_version': version + } + output = template.render(**template_vars) + output_path = PATH_PROJECT.joinpath(TEMPLATE_OUTPUT_README) + with output_path.open(mode='w', encoding='utf-8', newline='\n') as f: + f.write(output) -def render_template(version: str): - env = Environment(loader=FileSystemLoader(PATH_PROJECT)) + +def render_template(env: Environment, version: str): template = env.get_template(TEMPLATE_LESSFILTER) template_vars = { 'pygments_version': version, @@ -123,7 +144,7 @@ def render_template(version: str): INDENT_DOUBLE) } output = template.render(**template_vars) - output_path = PATH_PROJECT.joinpath(TEMPLATE_OUTPUT) + output_path = PATH_PROJECT.joinpath(TEMPLATE_OUTPUT_LESSFILTER) with output_path.open(mode='w', encoding='utf-8', newline='\n') as f: f.write(output) output_path.chmod(0o755) diff --git a/templates/template.README.md b/templates/template.README.md new file mode 100644 index 0000000..5799302 --- /dev/null +++ b/templates/template.README.md @@ -0,0 +1,69 @@ +# Syntax highlighter for `less` +Adds syntax highlighting to everyone's favorite terminal pager, `less`. +![screenshot](screenshot.png) + +## Installation +These instructions assume an Ubuntu-based distro; modify as needed. + +### 1. Install `pygmentize` & `awk` +[Pygments](https://pygments.org/) provides `pygmentize`. Your system may already have an outdated version of Pygments installed. If so, leave that alone and install the latest Pygments locally, giving it priority in your `$PATH`. [Pipx](https://pipx.pypa.io/stable/) can facilitate these two tasks. + +You'll also need `awk`: +```shell +# install pipx if needed +sudo apt install pipx + +# add pipx-installed binaries to `$PATH` if not already +pipx ensurepath + +# install Pygments and GNU awk +pipx install Pygments +sudo apt install gawk +``` + +### 2. Install `lesspipe` (optional, recommended) +Most Linux distros already have `lesspipe` enabled, but you can check for certain by running: +```shell +echo $LESSOPEN +``` +If you don't see `lesspipe` or `lessfile` in the output, install [lesspipe](https://github.com/wofr06/lesspipe). + +### 3. Configure Environment Variables +Add the following to `~/.bashrc`: +```shell +# sets LESSOPEN and LESSCLOSE variables +eval "$(SHELL=/bin/sh lesspipe)" + +# interpret color characters +export LESS='-R' + +# more styles available, see: `pygmentize -L styles` +export PYGMENTIZE_STYLE='paraiso-dark' + +# optional +alias ls='ls --color=always' +alias grep='grep --color=always' +``` +If you opted out of `lesspipe` in the previous step, replace the above `eval` statement with: +```shell +export LESSOPEN='|~/.lessfilter %s' +``` + +### 4. Generate `~/.lessfilter` (optional) +This repo contains a pre-generated [.lessfilter](.lessfilter) which is currently at version `{{ pygments_version }}` and is updated occasionally. You could use that and skip to the next step, even if its version lags behind that of Pygments (any unsupported file types would fallback to plain-text). + +You could also generate a `.lessfilter` yourself by running [main.py](main.py), which scrapes the Pygments lexer documentation website and produces a `.lessfilter` in this directory which corresponds to the latest published version: +```shell +git clone https://github.com/CoeJoder/lessfilter-pygmentize.git +cd lessfilter-pygmentize/ +pipenv install +pipenv run python main.py >/dev/null +``` + +### 5. Copy `~/.lessfilter` to `$HOME` and make it executable +```shell +cp ./.lessfilter ~ +chmod +x ~/.lessfilter +``` + +That's it. Test it out by running `less ~/.lessfilter`. diff --git a/template.lessfilter.sh b/templates/template.lessfilter.sh similarity index 100% rename from template.lessfilter.sh rename to templates/template.lessfilter.sh