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