Chapter 3: Halibut input format

Chapter 3: Halibut input format

This chapter describes the format in which you should write documents to be processed by Halibut.

3.1 The basics

Halibut's input files mostly look like ordinary ASCII text files; you can edit them with any text editor you like.

Writing paragraphs of ordinary text is very simple: you just write ordinary text in the ordinary way. You can wrap a paragraph across more than one line using line breaks in the text file, and Halibut will ignore this when it rewraps the paragraph for each output format. To separate paragraphs, use a blank line (i.e. two consecutive line breaks). For example, a fragment of Halibut input looking like this:

This is a line of text.
This is another line of text.

This line is separated from the previous one by a blank line.

will produce two paragraphs looking like this:

This is a line of text. This is another line of text.

This line is separated from the previous one by a blank line.

The first two lines of the input have been merged together into a single paragraph, and the line break in the input file was treated identically to the spaces between the individual words.

Halibut is designed to have very few special characters. The only printable characters in Halibut input which will not be treated exactly literally in the output are the backslash (\) and the braces ({ and }). If you do not use these characters, everything else you might type in normal ASCII text is perfectly safe. If you do need to use any of those three characters in your document, you will have to precede each one with a backslash. Hence, for example, you could write

This \\ is a backslash, and these are \{braces\}.

and Halibut would generate the text

This \ is a backslash, and these are {braces}.

If you want to write your input file in a character set other than ASCII, you can do so by using the \cfg{input-charset} command. See section 3.6 for details of this.

3.2 Simple inline formatting commands

Halibut formatting commands all begin with a backslash, followed by a word or character identifying the command. Some of them then use braces to surround one or more pieces of text acted on by the command. (In fact, the \\, \{ and \} sequences you met in section 3.1 are themselves formatting commands.)

This section describes some simple formatting commands you can use in Halibut documents. The commands in this section are inline commands, which means you can use them in the middle of a paragraph. Section 3.3 describes some paragraph commands, which affect a whole paragraph at a time.

Many of these commands are followed by a pair of braces surrounding some text. In all cases, it is perfectly safe to have a line break (in the input file) within those braces; Halibut will treat that exactly the same as a space. For example, these two paragraphs will be treated identically:

Here is some \e{emphasised
text}.

Here is some \e{emphasised text}.

3.2.1 `\e`: Emphasising text

Possibly the most obvious piece of formatting you might want to use in a document is emphasis. To emphasise text, you use the \e command, and follow it up with the text to be emphasised in braces. For example, the first sentence in this paragraph was generated using the Halibut input

Possibly the most obvious piece of formatting you might want
to use in a document is \e{emphasis}.

3.2.2 `\c` and `\cw`: Displaying computer code inline

Halibut was primarily designed to produce software manuals. It can be used for other types of document as well, but software manuals are its speciality.

In software manuals, you often want to format text in a way that indicates that it is something you might see displayed verbatim on a computer screen. In printed manuals, this is typically done by setting that text in a font which is obviously fixed-width. This provides a visual cue that the text being displayed is code, and it also ensures that punctuation marks are clearly separated and shown individually (so that a user can copy the text accurately and conveniently).

Halibut provides two commands for this, which are subtly different. The names of those commands are \c (‘code’) and \cw (‘weak code’). You use them just like \e, by following them with some text in braces. For example, this...

This sentence contains some \c{code} and some \cw{weak code}.

... produces this:

This sentence contains some code and some weak code.

The distinction between code and weak code is mainly important when producing plain text output. Plain text output is typically viewed in a fixed-width font, so there is no need (and no way) to change font in order to make the order of punctuation marks clear. However, marking text as code is also sometimes done to provide a visual distinction between it and the text around it, so that the reader knows where the literal computer text starts and stops; and in plain text, this cannot be done by changing font, so there needs to be an alternative way.

So in the plain text output format, things marked as code (\c) will be surrounded by quote marks, so that it's obvious where they start and finish. Things marked as weak code (\cw) will not look any different from normal text.

I recommend using weak code for any application where it is obvious that the text is literal computer input or output. For example, if the text is capitalised, that's usually good enough. If I talk about the Pentium's EAX and EDX registers, for example, you don't need quotes to notice that those are special; so I would write that in Halibut as ‘the Pentium's \cw{EAX} and \cw{EDX} registers’. But if I'm talking about the Unix command man, which is an ordinary English word in its own right, a reader might be slightly confused if it appeared in the middle of a sentence undecorated; so I would write that as ‘the Unix command \c{man}’.

In summary:

\c means ‘this text must be visually distinct from the text around it’. Halibut's various output formats will do this by changing the font if possible, or by using quotes if not.
\cw means ‘it would be nice to display this text in a fixed-width font if possible, but it's not essential’.

In really extreme cases, you might want Halibut to use quotation marks even in output formats which can change font. In section 3.2.5, for example, I mention the special formatting command ‘\.’. If that appeared at the end of a sentence without the quotes, then the two adjacent full stops would look pretty strange even if they were obviously in different fonts.

For this, Halibut supports the \cq command, which is exactly equivalent to using \q to provide quotes and then using \cw inside the quotes. So in the paragraph above, for example, I wrote

the special formatting command \cq{\\.}.

and I could equivalently have written

the special formatting command \q{\cw{\\.}}.

There is a separate mechanism for displaying computer code in an entire paragraph; see section 3.3.1 for that one.

3.2.3 `\q`: Quotation marks

Halibut's various output formats don't all use the same conventions for displaying text in ordinary quotation marks (‘like these’). Some output formats have access to proper matched quote characters, whereas others are restricted to using plain ASCII. Therefore, it is not ideal to use the ordinary ASCII double quote character in your document (although you can if you like).

Halibut provides the formatting command \q to indicate quoted text. If you write

Here is some \q{text in quotes}.

then Halibut will print

Here is some ‘text in quotes’.

and in every output format Halibut generates, it will choose the best quote characters available to it in that format. (The quote characters to use can be configured with the \cfg command.)

You can still use the ordinary quote characters of your choice if you prefer; or you could even use the \u command (see section 3.2.7) to generate Unicode matched quotes (single or double) in a way which will automatically fall back to the normal ASCII one if they aren't available. But I recommend using the built-in \q command in most cases, because it's simple and does the best it can everywhere.

If you're using the \c or \cw commands to display literal computer code, you will probably want to use literal ASCII quote characters, because it is likely to matter precisely which quote character you use. In fact, Halibut actually disallows the use of \q within either of \c and \cw, since this simplifies some of the output formats.

3.2.4 `\-` and `\_`: Non-breaking hyphens and spaces

If you use an ordinary hyphen in the middle of a word (such as ‘built-in’), Halibut's output formats will feel free to break a line after that hyphen when wrapping paragraphs. This is fine for a word like ‘built-in’, but if you were displaying some literal computer code such as the Emacs command M-x psychoanalyze-pinhead, you might prefer to see the whole hyphenated word treated as an unbreakable block. In some cases, you might even want to prevent the space in that command from becoming a line break.

For these purposes, Halibut provides the commands \- and \_, which generate a non-breaking hyphen and a non-breaking space respectively. So the above Emacs command might be written as

the Emacs command \c{M\-x\_psychoanalyze\-pinhead}

Unfortunately, some of Halibut's output formats do not support non-breaking hyphens, and others don't support breaking hyphens! So Halibut cannot promise to honour these commands in all situations. All it can do is make a best effort.

3.2.5 `\date`: Automatic date generation

Sometimes you might want your document to give an up-to-date indication of the date on which it was run through Halibut.

Halibut supplies the \date command to do this. In its simplest form, you simply say

This document was generated on \date.

and Halibut generates something like

This document was generated on Sun Aug 7 15:05:47 2005.

You can follow the \date command directly with punctuation (as in this example, where it is immediately followed by a full stop), but if you try to follow it with an alphabetic or numeric character (such as writing \dateZ) then Halibut will assume you are trying to invoke the name of a macro command you have defined yourself, and will complain if no such command exists. To get round this you can use the special ‘\.’ do-nothing command. See section 3.7 for more about general Halibut command syntax and ‘\.’.

If you would prefer the date to be generated in a specific format, you can follow the \date command with a format specification in braces. The format specification will be run through the standard C function strftime, so any format acceptable to that function is acceptable here as well. I won't document the format here, because the details vary from computer to computer (although there is a standard core which should be supported everywhere). You should look at your local system's manual for strftime for details.

Here's an example which generates the date in the international standard ISO 8601 format:

This document was generated on \date{%Y-%m-%d %H:%M:%S}.

And here's some sample output from that command:

This document was generated on 2005-08-07 15:05:47.

3.2.6 `\W`: WWW hyperlinks

Since one of Halibut's output formats is HTML, it's obviously useful to be able to provide links to arbitrary web sites in a Halibut document.

This is done using the \W command. \W expects to be followed by two sets of braces. In the first set of braces you put a URL; in the second set you put the text which should be a hyperlink. For example, you might write

Try searching on \W{http://www.google.com/}{Google}.

and Halibut would generate

Try searching on Google.

Note that hyperlinks, like the non-breaking commands discussed in section 3.2.4, are discretionary: if an output format does not support them then they will just be left out completely. So unless you're only intending to use the HTML output format, you should avoid storing vital content in the URL part of a \W command. The Google example above is reasonable (because most users are likely to be able to find Google for themselves even without a convenient hyperlink leading straight there), but if you really need to direct users to a specific web site, you will need to give the URL in actual displayed text (probably displayed as code as well). However, there's nothing to stop you making it a hyperlink as well for the convenience of HTML readers.

The \W command supports a piece of extra syntax to make this convenient for you. You can specify \c or \cw between the first and second pairs of braces. For example, you might write

Google is at \W{http://www.google.com/}\cw{www.google.com}.

and Halibut would produce

Google is at www.google.com.