HISTRETCH(1) General Commands Manual HISTRETCH(1)
NAME
histretch - translating binary HINT files to ASCII files
SYNOPSIS
histretch [options] [file]
DESCRIPTION
Stretching converts a binary HINT file, usually with the extension .hnt,
into an ASCII based HINT file, with the extension .hint.
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 ASCII based HINT file format - also called `long' format - is opti-
mized for readability. It can be edited using a text editor. Hence it
allows simple modifications that would be difficult to achieve when us-
ing the binary format. It is also convenient when debugging.
The binary HINT file format is designed for on-screen reading of docu-
ments. Using a HINT viewer to display a HINT file, its content will dy-
namically 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.
OPTIONS
This version of histretch understands the following command line op-
tions:
-a Write auxiliar files to disk using the localized path names as
explained in the FILES section below.
Use this option if you are stretching a HINT file that you later
want to shrink back to its binary format unless you know that you
have already all the auxiliary files contained in it.
-d bitmask
Sets HINT file debugging flags according to the bitmask. See the
--help option for details.
-f Force the replacement of existing auxiliary files. Use this op-
tion together with the -g or -a option to make sure that already
exiting auxiliary files are replaced by the auxiliary files con-
tained in the HINT file.
WARNING: This is a dangerous option especially together with the
-g option. Never use it on a HINT file of unknown origin. It will
possibly replace any file on your machine you have write access
to. If in doubt, don't use the -f option.
-g Write auxiliar files to disk using the path names as stored in
the HINT file. This option is an alternative to the -a option
and takes precedence if given. If in doubt, don't use the -g op-
tion. If you just want to stretch the HINT file, then edit it,
and then shrink it back to the binary format, you should use the
-a option.
You may use this option if you are stretching a HINT file on the
same machine and in the same directory where you have created the
HINT file. Then all files will be copied to the location they
came from in case they were deleted in the meantime.
If you are stretching a HINT file on one machine and the file was
created on a different machine, histretch will try to copy an
auxiliary file into the same directory that was used when the
HINT file was created, provided that you have the necessary writ-
ing rights. This is probably where you want the auxiliary file
assuming that both machines have the same directory structure.
WARNING: This is a dangerous option especially together with the
-f option. Never use it on a HINT file of unknown origin. It can
possibly write (and replace) any file on your machine where you
have write access.
--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 exten-
sion .hnt 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 .hint if the name does
not already has that extension.
-u Enable the use of UTF8 character codes. Without this option, the
output file is a pure ASCII file, because character codes outside
the ASCII range are written using their numeric representation.
With this option, the file will always represent printable char-
acters using their UTF8 character codes. This might make the out-
put file more readable if displayed using an UTF8 enabled pro-
gram; but it might be less readable if displayed by a program
that does not handle UTF8 characters properly. See also the -x
option.
--version
Print version information and exit.
-x Enable the use of hexadecimal character codes. Without this op-
tion, characters that are not represented using their character
codes are represented using a decimal representation of the char-
acter code. With this option a hexadecimal representation is
used. The range of character codes that have a numeric represen-
tation includes the non printable characters (character codes
smaller than 32) and unless the -u option is given, the character
codes with a value of 127 and above.
FILES
Binary HINT files must contain all resources necessary to display the
file, for example font and image files. These files are called auxil-
iary 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 neces-
sary to find these files, read them, and include them in the binary out-
put 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 ex-
tracting auxiliary files, it is possible to map the path names as stored
in the HINT file to localized path names before writing or reading aux-
iliar files.
When computing a localized path name from a given path name, a distinc-
tion 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 pa-
per.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/__/im-
age/img1.jpg.
NOTES
This manual page is not meant to be exhaustive. The complete documenta-
tion can be found in 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.
AVAILABILITY
histretch should compile on a large variety of machine architectures and
operating systems. It is part of the TeX Live distribution.
SEE ALSO
hishrink(1), hitex(1),
AUTHORS
Martin Ruckert
Version 1.3 11 November 2021 HISTRETCH(1)
Generated by dwww version 1.16 on Tue Dec 16 06:36:02 CET 2025.