1HISHRINK(1) General Commands Manual HISHRINK(1)
2
6 hishrink- translating ASCII HINT files to binary files
7
9 hishrink [options] [file]
10
12 Shrinking converts an ASCII HINT file, usually with the extension
13 .hint, into a binary HINT file, with the extension .hnt.
14 The ASCII based HINT file format - also called `long' format - is opti‐
16 mized for readability. It can be edited using a text editor. Hence it
17 allows simple modifications that would be difficult to achieve when us‐
18 ing the binary format. It is also convenient when debugging.
19 The binary HINT file format - also called `short' format - is optimized
21 for displaying HINT files. It can be parsed equally well in forward and
22 backward direction to enable fast forward or backward navigation in the
23 file.
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 hishrink understands the following command line op‐
33 tions:
34 -a Use only the localized names for auxiliary files as explained in
36 the FILES section below.
37 If you know that the auxiliary files can be found using the lo‐
39 calized names, for example after creating them with histretch
40 using the -a option, you can use hishrink with the -a option to
41 limit the search for the auxiliar files. If you are unsure, you
42 should use neither the -a nor the -g option. hishrink will then
43 search for auxiliar files first using the localized path names
44 and then using the path names as given.
45 -c Enable the use of compression for the HINT file. Compressed
47 files are smaller but require decompression when viewing. Use
48 only for large files if the file size matters.
49 -d bitmask
51 Sets HINT file debugging flags according to the bitmask. Use
52 the --help option for details.
53 -g Do not use the localized names for auxiliary files as explained
55 in the FILES section below.
56 You may use this option if you know that all auxiliar files are
58 at the locations described by the path names stored in the HINT
59 file. If you are unsure, you should use neither the -g nor the
60 -a option. hishrink will then search for auxiliar files first
61 using the localized path names and then using the path names as
62 given.
63 --help Print help message and exit.
65 -l Redirect standard error to a log file. The name of the log file
67 is derived from the name of the input file replacing the exten‐
68 sion .hint by the extension .log.
69 -o name
71 Use name for the output file instead of deriving it from the
72 name of the input file. Append the extension .hnt if the name
73 does not already has that extension.
74 --version
76 Print version information and exit.
77
79 Binary HINT files must contain all resources necessary to display the
80 file, for example font and image files. These files are called auxil‐
81 iary files. ASCII HINT files contain only the path names of these
82 files.
83 When creating a binary HINT file from an ASCII HINT file, it is neces‐
85 sary to find these files, read them, and include them in the binary
86 output file. When creating an ASCII HINT file from a binary HINT file,
87 it is convenient if these files can be extracted and written to the
88 file system. To avoid clobbering arbitrary directories with files when
89 extracting auxiliary files, it is possible to map the path names as
90 stored in the HINT file to localized path names before writing or read‐
91 ing auxiliar files.
92 When computing a localized path name from a given path name, a distinc‐
94 tion is made between global resources, like fonts, that are referenced
95 by an absolute path name, and local resources, for example an image,
96 that are referenced by a relative path name. The directory that starts
97 the localized path name of the former has the extension .abs and for
98 the latter the extension .rel is used. To keep auxiliary files in
99 these subdirectories even if their path contains links to a parent di‐
100 rectory, parent links `..' are replaced by `__' links to subdirecto‐
101 ries.
102 For example, given an input file paper.hint, the global resources are
104 stored in the paper.abs directory and local resources are stored in pa‐
105 per.rel. An absolute path like /usr/share/fonts/ will then map to the
106 localized path paper.abs/usr/share/fonts/ and a relative path like
107 ../image/img1.jpg will then map to the localized path paper.rel/__/im‐
108 age/img1.jpg.
109
111 This manual page is not meant to be exhaustive. The complete documen‐
112 tation can be found in the HINT: The file format. This document is
113 available as a book or in electronic form from the HINT project home
114 page at https://hint.userweb.mwn.de. There you find additional soft‐
115 ware, most importantly viewers for HINT files, and further information.
116
118 hishrink should compile on a large variety of machine architectures and
119 operating systems. It is part of the TeX Live distribution.
120
122 histretch(1), hitex(1),
123
125 Martin Ruckert
126Version 1.3 11 November 2021 HISHRINK(1)