HISTRETCH(1)

💖 histretch 💖

General Commands Manual

---

✨ NAME ✨

okay so histretch is the tool that translates binary HINT files into ASCII HINT files 🦋

---

🎀 SYNOPSIS 🎀

histretch [options] [file]

---

🌸 DESCRIPTION 🌸

okay so stretching takes a binary HINT file, usually the one ending in .hnt, and turns it into an ASCII based HINT file ending in .hint ✨

the binary HINT format (also called 'short' format) is built for displaying HINT files. it can be parsed equally well forward and backward, so navigating the file quickly in either direction is no problem 🏃‍♀️💨

the ASCII based HINT format (also called 'long' format) is built for readability 📖 you can edit it in any text editor, so simple changes that would be a total nightmare in the binary format become easy. it's also super convenient when you're debugging 🫶

the binary HINT format is designed for reading documents on screen 👀 when a HINT viewer shows one, the content adapts on the fly to whatever display area is available. for the full scoop on the HINT file format and programs that view HINT files, check out https://hint.userweb.mwn.de 💅

---

💜 OPTIONS 💜

this version of histretch understands these command line options, so let's go:

• -a — writes auxiliary files to disk using the localized path names explained in the FILES section below 🗂️ use this if you're stretching a HINT file that you plan to shrink back into binary format later, unless you already know it has all the auxiliary files inside it 🙈
• -d bitmask — sets HINT file debugging flags according to the bitmask 🐛 check the --help option for the details
• -f — forces existing auxiliary files to be replaced 💥 pair it with -g or -a so already existing auxiliary files get swapped out for the ones stored in the HINT file. WARNING: this is a dangerous option, especially together with -g 💀 never use it on a HINT file of unknown origin, because it can overwrite any file on your machine that you have write access to. if you're in doubt, don't use -f 🫣
• -g — writes auxiliary files to disk using the path names stored in the HINT file 🛣️ this is an alternative to -a, and it wins if both are given. if you're in doubt, skip -g. if you just want to stretch the file, edit it, then shrink it back to binary, you want -a instead 💖
  • if you're stretching on the same machine, in the same directory where you created the HINT file, -g can be a vibe 🌈 every file gets copied back to where it came from in case it was deleted in the meantime
  • if you're stretching on a different machine than the one that created the file, histretch will try to copy an auxiliary file into the same directory that was used when the HINT file was created, as long as you have the writing rights for it 📂 that's probably where you want it, assuming both machines have the same directory structure
  • WARNING: this is a dangerous option, especially together with -f 😭 never use it on a HINT file of unknown origin, because it can write (and replace) any file on your machine where you have write access
• --help — prints a help message and exits 🆘
• -l — redirects standard error to a log file 📝 the log file's name comes from the input file's name, with the .hnt extension swapped for .log
• -o name — uses name as the output file instead of deriving it from the input file name 🎯 the .hint extension gets appended if name doesn't already have it
• -u — enables UTF8 character codes ✨ without this, the output is a pure ASCII file, since character codes outside the ASCII range are written as their numeric representation. with this option, printable characters are always shown with their UTF8 character codes. this can make the output nicer to read in a UTF8 enabled program, but it can be harder to read in a program that doesn't handle UTF8 characters properly 🥺 see also the -x option
• --version — prints version information and exits 🏷️
• -x — enables hexadecimal character codes 🔢 without this, characters that aren't shown by their character codes get a decimal representation of their character code instead. with this option you get a hexadecimal representation. the characters that get a numeric representation include the non printable ones (character codes smaller than 32), and, unless -u is given, the character codes with a value of 127 and up 🌟

---

🧚 FILES 🧚

binary HINT files have to contain every resource needed to display the file, like font and image files 🖼️ these are called auxiliary files. ASCII HINT files only hold the path names of these files.

when you make a binary HINT file from an ASCII HINT file, histretch has to find those files, read them, and bundle them into the binary output file 📦 when you make an ASCII HINT file from a binary one, it's handy if those files can be extracted and written to the file system. to avoid clobbering random directories with files while extracting auxiliary files, the path names stored in the HINT file can be mapped to localized path names before auxiliary files are written or read 🧹

when computing a localized path name, there's a difference between global resources, like fonts, which are referenced by an absolute path name, and local resources, like an image, which are referenced by a relative path name 💁‍♀️ the directory that starts the localized path name of a global resource gets the extension .abs, and local resources use the extension .rel. to keep auxiliary files in these subdirectories even when their path contains links to a parent directory, parent links .. get replaced by __ links to subdirectories 🔁

for example, with an input file paper.hint, global resources are stored in the paper.abs directory and local resources go in paper.rel. an absolute path like /usr/share/fonts/ maps to the localized path paper.abs/usr/share/fonts/, and a relative path like ../image/img1.jpg maps to the localized path paper.rel/__/image/img1.jpg 🌷

---

🌈 NOTES 🌈

this manual page isn't meant to be exhaustive, bestie 🙈 the complete documentation is in HINT: The file format. it's available as a book or in electronic form from the HINT project home page at https://hint.userweb.mwn.de. over there you'll find extra software, most importantly viewers for HINT files, plus more info ✨

---

🦋 AVAILABILITY 🦋

histretch should compile on a huge variety of machine architectures and operating systems 💪 it's part of the TeX Live distribution 🎀

---

👑 SEE ALSO 👑

hishrink(1), hitex(1)

---

💖 AUTHORS 💖

Martin Ruckert

---

That's the whole thing, bestie 🧚 histretch v1.3, dated 11 November 2021, with the HISTRETCH(1) manual page to match 💅✨