Quotation

Several times I've mentioned how to interpret macro arguments as text — instead of, say, other macros — by quotation. In this section, I formalise the notion of quoting arguments. The issue of quotation is fairly complex owing to mdoc's predecessor, roff.

In short, quoting arguments to macros passes the enclosed text verbatim as a single argument. An obvious case follows:

.Fl "Ar"

By quoting Ar, it is passed verbatim to Fl If not, it would be interpreted as the macro Ar and open a new macro scope. What's worse is that the syntax is entirely legal! This illustrates a minor short-coming of mdoc: beginners may unwittingly invoke macros (such as Ar in our example). Printing a warning would cause more harm than good with well-formed manuals; thus, it's the responsibility of the document author to double-check that macro instructions are properly treated.

This condition could have been avoided by beginning the argument Ar with a zero-width escape, such as \&Ar. The need for quotation is more obvious with the Fn macro:

.Fn int foo int bar

The syntax of Fn is that it first accepts an optional function type, then a function name, then arguments to the function. These arguments usually include a type followed by a name. In our example, int refers to the function type, foo to the name, and both int and bar as separate arguments.

Our intention, however, was to have int bar considered a single argument. To do so, we would need to quote.

.Fn int foo "int bar"

The int bar argument is now passed intact to the macro.

To include quotation marks in quoted text, use two quotation marks in a row.

.Li """ "

This artificial invocation passes a quotation mark followed by four whitespaces to the Li macro. It is, however, unwise to use this language component: it's jarring to those expecting symmetric quotes, and easy to mis-type, leaving runaway quotes. It's safer to use an escape, such as \(dq, instead of pair-wise quotations.

Contents

Home

History