Debian Codegraph @

texmf-dist/doc/man/man1/hishrink.1

raw
1 .TH HISHRINK 1 "11 November 2021" "Version 1.3"
2 .\"=====================================================================
3 .if n .ds MF Metafont
4 .if t .ds MF Metafont
5 .if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
6 .if n .ds TX TeX
7 .ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP
8 .el .ds OX TeX
9 .\" BX definition must follow TX so BX can use TX
10 .if t .ds BX \fRB\s-2IB\s0\fP\*(TX
11 .if n .ds BX BibTeX
12 .\" LX definition must follow TX so LX can use TX
13 .if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
14 .if n .ds LX LaTeX
15 .if t .ds AX \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(TX
16 .if n .ds AX AmSTeX
17 .if t .ds AY \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(LX
18 .if n .ds AY AmSLaTeX
19 .if n .ds WB Web
20 .if t .ds WB W\s-2EB\s0
21 .\"=====================================================================
22 .SH NAME
23 hishrink\- translating ASCII HINT files to binary files
24 .SH SYNOPSIS
25 .B hishrink
26 .RI [ options ]
27 .RI [ file ]
28 .\"=====================================================================
29 .SH DESCRIPTION
30 Shrinking converts an ASCII HINT file, usually with the extension
31 .BR .hint ,
32 into a binary HINT file, with the extension
33 .BR .hnt .
34 .PP
35 The ASCII based HINT file format - also called `long' format - is optimized
36 for readability. It can be edited using a text editor. Hence it allows
37 simple modifications that would be difficult to achieve when using the binary
38 format. It is also convenient when debugging.
39 .PP
40 The binary HINT file format - also called `short' format - is optimized
41 for displaying HINT files. It can be parsed equally well in forward
42 and backward direction to enable fast forward or backward navigation in the file.
43 .PP
44 The binary HINT file format is designed for on-screen reading of documents.
45 Using a HINT viewer to display a HINT file, its content will dynamically
46 adapt to the available display area. For complete information on the
47 HINT file format and programs to view HINT files, see
48 .BR https://hint.userweb.mwn.de .
49 .\"=====================================================================
50 .SH OPTIONS
51 This version of
52 .B hishrink
53 understands the following command line options:
54 .TP
55 .B -a
56 Use only the localized names for auxiliary files as explained in the
57 .B FILES
58 section below.
59
60 If you know that the auxiliary files can be found using the localized names,
61 for example after creating them with
62 .B histretch
63 using the
64 .B -a
65 option, you can use
66 .B hishrink
67 with the
68 .B -a
69 option to limit the search for the auxiliar files.
70 If you are unsure, you should use neither the
71 .B -a
72 nor the
73 .B -g
74 option.
75 .B hishrink
76 will then search for auxiliar files first using the localized path names
77 and then using the path names as given.
78 .TP
79 .B -c
80 Enable the use of compression for the HINT file. Compressed files are
81 smaller but require decompression when viewing. Use only for large
82 files if the file size matters.
83 .TP
84 .BI -d \ bitmask
85 Sets HINT file debugging flags according to the
86 .IR bitmask .
87 Use the
88 .B --help
89 option for details.
90 .TP
91 .B -g
92 Do not use the localized names for auxiliary files as explained in the
93 .B FILES
94 section below.
95
96 You may use this option if you know that all auxiliar files
97 are at the locations described by the path names stored in the HINT file.
98 If you are unsure, you should use neither the
99 .B -g
100 nor the
101 .B -a
102 option.
103 .B hishrink
104 will then search for auxiliar files first using the localized path names
105 and then using the path names as given.
106 .TP
107 .B --help
108 Print help message and exit.
109 .TP
110 .B -l
111 Redirect standard error to a log file. The name of the log file is derived from
112 the name of the input file replacing the extension
113 .B .hint
114 by the extension
115 .BR .log .
116 .TP
117 .BI -o \ name
118 Use
119 .I name
120 for the output file instead of deriving it from the name of the input file.
121 Append the extension
122 .B .hnt
123 if the
124 .I name
125 does not already has that extension.
126 .TP
127 .B --version
128 Print version information and exit.
129 .\"=====================================================================
130 .SH FILES
131 Binary HINT files must contain all resources necessary to display the file,
132 for example font and image files. These files are called auxiliary files.
133 ASCII HINT files contain only the path names of these files.
134
135 When creating a binary HINT file from an ASCII HINT file, it is
136 necessary to find these files, read them, and include them in the binary output file.
137 When creating an ASCII HINT file from a binary HINT file, it is
138 convenient if these files can be extracted and written to the file system.
139 To avoid clobbering arbitrary directories with files when extracting auxiliary
140 files, it is possible to map the path names as stored in the HINT file
141 to
142 .B localized
143 path names before writing or reading auxiliar files.
144
145 When computing a localized path name from a given path name,
146 a distinction is made between global resources,
147 like fonts, that are referenced by an absolute path name, and local
148 resources, for example an image, that are referenced by a relative
149 path name. The directory that starts the localized path name of the former
150 has the extension
151 .B .abs
152 and for the latter the extension
153 .BR .rel
154 is used.
155 To keep auxiliary files in these subdirectories even if their path
156 contains links to a parent directory, parent links
157 .RB ` .. '
158 are replaced by
159 .RB ` __ '
160 links to subdirectories.
161
162 For example,
163 given an input file
164 .BR paper.hint,
165 the global resources are stored in the
166 .B paper.abs
167 directory and local resources are stored in
168 .BR paper.rel .
169 An absolute path like
170 .B /usr/share/fonts/
171 will then map to the localized path
172 .BR paper.abs/usr/share/fonts/
173 and a relative path like
174 .B ../image/img1.jpg
175 will then map to the localized path
176 .BR paper.rel/__/image/img1.jpg .
177 .\"=====================================================================
178 .SH NOTES
179 This manual page is not meant to be exhaustive. The complete
180 documentation can be found in the
181 .IR "HINT: The file format" .
182 This document is available as a book or in electronic form from the
183 HINT project home page at
184 .BR https://hint.userweb.mwn.de .
185 There you find additional software, most importantly viewers for HINT files,
186 and further information.
187 .\"=====================================================================
188 .SH AVAILABILITY
189 .B hishrink
190 should compile on a large variety of machine architectures
191 and operating systems.
192 It is part of the \*(TX Live distribution.
193 .PP
194 .\"=====================================================================
195 .SH "SEE ALSO"
196 .BR histretch (1),
197 .BR hitex (1),
198 .\"=====================================================================
199 .SH AUTHORS
200 Martin Ruckert
201 .\" vim: syntax=nroff