Halibut is a documentation production system, with elements similar to TeX, debiandoc-sgml, TeXinfo, and others. It is primarily targeted at people producing software manuals.
Halibut reads documentation source in a single input format, and produces multiple output formats containing the same text. The supported output formats are:
man
pages
info
, generated directly as .info
files rather than .texi
sources
.CHM
files), generated directly without needing a separate help compiler.
.HLP
files), also generated directly.
Other notable features include:
\u00F6{oe}
, and in output formats that support it you will see ‘ö’ whereas in those that don't you will see ‘oe’.
\i{this wrapper}
, and those words will appear in the index. More complex indexing is also supported, such as
A common question is why I had to write a new documentation system rather than using an existing one.
TeX is fundamentally geared towards typesetting on to a printed page, so it didn't seem feasible to get it to output any of the more markup-oriented formats such as man
pages and Windows Help.
TeXinfo can generate both printed manuals and on-line help, but neither one is very pretty IMO; and the on-line help output is limited to info
format, which I didn't fancy post-processing into Windows Help, HTML etc.
debiandoc-sgml generates a good range of file formats, suggesting that it would probably not have been too hard to hack in a couple more; but when I looked at it I didn't see indexing support at anything like the level I wanted. Indexing is a big and tricky task, and I would hate to hack index support into a document producer after it was written; better to design it in from scratch.
DocBook wasn't well known enough for me to have heard of it when this project started. When it was later brought to my attention, I looked at the DocBook input format and simply didn't like it. For a start, it just involved too much typing for my taste: all the keywords are far too long (<appendix>
rather than \A
, for example), and the SGML/XML syntax requires you to type each keyword again when you close the section. I just prefer the TeX-like backslash-and-braces markup syntax to the HTMLish angle-brackets-and-slashes one. I was also suspicious of DocBook's very detailed semantic markup such as individually annotating things like people's names; I find writing manuals hard enough work as it is, without having to write as much metadata as text. Perhaps, if anyone asks for it, I might consider writing a DocBook output format for Halibut, so that Halibut input can be conveniently translated into DocBook format.
This crazy idea came to me while I was working on NASM, and wanted the documentation to be available on the project's web site as well as in printable and online-viewable formats. I hacked together a Perl implementation of most of the Halibut concepts, without any real design, and it worked well enough to get the NASM manual off the ground.
However, the Perl version (which is still distributed in the current NASM archive as far as I know) had serious limitations, most noticeably that it was extremely slow. Also the code was very hard to maintain (largely because I wrote a lot of the parser as line-noise regexps), the index management had some good ideas but implemented them in fundamentally broken ways … It just didn't seem sensible to continue trying to put features into it. So I rewrote it from the ground up in portable C, learning from all my mistakes in the original Perl version (‘build one to throw away’).
Historical reasons. It's probably better not to ask.
Halibut 1.3 was released on 2021-10-30, and supports all of the features described above.
You can download the release source code here [halibut-1.3.tar.gz
], or you can read the release documentation online in HTML, PDF or plain text.
If you're using Windows, you can also download a Windows executable, and the same documentation again in the form of a Windows HTML Help file.
Alternatively, if you want to keep up to date with the very latest development, you can check the development sources out from our git
repository. This uses git submodule
, so in order to check out everything you need, you'll need the --recursive
option:
git clone --recursive https://git.tartarus.org/simon/halibut.git
Alternatively, you can browse the repository on the web, here.