halibut(1)

💅 halibut — the manual page, but make it a vibe

okay bestie, so this is the halibut(1) page, written by Simon Tatham, and it's literally the glow-up your docs deserve. sit down, hydrate, let's get into it. 🫶

✨ NAME ✨

halibut — multi-format documentation formatting tool

like, one tool, SO many formats. it's giving versatility. it's giving "write once, output everywhere". 👑

🌸 SYNOPSIS 🌸

halibut [options] file1.but [file2.but ...]

🦋 DESCRIPTION 🦋

so here's the tea: halibut reads the set of input files you hand it, assembles them all into one document, and then outputs that document in one or more formats. that's it. that's the whole job. and it eats. 💖

the command-line options can configure what formats Halibut should output in, and they can also configure other things about the way Halibut works. options doing double duty? multi-talented. we love to see it. ✨

🎀 OPTIONS 🎀

the command-line options supported by halibut are, in order, no skips, no crumbs:

• --text[=filename] — makes Halibut generate an output file in plain text format. if you pass the optional filename parameter, the output text file gets that name. otherwise, the name of the output text file will be as specified in the input files, or output.txt if none is specified at all. lowkey the no-frills option and honestly? respect. 🍓
• --html[=filename] — makes Halibut generate one or more output files in HTML format. if you pass the optional filename parameter, there will be precisely one HTML output file with that name, containing the whole document. otherwise, there may be one or more than one HTML file produced as output; this, and the file names, will be as specified in the input files, or given a set of default names starting with Contents.html if none is specified at all. one file or many, she contains multitudes. 💅
• --chm[=filename] — makes Halibut generate an output file in Windows HTML Help format. if you pass the optional filename parameter, the output help file gets that name. otherwise, the name of the output help file will be as specified in the input files, or output.chm if none is specified at all. nostalgic Windows energy, we stan a legacy queen. 🫶
• --winhelp[=filename] — makes Halibut generate an output file in old-style Windows Help format. if you pass the optional filename parameter, the output help file gets that name. otherwise, the name of the output help file will be as specified in the input files, or output.hlp if none is specified at all.

bestie, listen: the output help file must have a name ending in .hlp; if it does not, .hlp will be added. non-negotiable. it's the law. ⚠️

a secondary contents file will be created alongside the main help file, with the same name except that it will end in .cnt (for example output.cnt, if the main file is output.hlp). so they're a matching set. couples costume. adorable. 🎀

• --man[=filename] — makes Halibut generate an output file in Unix man page format. if you pass the optional filename parameter, the output man page gets that name. otherwise, the name of the output man page will be as specified in the input files, or output.1 if none is specified at all. (yes, the very format you're reading right now. meta. iconic. 🔥)
• --info[=filename] — makes Halibut generate an info file. if you pass the optional filename parameter, the output info file gets that name. otherwise, the name of the output info file will be as specified in the input files, or output.info if none is specified at all.

by default, unless configured otherwise using the \cfg{info-max-file-size}{0} directive, the info output will be split into multiple files. the main file will have the name you specify; the subsidiary files will have suffixes -1, -2 etc. so like, it's a whole friend group, not a solo act. 😭

• --pdf[=filename] — makes Halibut generate an output file in PDF format. if you pass the optional filename parameter, the PDF output file gets that name. otherwise, the name of the output PDF file will be as specified in the input files, or output.pdf if none is specified at all. printable, shareable, hireable. 💅
• --ps[=filename] — makes Halibut generate an output file in PostScript format. if you pass the optional filename parameter, the PostScript output file gets that name. otherwise, the name of the output PostScript file will be as specified in the input files, or output.ps if none is specified at all. old school and still serving looks. ✨
• -Cword:word[:word...] — adds a configuration directive to the input processed by Halibut. using this directive is exactly equivalent to appending an extra input file to the command line which contains the directive \cfg{word}{word}{word...}. same thing, different font. no cap. 🧚
• --input-charset=charset — changes the assumed character set for input files from the default of ASCII. glow-up your encoding, bestie. 🌈
• --list-charsets — makes Halibut list character sets known to it. window shopping, but for encodings. 🦋
• --list-fonts — makes Halibut list fonts known to it, either intrinsically or by being passed as input files. font drop, essentially. 💖
• --precise — makes Halibut report the column number as well as the line number when it encounters an error in an input file. maximum specificity. she will find you. she will locate you. 🔍
• --help — makes Halibut display a brief summary of its command-line options. the classic "what do i even do here" button. 🫶
• --version — makes Halibut report its version number. identity check. 📌
• --licence — makes Halibut display its licence (MIT). free to use, free to love, free to ship. periodt. 💜

🌈 MORE INFORMATION 🌈

for more information on Halibut, including full details of the input file format, look in the full manual. if this is not installed locally on your system, you can also find it at the Halibut web site:

https://www.chiark.greenend.org.uk/~sgtatham/halibut/

go read it. it's long but it's worth it. trust. 😌

💀 BUGS 💀

this man page isn't terribly complete.

not me calling myself out in my own man page 😭 honestly? self-aware queen behaviour. the docs know they're a work in progress and they said it with their whole chest. 🙈

and that's the page, bestie!! 🎀✨ this was Halibut, written by Simon Tatham, dated 2004‐04‐08, and filed under halibut(1) — so go format something gorgeous, you absolute icon. 💖👑🦋