![]() ![]() 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. 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. ![]() 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. 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. 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. I just prefer the TeX-like backslash-and-braces markup syntax to the HTMLish angle-brackets-and-slashes one. ![]() For a start, it just involved too much typing for my taste: all the keywords are far too long ( rather than \A, for example), and the SGML/XML syntax requires you to type each keyword again when you close the section. When it was later brought to my attention, I looked at the DocBook input format and simply didn't like it. 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.ĭocBook wasn't well known enough for me to have heard of it when this project started. 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.ĭebiandoc-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. 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. Each output format supplies configuration directives, so it is easy to tailor the HTML output (say) to contain a standard header with links to other parts of a site, or to use a style sheet, or whatever.Ī common question is why I had to write a new documentation system rather than using an existing one. (Well, you might have trouble outputting PDF under VMS, due to file typing issues. The Halibut source code is portable ANSI C (apart from a dependency on having at least a 32-bit platform), so it should run without change on Unix, Windows, BeOS, MacOS, VMS, or whatever other (non-16-bit) OS you fancy. Merging references to several things into one combined list. ![]() Rewriting the appearance of index entries for a consistent styleĭuplicating index entries to several places because you don't know which concept they'll be looked up under More complex indexing is also supported, such asĪdding references to things you never explicitly said For example, you can write \u00F6, and those words will appear in the index. Support for international characters via Unicode, with the ability to fall back to an alternative representation. (It seems daft to me that so many PDF documents fail to have this it's one of the most useful features of PDF.) In particular, the HTML and PDF output both have hyperlinks in every reference between sections, and throughout the index and contents sections. Hypertext cross-references are ubiquitous where possible. CHM files), generated directly without needing a separate help compiler. Halibut reads documentation source in a single input format, and produces multiple output formats containing the same text. It is primarily targeted at people producing software manuals. Halibut is a documentation production system, with elements similar to TeX, debiandoc-sgml, TeXinfo, and others. Halibut: yet another free document preparation system Halibut: yet another free document preparation system ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |