11 PLT Reference Style Guide
Notes toward an eventual guide chapter...
In the descriptive body of defform, defproc, etc., do not start with “This...” Instead, start with a sentence whose implicit subject is the form or value being described. Thus, the description will often start with “Produces.” Refer to arguments by name.
Use id or something that ends -id in a syntactic form to mean an identifier, not identifier, name, or symbol. Similarly, use expr or something that ends -expr for an expression position within a syntactic form. Use body for a form (definition or expression) in an internal-definition position.
Break up HTML documents into multiple pages by using the 'toc section style in combination with local-table-of-contents. The local-table-of-contents should go after a short introduction, if any. In some cases, a longer introduction is better placed after the local-table-of-contents call, especially if the contents are short.
Favor hyperlinks installed by scheme instead of explicit section links produced by secref. In particular, there’s rarely a need to have both links (e.g., “see scheme in Typesetting Code”).
Link tags are resolved relative to surrounding sections, but if you think anyone will ever refer to a link targer, try to pick a tag that will be globally unique. For example, all of the section tags in the PLT Scheme reference start with mz:.
Pay attention to the difference between identifiers and meta-variables when using scheme, especially outside of defproc or defform. Prefix a meta-variable with _; for example,
@scheme[(rator-expr rand-expr ...)] |
would be the wrong way to refer to the grammar of a function call, because it produces (rator-expr rand-expr ...), where rator-expr and rand-expr are typeset as variables. The correct description is
@scheme[(_rator-expr _rand-expr ...)] |
which produces (rator-expr rand-expr ...), where rator-expr rand-expr are typeset as meta-variables. The defproc, defform, etc. forms greatly reduce this burden in description, since they automatically set up meta-variable typesetting for non-literal identifiers.
To typeset an identifier with no particular interpretation – syntax, variable, meta-variable, etc. – use schemeidfont (e.g., as in rand-expr above). Otherwise, use litchar, not merely schemefont or verbatim, to refer to a specific sequence of characters.
Use American style for quotation marks and punctuation at the end of quotation marks (i.e., a sentence-terminating period goes inside the quotation marks). Of course, this rule does not apply for quotation marks that are part of code.