{
    "mode": "man",
    "parameter": "histretch",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/histretch/1/json",
    "generated": "2026-11-22T16:03:48Z",
    "synopsis": "histretch [options] [file]",
    "sections": {
        "NAME": {
            "content": "histretch - translating binary HINT files to ASCII files\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "histretch [options] [file]\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Stretching converts a binary HINT file, usually with the extension .hnt, into an  ASCII based\nHINT file, with the extension .hint.\n\nThe  binary  HINT file format - also called `short' format - is optimized for displaying HINT\nfiles. It can be parsed equally well in forward and backward direction to enable fast forward\nor backward navigation in the file.\n\nThe ASCII based HINT file format - also called `long' format - is optimized for  readability.\nIt can be edited using a text editor. Hence it allows simple modifications that would be dif‐\nficult to achieve when using the binary format. It is also convenient when debugging.\n\nThe  binary  HINT  file  format is designed for on-screen reading of documents.  Using a HINT\nviewer to display a HINT file, its content will dynamically adapt to  the  available  display\narea.  For  complete information on the HINT file format and programs to view HINT files, see\nhttps://hint.userweb.mwn.de.\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "This version of histretch understands the following command line options:\n",
            "subsections": [
                {
                    "name": "-a",
                    "content": "section below.\n\nUse  this  option if you are stretching a HINT file that you later want to shrink back\nto its binary format unless you know that you have already  all  the  auxiliary  files\ncontained in it.\n",
                    "flag": "-a"
                },
                {
                    "name": "-d",
                    "content": "Sets  HINT  file  debugging flags according to the bitmask.  See the --help option for\ndetails.\n",
                    "flag": "-d"
                },
                {
                    "name": "-f",
                    "content": "-g  or -a option to make sure that already exiting auxiliary files are replaced by the\nauxiliary files contained in the HINT file.\n\nWARNING: This is a dangerous option especially together with the -g option. Never  use\nit on a HINT file of unknown origin. It will possibly replace any file on your machine\nyou have write access to.  If in doubt, don't use the -f option.\n",
                    "flag": "-f"
                },
                {
                    "name": "-g",
                    "content": "option is an alternative to the -a option and takes precedence if given.  If in doubt,\ndon't use the -g option.  If you just want to stretch the HINT file, then edit it, and\nthen shrink it back to the binary format, you should use the -a option.\n\nYou may use this option if you are stretching a HINT file on the same machine  and  in\nthe same directory where you have created the HINT file. Then all files will be copied\nto the location they came from in case they were deleted in the meantime.\n\nIf you are stretching a HINT file on one machine and the file was created on a differ‐\nent machine, histretch will try to copy an auxiliary file into the same directory that\nwas  used when the HINT file was created, provided that you have the necessary writing\nrights.  This is probably where you want the auxiliary file  assuming  that  both  ma‐\nchines have the same directory structure.\n\nWARNING:  This is a dangerous option especially together with the -f option. Never use\nit on a HINT file of unknown origin. It can possibly write (and replace) any  file  on\nyour machine where you have write access.\n\n--help Print help message and exit.\n",
                    "flag": "-g"
                },
                {
                    "name": "-l",
                    "content": "name of the input file replacing the extension .hnt by the extension .log.\n",
                    "flag": "-l"
                },
                {
                    "name": "-o",
                    "content": "Use name for the output file instead of deriving it from the name of the  input  file.\nAppend the extension .hint if the name does not already has that extension.\n",
                    "flag": "-o"
                },
                {
                    "name": "-u",
                    "content": "pure ASCII file, because character codes outside the ASCII  range  are  written  using\ntheir numeric representation.  With this option, the file will always represent print‐\nable characters using their UTF8 character codes. This might make the output file more\nreadable  if displayed using an UTF8 enabled program; but it might be less readable if\ndisplayed by a program that does not handle UTF8 characters properly. See also the  -x\noption.\n",
                    "flag": "-u"
                },
                {
                    "name": "--version",
                    "content": "Print version information and exit.\n",
                    "long": "--version"
                },
                {
                    "name": "-x",
                    "content": "are not represented using their character codes are represented using a decimal repre‐\nsentation of the character code. With this  option  a  hexadecimal  representation  is\nused.   The  range  of character codes that have a numeric representation includes the\nnon printable characters (character codes smaller than 32) and unless the -u option is\ngiven, the character codes with a value of 127 and above.\n",
                    "flag": "-x"
                }
            ]
        },
        "FILES": {
            "content": "Binary HINT files must contain all resources necessary to display the file, for example  font\nand  image files.  These files are called auxiliary files.  ASCII HINT files contain only the\npath names of these files.\n\nWhen creating a binary HINT file from an ASCII HINT file,  it  is  necessary  to  find  these\nfiles,  read  them,  and include them in the binary output file.  When creating an ASCII HINT\nfile from a binary HINT file, it is convenient if these files can be extracted and written to\nthe file system.  To avoid clobbering arbitrary directories with files when extracting auxil‐\niary files, it is possible to map the path names as stored in the HINT file to localized path\nnames before writing or reading auxiliar files.\n\nWhen computing a localized path name from a given path name, a distinction  is  made  between\nglobal  resources,  like  fonts,  that are referenced by an absolute path name, and local re‐\nsources, for example an image, that are referenced by a relative  path  name.  The  directory\nthat  starts  the localized path name of the former has the extension .abs and for the latter\nthe extension .rel is used.  To keep auxiliary files in these subdirectories  even  if  their\npath  contains  links to a parent directory, parent links `..'  are replaced by `' links to\nsubdirectories.\n\nFor example, given an input file paper.hint, the global resources are stored in the paper.abs\ndirectory  and  local  resources  are  stored  in   paper.rel.    An   absolute   path   like\n/usr/share/fonts/  will then map to the localized path paper.abs/usr/share/fonts/ and a rela‐\ntive path like ../image/img1.jpg  will  then  map  to  the  localized  path  paper.rel//im‐\nage/img1.jpg.\n",
            "subsections": []
        },
        "NOTES": {
            "content": "This  manual  page is not meant to be exhaustive.  The complete documentation can be found in\nHINT: The file format.  This document is available as a book or in electronic form  from  the\nHINT  project  home page at https://hint.userweb.mwn.de.  There you find additional software,\nmost importantly viewers for HINT files, and further information.\n",
            "subsections": []
        },
        "AVAILABILITY": {
            "content": "histretch should compile on a large variety of machine architectures and  operating  systems.\nIt is part of the TeX Live distribution.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "hishrink(1), hitex(1),\n",
            "subsections": []
        },
        "AUTHORS": {
            "content": "Martin Ruckert\n\nVersion 1.3                               11 November 2021                              HISTRETCH(1)",
            "subsections": []
        }
    },
    "summary": "histretch - translating binary HINT files to ASCII files",
    "flags": [
        {
            "flag": "-a",
            "long": null,
            "arg": null,
            "description": "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."
        },
        {
            "flag": "-d",
            "long": null,
            "arg": null,
            "description": "Sets HINT file debugging flags according to the bitmask. See the --help option for details."
        },
        {
            "flag": "-f",
            "long": null,
            "arg": null,
            "description": "-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."
        },
        {
            "flag": "-g",
            "long": null,
            "arg": null,
            "description": "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 differ‐ ent 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 ma‐ chines 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."
        },
        {
            "flag": "-l",
            "long": null,
            "arg": null,
            "description": "name of the input file replacing the extension .hnt by the extension .log."
        },
        {
            "flag": "-o",
            "long": null,
            "arg": null,
            "description": "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."
        },
        {
            "flag": "-u",
            "long": null,
            "arg": null,
            "description": "pure ASCII file, because character codes outside the ASCII range are written using their numeric representation. With this option, the file will always represent print‐ able 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."
        },
        {
            "flag": "",
            "long": "--version",
            "arg": null,
            "description": "Print version information and exit."
        },
        {
            "flag": "-x",
            "long": null,
            "arg": null,
            "description": "are not represented using their character codes are represented using a decimal repre‐ sentation 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."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "hishrink",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/hishrink/1/json"
        },
        {
            "name": "hitex",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/hitex/1/json"
        }
    ]
}