man > hishrink(1)

HISHRINK(1)                            General Commands Manual                           HISHRINK(1)

NAME
       hishrink- translating ASCII HINT files to binary files

SYNOPSIS
       hishrink [options] [file]

DESCRIPTION
       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 dif‐
       ficult 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.

OPTIONS
       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 be‐
              low.

              If you know that the auxiliary files can be found using the localized names, for exam‐
              ple  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  re‐
              quire 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 de‐
              scribed 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.

FILES
       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 auxil‐
       iary 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 re‐
       sources, 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 rela‐
       tive 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 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 soft‐
       ware, most importantly viewers for HINT files, and further information.

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

SEE ALSO
       histretch(1), hitex(1),

AUTHORS
       Martin Ruckert

Version 1.3                               11 November 2021                               HISHRINK(1)