HTags plugin for Take Command / TCC / 4NT

beta version 0.60.4     2013-04-24

Charles Dye

Purpose:

Generating HTML from within a TCC batch file can be tricky, since many of the characters required for HTML — less-than and greater-than signs and ampersands in particular — also have special meaning to TCC. This plugin provides functions which make it easy to write HTML tags and entities from Take Command.

Installation:

To use this plugin, copy HTAGS.DLL to some known location on your hard drive. Load the plugin with a PLUGIN /L command. For example:

plugin /l c:\bin\tcmd\htags\htags.dll

If you copy the .DLL to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically by each new instance of TCC.

Theory:

This plugin takes advantage of Unicode’s “Halfwidth and Fullwidth Forms” block, specifically the characters at U+FF01 through U+FF5E. These characters correspond to ASCII characters 0x21 through 0x7E, and when redirected to a file with //UnicodeOutput=No, they will be automatically translated back to their ASCII equivalents. But TCC doesn’t assign any significance to the characters in this range, so they can be safely used in a batch file. In particular, HTags makes heavy use of U+FF05 (fullwidth percent sign), U+FF06 (fullwidth ampersand), U+FF1C (fullwidth less-than sign), and U+FF1E (fullwidth greater-than sign.) Using these characters gives us HTML tags and entities which can be used in batch files and functions, displayed on screen or redirected to a file, without tripping over TCC’s special syntax characters.

Depending on your font, whether TCC is running in a standalone console window or within a Take Command tab, the phase of the moon, and general Windows witchiness, these characters may or may not appear the same on-screen as their ASCII equivalents. If you see empty boxes instead of normal-looking characters, try a different font. The default “Raster Fonts” works well for me, although it’s not terribly attractive.

One consequence of this approach is that TCC’s Unicode output option must be turned off. If //UnicodeOutput=Yes, then redirected characters will not be translated into ASCII, and you’ll get strange characters in the output file. When any of the new functions are called the plugin will check that Unicode output is disabled, and display an error message if it isn’t.

Syntax Note:

The syntax definitions in the following text use these conventions for clarity:

BOLD CODEindicates text which must be typed exactly as shown.
CODEindicates optional text, which may be typed as shown or omitted.
Bold italicnames a required argument; a value must be supplied.
Regular italicnames an optional argument.
ellipsis…after an argument means that more than one may be given.

Plugin Functions:


@DEENTITIZE — Removes any HTML entities from the input string, substituting equivalent characters where available.

Syntax: @DEENTITIZE[string]

stringthe text to process

The appearance of this function’s output depends on both the character set and the display font. In general, if an entity shows up as a question mark, either the corresponding character does not exist in the current character set, or else this plugin just doesn’t recognize the entity. If an entity appears as a hollow rectangle, it’s usually because the display fonts doesn’t contain a glyph for that character.

C:\> echo %@deentitize[“Here Today — Here Tomorrow!” ®]
"Here Today -- Here Tomorrow!" (R)

C:\>



@DOCTYPE — Returns an HTML document type tag.

Syntax: @DOCTYPE[n]

nwhich document type to return:
   0: HTML 5 (default)
   1: HTML 4.01 strict
   2: HTML 4.01 transitional
   3: HTML 4.01 frameset
   16: XHTML 1.0 strict
   17: XHTML 1.0 transitional
   18: XHTML 1.0 frameset

C:\> echo %@doctype[]
<!DOCTYPE HTML>

C:\>



@ENTAG — Entitizes a string, and encloses it in open-and-close HTML tags.

Syntax: @ENTAG[tag,string]

tagan HTML tag
stringthe string to enclose in tags

tag will be used verbatim for the opening tag. For the closing tag, a slash will be prefixed, and tag will be truncated at the first space (if any). The string will be entitized according to the current plugin settings. It is possible to nest one @ENTAG function within the string argument of another @ENTAG.

C:\> echo %@entag[p,This is a test.]
<p>This is a test.</p>

C:\> echo %@entag[p class="demo","This is a test", he said.]
<p class="demo">&ldquo;This is a test&rdquo;, he said.</p>

C:\> echo %@entag[p,"This is %@entag[em,only] a test", he said.]
<p>&ldquo;This is <em>only</em> a test&rdquo;, he said.</p>

C:\>



@ENTITIZE — Searches a string for special characters, and replaces them with HTML entities.

Syntax: @ENTITIZE[string]

stringthe string to be entitized

See also the HTAGS command, which allows you to change options controlling entitization.

C:\> echo %@entitize["Quick & Silver's"]
&ldquo;Quick&nbsp;&amp; Silver&rsquo;s&rdquo;

C:\>



@HCOMMENT — Returns an HTML comment.

Syntax: @HCOMMENT[string]

stringthe text of the comment

C:\> echo %@hcomment[Hello, world.]
<!-- Hello, world. -->

C:\>



@HEXDEC — Replaces two-digit hex codes with characters in the input string.

Syntax: @HEXDEC[string]

stringthe string to be decoded

Only sequences of a percent sign followed by two valid hexadecimal digits will be replaced. Anything else (e.g. a percent sign followed by a single hex digit) will be returned unchanged. The null character, %00, is not allowed.

C:\> echo %@hexdec[This%%20is%%20a%%20test.]
This is a test.

C:\>



@HEXENC — Replaces troublesome characters in a string with hexadecimal codes.

Syntax: @HEXENC[string]

stringthe string to be hex-encoded

The characters not replaced with hex codes are letters, digits, and these symbols: #$+-./:;=?@_ To define a different list of characters not to hex-encode, create an environment variable named HEXENC_KEEP.

C:\> echo %@hexenc[This is a test.]
This%20is%20a%20test.

C:\>



@MAKEENTITY — Returns an HTML representation for a character.

Syntax: @MAKEENTITY[char¦string]

chara single character, or
stringthe name of an HTML entity

If a single character is specified, the plugin will attempt to find a matching named entity, e.g. &amp;. Failing that, it will return a decimal numeric entity, e.g. &#64;. If a multicharacter string is specified, the plugin will assume it’s the name of an HTML entity, and just wrap it fore-and-aft with an ampersand and a semicolon.

C:\> echo %@makeentity[copy] %@makeentity[@]
&copy; &#64;

C:\>



@TAG — Returns an HTML tag.

Syntax: @TAG[tag]

tagan HTML tag

The argument is simply wrapped in less-than and greater-than signs.

C:\> echo %@tag[p class="bodytext"]
<p class="bodytext">

C:\>



Plugin Commands:

ARRAYTABLE — Dumps a two-dimensional array to stdout as an HTML table.

Syntax: ARRAYTABLE /L:n /H:text /K:class /S:style /CKn:class /CSn:style /LK:class /LS:style arrayname

/Linsert line numbers; /L:n starting at n (default 0)
/H:textcreate a header row
/K:classCSS class name for the TABLE tag
/S:styleCSS style info for the TABLE tag
/CKn:classCSS class name for column n TD tags
/CSn:styleCSS style info for column n TD tags
/LK:classCSS class name for line-number TD tags; implies /L
/LS:styleCSS style info for line-number TD tags; implies /L
/RK0:classCSS class name for TD tags of even-numbered rows
/RK1:classCSS class name for TD tags of odd-numbered rows
/RS0:classCSS style info for TD tags of even-numbered rows
/RS1:classCSS style info for TD tags of odd-numbered rows
arraynamea two-dimensional array variable

The arrayname is required. The variable should be declared and filled with data before running ARRAYTABLE. The first dimension of the array is the row number; the second is the column number. Array cells will be entitized; any empty cell will be stored as a non-breakable space.

• Note: This command is disabled in TCC/LE, and in 4NT/Take Command prior to v10. It is only available in versions which support array variables.



HTAGS — Displays or changes plugin options.

Syntax: HTAGS QUOTES:n SPACES:n DASH:n APOS:n DEFAULTS

Option:0123default
QUOTESdon’t changealways replace with &quot;&ldquo; or &rdquo; (best guess) 2
SPACESdon’t changealways replace with &nbsp;best guess 2
DASHdon’t changereplace -- with &mdash;  1
APOSdon’t changereplace with &#39;replace with &apos;&lsquo; or &rsquo; (best guess)3
 
DEFAULTSresets all options to their default states

At this time, all of the options set or reported by HTAGS control details of how characters in strings are converted to HTML entities. QUOTES controls how the ASCII double-quote character " is handled; SPACES controls the ASCII space character; DASH determines whether or not a double dash, surrounded by spaces, is converted to an &mdash; and APOS controls the ASCII apostrophe, '. DEFAULTS resets all of the above options to their default values.

If no options are specified, HTAGS will display the current settings and the plugin version.



Size Limits:

All strings in this plugin are limited to 16,383 characters. Attempting to pass or return a string longer than 16,383 characters may result in an error message, silent truncation, or possibly even a crash.

Status and Licensing:

Consider this beta software. It may well have issues. Try it at your own risk. If you find a problem, you can report it in the JP Software support forum.

HTags is currently licensed only for testing purposes. I may make binaries and source code available under some free license once I consider it ready for use.

Download:

You can download the current version of the plugin from http://prospero.unm.edu/dl/htags.zip or ftp://prospero.unm.edu/htags.zip.