hishrink - Man Page

hishrink [options] [file]

Shrinking converts an ASCII HINT file, usually with the extension .hint, into a binary HINT file, with the extension .hnt.

The ASCII based HINT file format - also called `long' format - is optimized for readability. It can be edited using a text editor. Hence it allows simple modifications that would be difficult to achieve when using the binary format. It is also convenient when debugging.

The binary HINT file format - also called `short' format - is optimized for displaying HINT files. It can be parsed equally well in forward and backward direction to enable fast forward or backward navigation in the file.

The binary HINT file format is designed for on-screen reading of documents.  Using a HINT viewer to display a HINT file, its content will dynamically adapt to the available display area. For complete information on the HINT file format and programs to view HINT files, see https://hint.userweb.mwn.de.

This version of hishrink understands the following command line options:

-a

Use only the localized names for auxiliary files as explained in the Files section below.

If you know that the auxiliary files can be found using the localized names, for example after creating them with histretch using the -a option, you can use hishrink with the -a option to limit the search for the auxiliar files. If you are unsure, you should use neither the -a nor the -g option. hishrink will then search for auxiliar files first using the localized path names  and then using the path names as given.

-c

Enable the use of compression for the HINT file. Compressed files are smaller but require decompression when viewing. Use only for large files if the file size matters.

-d bitmask

Sets HINT file debugging flags according to the bitmask. Use the --help option for details.

-g

Do not use the localized names for auxiliary files as explained in the Files section below.

You may use this option if you know that all auxiliar files are at the locations described by the path names stored in the HINT file. If you are unsure, you should use neither the -g nor the -a option. hishrink will then search for auxiliar files first using the localized path names  and then using the path names as given.

--help

Print help message and exit.

-l

Redirect standard error to a log file. The name of the log file is derived from the name of the input file replacing the extension .hint by the extension .log.

-o name

Use name for the output file instead of deriving it from the name of the input file. Append the extension .hnt if the name does not already has that extension.

--version

Print version information and exit.

Binary HINT files must contain all resources necessary to display the file, for example font and image files.  These files are called auxiliary files. ASCII HINT files contain only the path names of these files.

When creating a binary HINT file from an ASCII HINT file, it is necessary to find these files, read them, and include them in the binary output file. When creating an ASCII HINT file from a binary HINT file, it is convenient if these files can be extracted and written to the file system. To avoid clobbering arbitrary directories with files when extracting auxiliary  files, it is possible to map the path names as stored in the HINT file to localized path names before writing or reading auxiliar files.

When computing a localized path name from a given path name, a distinction is made between global resources, like fonts, that are referenced by an absolute path name, and local resources, for example an image, that are referenced by a relative path name. The directory that starts the localized path name of the former  has the extension .abs and for the latter the extension .rel is used. To keep auxiliary files in these subdirectories even if their path contains links to a parent directory, parent links `..' are replaced by `__' links to subdirectories.

For example, given an input file paper.hint, the global resources are stored in the paper.abs directory and local resources are stored in paper.rel. An absolute path like /usr/share/fonts/ will then map to the localized path paper.abs/usr/share/fonts/ and a relative path like ../image/img1.jpg will then map to the localized path paper.rel/__/image/img1.jpg.

This manual page is not meant to be exhaustive.  The complete documentation can be found in the HINT: The file format. This document is available as a book or in electronic form from the  HINT project home page at https://hint.userweb.mwn.de. There you find additional software, most importantly viewers for HINT files, and further information.

hishrink should compile on a large variety of machine architectures and operating systems. It is part of the T E X Live distribution.

histretch(1), hitex(1),

Martin Ruckert

histretch(1), hitex(1).