⇉📺⇉ pyscFilteredViewer

This is a helper-script for Notepad++ using PythonScript. It runs the active file in Notepad++ through a filter to convert it to HTML, then launches that HTML in the default browser. This filtering process can be run automatically with every save of your file in Notepad++, or you can do it just on-demand.

This is useful for code that has embedded documentation that can be easily extracted and rendered to HTML (such as POD in Perl), or when editing marked-up text like a Markdown file. Anything that you can meaningfully convert to HTML, where you want to be able to edit the non-HTML source but render the final HTML in your browser is fair game.

TOP
Installation
Configuration
Filtering
- One-time Filtering
- Filter On Save
Inspiration / Justification
Future Features

Installation

Installation Prerequsisites

Notepad++ -- text editor with plugin capability
PythonScript -- a plugin for Notepad++ which can be used to automate tasks inside Notepad++ using Python 2.7

Installation Procedure

Download the latest release of pyscFilteredViewer from https://github.com/pryrt/pyscFilteredViewer/releases/latest.
Extract the pyscFilteredViewer folder from the zipfile into the PythonScript scripts\ location:
- %AppData%\Notepad++\plugins\config\PythonScript\scripts\pyscFilteredViewer\ is the most common location.
- If you have a portable version of Notepad++, or if you want these scripts to be available to all users on the machine, rather than just the current user, please see docs/AlternateInstall.md
If you had Notepad++ open, close and reload Notepad++ .
- This will cause Notepad++ and PythonScript to see the new scripts
- You can see them in the Plugins > PythonScript > Scripts menu
Run Plugins > PythonScript > Scripts > pyscFilteredViewer > pyscfvEditConfig to configure this utility: see Configuration (below) for configuration details

Scripts

pyscFilteredViewerLibrary.py -- this is the main library, which all the other scripts will use. Not intended for being run directly as a PythonScript script
pyscfvEditConfig.py -- running this script will load the psycFilteredViewer.ini file, and allow you to edit it (see Configuration, below)
pyscFilteredViewer.py -- running this script will do a one-time filter of the active file (see One-time Filtering, below)
pyscfvToggleFilterOnSave.py -- running this script will toggle between running the filter any time the file is saved and not running it (equivalent to choosing the correct version of pyscfvRegisterFilterOnSave or pyscfvUnRegisterFilterOnSave) (see Filter On Save, below)
pyscfvRegisterFilterOnSave.py -- this will set up Notepad++ to run the filter any time any file is saved (see Filter On Save, below)
pyscfvUnRegisterFilterOnSave.py -- this will stop Notepad++ from running the filter any time any file is saved (see Filter On Save, below)

Configuration

The first time you run any of the scripts (I recommend pyscfvEditConfig as the first of these scripts you run), it will create a configuration file called pyscFilteredViewer.ini. (If it finds a PreviewHTML filters.ini file, it will copy that to the new location and name. See Inspiration / Justification (below) for the connection with PreviewHTML.)

The configuration file is used to set the filter-command on a per-file-type basis (where a file-type is based on either the Language that Notepad++ has set for the file, or the file extension). Each file-type needs its own section in the config file.

The default configuration file looks something like:

; pyscFilteredViewer Config File (compatible with PreviewHTML Filters.ini file)
; Everything after ; are comments, and will help you read/understand the ini file
[IniFile]                                          ;   => this is the name of the section; it must be unique.  Typically, based on the language
Extension=.ini .cfg                                ;   => space-separated list of filename extensions, including the period.
Language=INI                                       ;   => this is the name of the language (from Notepad++'s perspective): for a UDL, use your "UserName" from the UDL dialog
; the 'Command=' line below is the filter command;
;   the first part of the command should be the full path to the command
;       if it has spaces in the path, it MUST have quotes around it
;       if it does not have spaces in the path, it still MAY have quotes around it
;   %1 is the name of the active file/buffer; it is in quotes "%1" because the path might contain spaces, and windows needs the quotes to know it's a single filename
;   the command must result in the HTML being dumped to STDOUT
Command="%AppData%\Notepad++\Plugins\Config\pyscFilteredViewer\ExampleConverterCommand.bat" "%1"
; this example command just wraps the text of the INI file in HTML XMP tags, so the browser will render it as plaintext inside an HTML file

[SECTION]: each section in the config file is a logical grouping, which will define the filter command for a given file-type. The section name chosen is irrelevant, as long as it is unique. It is recommended that it be similar to the Language setting
- example ⇒ [IniFile]
Extension: this setting is a space-separated list of filename extensions (including the period/dot)
- example ⇒ Extension=.ini .cfg
Language: this is the name of the "language" of the file (Notepad++ calls the file-type "Language", since it's often a programming language, like "Python" or "Perl")
- If you want this to work for a User Defined Language (UDL), use whatever name you saved it as from the Language > Define Your Language dialog, Save As... button
- example ⇒ Language=INI -- this assumes Notepad++ calls the language for .ini files "INI" (it does in my versions)
Command: this is the command to use to filter the file into HTML.
- This command should take the name of a file as the command-line argument, and should output HTML to STDOUT.
  - You can look at the ExampleConverterCommand.bat, which unzipped in the same folder as the python scripts, for an example of a batch file that takes the filename as an argument and outputs to the
  - Many converters (markdown-to-HTML, POD-to-HTML, etc) follow this filename-in/STDOUT-out by default
- To reference the filename of the source file (ie, the file that's in Notepad++), use %1. Since the file's path and or name may have a space, it is highly recommended to always enclose it in quotes, as "%1"
- The path to the command (executable, batch file, or anything else "runnable" from a Windows perspective) should be spelled out, as it is likely not in your PATH
- This is not the browser (or other viewer) command. The viewer used is based on your Windows settings, whatever the default / open "action" is for the HTML file type (usually your default web browser).
- example ⇒ Command="%AppData%\Notepad++\Plugins\Config\pyscFilteredViewer\ExampleConverterCommand.bat" "%1"

NOTE: you technically only need one of either Language or Extension, since one is usually enough to define a file-type. But if both are defined, pyscFilteredViewer will first try to match on Language, and then on Extension.

Configuring Keyboard Shortcut(s)

If you want to be able to use one or more of these scripts with a keyboard shortcut, use the Plugins > PythonScript > Configuration... dialog to add the script(s) to the Menu items list, then Settings > Shortcut Mapper > Plugin Commands, filter for Python, and edit the keyboard shortcut for the appropriate script(s).

Once you are ready to replace PreviewHTML with pyscFilteredViewer, I highly recommend mapping the PreviewHTML shortcut (Ctrl+H) to pyscfvToggleFilterOnSave (see Filter On Save, below).

Filtering

You can either filter your file on demand, using One-time Filtering, or you can make it filter every time you hit SAVE in Notepad++ using Filter On Save.

One-time Filtering

This will take the active file, filter it as defined in the Configuration, and the resulting filtered file will be displayed in your default browser. With one-time filtering, it will immediately delete the temporary HTML file -- so if you try to hit RELOAD or REFRESH in your browser or viewer, it won't find the file. To reload the file, you will need to close the old version in your viewer, and re-run the one-time filter from Notepad++.

Filter On Save

If you want to keep updating the filtered file (usually HTML) every time you change the source, you need to "register" the FilterOnSave action, using the pyscfvRegisterFilterOnSave script. This will register a "hook" such that every time Notepad++ saves a file, it will run the filter. If the filter hasn't been run on this file yet, it will launch the filtered file in the appropriate viewer. If the filter had been run on this file before, then you will have to move to the viewer (usually, the web browser) and refresh the appropriate page (or find a

PyscFilteredViewer

Install / Use

README