texlive[61151] Build/source/texk/web2c/hitexdir: adding the hishrink
commits+mruckert at tug.org
commits+mruckert at tug.org
Thu Nov 25 15:09:09 CET 2021
Revision: 61151
http://tug.org/svn/texlive?view=revision&revision=61151
Author: mruckert
Date: 2021-11-25 15:09:09 +0100 (Thu, 25 Nov 2021)
Log Message:
-----------
adding the hishrink manual page, merging improvements back to the histretch man page
Modified Paths:
--------------
trunk/Build/source/texk/web2c/hitexdir/histretch.man
Added Paths:
-----------
trunk/Build/source/texk/web2c/hitexdir/hishrink.man
Added: trunk/Build/source/texk/web2c/hitexdir/hishrink.man
===================================================================
--- trunk/Build/source/texk/web2c/hitexdir/hishrink.man (rev 0)
+++ trunk/Build/source/texk/web2c/hitexdir/hishrink.man 2021-11-25 14:09:09 UTC (rev 61151)
@@ -0,0 +1,201 @@
+.TH HISHRINK 1 "11 November 2021" "Version 1.3"
+.\"=====================================================================
+.if n .ds MF Metafont
+.if t .ds MF Metafont
+.if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
+.if n .ds TX TeX
+.ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP
+.el .ds OX TeX
+.\" BX definition must follow TX so BX can use TX
+.if t .ds BX \fRB\s-2IB\s0\fP\*(TX
+.if n .ds BX BibTeX
+.\" LX definition must follow TX so LX can use TX
+.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
+.if n .ds LX LaTeX
+.if t .ds AX \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(TX
+.if n .ds AX AmSTeX
+.if t .ds AY \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(LX
+.if n .ds AY AmSLaTeX
+.if n .ds WB Web
+.if t .ds WB W\s-2EB\s0
+.\"=====================================================================
+.SH NAME
+hishrink\- translating ASCII HINT files to binary files
+.SH SYNOPSIS
+.B hishrink
+.RI [ options ]
+.RI [ file ]
+.\"=====================================================================
+.SH DESCRIPTION
+Shrinking converts an ASCII HINT file, usually with the extension
+.BR .hint ,
+into a binary HINT file, with the extension
+.BR .hnt .
+.PP
+The ASCII based HINT file format - also called `long' format - is optimized
+for readability. It can be edited using a text editor. Hence it allows
+simple modifications that would be difficult to achieve when using the binary
+format. It is also convenient when debugging.
+.PP
+The binary HINT file format - also called `short' format - is optimized
+for displaying HINT files. It can be parsed equally well in forward
+and backward direction to enable fast forward or backward navigation in the file.
+.PP
+The binary HINT file format is designed for on-screen reading of documents.
+Using a HINT viewer to display a HINT file, its content will dynamically
+adapt to the available display area. For complete information on the
+HINT file format and programs to view HINT files, see
+.BR https://hint.userweb.mwn.de .
+.\"=====================================================================
+.SH OPTIONS
+This version of
+.B hishrink
+understands the following command line options:
+.TP
+.B -a
+Use only the localized names for auxiliary files as explained in the
+.B FILES
+section below.
+
+If you know that the auxiliary files can be found using the localized names,
+for example after creating them with
+.B histretch
+using the
+.B -a
+option, you can use
+.B hishrink
+with the
+.B -a
+option to limit the search for the auxiliar files.
+If you are unsure, you should use neither the
+.B -a
+nor the
+.B -g
+option.
+.B hishrink
+will then search for auxiliar files first using the localized path names
+and then using the path names as given.
+.TP
+.B -c
+Enable the use of compression for the HINT file. Compressed files are
+smaller but require decompression when viewing. Use only for large
+files if the file size matters.
+.TP
+.BI -d \ bitmask
+Sets HINT file debugging flags according to the
+.IR bitmask .
+Use the
+.B --help
+option for details.
+.TP
+.B -g
+Do not use the localized names for auxiliary files as explained in the
+.B FILES
+section below.
+
+You may use this option if you know that all auxiliar files
+are at the locations described by the path names stored in the HINT file.
+If you are unsure, you should use neither the
+.B -g
+nor the
+.B -a
+option.
+.B hishrink
+will then search for auxiliar files first using the localized path names
+and then using the path names as given.
+.TP
+.B --help
+Print help message and exit.
+.TP
+.B -l
+Redirect standard error to a log file. The name of the log file is derived from
+the name of the input file replacing the extension
+.B .hint
+by the extension
+.BR .log .
+.TP
+.BI -o \ name
+Use
+.I name
+for the output file instead of deriving it from the name of the input file.
+Append the extension
+.B .hnt
+if the
+.I name
+does not already has that extension.
+.TP
+.B --version
+Print version information and exit.
+.\"=====================================================================
+.SH FILES
+Binary HINT files must contain all resources necessary to display the file,
+for example font and image files. These files are called auxiliary files.
+ASCII HINT files contain only the path names of these files.
+
+When creating a binary HINT file from an ASCII HINT file, it is
+necessary to find these files, read them, and include them in the binary output file.
+When creating an ASCII HINT file from a binary HINT file, it is
+convenient if these files can be extracted and written to the file system.
+To avoid clobbering arbitrary directories with files when extracting auxiliary
+files, it is possible to map the path names as stored in the HINT file
+to
+.B localized
+path names before writing or reading auxiliar files.
+
+When computing a localized path name from a given path name,
+a distinction is made between global resources,
+like fonts, that are referenced by an absolute path name, and local
+resources, for example an image, that are referenced by a relative
+path name. The directory that starts the localized path name of the former
+has the extension
+.B .abs
+and for the latter the extension
+.BR .rel
+is used.
+To keep auxiliary files in these subdirectories even if their path
+contains links to a parent directory, parent links
+.RB ` .. '
+are replaced by
+.RB ` __ '
+links to subdirectories.
+
+For example,
+given an input file
+.BR paper.hint,
+the global resources are stored in the
+.B paper.abs
+directory and local resources are stored in
+.BR paper.rel .
+An absolute path like
+.B /usr/share/fonts/
+will then map to the localized path
+.BR paper.abs/usr/share/fonts/
+and a relative path like
+.B ../image/img1.jpg
+will then map to the localized path
+.BR paper.rel/__/image/img1.jpg .
+.\"=====================================================================
+.SH NOTES
+This manual page is not meant to be exhaustive. The complete
+documentation can be found in the
+.IR "HINT: The file format" .
+This document is available as a book or in electronic form from the
+HINT project home page at
+.BR https://hint.userweb.mwn.de .
+There you find additional software, most importantly viewers for HINT files,
+and further information.
+.\"=====================================================================
+.SH AVAILABILITY
+.B hishrink
+should compile on a large variety of machine architectures
+and operating systems.
+It is part of the \*(TX Live distribution.
+.PP
+.\"=====================================================================
+.SH "SEE ALSO"
+.BR histretch (1),
+.BR hitex (1),
+.\"=====================================================================
+.SH AUTHORS
+Martin Ruckert
+.\" vim: syntax=nroff
Modified: trunk/Build/source/texk/web2c/hitexdir/histretch.man
===================================================================
--- trunk/Build/source/texk/web2c/hitexdir/histretch.man 2021-11-25 10:54:44 UTC (rev 61150)
+++ trunk/Build/source/texk/web2c/hitexdir/histretch.man 2021-11-25 14:09:09 UTC (rev 61151)
@@ -22,7 +22,7 @@
.SH NAME
histretch \- translating binary HINT files to ASCII files
.SH SYNOPSIS
-.B hitex
+.B histretch
.RI [ options ]
.RI [ file ]
.\"=====================================================================
@@ -41,7 +41,7 @@
simple modifications that would be difficult to achieve when using the binary
format. It is also convenient when debugging.
.PP
-The HINT file format is designed for on-screen reading of documents.
+The binary HINT file format is designed for on-screen reading of documents.
Using a HINT viewer to display a HINT file, its content will dynamically
adapt to the available display area. For complete information on the
HINT file format and programs to view HINT files, see
@@ -53,46 +53,14 @@
understands the following command line options:
.TP
.B -a
-Enable the writing of auxiliary files.
+Write auxiliar files to disk using the localized path names as explained in the
+.B FILES
+section below.
-Binary HINT files contain all resources necessary to display the file.
-This includes font and images. There are special file formats for fonts,
-like TrueType or OpenType, and special file formats for images like PNG
-or JPG. The HINT file format does not invent new file formats for these
-resources but includes them without modification.
-To obtain a `long' format that can be edited, these embedded
-files need to be written to disk as auxiliary files where they can be
-edited with suitable programs.
-
-The HINT file format makes a distinction between global resources,
-like fonts, that are referenced by an absolute path name, and local
-resources, for example an image, that are referenced by a relative
-path name. To avoid clobbering arbitrary directories with the unpacked
-files, the auxiliary files are written to two directories, one
-with the extension
-.B .abs
-and one with the extension
-.BR .rel .
-
-For example
-Given an input file
-.BR paper.hnt,
-the global resources are written to disk using
-.B paper.abs
-as root directory. The local resources are written to disk using
-.B paper.rel
-as starting point for the relative path.
-To prevent auxiliary files from escaping from these subdirectories,
-.B ..
-links to a parent directory are replaced by
-.B __
-links to true subdirectories.
+Use this option if you are stretching a HINT file that you later want
+to shrink back to its binary format unless you know that you have
+already all the auxiliary files contained in it.
.TP
-.B -c
-Enable the use of compression for the HINT file. Compressed files are
-smaller but require decompression when viewing. Use only for large
-files if the file size matters.
-.TP
.BI -d \ bitmask
Sets HINT file debugging flags according to the
.IR bitmask .
@@ -101,7 +69,8 @@
option for details.
.TP
.B -f
-Force the replacement of existing auxiliary files. Use together with the
+Force the replacement of existing auxiliary files.
+Use this option together with the
.B -g
or
.B -a
@@ -113,13 +82,22 @@
.B -g
option. Never use it on a HINT file of unknown
origin. It will possibly replace any file on your machine you have
-write access to.
+write access to. If in doubt, don't use the
+.B -f
+option.
.TP
.B -g
-Enable the writing of auxiliary files using the file's path as stored in the HINT file.
+Write auxiliar files to disk using the path names as stored in the HINT file.
This option is an alternative to the
.B -a
option and takes precedence if given.
+If in doubt, don't use the
+.B -g
+option.
+If you just want to stretch the HINT file, then edit it, and then shrink
+it back to the binary format, you should use the
+.B -a
+option.
You may use this option if you are stretching a HINT file on the same machine and in
the same directory where you have created the HINT file. Then all files
@@ -141,11 +119,6 @@
option. Never use it on a HINT file of unknown
origin. It can possibly write (and replace) any file on your machine where you have
write access.
-
-If you just want to stretch the HINT file, then edit it, and then shrink
-it back to the binary format, you should use the
-.B -a
-option.
.TP
.B --help
Print help message and exit.
@@ -192,9 +165,57 @@
.B -u
option is given, the character codes with a value of 127 and above.
.\"=====================================================================
+.SH FILES
+Binary HINT files must contain all resources necessary to display the file,
+for example font and image files. These files are called auxiliary files.
+ASCII HINT files contain only the path names of these files.
+
+When creating a binary HINT file from an ASCII HINT file, it is
+necessary to find these files, read them, and include them in the binary output file.
+When creating an ASCII HINT file from a binary HINT file, it is
+convenient if these files can be extracted and written to the file system.
+To avoid clobbering arbitrary directories with files when extracting auxiliary
+files, it is possible to map the path names as stored in the HINT file
+to
+.B localized
+path names before writing or reading auxiliar files.
+
+When computing a localized path name from a given path name,
+a distinction is made between global resources,
+like fonts, that are referenced by an absolute path name, and local
+resources, for example an image, that are referenced by a relative
+path name. The directory that starts the localized path name of the former
+has the extension
+.B .abs
+and for the latter the extension
+.BR .rel
+is used.
+To keep auxiliary files in these subdirectories even if their path
+contains links to a parent directory, parent links
+.RB ` .. '
+are replaced by
+.RB ` __ '
+links to subdirectories.
+
+For example,
+given an input file
+.BR paper.hint,
+the global resources are stored in the
+.B paper.abs
+directory and local resources are stored in
+.BR paper.rel .
+An absolute path like
+.B /usr/share/fonts/
+will then map to the localized path
+.BR paper.abs/usr/share/fonts/
+and a relative path like
+.B ../image/img1.jpg
+will then map to the localized path
+.BR paper.rel/__/image/img1.jpg .
+.\"=====================================================================
.SH NOTES
This manual page is not meant to be exhaustive. The complete
-documentation can be found in the
+documentation can be found in
.IR "HINT: The file format" .
This document is available as a book or in electronic form from the
HINT project home page at
More information about the tex-live-commits
mailing list.