| 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 |