The file parser adds subdocuments ¾ that is, headers, footers, footnotes, and comments ¾ to the document by using the SOPutBreak function. The file parser must call SOPutBreak with the SO_SUBDOCBEGINBREAK value to start a subdocument and with the SO_SUBDOCENDBREAK value to end it.
After ending a subdocument, the file parser must restore character and paragraph attributes to their state before the subdocument was started. The file parser can use the SUUserPushData and SUUserPopData functions to save and restore nested subdocument information. A parser can nest subdocuments without limit. The following example shows when to save and restore this information.
This is a <Bold On> test
// At this point, the filter should save its internal
// information to reflect the fact that bold is on.
SOPutBreak(SO_SUBDOCBEGINBREAK);
SoPutSubdocInfo(...);
<Subdoc Begin> This is a <Bold Off>subdocument<Subdoc End>
// At this point, the filter should restore its internal
// information to reflect the fact that bold is on.
SOPutBreak(SO_SUBDOCENDBREAK);
document <Bold Off>of mine.
File parsers are not expected to correctly exit a subdocument when run from a regular paragraph break (with the SO_PARABREAK value) inside the subdocument. The display engine lets the file parser run to the subdocument's end break (that is, the SO_SUBDOCENDBREAK value) and returns the SO_STOP value to it.