From 7175f5c7d894f1d49b87effa4f6b886db035cda6 Mon Sep 17 00:00:00 2001 From: Martin Ruckert Date: Thu, 25 Nov 2021 10:54:44 +0000 Subject: adding the manual page for histretch git-svn-id: svn://tug.org/texlive/trunk@61150 c570f23f-e606-0410-a88d-b1316a301751 --- Build/source/texk/web2c/hitexdir/histretch.man | 218 +++++++++++++++++++++++++ Build/source/texk/web2c/hitexdir/hitex.man | 27 +-- 2 files changed, 234 insertions(+), 11 deletions(-) create mode 100644 Build/source/texk/web2c/hitexdir/histretch.man (limited to 'Build') 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 -- cgit v1.2.3