Callouts

A callout is a passage set off from the rest of the text and numbered on its own — a technical session, a case study, a note to the reader, a worked example. It behaves like a block quote, in that it is a container holding whatever you put in it, but it also carries a heading of its own, gets a number, can be cross-referenced, and can be collected into a list at the back of the book.

Defining a kind

Callouts come in kinds, and you define them. A textbook might have Technical Session and Case Study; a devotional might have just For Reflection. Nothing is defined to begin with, so the first step is always to make a kind.

Callouts live in the paragraph style dropdown, alongside Blockquote — they are chosen the same way. Open it and pick (New Callout Kind…) at the bottom. Give the kind a name in the singular — "Technical Session", not "Technical Sessions" — because the name is what appears in front of the number: Technical Session 3. Inkwell works out the plural on its own for the list page.

Whatever you had selected becomes a callout of the new kind straight away.

You can also add and edit kinds under Callouts in Project Settings.

Inserting one

Select the paragraphs you want set off and pick the kind from the style dropdown. The whole selection is wrapped, so you can take in a run of paragraphs, a list, a table — anything.

With the cursor inside a callout the dropdown shows its kind rather than the style of the paragraph you are in. Pick a different kind to change what it is, or pick Paragraph to take the callout apart — exactly as choosing a style inside a block quote takes you out of the quotation. The content stays; only the callout around it goes, and a title becomes an ordinary paragraph.

Giving it a title

A new callout starts with an empty title line at the top, marked Title (optional), and the cursor waiting in it — so you can name the thing as you make it. The title is what appears in the callout's heading and in the list at the back.

It really is optional. Press Enter to leave it empty and move down into the body, and a callout with no title simply shows its label and number. Press Backspace on the empty title line to take it off altogether.

To carry on writing after a callout — including one that ends the chapter, with nothing below it yet — press Enter on an empty last line, or click just beneath it.

The template

Everything a reader sees around a callout's content comes from a template you can edit, rather than from a row of settings. Open Project Settings, find your kind under Callouts, and click Edit Template.

The template is ordinary document content with variables in it:

• Label — the kind's name, "Technical Session"
• Number — the number, "3" or "1.4"
• Title — the title you typed on the callout's first line
• Body — where the callout's own content goes

Body is the important one. Whatever you put above it becomes the callout's header, and whatever you put below it becomes its footer. So a rule above and below, a bold label line, a closing "— end of session" — all of it is just content you type into the template, in the order you want it.

The default template is one bold line reading Label Number: Title, followed by the body. If a callout has no title, the colon disappears with it; if the kind is not numbered, the number and its separator disappear too. You never end up with a stray "Technical Session 3: " and nothing after it.

Because the template can hold anything a page can hold, putting the Body variable inside a block quote indents the whole callout, and a table above it gives the header a rule or a shaded band.

Numbering

Each kind is numbered independently, so Case Study 1 and Technical Session 1 can sit on the same page without either looking wrong. Under the kind's settings:

• Numbered By — Chapter restarts in every chapter, Book runs straight through from beginning to end, and Not Numbered leaves the callout without a number at all.
• Numbering — numerals, letters, roman numerals and the rest.
• Include Chapter Number Prefix — whether a chapter-numbered callout reads "3" or "1.3".

Numbers are worked out as you write. Insert a callout in chapter two and every later callout of that kind renumbers itself immediately, in the editor as well as in the PDF.

Referring to one

Type the kind's name followed by a space — Technical Session — and a list of that kind's callouts appears; pick one and Inkwell inserts a live cross-reference to it. The reference shows the callout's number and follows it if the numbering changes.

Each kind has its own trigger, so typing Case Study offers only the case studies. Rename a kind and the trigger changes with it.

The list at the back

Each kind can have its own list page, the way figures have a List of Figures. Open the + menu at the top of the chapter list and choose List of Technical Sessions — one entry appears there for every kind you have defined.

The page lists that kind alone, in the order the callouts appear in the book, with the page each one starts on. Its layout is a template too: open it from the kind's settings to change what the rows hold. Its title starts out as "List of …" and you can rename it by editing the heading on the page itself.

Callouts and comments

Callouts are part of the book: they are printed, numbered and listed. They are not the same thing as the comments you leave for a collaborator, which live beside the text and never appear in the finished book — those are covered in Collaboration. The Comment (In Document) paragraph style is a third thing again: a note to yourself, shown grey and italic, and left out of the built book.