WinPrint

winprint - Advanced source code and text file printing for terminals (all platforms) and Windows/macOS GUIs.

By Tig Kindel
@tigkindel on X

User’s Guide

Features

Command Line Interface

The primary command for WinPrint is wp. It provides a terminal UI.

wp [options] [file...]

Launching Modes

Command Description
wp file.cs Open a file in the TUI
wp Launch the TUI (terminal user interface)
wp print file.cs Print one or more files without opening the UI
wp gui Launch the graphical user interface on Windows/macOS
wp gui file.cs Launch the GUI with a file (and options) loaded

Examples

Check the installed version:

wp --version

Open a file in the terminal UI:

wp Program.cs

Pass print preview options:

wp Program.cs --printer "Microsoft Print to PDF" --sheet "Default 2-Up"

Print without opening the UI (use --what-if to count sheets without printing):

wp print Program.cs --printer "Microsoft Print to PDF" --sheet "Default 2-Up"
wp print *.cs --landscape
wp print Program.cs --what-if

Launch the GUI:

wp gui

Launch the GUI with a file (and options) loaded:

wp gui ./testfiles/Program.cs --sheet "Default 2-Up"

Get help:

wp --help

CLI Options

winprint exposes one canonical set of print options across every front end — the wp CLI, the TUI, and the gui on Windows and macOS. The same name, short alias, and meaning apply everywhere:

Option Alias Description
--sheet -s Sheet definition to use (ID or friendly name).
--landscape -l Force landscape orientation.
--portrait -r Force portrait orientation.
--printer -p Printer name.
--paper-size -z Paper size name.
--from-sheet -f First sheet to print (use with --to-sheet).
--to-sheet -t Last sheet to print (use with --from-sheet).
--content-type -e Content type engine / language override (e.g. text/plain, text/html, or a <language>).

Front ends add their own appropriate extras: the interactive TUI adds --view, --width, --height; the wp print command adds --what-if (-w, count sheets without printing); and the GUI launches through the separate wp gui command. The wp command line also provides --help, --version, --opencli, --json, --output, --initial, --timeout, and --cat.

The same print options behave identically across the wp CLI, the TUI, and the GUI.

Overriding Content Type / Language

Use --content-type (alias -e) to override winprint’s automatic content type and language detection. The value can be a content type (e.g. text/plain, text/html) or a language alias:

wp print README --content-type text/x-markdown
wp print notes.txt -e text/html

Graphical User Interface

Launch the GUI with:

wp gui

Or find WinPrint in the Start Menu (Windows) or via Spotlight (macOS).

The GUI provides an easy-to-use interface for previewing how a file will be printed and changing settings.

Auto-Update

WinPrint’s packaged builds include a built-in install/update engine.

You can also update manually using your package manager:

# Windows (Scoop; winget coming soon)
scoop update winprint

# macOS
brew upgrade --cask winprint

# Linux
brew upgrade winprint

Sheet Definitions

Font choices, header/footer options, and other print-job settings are defined in winprint as Sheet Definitions. In the winprint world a Sheet is a side of a sheet of paper. Depending on how its configured, winprint will print one or more Pages on each Sheet.

This is called “n-up” printing. The most common form of “n-up” printing is “2-up” where the page orientation is set to landscape and there are two columns of pages.

The layout and format of the Sheet is defined by a set of configuration settings called a Sheet Definition. Out of the box winprint comes with two: Default 1-Up and Default 2-Up.

Sheet Definitions are defined and stored in the WinPrint.config.json configuration file. On Windows this file lives in %appdata%\Kindel\winprint; on macOS and Linux winprint runs in portable mode and the file sits next to the application (the wp executable, or inside WinPrint.app for the GUI).

Headers & Footers Macros

The format for header & footer specifiers is:

<left part>|<center part>|<right part>

where <left part>,<center part>, and <right part> can be composed of text and any of the Macros described below. For example, this is the default header specifier:

{DateRevised:D}|{Title}|Type: {FileType}

This is the default footer specifier:

Printed with love by WinPrint||Page {Page} of {NumPages}

The following macros are supported:

The numeric macros ({NumPages} and {Page}) support standard .NET numeric formatting modifiers. For example, using Page {Page:D3} of {NumPages:D3} in a footer will print Page 001 of 004 on the first page of 4.

The {DatePrinted} and {DateRevised} macros support the standard .NET date and time formatting modifiers. For example {DateRevised:M} will generate just the month and date (e.g. September 10) while {DateRevised:t} will generate just the short time (4:55 PM).

Modifying Sheet Definitions

The winprint GUI can be used to change many Sheet Definition settings. All settings can be changed by editing the WinPrint.config.json file. Note if WinPrint.config.json is changed while the winprint GUI App is running, it will detect the change and re-flow the currently loaded file. In other-words, a text editor can be used as the UI for advanced settings.

Creating new Sheet Definitions

winprint includes two pre-defined Sheet Definitions: Default 1-Up and Default 2-Up. Additional Sheet Definitions can be created by editing WinPrint.config.json, copying one of the existing Sheet Definitions and giving it a new unique name and unique ID (in the form of a UUID).

Content Types

winprint supports five types of files. Support for each is provided by a winprint Content Type Engine (CTE):

  1. TextMateCte - This is the default CTE used for most text and source files. It uses bundled TextMate grammars for syntax highlighting.

  2. MarkdownCte - Renders Markdown files (text/x-markdown; e.g. .md).

  3. AnsiCte - Decodes files containing ANSI Escape Sequences (text/ansi; e.g. .ans/.ansi ANSI-art and colorized console captures), reflowing them for the page.

  4. TextCte - This CTE knows only how to print raw text/plain files. The format of the printed text can be changed (e.g. to turn off line numbers or use a different font). Lines that are too long for a page are wrapped at character boundaries. \f (form feed) characters can be made to cause following text to print on the next page (this is off by default). Settings for text/plain can be changed by editing the textContentTypeEngineSettings section or a Sheet Definition in WinPrint.config.json.

  5. HtmlCte - Renders HTML files (text/html; e.g. .html/.htm, as well as .mhtml/.mht web archives) by laying out the HTML/CSS. Any CSS specified inline in the HTML file will be honored. Local (document-relative) files, data: URIs, and MHTML-embedded resources always load; http(s) resources are only fetched when AllowRemoteResources is enabled. text/html does not support line numbers.

When using winprint from the command line, the --content-type (-e) option can be used to specify the content type / CTE to use.

The extension of the file being printed (e.g. .cs) determines which Content Type rendering engine will be used. winprint has a built-in library of hundreds of file extension to content type/language mappings. When using winprint from the command line, the --content-type (-e) option can be used to override this behavior.

To associate a file extension with a particular Content Type Engine, modify the fileTypeMapping.filesAssociations section of WinPrint.config.json. For example, to associate files with a .htm extension with the text/html Content Type Engine add a line as shown below:

    "fileTypeMapping": {
      "filesAssociations": {
        "*.htm": "text/html"
      }
    }

For associating file extensions with a particular programming language see below.

The wp --content-type (-e) option overrides content type and language detection.

Language Associations

winprint has a built-in file extension to language mapping that should work for most modern scenarios. For example it knows that .cs files hold C# and .bf files hold brainfuck.

Adding or Changing Language Associations

To associate a file extension with a content type, modify the fileTypeMapping.filesAssociations section of WinPrint.config.json. For example, to associate files with a .json5 extension with the JSON content type add a line as shown below:

    "fileTypeMapping": {
      "filesAssociations": {
        "*.json5": "text/x-json"
      }
    }

A new content type can be defined by modifying the fileTypeMapping.contentTypes section of WinPrint.config.json. For example, to enable the Icon Programming Language, the fileTypeMapping.filesAssociations and fileTypeMapping.contentTypes sections would look like the following:

    "fileTypeMapping": {
      "filesAssociations": {
        "*.icn": "text/x-icon"
      },
      "contentTypes": [
        {
          "id": "text/x-icon",
          "title": "Icon Programming Language",
          "extensions": [
            "*.icn"
          ],
          "aliases": [
              "icon"
          ]
        }
      ]
    }

For TextMate highlighting to work, the mapped language must resolve to a bundled TextMate grammar. If it does not, winprint still prints the file as plain text.

Logging & Diagnostics

winprint writes diagnostic logs to a logs folder alongside its settings. On Windows that’s %appdata%\Kindel\winprint\logs (or next to the executable when running in portable mode); on macOS and Linux the logs folder sits next to the wp executable (inside WinPrint.app for the GUI). Run the wp command line with --debug for more detail.

Additional printing diagnostics can be turned on via settings in the configuration file.

To help diagnose printer-related rendering issues, or issues with Sheet Definitions, winprint set the appropriate diagnostic flags found at the end of the config file to true (each flag has a print and print preview variant):

  "previewPrintableArea": false,
  "printPrintableArea": false,
  "previewPaperSize": false,
  "printPaperSize": false,
  "previewMargins": false,
  "printMargins": false,
  "previewHardMargins": false,
  "printHardMargins": false,
  "printBounds": false,
  "previewBounds": false,
  "printContentBounds": false,
  "previewContentBounds": false,
  "printHeaderFooterBounds": false,
  "previewHeaderFooterBounds": false,
  "previewPageBounds": false,
  "printPageBounds": false

To help diagnose why content may be rendering incorrectly, set diagnostics to true in any contentSettings section. This will cause the Content Type Engine to print/display diagnostic rules.

      "contentSettings": {
        "diagnostics": false
      },