Debian Codegraph @

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

raw
1 .TH HISTRETCH 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 histretch \- translating binary HINT files to ASCII files
24 .SH SYNOPSIS
25 .B histretch
26 .RI [ options ]
27 .RI [ file ]
28 .\"=====================================================================
29 .SH DESCRIPTION
30 Stretching converts a binary HINT file, usually with the extension
31 .BR .hnt ,
32 into an ASCII based HINT file, with the extension
33 .BR .hint .
34 .PP
35 The binary HINT file format - also called `short' format - is optimized
36 for displaying HINT files. It can be parsed equally well in forward
37 and backward direction to enable fast forward or backward navigation in the file.
38 .PP
39 The ASCII based HINT file format - also called `long' format - is optimized
40 for readability. It can be edited using a text editor. Hence it allows
41 simple modifications that would be difficult to achieve when using the binary
42 format. It is also convenient when debugging.
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 histretch
53 understands the following command line options:
54 .TP
55 .B -a
56 Write auxiliar files to disk using the localized path names as explained in the
57 .B FILES
58 section below.
59
60 Use this option if you are stretching a HINT file that you later want
61 to shrink back to its binary format unless you know that you have
62 already all the auxiliary files contained in it.
63 .TP
64 .BI -d \ bitmask
65 Sets HINT file debugging flags according to the
66 .IR bitmask .
67 See the
68 .B --help
69 option for details.
70 .TP
71 .B -f
72 Force the replacement of existing auxiliary files.
73 Use this option together with the
74 .B -g
75 or
76 .B -a
77 option to make sure that already exiting auxiliary files are replaced by the
78 auxiliary files contained in the HINT file.
79
80 .BR WARNING :
81 This is a dangerous option especially together with the
82 .B -g
83 option. Never use it on a HINT file of unknown
84 origin. It will possibly replace any file on your machine you have
85 write access to. If in doubt, don't use the
86 .B -f
87 option.
88 .TP
89 .B -g
90 Write auxiliar files to disk using the path names as stored in the HINT file.
91 This option is an alternative to the
92 .B -a
93 option and takes precedence if given.
94 If in doubt, don't use the
95 .B -g
96 option.
97 If you just want to stretch the HINT file, then edit it, and then shrink
98 it back to the binary format, you should use the
99 .B -a
100 option.
101
102 You may use this option if you are stretching a HINT file on the same machine and in
103 the same directory where you have created the HINT file. Then all files
104 will be copied to the location they came from in case they were deleted
105 in the meantime.
106
107 If you are stretching a HINT file on one machine and the file was created
108 on a different machine,
109 .B histretch
110 will try to copy an auxiliary file
111 into the same directory that was used when the HINT file was created, provided that
112 you have the necessary writing rights.
113 This is probably where you want the auxiliary file assuming that both machines have the
114 same directory structure.
115
116 .BR WARNING :
117 This is a dangerous option especially together with the
118 .B -f
119 option. Never use it on a HINT file of unknown
120 origin. It can possibly write (and replace) any file on your machine where you have
121 write access.
122 .TP
123 .B --help
124 Print help message and exit.
125 .TP
126 .B -l
127 Redirect standard error to a log file. The name of the log file is derived from
128 the name of the input file replacing the extension
129 .B .hnt
130 by the extension
131 .BR .log .
132 .TP
133 .BI -o \ name
134 Use
135 .I name
136 for the output file instead of deriving it from the name of the input file.
137 Append the extension
138 .B .hint
139 if the
140 .I name
141 does not already has that extension.
142 .TP
143 .B -u
144 Enable the use of UTF8 character codes.
145 Without this option, the output file is a pure ASCII file, because character codes
146 outside the ASCII range are written using their numeric representation.
147 With this option, the file will always represent printable characters using their UTF8
148 character codes. This might make the output file more readable if displayed
149 using an UTF8 enabled program; but it might be less readable if displayed
150 by a program that does not handle UTF8 characters properly. See also the
151 .B -x
152 option.
153 .TP
154 .B --version
155 Print version information and exit.
156 .TP
157 .B -x
158 Enable the use of hexadecimal character codes.
159 Without this option, characters that are not represented using their
160 character codes are represented using a decimal representation of
161 the character code. With this option a hexadecimal representation is used.
162 The range of character codes that have a numeric representation includes
163 the non printable characters (character codes smaller than 32)
164 and unless the
165 .B -u
166 option is given, the character codes with a value of 127 and above.
167 .\"=====================================================================
168 .SH FILES
169 Binary HINT files must contain all resources necessary to display the file,
170 for example font and image files. These files are called auxiliary files.
171 ASCII HINT files contain only the path names of these files.
172
173 When creating a binary HINT file from an ASCII HINT file, it is
174 necessary to find these files, read them, and include them in the binary output file.
175 When creating an ASCII HINT file from a binary HINT file, it is
176 convenient if these files can be extracted and written to the file system.
177 To avoid clobbering arbitrary directories with files when extracting auxiliary
178 files, it is possible to map the path names as stored in the HINT file
179 to
180 .B localized
181 path names before writing or reading auxiliar files.
182
183 When computing a localized path name from a given path name,
184 a distinction is made between global resources,
185 like fonts, that are referenced by an absolute path name, and local
186 resources, for example an image, that are referenced by a relative
187 path name. The directory that starts the localized path name of the former
188 has the extension
189 .B .abs
190 and for the latter the extension
191 .BR .rel
192 is used.
193 To keep auxiliary files in these subdirectories even if their path
194 contains links to a parent directory, parent links
195 .RB ` .. '
196 are replaced by
197 .RB ` __ '
198 links to subdirectories.
199
200 For example,
201 given an input file
202 .BR paper.hint,
203 the global resources are stored in the
204 .B paper.abs
205 directory and local resources are stored in
206 .BR paper.rel .
207 An absolute path like
208 .B /usr/share/fonts/
209 will then map to the localized path
210 .BR paper.abs/usr/share/fonts/
211 and a relative path like
212 .B ../image/img1.jpg
213 will then map to the localized path
214 .BR paper.rel/__/image/img1.jpg .
215 .\"=====================================================================
216 .SH NOTES
217 This manual page is not meant to be exhaustive. The complete
218 documentation can be found in
219 .IR "HINT: The file format" .
220 This document is available as a book or in electronic form from the
221 HINT project home page at
222 .BR https://hint.userweb.mwn.de .
223 There you find additional software, most importantly viewers for HINT files,
224 and further information.
225 .\"=====================================================================
226 .SH AVAILABILITY
227 .B histretch
228 should compile on a large variety of machine architectures
229 and operating systems.
230 It is part of the \*(TX Live distribution.
231 .PP
232 .\"=====================================================================
233 .SH "SEE ALSO"
234 .BR hishrink (1),
235 .BR hitex (1),
236 .\"=====================================================================
237 .SH AUTHORS
238 Martin Ruckert
239 .\" vim: syntax=nroff