Manual pages of res2image 0.3

If no options are specified, the program res2image reads a single fragment of RES encoding (or of REScode) from standard input, possibly consisting of several lines, and turns it into a TIFF image, which is stored in file noname.tif. Furthermore, two lines are written to standard output. The first contains the string "noname", followed by four real numbers expressing the sizes of the left, bottom, right and top margins, in inches. The second line contains a header and/or a switch for values that hold at the end of the encoding and that differ from the defaults. (In the case of REScode input, the second line contains a fragment of REScode with zero groups.)

In general, the names of files where images are stored each consist of a base name, then a suffix, and then an extension. The base name is by default the name "noname", but can be changed to a different base_name by option -b (see below). The suffix is the empty string for the basic mode (see below), it consists of one number for the repeat mode, and it consists of two numbers separated by a hyphen for the multi mode. The extension can be .tif, .pnm, .ps or .eps.

To the basic, the repeat and the multi modes, the following applies. For each image, the base name followed by the suffix (but not the extension) is written to an odd line of the (standard) output, followed by the sizes of the margins. The even lines of the (standard) output each contain a fragment of RES encoding, possibly containing a header and/or a switch and/or hieroglyphic. (In the case of REScode input, the even lines contain fragments of REScode.) If the output fragment starts with a space, this signals that the required processing could not be carried through (see below). Otherwise, output fragments never contain superfluous layout characters.

For the echo mode, each line of the (standard) output contains a fragment; no names of files are output since no images are generated.

Options

Options are processed from left to right. If two options are specified that are in conflict, the right-most option overrides the left-most one. Empty strings at options -e, -o and -pipe are seen as denoting non-existence of a specified value; e.g. -o "" is equivalent to not specifying the option -o at all.

`[-help]`

With this option, res2image only prints a list of the allowable options to standard output.

`[-version]`

With this option, res2image only prints the number and date of the current version of res2image to standard output.

`[-basic] [-repeat] [-multi] [-echo]`

There are four possible modes. In the basic mode, which is the default, the input is a single fragment of RES encoding (or REScode), possibly consisting of several lines. If a length restriction is specified by the option -length (see below), then the longest prefix of the encoding that fits within the length restriction is turned into an image, and the base name is written to the first line of the output, followed by the sizes of the margins. The second line of the output contains the remainder of the encoding, possibly preceded by a header and/or a switch in the case of RES values that differ from the defaults; if no length restriction was specified, the remainder will consist solely of a possible header and/or switch, since the complete fragment is turned into an image. (In the case of REScode input, the second line consists of a REScode fragment expressing the remainder, which is possibly empty.) If nothing at all can be processed from the input, because the hieroglyphic starts with a large top_group and the length restriction is too narrow, then no image is generated and the first line of the output remains empty, and the second line of the output starts with a space, possibly followed by a header and/or a switch, and by the hieroglyphic. (The same happens in the case of REScode input if the first group is too large: the output REScode is preceded by a space.)

In the repeat mode, the input is processed repeatedly, each time as much of it is turned into an image as fits within the length restriction. The first line contains the names (without extensions) of the files where the images are stored, each of which consists of the base name and a unique number. The names are followed by the sizes of the margins. The input is processed until either it is completely exhausted, or a top_group (or group for REScode) is encountered that does not fit within the length restriction. In the first case, the second line of the output may contain merely a header and/or a switch. In the second case, the second line starts with a space, then may contain a header and/or a switch, and the suffix of the input starting with the offending top_group. (For REScode input, the output fragment is preceded by a space in the second case.)

In the multi mode, the input is assumed to consist of several fragments, each on one line, and each line is processed as if by the repeat mode. That means that the output consists of twice as many lines as the input. The names of the files where images are stored each consist of a base name followed by two numbers separated by a hyphen (and by an extension, which is omitted in the output as usual). The first number is the number of the corresponding input line.

In the echo mode, the input is assumed to consist of several fragments, each on one line, as in the multi mode. However, these are merely echoed back in a normalized form to the output. No images are written in the echo mode. The echo mode can be used to test syntactic validity of RES encoding or REScode.

The four modes are mutually exclusive in the sense that specifying one of the four options overrides all other occurrences specified earlier on the same command line.

`[-grayscale] [-bilevel] [-palette] [-color]`

There are four types of graphical output, the default being grayscale, i.e. pixels are shades of gray. Bilevel means that each pixel is either black or white. Palette means that each pixel is of one of 16 colors. Color means that these 16 colors may also occur in different shades.

Bilevel is about 8 times more compact than grayscale. Grayscale is about 3 times more compact than color. For TIFF and (encapsulated) postscript, palette is about 2 times more compact than grayscale. For PNM however, palette is no more compact than color.

If no colors are actually needed for a certain fragment, then a palette image is automatically converted to bilevel, and a color image is converted to grayscale, overriding the options -palette and -color respectively.

The four options above are mutually exclusive, i.e. res2image only creates images of one type at a time.

`[-tif] [-pnm] [-ps] [-eps] [-code]`

Images can be generated in four pixel formats, viz. TIFF, PNM, postscript and encapsulated postscript, and in one symbolic format (viz. REScode); the default is TIFF. The file names where pixel formats are stored consist of a base name, a suffix, and extensions .tif, .pnm, .ps, or .eps, respectively. For REScode, the representation is not stored in a file, but written to output, in place of the file name and the sizes of the margins.

The five options above are mutually exclusive, i.e. res2image only creates images in one graphical format at a time.

`[-noline] [-underline] [-overline]`

If no colors are available, colored glyphs can be indicated by underlining or overlining them. The default is that glyphs are not underlined or overlined, as specified by -noline. In the case of vertical text, underlining (or overlining) means that a vertical line is placed at the left side (or right side) for a left-to-right direction, and at the right side (or left side) for a right-to-left direction.

The three options above are mutually exclusive.

`[-linedist line_distance]`

Specifies the distance in EM between underlines or overlines and the main hieroglyphic text; line_distance is a real number. The default is 0.13.

The value of line_distance is ignored in the case of -noline.

`[-linesize line_thickness]`

Specifies the thickness in EM of underlines or overlines; line_thickness is a non-negative real number. The default is 0.04.

The value of line_thickness is ignored in the case of -noline.

`[-linegray line_grayness]`

Specifies the darkness of underlines or overlines; line_grayness is an integer between 0 and 255, where 0 means white (invisible) and 255 means black. The default is 200.

The value of line_grayness is ignored in the case of -noline, and also in the case of -bilevel or -palette.

`[-linecolor line_color]`

Specifies the color of underlines or overlines. The default is black and the other allowable colors are red, green, blue, white, aqua, fuchsia, gray, lime, maroon, navy, olive, purple, silver, teal, and yellow.

The value of line_color is ignored in the case of -noline, and also in the case of -bilevel or -grayscale.

`[-dpi device_resolution]`

Specifies the device resolution, in dots per inch; device_resolution is a positive integer. The default is 72.

`[-fontsize font_size]`

Specifies the font size, i.e. the size of EM, expressed in points; font_size is a positive integer. The default is 45.

`[-f fonts_file]`

Specifies the file that determines which font files are to be loaded and how the glyph names are to be mapped to indices in those font files. The default is the file fonts.txt in the directory where the res2image program is located.

`[-e encoding_file]`

Specifies the name of the file that contains the input RES encoding or REScode; by default, the encoding is read from standard input. In the basic mode and repeat mode, the encoding is assumed to consist of a single fragment, possibly containing newlines. In the multi mode and echo mode, the input is considered to contain several fragments, each on one separate line.

`[-o output_file]`

Specifies the name of the file to which output is written; by default, output is written to standard output. In the basic, repeat and multi modes, the odd lines (starting with the first line) contain names (without extensions) of files where images are stored, followed by the sizes of the four margins. The even lines each contain a fragment that may be fed back to res2image in a next iteration.

In the echo mode, there is no distinction between even and odd lines and all lines contain fragments.

`[-b base_name]`

Specifies the base name of files in which images are stored. The default is "noname". The base name is followed by a suffix and an extension to form the actual file name. The suffix is the empty string for the basic mode, a number for the repeat mode, and two numbers separated by a hyphen for the multi mode. The extension can be .tif, .pnm, .ps or .eps.

`[-pipe command]`

Instead of writing images directly to files, one may also pipe them to a command, which may contain the string "%s" zero or more times; each such string is replaced by the base name plus the suffix (but without the extension). For the character "%" itself in the command, write "%%".

The pipe option can be used to have res2image write images in other formats than TIFF, PNM or (encapsulated) postscript, by means of external programs that may or may not have been installed on the user's platform.

For example, to produce GIF images, one may use:

res2image -pnm -pipe "ppmtogif > %s.gif 2> /dev/null"

making use of the external program ppmtogif to convert PNM to GIF. With colors, additional use of ppmquant may be necessary:

res2image -color -pnm -pipe "ppmquant 256 | ppmtogif > %s.gif"

For another example, compressed TIFF images can be obtained by:

res2image -pipe "cat > %s.tmp; tiffcp -c packbits %s.tmp %s.tif 2> /dev/null; rm %s.tmp"

making use of the external program tiffcp to convert TIFF files.

`[-freedir] [-hlr] [-hrl] [-vlr] [-vrl] [-h] [-v] [-lr] [-rl] [-hlrspec]`

The options -hlr, -hrl, -vlr, -vrl override the directions specified in RES fragments and force a horizontal left-to-right, horizontal right-to-left, vertical left-to-right or vertical right-to-left direction. The options -h and -v merely force a horizontal or vertical direction, maintaining the left-to-right or right-to-left direction as determined by the fragment. Similarly, the options -lr and -rl force a left-to-right or right-to-left direction, maintaining the horizontal or vertical direction as determined by the fragment.

The option -hlrspec is like -hlr, but in addition to forcing a horizontal left-to-right direction, it also puts a symbol at the beginning of the first image generated for each fragment that specifies the direction in the encoding.

The default is -freedir, which means that the directions are taken that are specified in the fragments. The above 10 options are mutually exclusive.

In the case of REScode input, the options -h, -v and -hlrspec are ignored. Further, -hlrspec, -hlr and -vlr have the same meaning as -lr, and -hrl and -vrl have the same meaning as -rl. This is because the choice between horizontal and vertical direction is fixed in REScode, and only left-to-right and right-to-left can be switched.

`[-size size]`

Value size is a non-negative real number. If positive, it overrides the value for 'size' specified in RES fragments. The default is 0, which means that the unit size is taken as specified in the fragments.

This option is ignored in the case of REScode input.

`[-specdist spec_distance]`

Specifies the distance in EM between the symbol indicating the direction, and the following hieroglyphic; spec_distance is a non-negative real number. The default is 0.20.

The value of spec_distance is ignored unless the option -hlrspec is specified.

`[-speccolor spec_color]`

Specifies the color of the symbol indicating the direction. The color can be chosen from the collection of 16 colors above (see option -linecolor). The default is black.

The value of spec_color is ignored unless the option -hlrspec is specified.

`[-length length]`

Specifies the maximal length (width for horizontal directions and height for vertical directions) of one image, expressed in inches; length is a real number, and a negative number means there is no length restriction, which is the default. The suffix of a fragment that does not fit within the specified length restriction is output (for the basic mode), or is reprocessed in a next iteration (for the repeat mode and the multi mode), as explained above.

`[-padding padding_factor]`

If a maximum length is specified by option -length and if the image would otherwise be smaller than this length, then extra white space may be inserted at occurrences of the operator '-' to make it longer (provided no argument 'fix' is specified there), but only if the image can be made precisely length long by inserting no more than a certain amount of additional white space per occurrence of '-', specified by the padding_factor; padding_factor is a non-negative real number, and expresses a distance in terms of the `sep' factor of the font in the case of RES input. In the case of REScode input, the padding_factor is in terms of the average separation between groups in a fragment. (Such separations are determined by subtracting the lengths from the increments.) The default is 1, which in the case of RES means that the distance between top_groups in hieroglyphic can become at most twice as large as normal.

`[-lm margin] [-bm margin] [-rm margin] [-tm margin]`

These specify the sizes of the margins around the actual hieroglyphic, where lm stands for left margin, bm stands for bottom margin, rm stands for right margin, and tm stands for top margin; all margins are non-negative real numbers, expressed in inches, which default to 0.

Independent of the above options, margins are automatically enlarged when necessary to ensure that all glyphs (cf. function modify) and notes fall within the image.

`[-shadegray shading_grayness]`

Shading is indicated by diagonal lines. The grayness of these lines is specified by option -shadegray; shading_grayness is an integer between 0 and 255, where 0 means white (invisible) and 255 means black. The default is 100.

The value of shading_grayness is ignored in the case of -bilevel or -palette.

`[-shadefreq shading_frequency]`

Specifies the number of diagonal lines per EM; shading_frequency is a non-negative integer. If shading_frequency is 1, then there is one single diagonal line across an area of 1 EM high and 1 EM wide. The value 0 deactivates shading completely. The default is 10.

`[-shadecover shading_cover]`

Specifies the portion of the surface that is covered by the diagonal lines; shading_cover is a positive integer. If shading_cover is 1, then the surface is completely covered. In general, the surface that is covered by diagonal lines is 1 / shading_cover. The default is 10.

`[-shadecolor shading_color]`

Specifies the color of the diagonal lines. The color can be chosen from the collection of 16 colors above (see option -linecolor). The default is black.

The value of shading_color is ignored in the case of -bilevel or -grayscale.

`[-notesize note_font_size]`

Specifies the font size for notes, expressed in points; note_font_size is a positive integer. The default is 12.

This option is ignored for REScode input.

`[-notedist note_distance]`

Specifies the minimal distance in points between notes and glyphs and/or shaded areas; note_distance is a non-negative integer. The default is 3.

This option is ignored for REScode input.

`[-notecolor note_color]`

Specifies the default color of notes. The color can be chosen from the collection of 16 colors above (see option -linecolor). The default is black.

The value of note_color is ignored in the case of -bilevel or -grayscale. This option is also ignored for REScode input.

Examples of use

We assume "$ " stands for the Unix prompt. The lines that are read from standard input are preceded by "> ", and "Ctrl-D" stands for the combination of the Control key and the key "D".

The following creates a TIFF image of a sitting man and a sitting woman, stored in file noname.tif. We assume a program xv is available for viewing TIFF files.
```
$ res2image
> A1 - B1
> Ctrl-D
noname 0.0000 0.0000 0.0000 0.0000

$ xv noname.tif
```
Note that the second line output by res2image is empty.
In the following, the image is horizontally right-to-left, in color, and in encapsulated postscript. The colored glyph is furthermore marked with a maximally dark underline. The resolution is 100 dots per inch. The image is written to myimage.eps. We assume a program ghostview is available for viewing (encapsulated) postscript. (An alternative command on your platform may be gv.)
```
$ res2image -hrl -color -eps -underline -linegray 255 -dpi 100 -b myimage
> [size=2] A1 - ![red] B1
> Ctrl-D
myimage 0.0000 0.1100 0.0000 0.0000
[size=2.00]![red]
$ ghostview myimage.eps
```
Note that the header '[size=2.00]' and the switch '![red]' are echoed back, since these are values that are different from the defaults and that hold at the end of the input fragment. Further note that the underline has lead to the creation of a non-empty bottom margin.
In the following, the actual encoding indicates a vertical right-to-left direction, but this is overridden by the option -hlrspec, which forces a horizontal left-to-right direction, and puts a symbol in front of the image indicating that the direction in the encoding is verticall right-to-left; this symbol is printed in green. The image is in palette.
```
$ res2image -palette -hlrspec -speccolor green
> [vrl] A1 - B2[red]
> Ctrl-D
noname 0.0000 0.0000 0.0000 0.0000
[vrl]
$ xv noname.tif
```
The following demonstrates the use of the multi mode. The input consists of several lines. Each is broken up into pieces to create images that fit within the length restriction. For the first input line, this length restriction refers to the height since the fragment has a vertical direction.
```
$ res2image -multi -length 1 2> /dev/null 
> [vrl] X1-X2
noname1-1 0.0000 0.0000 0.0000 0.0000
[vrl]
> ![red] A1-B1-C1-D1-oval(E1-F1-G1-H1)-I1
noname2-1 0.0000 0.0000 0.0000 0.0000 noname2-2 0.0000 0.0000 0.0000 0.0000
 ![red]oval(E1-F1-G1-H1)-I1
> Ctrl-D 
```
The first fragment entirely fits within 1 inch, so only one image is created. For the second fragment, two images are written before the box is encountered, which is longer than 1 inch, and therefore processing of the second input line prematurely stops. Note the space at the beginning of the fourth output line.
Without 2> /dev/null at the end of the command line, the following is furthermore written to standard error:
```
Warning: nothing could be processed from:
![red]oval(E1-F1-G1-H1)-I1
```