Update installation instructions

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`.

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)

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`.