Understand How Smart Returns are Inserted After Instructions

By default, each time you insert any instruction (IF/END IF, REPEAT/END REPEAT, SPAN/END SPAN, INSERT, or ASK) in a template, HotDocs adds a return following the instruction. Then, when HotDocs assembles the template and processes the instruction, it removes the return it inserted. To some, this insertion of returns creates problems or confusion in automating the template because it sometimes makes the template text difficult to read and understand, especially when instructions (and their subsequent returns) within a paragraph sometimes break the paragraph into separate lines of text.

To accommodate this, HotDocs allows you to choose whether to insert returns following these instructions. (See Control When Returns Are Inserted After Instructions in Text Templates.). Specifically, you can:

  • Always insert a return after an instruction.
  • Never insert a return after an instruction.
  • Use "smart" return insertion.

The first two options behave exactly as expected—HotDocs will either always insert a return (and remove it during assembly) or never insert a return, depending on which of the two options you choose.

The behavior of third option, using smart returns, depends on how and where you're inserting the instruction.

If text you select represents a complete paragraph (meaning there's a paragraph mark at the end of the selected text), HotDocs will insert a return character after the instruction. In the following example, brackets ([ ]) indicate where text selection begins and ends. Note that the closing bracket ends on the line after the paragraph mark (¶):

Here is a paragraph.

[Here is another paragraph.¶

] Here is a third paragraph.

Would produce a section of conditional text that looks like this:

Here is a paragraph.

«IF Instruction»

Here is another paragraph.


Here is a third paragraph.

However, if the text you select is within a paragraph, HotDocs will not insert a return character. So, in the following example, when you insert the REPEAT instruction, HotDocs does not insert a return because the insertion is happening in the middle of a paragraph. There is no paragraph break at the end of the insertion:

The client, «Client Name», has the following children: «REPEAT Children:a, b, and c»«Child Name»«END REPEAT». These children live with the client and are covered under the provision.¶

At times, you may simply insert an instruction without first selecting text, or perhaps you may select some text but not include the paragraph mark in the selection. If HotDocs detects an existing paragraph break immediately after the instruction, it includes a Keep Return code (or vertical bar (|) ) at the end of the instruction. The code tells HotDocs to not delete the return when it assembles the document. So, the following example, where brackets indicate text selection:

Here is a paragraph.

[Here is another paragraph.]

Here is a third paragraph.

would produce the following automation:

Here is a paragraph.

«IF Instruction»Here is another paragraph.«END IF|»

Here is a third paragraph.

Note that the Keep Return code (|) in the END IF instruction indicates to HotDocs to keep the return character when it assembles the document.

HotDocs' capacity to delete both an IF instruction and the return that follows it is very important in some situations. If an optional paragraph includes numbering, it is difficult to condition out the entire paragraph and its numbering without putting the IF on a separate line before the paragraph. It can be done, but the template looks odd, since the IF is inside the numbering of the paragraph.