|
Start of Chapter 27: Extensions |
|
Back to §27.11. Extension documentation |
|
Onward to §27.13. Implications |
Inform 7 Home Page / Documentation
§27.12. Examples and headings in extension documentation
Extensions with very large amounts of documentation can, if the author chooses, divide the material up using headings and/or subheadings. These must be written as paragraphs exactly like so:
Inform will then typeset them to stand out, will number them automatically, and will add a table of contents at the top of the page. (For most extensions, the documentation will be short and sweet, and this would just be clutter: headings and subheadings are best used only where the text would otherwise be difficult to read.)
Any extension's documentation can contain Examples, just as the main Inform documentation does: these are automatically labelled A, B, C, ... rather than given numbers, to ensure that they do not clash with the numbering used in the built-in chapters. (The labels may be helpful in writing an extension's documentation: we can write, for instance, a note such as "see Example C below".)
Examples must be given last in the documentation, and there can be up to 26 of them, though most extensions will need one example at the most, and some will have none at all. Each example must begin with a paragraph exactly like so:
Example: ** We Must Perform a Quirkafleeg - Ducking to avoid arrows as one proceeds east across battlements.
Again, there must be a skipped line before and after. The row of asterisks must be *, **, *** or ****, just as in the main documentation, which we should follow on all points of style. The rest of the line contains the title, a hyphen, and then the description. The title should be given with Each Word except Prepositions and Similar Things Capitalized, while the description should look like a sentence, and end with a full stop.
The text of the example follows, of course, and continues until the end of the file, or the next "Example:" line, whichever comes first.
Each example should (normally) contain one single, complete, story, long enough to demonstrate the use of the extension and to have a little flavour to it, but not so long that the reader gets lost. It should have a title, which should match the name of the example (in the case above, "We Must Perform a Quirkafleeg"). It should conclude with a paragraph defining a test:
Test me with "east / duck / east / jump / east / duck / east / rescue esmerelda".
The idea is that typing one single command, TEST ME, into the resulting story should show off what the extension does.
When an extension contains more than one example, they should be given in order of asterisk rating, that is, starting with the * examples, then the ** examples, and so on up.
Extension documentation can provide "paste" buttons, much like the examples in this book. For example:
The coriander is a herb. Understand "cilantro" as the coriander.
Note that the paste button, denoted "*:", pastes in the text following it, but only as far as the next paragraph of unindented documentation - here, the one beginning "If we...". (But of course, an extension can have multiple paste buttons if desired.)