<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="../services.html">Services</a></li><li><ahref="index.html">problems</a></li><li><ahref="index.html#P">Preliminaries</a></li><li><b>How To Include This Module</b></li></ul></div>
<ulclass="toc"><li><ahref="P-htitm.html#SP1">§1. Status</a></li><li><ahref="P-htitm.html#SP2">§2. Importing the module</a></li><li><ahref="P-htitm.html#SP3">§3. Using callbacks</a></li></ul><hrclass="tocbar">
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. Status. </b>The problems module provided as one of the "services" suite of modules, which means
that it was built with a view to potential incorporation in multiple tools.
It can be found, for example, in <ahref="../inform7/index.html"class="internal">inform7</a> and <ahref="../problems-test/index.html"class="internal">problems-test</a>.
</p>
<pclass="commentary">By convention, the modules considered as "services" have no dependencies on
<pclass="commentary">A tool can import <ahref="index.html"class="internal">problems</a> only if it also imports <ahref="../../../inweb/foundation-module/index.html"class="internal">foundation</a>,
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. Importing the module. </b>We'll use the term "parent" to mean the tool which is importing <ahref="index.html"class="internal">problems</a>,
<ulclass="items"><li>● The parent must call <spanclass="extract"><spanclass="extract-syntax">ProblemsModule::start()</span></span> just after it starts up, and
<spanclass="extract"><spanclass="extract-syntax">ProblemsModule::end()</span></span> just before it shuts down. (But just after, and just
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. Using callbacks. </b>Shared modules like this one are tweaked in behaviour by defining "callback
<pclass="commentary firstcommentary"><aid="SP4"class="paragraph-anchor"></a><b>§4. </b><spanclass="extract"><spanclass="extract-syntax">DESCRIBE_SOURCE_FILE_PROBLEMS_CALLBACK</span></span> can change the description of a
<pclass="commentary firstcommentary"><aid="SP5"class="paragraph-anchor"></a><b>§5. </b><spanclass="extract"><spanclass="extract-syntax">DOCUMENTATION_REFERENCE_PROBLEMS_CALLBACK</span></span> is invited to add a clickable
<pclass="commentary firstcommentary"><aid="SP6"class="paragraph-anchor"></a><b>§6. </b><spanclass="extract"><spanclass="extract-syntax">ENDING_MESSAGE_PROBLEMS_CALLBACK</span></span> is called just before a problem message
<pclass="commentary firstcommentary"><aid="SP7"class="paragraph-anchor"></a><b>§7. </b><spanclass="extract"><spanclass="extract-syntax">FIRST_PROBLEMS_CALLBACK</span></span> is called before the first problem in a run is
<pclass="commentary firstcommentary"><aid="SP8"class="paragraph-anchor"></a><b>§8. </b><spanclass="extract"><spanclass="extract-syntax">FORMAT_CONSOLE_PROBLEMS_CALLBACK</span></span> is called when a Problem message is to
be printed to the <spanclass="extract"><spanclass="extract-syntax">stderr</span></span> console (it has no effect on the rendering of Problems
in HTML). See <ahref="2-pl1.html#SP5"class="internal">ProblemBuffer::output_problem_buffer_to</a>.
</p>
<pclass="commentary firstcommentary"><aid="SP9"class="paragraph-anchor"></a><b>§9. </b><spanclass="extract"><spanclass="extract-syntax">GLOSS_EXTENSION_SOURCE_FILE_PROBLEMS_CALLBACK</span></span> is called to add a note
<pclass="commentary firstcommentary"><aid="SP10"class="paragraph-anchor"></a><b>§10. </b><spanclass="extract"><spanclass="extract-syntax">INFORMATIONAL_ADDENDA_PROBLEMS_CALLBACK</span></span> is called just before a problems
<pclass="commentary firstcommentary"><aid="SP11"class="paragraph-anchor"></a><b>§11. </b><spanclass="extract"><spanclass="extract-syntax">START_PROBLEM_FILE_PROBLEMS_CALLBACK</span></span> is called when <ahref="index.html"class="internal">problems</a> wants
to open some kind of file for problem messages, with two arguments: the
filename <spanclass="extract"><spanclass="extract-syntax">F</span></span> and the stream <spanclass="extract"><spanclass="extract-syntax">P</span></span> to open to it. If the callback function wants
this to come to anything, it must perform the file-open, and write any header
material it would like. See <ahref="2-pl3.html#SP19"class="internal">StandardProblems::start_problems_report</a>.
<pclass="commentary firstcommentary"><aid="SP12"class="paragraph-anchor"></a><b>§12. </b><spanclass="extract"><spanclass="extract-syntax">END_PROBLEM_FILE_PROBLEMS_CALLBACK</span></span> is called when <ahref="index.html"class="internal">problems</a> wants
to close this file again. See <ahref="2-pl1.html#SP7"class="internal">ProblemBuffer::write_reports</a>.
</p>
<pclass="commentary firstcommentary"><aid="SP13"class="paragraph-anchor"></a><b>§13. </b><spanclass="extract"><spanclass="extract-syntax">WORDING_FOR_HEADING_NODE_PROBLEMS_CALLBACK</span></span> is called to ask what wording