adding the manual page for histretch

git-svn-id: svn://tug.org/texlive/trunk@61150 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 234 insertions, 11 deletions

diff --git a/Build/source/texk/web2c/hitexdir/histretch.man b/Build/source/texk/web2c/hitexdir/histretch.man
new file mode 100644
index 00000000000..38d1b1ed8a9
--- /dev/null
+++ b/Build/source/texk/web2c/hitexdir/histretch.man
@@ -0,0 +1,218 @@
+.TH HISTRETCH 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
+histretch \- translating binary HINT files to ASCII files
+.SH SYNOPSIS
+.B hitex
+.RI [ options ]
+.RI [ file ]
+.\"=====================================================================
+.SH DESCRIPTION
+Stretching converts a binary HINT file, usually with the extension 
+.BR .hnt ,
+into an  ASCII based HINT file, with the extension
+.BR .hint .
+.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 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 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 histretch
+understands the following command line options:
+.TP
+.B -a
+Enable the writing of auxiliary files. 
+
+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. 
+.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 .
+See the
+.B --help
+option for details.
+.TP
+.B -f
+Force the replacement of existing auxiliary files. Use together with the
+.B -g
+or 
+.B -a
+option to make sure that already exiting auxiliary files are replaced by the
+auxiliary files contained in the HINT file.
+
+.BR WARNING :
+This is a dangerous option especially together with the
+.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.
+.TP
+.B -g
+Enable the writing of auxiliary files using the file's path as stored in the HINT file.
+This option is an alternative to the 
+.B -a
+option and takes precedence if given. 
+
+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
+will be copied to the location they came from in case they were deleted
+in the meantime.
+
+If you are stretching a HINT file on one machine and the file was created
+on a different machine, 
+.B histretch 
+will try to copy an auxiliary file
+into the same directory that was used when the HINT file was created, provided that 
+you have the necessary writing rights. 
+This is probably where you want the auxiliary file assuming that both machines have the
+same directory structure.
+
+.BR WARNING :
+This is a dangerous option especially together with the
+.B -f
+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.
+.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 .hnt
+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 .hint
+if the
+.I name
+does not already has that extension.
+.TP
+.B -u
+Enable the use of UTF8 character codes. 
+Without this option, the output file is a pure ASCII file, because character codes
+outside the ASCII range are written using their numeric representation.
+With this option, the file will always represent printable characters using their UTF8 
+character codes. This might make the output file more readable if displayed 
+using an UTF8 enabled program; but it might be less readable if displayed
+by a program that does not handle UTF8 characters properly. See also the
+.B -x
+option.
+.TP
+.B --version
+Print version information and exit.
+.TP
+.B -x
+Enable the use of hexadecimal character codes.
+Without this option, characters that are not represented using their
+character codes are represented using a decimal representation of 
+the character code. With this option a hexadecimal representation is used.
+The range of character codes that have a numeric representation includes
+the non printable characters (character codes smaller than 32)
+and unless the 
+.B -u
+option is given, the character codes with a value of 127 and above.
+.\"=====================================================================
+.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 histretch
+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 hishrink (1),
+.BR hitex (1),
+.\"=====================================================================
+.SH AUTHORS
+Martin Ruckert
+.\" vim: syntax=nroff
diff --git a/Build/source/texk/web2c/hitexdir/hitex.man b/Build/source/texk/web2c/hitexdir/hitex.man
index 4fe6516744e..b78d16183c3 100644
--- a/Build/source/texk/web2c/hitexdir/hitex.man
+++ b/Build/source/texk/web2c/hitexdir/hitex.man
@@ -33,7 +33,7 @@ Run the Hi\*(TX typesetter on
 usually creating
 .IR file.hnt .
 If the file argument has no extension, ".tex" will be appended to it. 
-Instead of a filename, a set of Hi\*(TX commands can be given, the first
+Instead of a file name, a set of Hi\*(TX commands can be given, the first
 of which must start with a backslash.
 With a 
 .BI & format
@@ -49,10 +49,10 @@ Hi\*(TX is a version of \*(TX that creates HINT files. The HINT file
 format is designed for on-screen reading of documents. Using a HINT
 viewer (see
 .BR  https://hint.userweb.mwn.de )
-to display a HINT file its content will dynamicaly adapt to the
+to display a HINT file its content will dynamically adapt to the
 available display area.
 .PP
-The typical use of Hi\*(TX is with pregenerated formats.
+The typical use of Hi\*(TX is with pre generated formats.
 The
 .B hitex
 command uses the equivalent of the plain \*(TX format, and the
@@ -144,10 +144,10 @@ option for details.
 Print an explanation of the HINT debugging flags and exit.
 .TP
 .B -hyphenate-first-word
-\*(TX will usualy not attempt to insert hyphenation points into the first 
+\*(TX will usually not attempt to insert hyphenation points into the first 
 word of a paragraph. If a HINT file must be displayed on a very small device
 such hyphenation points might prove necessary. This option is set by default
-and enables the genaration of these hyphenation points.
+and enables the generation of these hyphenation points.
 .TP
 .B -no-hyphenate-first-word
 Disable the automatic insertion of hyphenation points in the first word
@@ -258,9 +258,9 @@ The
 .B kpsewhich
 utility can be used to query the values of the variables.
 .PP
-One caveat: In most Hi\*(TX formats, you cannot use ~ in a filename you
+One caveat: In most Hi\*(TX formats, you cannot use ~ in a file name you
 give directly to Hi\*(TX, because ~ is an active character in \*(TX,
-and hence is expanded, not taken as part of the filename. Other
+and hence is expanded, not taken as part of the file name. Other
 programs, such as \*(MF, do not have this problem.
 .PP
 .TP
@@ -305,8 +305,8 @@ files.
 .TP
 .B SOURCE_DATE_EPOCH
 If set, its value, taken to be in epoch-seconds, will be used for the
-timestamps in the PDF output, such as the CreationDate and ModDate keys.
-This is useful for making reproducible builds.
+creation date and as the reference moment for the time related 
+primitives of \*(LX. This is useful for making reproducible builds.
 .TP
 .B FORCE_SOURCE_DATE
 If set to the value "1", the time-related \*(TX primitives
@@ -339,8 +339,13 @@ Font files used by Hi\*(TX.
 This manual page is not meant to be exhaustive.  The complete
 documentation for Hi\*(TX can be found in the 
 .IR "Hi\*(TX user manual"
-and the manual of the
-.IR "Kpathsea library" .
+Further information can be found in the  manual of the
+.I "Kpathsea library" 
+and in
+.IR "HINT: The file format" .
+which is available as a book or in electronic form from the 
+HINT project home page at 
+.BR https://hint.userweb.mwn.de .
 .PP.\"=====================================================================
 .SH BUGS
 This version of Hi\*(TX fails to handle correctly glues and kerns with a