The Chapters action statement provides a programmatic interface to the functionality found in the Chapter Editor.
The statement is valid in all execution modes but the returned action test state may be more meaningful when executing grouped.
When a chapter number is specified, the field may contain any of the escape sequences described in Escape Sequences. Note that chapter numbers start with 1. 0 is an invalid chapter number.
The following functions are available:
- Get the Number of Chapters
- The specified track variable will be set to the number of chapters or empty if there are none. An action test state of true implies all files in the current execution mode contained chapters.
- Get the Modification State
- The specified track variable will be set to 1 if any chapter names are modified. Otherwise the track variable will be set to empty. An action test state of true implies that at least one file had modifications to the chapter names.
- Get the Initial Name of a Chapter
- The specified track variable will be set to the initial name of the specified chapter. If there are no chapters or the supplied chapter number is invalid the track variable will be set to empty. An action test state of false implies that at least one file did not have chapters or that the supplied chapter number was invalid. The initial name is the name currently stored in a file.
- Get the Updated Name of a Chapter
- The specified track variable will be set to the updated name of the specified chapter if there is one. Otherwise the track variable will be set to empty. An action test state of true implies that at least one updated chapter name was returned.
- Update the Name of a Chapter
- The specified chapter name, if possible, will be set to the contents of the specified track variable. An action test state of true implies that at least one chapter name was modified. If the specified track variable is empty or is the same as the initial chapter name, the chapter name will effectively be reset to its initial value. Chapters only have updated names if they differ from the initial names.
