diff options
author | Martin Ruckert <martin.ruckert@hm.edu> | 2021-11-25 14:09:09 +0000 |
---|---|---|
committer | Martin Ruckert <martin.ruckert@hm.edu> | 2021-11-25 14:09:09 +0000 |
commit | 44ef5de2a9fc14c12486aabd3e1d50dd7cc85e97 (patch) | |
tree | 281cdf6bea25acd0acb16173d51d2dfba812f3c5 /Build | |
parent | 7175f5c7d894f1d49b87effa4f6b886db035cda6 (diff) |
adding the hishrink manual page, merging improvements back to the histretch man page
git-svn-id: svn://tug.org/texlive/trunk@61151 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build')
-rw-r--r-- | Build/source/texk/web2c/hitexdir/hishrink.man | 201 | ||||
-rw-r--r-- | Build/source/texk/web2c/hitexdir/histretch.man | 119 |
2 files changed, 271 insertions, 49 deletions
diff --git a/Build/source/texk/web2c/hitexdir/hishrink.man b/Build/source/texk/web2c/hitexdir/hishrink.man new file mode 100644 index 00000000000..bf29ca9f440 --- /dev/null +++ b/Build/source/texk/web2c/hitexdir/hishrink.man @@ -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 diff --git a/Build/source/texk/web2c/hitexdir/histretch.man b/Build/source/texk/web2c/hitexdir/histretch.man index 38d1b1ed8a9..cbc385f5f01 100644 --- a/Build/source/texk/web2c/hitexdir/histretch.man +++ b/Build/source/texk/web2c/hitexdir/histretch.man @@ -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 @@ 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. +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,45 +53,13 @@ This version of 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. +Write auxiliar files to disk using the localized path names as explained in the +.B FILES +section below. -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. +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 .BI -d \ bitmask Sets HINT file debugging flags according to the @@ -101,7 +69,8 @@ See the 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 @@ 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. +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 @@ This is a dangerous option especially together with the 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 @@ and unless the .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 |