PasHi Pascal Highlighter

User Guide

Contents

• Introduction
• Installation
• Using PasHi
• Configuring PasHi
• CSS styles used by PasHi
• Using PasHiGUI

» Contents

Introduction

PasHi is a fully featured command line program that highlights Pascal source code. It reads the original source code from standard input, files or the clipboard and writes the highlighted code as HTML to standard output, a file, or the clipboard.

HTML 4 [deprecated], XHTML and HTML 5 are all supported. CSS is used for styling. Style sheets may be external or can be embedded in the HTML document. Several predefined style sheets can be installed with the program. You can also create your own.

PasHi can either generate complete HTML documents or just fragments of HTML code. HTML fragments make it easy to embed highlighted code in existing web pages. Web page authors simply need to ensure that the necessary CSS classes are available. The easiest way to do this is to use an external style sheet.

PasHiGUI, a GUI front end for PasHi, is optionally included in the release. This provides a point and click way of using PasHi. Most, but not all, command line options are supported. Files and text can be dragged and dropped onto the program's window to highlight them.

» Contents

Installation

Details of how to install PasHi and PasHiGUI are provided in the file ReadMe.txt that is included in the program download.

Using PasHi

Default behaviour

By default PasHi reads input from standard input and writes highlighted output to standard output. You can process a single file and write output to another file using shell redirection. For example, to highlight source.pas and output to source.html use:

PasHi <source.pas >source.html

If you do not redirect output the resulting HTML is displayed on the console. If you don't redirect input then you must enter the source code manually on the command line, a line at a time. When you have finished you must signal end-of-file by pressing Ctrl+Z on a line on its own, followed by Return.

Note that PasHi's default behaviour can be altered by using a configuration file. See Configuring PasHi for full details.

Command line

PasHi's behaviour can be modified by specifying one or more file names and / or commands on the command line.

File names and commands can be intermixed. Deprecated: a later major release may require file names to be specified before the first command.

If one or more file names are entered on the command line then input is taken from the files. Source code is read from each named file in turn and concatenated before being highlighted. Standard input is ignored. Specifying a single file name has the same effect as redirecting standard input from that file.

If you specify file names on the command line you should not use the --input-stdin or --input-clipboard commands. No error will be reported if you do so, but the behaviour may not be as expected.

Many commands have both a long and a short form, but some commands have only a long form. They are explained in the following table.

There are some commands inherited from PasHi v1 that are not listed above. They have now been superseded by other commands but are still supported for compatibility reasons. However they are now deprecated.

They are:

Input encoding

Normally PasHi takes text files as input, either via redirection to standard input or from files.

Byte order marks (BOM) are checked to determine the encoding of Unicode files. Supported encodings are: UTF-8, UTF-16 little endian and UTF-16 big endian. If there is no BOM then the file is assumed to be encoded in the user's default code page.

The exception to the above is when the --input-clipboard command is used. The source code is then expected to be in Unicode.

Exit codes

PasHi uses the following exit codes:

• 0: The program completed successfully.
• 1: The program encountered an error and terminated. Examine the error message written to standard error for details.

Usage example

Perhaps the most common usage of PasHi is to read source code from the clipboard and replace it with a highlighted fragment. Here's what I do when pasting highlighted source into a web page:

1. Select the unformatted source in an editor and copy it to the clipboard.
2. Switch to a command window and do

   PasHi --input-clipboard --output-clipboard --doc-type fragment

   Alternatively you can use short forms or v1 commands to shorten this:

   PasHi -r -w -d fragment

   or

   PasHi -rc -wc -frag [deprecated]

3. Switch to the editor containing the web page and paste in the highlighted code.

If you mainly use PasHi in this way you can configure PasHi to use those parameters by default. See the example below for details.

» Contents

Configuring PasHi

If PasHi finds a file named config in the %AppData%\DelphiDabbler\PasHi directory when it starts up, it is read. Any commands found in that file are used to change the program's default state.

PasHi does not install a config file by default, so if you need one you must create your own. You can do this either by creating a new file or by copying and editing one of the sample scripts provided with PasHi (providing you installed them).

The format of the config file is as follows:

• Each command is listed on its own line.
• Where a command takes a parameter the parameter should be placed on the same line as the command, separated from it by one or more spaces. Parameters containing spaces should not be quoted (unlike on the command line).

• Most of the long form commands listed in Using PasHi have an equivalent in the config file. Config commands have the same name as the long form version except that the leading "--" characters are omitted. For example, the equivalent of the--doc-type command in the config file is doc-type.

  WARNING: The --help and --version commands are exceptions that have no equivalent config file command. If either help or version are included in the config file then PasHi will stop with an error every time it is run.

• None of the short form commands can be used in the config file, and nor can any of the v1 style commands.

  WARNING: Using a short form or v1 style command in the config file will cause PasHi to stop with an error every time it is run.

• Lines begining with "#" are treated as comments and ignored.
• Blank lines are ignored.
• Leading and trailing spaces are ignored.

PasHi expects config to be a UTF-8 encoded text file. The UTF-8 byte order mark may be omitted from the start of the file if required. If your text editor does not support UTF-8, confine yourself to valid ASCII characters and all will be well.

Sample config scripts

Some example config scripts are optionally installed in the %AppData%\DelphiDabbler\PasHi directory. The sample scripts are:

config-template

This script does nothing, but is copiously commented with all possible commands. Used in conjunction with the command reference above it is a good starting point for your own config script.

config-v1 [deprecated]

Emulates, as far as possible, the functioning of PasHi v1. This script requires that the file v1-default.css (provided) is present in the same directory.

The example config files, where installed, will not appear in the %AppData%\DelphiDabbler\PasHi directory until after PasHi has been run once.

Examples

Example 1

As mentioned above, a common use for PasHi is to highlight source code from the clipboard as an HTML fragment and place the HTML back on the clipboard. Instead of using the necessary commands each time you run PasHi you can add the following to the config file:

input-clipboard
output-clipboard
doc-type fragment

Now all you need to do is enter:

PasHi

on its own on the command line and it will perform the required actions by default.

Be warned that if you do this, you will need to specify the --input-stdin, --output-stdout and --doc-type commands on the command line to revert to default behaviour.

Example 2

Another useful example is where you have a CSS file containing your desired highlighting style that you always want to embed in your highlighted document. To save you having to specify a --embed-css command each time you run PasHi, simply put the command in config, something like:

embed-css C:\CSS\my-style.css

Or, in the special case of the CSS files optionally installed with PasHi in %AppData%\DelphiDabbler\PasHi, omit the path information and use, for example:

embed-css twilight.css

If you prefer to link to your CSS file instead of embedding it, you can add a line to config like:

link-css https://example.com/css/my-style.css

Should you now need to revert PasHi to using its default CSS you will need to include --default-css on the command line.

CSS styles used by PasHi

Styles defined

All the highlighted HTML generated by PasHi is enclosed in a <div> block that is given the class .code-pascal. CSS may be defined for this class to provide any required background, padding, margin or border for the entire code listing.

Each line of source code is enclosed in its own <pre> block. This tag should have CSS associated with it to set the required (mono spaced) font family and size. It is also used to set the spacing between lines using the margin CSS property - usually set to 0.

There are further CSS classes that can be associated with each line. They are:

.line

Applied to each <pre> tag when all lines are to be rendered the same, i.e. when code striping is switched off (see the --striping command above). Provide CSS for this class if you want to style the line, for example to draw a border.

.even-line
.odd-line

These classes are applied to <pre> tags in place of the .line class in even and odd numbered lines respectively when code striping is switched on (see the --striping command above). .even-line and .odd-line must be styled differently otherwise striping will have no visible effect. It is usual to provide a different background colour for alternate lines – hence the name "striping".

.linenum

This class is applied to any line numbers that may be prepended to the start of a line (see --line-numbering and related commands above). .linenum can be used to set the font style and colour used for the line number, along with the margin between the line number and source code and any separating border. The font used should be mono spaced otherwise the numbers may not line up correctly.

PasHi encloses every syntactic element within each line's <pre> block in <span> tags. Each of these tags is given a class name relating to the type of the element. CSS defining the font style & weight, text decoration and colour for each class should be provided. These classes are:

.comment

Style for comments.

.kwd

Style for keywords and reserved words.

.ident

Style for non-keyword identifiers.

.sym

Style for symbols (e.g := and >).

.str

Style for string literals.

.num

Style for whole numbers (integers).

.float

Style for floating point numbers.

.hex

Style for hexadecimal numbers.

.preproc

Style for preprocessor directives.

.asm

Style for assembler.

.space

Style for whitespace.

.err

Style for any errors detected.

These CSS classes should be defined as children of .code-pascal to avoid potential clashes with other similarly named styles in an HTML document.

Whenever you need to define your own CSS style sheets to use with files generated by PasHi you must provide definitions for all the above styles. You will need your own CSS if you:

• Embed your own styles in the output HTML document using the --embed-css switch.
• Link to your own external style sheet from the output document using the --link-css switch.
• Include a code fragment generated by the --doc-type fragment command in another HTML file.

Default style

To help you get started in defining your own classes, here are the default definitions that are used by PasHi.

.code-pascal,
.pas-source {
  background-color: transparent;
}

.code-pascal pre,
.pas-source pre {
  font-family: "Courier New", monospace;
  font-size: 9pt;
  margin: 0;
}

.code-pascal pre.line,
.pas-source pre.line {
}

.code-pascal pre.odd-line,
.pas-source pre.odd-line {
}

.code-pascal pre.even-line,
.pas-source pre.even-line {
  background-color: #f0f0f0;
}

.code-pascal .linenum,
.pas-source .linenum {
  border-right: 1px silver solid;
  padding: 1px 4px 1px 2px;
  margin-right: 0.75em;
  color: gray;
  background-color: #f0f0f0;
}

.code-pascal .comment,
.pas-comment {
  color: green;
  font-weight: normal;
  font-style: italic;
  text-decoration: none;
}

.code-pascal .kwd,
.pas-kwd {
  color: navy;
  font-weight: bold;
  font-style: normal;
  text-decoration: none;
}

.code-pascal .ident,
.pas-ident {
  color: black;
  font-weight: normal;
  font-style: normal;
  text-decoration: none;
}

.code-pascal .sym,
.pas-sym {
  color: black;
  font-weight: normal;
  font-style: normal;
  text-decoration: none;
}

.code-pascal .str,
.pas-str {
  color: blue;
  font-weight: normal;
  font-style: normal;
  text-decoration: none;
}

.code-pascal .num,
.code-pascal .float,
.code-pascal .hex,
.pas-num,
.pas-float,
.pas-hex {
  color: maroon;
  font-weight: normal;
  font-style: normal;
  text-decoration: none;
}

.code-pascal .preproc,
.pas-preproc {
  color: teal;
  font-weight: normal;
  font-style: normal;
  text-decoration: none;
}

.code-pascal .asm,
.pas-asm {
  color: black;
  font-weight: normal;
  font-style: normal;
  text-decoration: none;
}

.code-pascal .space,
.pas-space {
}

.code-pascal .err,
.pas-err {
  color: black;
  background-color: yellow;
  font-weight: normal;
  font-style: normal;
  text-decoration: none;
}

Change the styles to suit your needs.

Predefined style sheets

PasHi provides several .css files that can be used to change the style of highlighted code. They are (optionally) installed into the %AppData%\DelphiDabbler\PasHi directory when PasHi is first run after installation. The files are:

delphi4.css

Emulates the default syntax highlighting used by Delphi 4.

delphi7.css

Emulates the default syntax highlighting used by Delphi 7.

delphi2010.css

Emulates the default syntax highlighting used by Delphi 2010.^†

classic.css

Emulates the "Classic" highlighting style provided by Delphi 2010.^†

ocean.css

Emulates the "Ocean" highlighting style provided by Delphi 2010.^†

twilight.css

Emulates the "Twilight" highlighting style provided by Delphi 2010.^†

visual-studio.css

Emulates the "Visual Studio™" highlighting style provided by Delphi 2010.^†

mono.css

A monochrome highlighter.

null.css

Renders all elements in plain text: no highlighting.

notebook.css

Adopts the appearance of lined pale yellow notepaper with monochrome highlighting.

v1-default.css

Replicates the highlighting style used by PasHi v1. There is also a custom config script that replicates v1 as far as possible, and that script requires this CSS file.

† All the Delphi 2010 related files attempt to emulate the IDE code editor's left hand gutter when line numbers are displayed.

You can embed these files using the --embed-css command, followed by the file name on its own with no path information. You can also configure PasHi to always use one of the files by including a suitable embed-css command in the config file. You may copy and edit these files freely, and may use them on any website.

All the sample files support both legacy and new CSS class names.

» Contents

Using PasHiGUI

PasHiGUI provides a GUI for PasHi and permits many of PasHi's features to be accessed via a point and click interface.

Main display

PasHiGUI's main window displays two tabs: Display View and HTML view. These tabs provide different views of the generated HTML, as follows:

Display View

Renders the HTML as it will appear in a browser. If the generated code is a complete document it is displayed as-is. If it is a fragment the code is displayed using PasHiGUI's built in style sheet.

HTML View

Displays the generated HTML source code.

Options side bar

PasHi's behaviour is customised using the Options Side Bar. This can be displayed on the right hand side of the main window when required. It is toggled on and off using the Options | Show / Hide Options Bar menu option or the "cog" button on the toolbar.

All PasHi options supported by PasHiGUI can be set from this side bar. Options are grouped under various collapsible sections. Each group relates to one or more PasHi commands. Select the required options and click the Apply button when ready. Any currently displayed document will then be regenerated using the new settings.

You can revert to PasHi's default settings, as modified by any config file. Click the Restore Defaults to do this. Clicking this button updates the options in the side bar but does not regenerate the current document. You need to click the Apply button to do this.

The options set in the side bar are recorded in a file when PasHiGUI closes. They are reloaded the next time the program is started. This means that you can keep a different set of "defaults" for PasHiGUI to those used for PasHi.

Main menu

PasHiGUI is controlled by a main menu along with a toolbar that replicates some of the functions accessed via the menus. The menus are described below:

File | Open

Opens one or more source files for highlighting.

File | Save

Saves highlighted code as HTML to a file. The file can be saved with either .html or .txt extensions.

File | Exit

Quits the program.

Edit | Copy

Copies highlighted code to the clipboard as HTML, in text format.

Edit | Paste

Attempts to highlight any text on the clipboard. The text is assumed to be source code.

Options | Show Options Bar
Options | Hide Options Bar

Displays or hides the Options Side Bar.

Help | PasHi & PasHiGUI User Guide

Displays the combined user guide for PasHi and PasHiGUI in the default web browser.

Help | About

Displays the program's About Box.

Drag and drop

PasHiGUI supports the following drag and drop operations as a means of inputing source code to be highlighted:

• Drag and drop one or more file names from Windows Explorer: this highlights the dropped file(s). Folders are ignored.
• Drag and drop selected text from a compatible text editor: the selected text is syntax highlighted and is assumed to be valid Pascal source code.

Dependencies

PasHiGUI will not work unless PasHi is installed in the same directory and is the correct version. Using the installer to install both programs is the best means of ensuring that everything is set up correctly.

Deprecated features

Commands, parameters, defaults, CSS styles and configuration files marked as deprecated are likely to removed in the next major release. In the main these are breaking changes: they won't be backwards compatible will the current version.