1HISTRETCH(1) General Commands Manual HISTRETCH(1)
2
6 histretch - translating binary HINT files to ASCII files
7
9 histretch [options] [file]
10
12 Stretching converts a binary HINT file, usually with the extension
13 .hnt, into an ASCII based HINT file, with the extension .hint.
14 The binary HINT file format - also called `short' format - is optimized
16 for displaying HINT files. It can be parsed equally well in forward and
17 backward direction to enable fast forward or backward navigation in the
18 file.
19 The ASCII based HINT file format - also called `long' format - is opti‐
21 mized for readability. It can be edited using a text editor. Hence it
22 allows simple modifications that would be difficult to achieve when us‐
23 ing the binary format. It is also convenient when debugging.
24 The binary HINT file format is designed for on-screen reading of docu‐
26 ments. Using a HINT viewer to display a HINT file, its content will
27 dynamically adapt to the available display area. For complete informa‐
28 tion on the HINT file format and programs to view HINT files, see
29 https://hint.userweb.mwn.de.
30
32 This version of histretch understands the following command line op‐
33 tions:
34 -a Write auxiliar files to disk using the localized path names as
36 explained in the FILES section below.
37 Use this option if you are stretching a HINT file that you later
39 want to shrink back to its binary format unless you know that
40 you have already all the auxiliary files contained in it.
41 -d bitmask
43 Sets HINT file debugging flags according to the bitmask. See
44 the --help option for details.
45 -f Force the replacement of existing auxiliary files. Use this op‐
47 tion together with the -g or -a option to make sure that already
48 exiting auxiliary files are replaced by the auxiliary files con‐
49 tained in the HINT file.
50 WARNING: This is a dangerous option especially together with the
52 -g option. Never use it on a HINT file of unknown origin. It
53 will possibly replace any file on your machine you have write
54 access to. If in doubt, don't use the -f option.
55 -g Write auxiliar files to disk using the path names as stored in
57 the HINT file. This option is an alternative to the -a option
58 and takes precedence if given. If in doubt, don't use the -g
59 option. If you just want to stretch the HINT file, then edit
60 it, and then shrink it back to the binary format, you should use
61 the -a option.
62 You may use this option if you are stretching a HINT file on the
64 same machine and in the same directory where you have created
65 the HINT file. Then all files will be copied to the location
66 they came from in case they were deleted in the meantime.
67 If you are stretching a HINT file on one machine and the file
69 was created on a different machine, histretch will try to copy
70 an auxiliary file into the same directory that was used when the
71 HINT file was created, provided that you have the necessary
72 writing rights. This is probably where you want the auxiliary
73 file assuming that both machines have the same directory struc‐
74 ture.
75 WARNING: This is a dangerous option especially together with the
77 -f option. Never use it on a HINT file of unknown origin. It can
78 possibly write (and replace) any file on your machine where you
79 have write access.
80 --help Print help message and exit.
82 -l Redirect standard error to a log file. The name of the log file
84 is derived from the name of the input file replacing the exten‐
85 sion .hnt by the extension .log.
86 -o name
88 Use name for the output file instead of deriving it from the
89 name of the input file. Append the extension .hint if the name
90 does not already has that extension.
91 -u Enable the use of UTF8 character codes. Without this option,
93 the output file is a pure ASCII file, because character codes
94 outside the ASCII range are written using their numeric repre‐
95 sentation. With this option, the file will always represent
96 printable characters using their UTF8 character codes. This
97 might make the output file more readable if displayed using an
98 UTF8 enabled program; but it might be less readable if displayed
99 by a program that does not handle UTF8 characters properly. See
100 also the -x option.
101 --version
103 Print version information and exit.
104 -x Enable the use of hexadecimal character codes. Without this op‐
106 tion, characters that are not represented using their character
107 codes are represented using a decimal representation of the
108 character code. With this option a hexadecimal representation is
109 used. The range of character codes that have a numeric repre‐
110 sentation includes the non printable characters (character codes
111 smaller than 32) and unless the -u option is given, the charac‐
112 ter codes with a value of 127 and above.
113
115 Binary HINT files must contain all resources necessary to display the
116 file, for example font and image files. These files are called auxil‐
117 iary files. ASCII HINT files contain only the path names of these
118 files.
119 When creating a binary HINT file from an ASCII HINT file, it is neces‐
121 sary to find these files, read them, and include them in the binary
122 output file. When creating an ASCII HINT file from a binary HINT file,
123 it is convenient if these files can be extracted and written to the
124 file system. To avoid clobbering arbitrary directories with files when
125 extracting auxiliary files, it is possible to map the path names as
126 stored in the HINT file to localized path names before writing or read‐
127 ing auxiliar files.
128 When computing a localized path name from a given path name, a distinc‐
130 tion is made between global resources, like fonts, that are referenced
131 by an absolute path name, and local resources, for example an image,
132 that are referenced by a relative path name. The directory that starts
133 the localized path name of the former has the extension .abs and for
134 the latter the extension .rel is used. To keep auxiliary files in
135 these subdirectories even if their path contains links to a parent di‐
136 rectory, parent links `..' are replaced by `__' links to subdirecto‐
137 ries.
138 For example, given an input file paper.hint, the global resources are
140 stored in the paper.abs directory and local resources are stored in pa‐
141 per.rel. An absolute path like /usr/share/fonts/ will then map to the
142 localized path paper.abs/usr/share/fonts/ and a relative path like
143 ../image/img1.jpg will then map to the localized path paper.rel/__/im‐
144 age/img1.jpg.
145
147 This manual page is not meant to be exhaustive. The complete documen‐
148 tation can be found in HINT: The file format. This document is avail‐
149 able as a book or in electronic form from the HINT project home page at
150 https://hint.userweb.mwn.de. There you find additional software, most
151 importantly viewers for HINT files, and further information.
152
154 histretch should compile on a large variety of machine architectures
155 and operating systems. It is part of the TeX Live distribution.
156
158 hishrink(1), hitex(1),
159
161 Martin Ruckert
162Version 1.3 11 November 2021 HISTRETCH(1)