The most basic use of this is when pressing
TAB on an empty line. If there’s an empty line above, this will offer to autocomplete a character name. Character names are suggested in the order:
TAB will also offer character name completion if a line has a partial character name.
When the cursor is after a character name and opening parenthesis,
TAB will offer completions from
MARY ┃ I'm hungry.
When the cursor is at an empty line within dialogue,
TAB will add an empty parenthetical.
MARY (┃) I'm hungry.
Likewise, if the cursor is within an empty parenthetical,
TAB will remove the parenthetical.
MARY (angry┃) I'm hungry.
When the cursor is at the end of a non-empty parenthetical, either inside or outside the closing parenthesis,
TAB will move to the beginning of the next line if the next line is non-empty, otherwise it will insert a newline.
MARY (angry) I'm hungry.┃
When the cursor is at the end of a non-empty line of dialogue, and the value of
fountain-dwim-insert-next-character is non-nil,
TAB will insert an empty line and the second-to-last previously speaking character.
MARY (angry) I'm hungry. JOHN┃
The cursor will be left at the end of the next character, allowing successive presses of
TAB to cycling through additional character completion candidates.