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 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 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 histretch understands the following command line options:

       -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 option together with the -g or -a
              option to make sure that already exiting auxiliary files  are  replaced  by  the  auxiliary  files
              contained 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 option.
              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 writing 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 extension .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 characters using their
              UTF8 character codes. This might make the output file more readable if  displayed  using  an  UTF8
              enabled program; 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 option, characters that are not
              represented using their character codes are represented using  a  decimal  representation  of  the
              character  code.  With  this  option a hexadecimal representation is used.  The range of character
              codes that have a numeric representation 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 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.

NOTES

       This  manual  page  is  not meant to be exhaustive.  The complete documentation 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)