/usr/share/doc/racket/scribble/reference-style.html is in racket-doc 6.1-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>4.2 Style Guide</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">Scribble:<span class="mywbr"> </span> The Racket Documentation Tool</a></td></tr></table></div><div class="tocviewsublisttop" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="getting-started.html" class="tocviewlink" data-pltdoc="x">Getting Started</a></td></tr><tr><td align="right">2 </td><td><a href="reader.html" class="tocviewlink" data-pltdoc="x">@ Syntax</a></td></tr><tr><td align="right">3 </td><td><a href="generic-prose.html" class="tocviewlink" data-pltdoc="x">High-<wbr></wbr>Level Scribble API</a></td></tr><tr><td align="right">4 </td><td><a href="plt-manuals.html" class="tocviewselflink" data-pltdoc="x">Scribbling Documentation</a></td></tr><tr><td align="right">5 </td><td><a href="lp.html" class="tocviewlink" data-pltdoc="x">Literate Programming</a></td></tr><tr><td align="right">6 </td><td><a href="internals.html" class="tocviewlink" data-pltdoc="x">Low-<wbr></wbr>Level Scribble API</a></td></tr><tr><td align="right">7 </td><td><a href="running.html" class="tocviewlink" data-pltdoc="x">Running <span class="stt">scribble</span></a></td></tr><tr><td align="right"></td><td><a href="doc-index.html" class="tocviewlink" data-pltdoc="x">Index</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">▼</a></td><td>4 </td><td><a href="plt-manuals.html" class="tocviewlink" data-pltdoc="x">Scribbling Documentation</a></td></tr></table><div class="tocviewsublist" style="display: block;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">4.1 </td><td><a href="how-to-doc.html" class="tocviewlink" data-pltdoc="x">Getting Started with Documentation</a></td></tr><tr><td align="right">4.2 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Style Guide</a></td></tr><tr><td align="right">4.3 </td><td><a href="manual.html" class="tocviewlink" data-pltdoc="x">Manual Forms</a></td></tr><tr><td align="right">4.4 </td><td><a href="scheme.html" class="tocviewlink" data-pltdoc="x">Racket</a></td></tr><tr><td align="right">4.5 </td><td><a href="eval.html" class="tocviewlink" data-pltdoc="x">Evaluation and Examples</a></td></tr><tr><td align="right">4.6 </td><td><a href="srcdoc.html" class="tocviewlink" data-pltdoc="x">In-<wbr></wbr>Source Documentation</a></td></tr><tr><td align="right">4.7 </td><td><a href="bnf.html" class="tocviewlink" data-pltdoc="x">BNF Grammars</a></td></tr><tr><td align="right">4.8 </td><td><a href="Compatibility_Libraries.html" class="tocviewlink" data-pltdoc="x">Compatibility Libraries</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_2");">►</a></td><td>4.2 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Style Guide</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_2"><table cellspacing="0" cellpadding="0"><tr><td align="right">4.2.1 </td><td><a href="#%28part._.Prose_and_.Terminology%29" class="tocviewlink" data-pltdoc="x">Prose and Terminology</a></td></tr><tr><td align="right">4.2.2 </td><td><a href="#%28part._.Typesetting_.Code%29" class="tocviewlink" data-pltdoc="x">Typesetting Code</a></td></tr><tr><td align="right">4.2.3 </td><td><a href="#%28part._.Typesetting_.Prose%29" class="tocviewlink" data-pltdoc="x">Typesetting Prose</a></td></tr><tr><td align="right">4.2.4 </td><td><a href="#%28part._.Section_.Titles%29" class="tocviewlink" data-pltdoc="x">Section Titles</a></td></tr><tr><td align="right">4.2.5 </td><td><a href="#%28part._.Indexing%29" class="tocviewlink" data-pltdoc="x">Indexing</a></td></tr><tr><td align="right">4.2.6 </td><td><a href="#%28part._examples-style%29" class="tocviewlink" data-pltdoc="x">Examples</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">4.2.1<tt> </tt></span><a href="#%28part._.Prose_and_.Terminology%29" class="tocsubseclink" data-pltdoc="x">Prose and Terminology</a></td></tr><tr><td><span class="tocsublinknumber">4.2.2<tt> </tt></span><a href="#%28part._.Typesetting_.Code%29" class="tocsubseclink" data-pltdoc="x">Typesetting Code</a></td></tr><tr><td><span class="tocsublinknumber">4.2.3<tt> </tt></span><a href="#%28part._.Typesetting_.Prose%29" class="tocsubseclink" data-pltdoc="x">Typesetting Prose</a></td></tr><tr><td><span class="tocsublinknumber">4.2.4<tt> </tt></span><a href="#%28part._.Section_.Titles%29" class="tocsubseclink" data-pltdoc="x">Section Titles</a></td></tr><tr><td><span class="tocsublinknumber">4.2.5<tt> </tt></span><a href="#%28part._.Indexing%29" class="tocsubseclink" data-pltdoc="x">Indexing</a></td></tr><tr><td><span class="tocsublinknumber">4.2.6<tt> </tt></span><a href="#%28part._examples-style%29" class="tocsubseclink" data-pltdoc="x">Examples</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="how-to-doc.html" title="backward to "4.1 Getting Started with Documentation"" data-pltdoc="x">← prev</a> <a href="plt-manuals.html" title="up to "4 Scribbling Documentation"" data-pltdoc="x">up</a> <a href="manual.html" title="forward to "4.3 Manual Forms"" data-pltdoc="x">next →</a></span> </div><h4 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""reference-style"">4.2<tt> </tt><a name="(part._reference-style)"></a>Style Guide</h4><p>Consistent style—<wbr></wbr>for terms, typesetting, and prose—<wbr></wbr>makes
documentation clearer. As much as possible, follow the rules listed in
this section. Many of the rules are arbitrary in the sense that a
different choice of rule could work fine, but the only way to make our
documentation consistent is to pick one of the choices.</p><p>There are too many rules to absorb easily on a first reading. Re-read
this section after writing documentation for a library or two, and
revisit the section periodically to refresh your memory and check for
new rules.</p><h5 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""Prose_and_Terminology"">4.2.1<tt> </tt><a name="(part._.Prose_and_.Terminology)"></a>Prose and Terminology</h5><p>In the descriptive body of <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%29%29" class="RktStxLink" data-pltdoc="x">defform</a></span>, <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defproc%29%29" class="RktStxLink" data-pltdoc="x">defproc</a></span>, etc.,
do not start with “This ...” Instead, start with a sentence whose
implicit subject is the form or value being described (but only start
the first sentence that way). Capitalize the first word. Thus, the
description will often start with “Returns” or “Produces.” Refer
to arguments and sub-forms by name.</p><p>Do not use the word “argument” to describe a sub-form in a syntactic
form; use the term “sub-form” instead, reserving “argument” for
values or expressions in a function call. Refer to libraries and
languages as such, rather than as “modules” (even though the form to
typeset a library or language name is called <span class="RktSym"><a href="scribble_manual_code.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._racketmodname%29%29" class="RktStxLink" data-pltdoc="x">racketmodname</a></span>).
Do not call an identifier (i.e., a syntactic element) a “variable”
or a “symbol.” Do not use the word “expression” for a form that is
a definition or might be a definition; use the word “form,” instead.
Prefer “function” to “procedure.”</p><p>Use the word “list” only when you mean a run-time value consisting
of the empty list and cons cells; use the word “sequence” in other
cases, if you must use any word. For example, do not write that
<span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=begin.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._begin%2529%2529&version=6.1" class="RktStxLink Sq" data-pltdoc="x">begin</a></span> has a “list of sub-forms;” instead, it has a
“sequence of sub-forms.” Similarly, do not refer to a “list of
arguments” in a function call; just write “arguments” if possible,
or write “sequence of argument expressions.” (Unfortunately,
“<a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=sequences.html%23%2528tech._sequence%2529&version=6.1" class="techoutside Sq" data-pltdoc="x"><span class="techinside">sequence</span></a>” has acquired a
specific run-time meaning, too, but the collision is less severe than
the historical confusion between lists and other entities in Lisp.)</p><p>Avoid cut-and-paste for descriptive text. If two functions are
similar, consider documenting them together with
<span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._deftogether%29%29" class="RktStxLink" data-pltdoc="x">deftogether</a></span>. To abstract a description, consider using
explicit prose abstraction, such as “<span class="RktSym">x</span> is like <span class="RktSym">y</span>,
except that ...,” instead of abstracting the source and instantiating
it multiple times; often, a prose abstraction is clearer to the reader
than a hidden abstraction in the document implementation.</p><p>Hyphenate the words “sub-form” and “sub-expression.”</p><p>Use “Windows,” “Mac OS X,” and “Unix” for the three
“platforms” (as opposed to “systems”) on which Racket runs. Use
“Unix” as a generic term for Unix-like operating systems—<wbr></wbr>notably
including Linux—<wbr></wbr>other than Mac OS X. Use “Unix” even when “Gtk”
or “the X11 windowing system” would be more precisely correct, but
use “X11” as adjective when necessary, such as “X11 display.”
Racket runs “on” a platform, as opposed to “under” a platform.</p><h5 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""Typesetting_Code"">4.2.2<tt> </tt><a name="(part._.Typesetting_.Code)"></a>Typesetting Code</h5><p>Use <span class="RktSym">id</span> or a name that ends <span class="RktSym">-id</span> in
<span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%29%29" class="RktStxLink" data-pltdoc="x">defform</a></span> to mean an identifier, not <span class="RktSym">identifier</span>,
<span class="RktSym">variable</span>, <span class="RktSym">name</span>, or
<span class="RktSym">symbol</span>. Similarly, use <span class="RktSym">expr</span> or something
that ends <span class="RktSym">-expr</span> for an expression position within a
syntactic form. Use <span class="RktSym">body</span> for a form (definition or
expression) in an internal-definition position—<wbr></wbr>always followed by
<span class="RktSym">...+</span> in a grammar description. Do not use
<span class="RktSym">expr</span> for something that isn’t exactly an expression,
<span class="RktSym">id</span> for something that isn’t exactly an identifier, etc.;
instead, use <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%2Fsubs%29%29" class="RktStxLink" data-pltdoc="x">defform/subs</a></span> to define a new non-terminal.</p><p>Beware of using <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._deftogether%29%29" class="RktStxLink" data-pltdoc="x">deftogether</a></span> to define multiple variants of a
syntactic form or procedure, because each <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%29%29" class="RktStxLink" data-pltdoc="x">defform</a></span> or
<span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defproc%29%29" class="RktStxLink" data-pltdoc="x">defproc</a></span> creates a definition point, but each form or
procedure should have a single definition point. (Scribble issues a
warning when a binding has multiple definition points.) Instead, use
<span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defproc%2A%29%29" class="RktStxLink" data-pltdoc="x">defproc*</a></span> or <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%2A%29%29" class="RktStxLink" data-pltdoc="x">defform*</a></span>.</p><p>For function arguments, use <span class="RktSym">v</span> as the meta-variable for “any
value.” Use <span class="RktSym">x</span> as a meta-variable only for numerical
values. Other conventions include <span class="RktSym">lst</span> for a list and
<span class="RktSym">proc</span> for a procedure.</p><p>Pay attention to the difference between identifiers and meta-variables
when using <span class="RktSym"><a href="scribble_manual_code.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._racket%29%29" class="RktStxLink" data-pltdoc="x">racket</a></span>, especially outside of <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defproc%29%29" class="RktStxLink" data-pltdoc="x">defproc</a></span> or
<span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%29%29" class="RktStxLink" data-pltdoc="x">defform</a></span>. Prefix a meta-variable with <span class="RktInBG"><span class="hspace"></span><span class="RktIn">_</span><span class="hspace"></span></span>; for
example,</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="hspace"> </span><span class="stt">@racket[(rator-expr rand-expr ...)]</span></p></td></tr></table></p><p>would be the wrong way to refer to the grammar of a function call,
because it produces <span class="RktPn">(</span><span class="RktSym">rator-expr</span><span class="stt"> </span><span class="RktSym">rand-expr</span><span class="stt"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=stx-patterns.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fstxcase-scheme..rkt%2529._......%2529%2529&version=6.1" class="RktStxLink Sq" data-pltdoc="x">...</a></span><span class="RktPn">)</span>, where
<span class="RktSym">rator-expr</span> and <span class="RktSym">rand-expr</span> are
typeset as variables. The correct description is</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="hspace"> </span><span class="stt">@racket[(_rator-expr _rand-expr ...)]</span></p></td></tr></table></p><p>which produces <span class="RktPn">(</span><span class="RktVar">rator-expr</span><span class="stt"> </span><span class="RktVar">rand-expr</span><span class="stt"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=stx-patterns.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fstxcase-scheme..rkt%2529._......%2529%2529&version=6.1" class="RktStxLink Sq" data-pltdoc="x">...</a></span><span class="RktPn">)</span>, where
<span class="RktSym">rator-expr</span> and <span class="RktSym">rand-expr</span> are typeset as
meta-variables. The <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defproc%29%29" class="RktStxLink" data-pltdoc="x">defproc</a></span>, <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%29%29" class="RktStxLink" data-pltdoc="x">defform</a></span>, etc<span class="Sendabbrev">.</span> forms
greatly reduce this burden in descriptions, since they automatically
set up meta-variable typesetting for non-literal identifiers. In
<span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%29%29" class="RktStxLink" data-pltdoc="x">defform</a></span>, be sure to include literal identifiers (i.e., those
not meant as variables, other than the form name being defined) in a
<span class="RktPn">#:literals</span> clause.</p><p>To typeset an identifier with no particular interpretation—<wbr></wbr>syntax,
variable, meta-variable, etc.—<wbr></wbr>use <span class="RktSym"><a href="scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._racketidfont%29%29" class="RktValLink" data-pltdoc="x">racketidfont</a></span> (e.g., as in
<span class="RktSym">rand-expr</span> above). Otherwise, use <span class="RktSym"><a href="scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._litchar%29%29" class="RktValLink" data-pltdoc="x">litchar</a></span>,
not merely <span class="RktSym"><a href="scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._racketfont%29%29" class="RktValLink" data-pltdoc="x">racketfont</a></span> or <span class="RktSym"><a href="base.html#%28def._%28%28lib._scribble%2Fbase..rkt%29._verbatim%29%29" class="RktValLink" data-pltdoc="x">verbatim</a></span>, to refer to a
specific sequence of characters.</p><p>When a syntactic form synthesizes an identifier from a given
identifier, use a combination of <span class="RktSym"><a href="scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._racketidfont%29%29" class="RktValLink" data-pltdoc="x">racketidfont</a></span> and
<span class="RktSym"><a href="scribble_manual_code.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._racket%29%29" class="RktStxLink" data-pltdoc="x">racket</a></span> to describe the identifiers. For example, if
<span class="RktVar">id</span> is combined with <span class="RktSym">is-</span> and <span class="RktSym">?</span>
to form <span class="RktSym">is-</span><span class="RktVar">id</span><span class="RktSym">?</span>, then implement
that identifier as
<span class="RktMeta"></span><span class="RktPn">@</span><span class="RktSym"><a href="scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._racketidfont%29%29" class="RktValLink" data-pltdoc="x">racketidfont</a></span><span class="RktPn">{</span><span class="RktMeta">is-</span><span class="RktPn">}</span><span class="RktPn">@</span><span class="RktSym"><a href="scribble_manual_code.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._racket%29%29" class="RktStxLink" data-pltdoc="x">racket</a></span><span class="RktPn">[</span><span class="RktSym">id</span><span class="RktPn">]</span><span class="RktPn">@</span><span class="RktSym"><a href="scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._racketidfont%29%29" class="RktValLink" data-pltdoc="x">racketidfont</a></span><span class="RktPn">{</span><span class="RktMeta">?</span><span class="RktPn">}</span><span class="RktMeta"></span>.</p><p>When using <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%29%29" class="RktStxLink" data-pltdoc="x">defform</a></span> to describe a syntactic form, don’t
confuse the <span class="RktPn">#:contracts</span> clause with a grammar
specification. Use <span class="RktPn">#:contracts</span> only for expressions within the
syntactic form, and the contract is a run-time constraint—<wbr></wbr>not a
syntactic constraint, such as requiring a sub-form to be an identifier.
Use <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%2Fsubs%29%29" class="RktStxLink" data-pltdoc="x">defform/subs</a></span> for syntactic constraints.</p><p>When showing example evaluations, use the REPL-snapshot style:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="hspace"> </span><span class="stt">@interaction[</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">(+ 1 2)</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">]</span></p></td></tr></table></p><p>See also the <span class="RktSym">scribble/eval</span> library and <a href="#%28part._examples-style%29" data-pltdoc="x">Examples</a>.</p><p>Use four dots, <span class="RktInBG"><span class="hspace"></span><span class="RktIn">....</span><span class="hspace"></span></span>, in place of omitted code, since
<span class="RktInBG"><span class="hspace"></span><span class="RktIn">...</span><span class="hspace"></span></span> means repetition.</p><h5 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""Typesetting_Prose"">4.2.3<tt> </tt><a name="(part._.Typesetting_.Prose)"></a>Typesetting Prose</h5><p>Refrain from referring to documentation “above” or “below,” and
instead have a hyperlink point to the right place.</p><p>In prose, use <span class="RktInBG"><span class="hspace"></span><span class="RktIn">``</span><span class="hspace"></span></span> and <span class="RktInBG"><span class="hspace"></span><span class="RktIn">''</span><span class="hspace"></span></span> quotation marks instead of
<span class="RktInBG"><span class="hspace"></span><span class="RktIn">"</span><span class="hspace"></span></span>. Use <span class="RktInBG"><span class="hspace"></span><span class="RktIn">---</span><span class="hspace"></span></span> for an em dash, and do not include
spaces on either side. 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.</p><p>Do not use a citation reference (as created by <span class="RktSym"><a href="Bibliography.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._cite%29%29" class="RktValLink" data-pltdoc="x">cite</a></span>) as a
noun; use it as an annotation.</p><p>Do not start a sentence with a Racket variable name, since it is
normally lowercase. For example, use “The <span class="RktVar">thing</span> argument
is...” instead of “<span class="RktVar">thing</span> is...”</p><p>Use <span class="RktSym"><a href="Miscellaneous.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._etc%29%29" class="RktValLink" data-pltdoc="x">etc</a></span> for “etc<span class="Sendabbrev">.</span>” when it does not end a sentence, and
include a comma after “etc<span class="Sendabbrev">.</span>” unless it ends a sentence of is
followed by other punctuation (such as a parenthesis).</p><h5 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""Section_Titles"">4.2.4<tt> </tt><a name="(part._.Section_.Titles)"></a>Section Titles</h5><p>Capitalize all words except articles (“the,” “a,” etc.),
prepositions, and conjunctions that are not at the start of the title.</p><p>A manual title should normally start with a suitable keyword or key
phrase (such as “Scribble” for this manual) that is in boldface. If
the key word is primarily an executable name, use <span class="RktSym"><a href="doc-strings.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._exec%29%29" class="RktValLink" data-pltdoc="x">exec</a></span>
instead of <span class="RktSym"><a href="base.html#%28def._%28%28lib._scribble%2Fbase..rkt%29._bold%29%29" class="RktValLink" data-pltdoc="x">bold</a></span>. Optionally add further descriptive text in
the title after a colon, where the text starting with the colon is not
in boldface.</p><h5 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""Indexing"">4.2.5<tt> </tt><a name="(part._.Indexing)"></a>Indexing</h5><p>Document and section titles, identifiers that are documented with
<span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defproc%29%29" class="RktStxLink" data-pltdoc="x">defproc</a></span>, <span class="RktSym"><a href="doc-forms.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defform%29%29" class="RktStxLink" data-pltdoc="x">defform</a></span>, etc. are automatically indexed, as
are terms defined with <span class="RktSym"><a href="section-links.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._deftech%29%29" class="RktValLink" data-pltdoc="x">deftech</a></span>.</p><p>Symbols are not indexed automatically. Use <span class="RktSym"><a href="manual-indexing.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._indexed-racket%29%29" class="RktStxLink" data-pltdoc="x">indexed-racket</a></span>
instead of <span class="RktSym"><a href="scribble_manual_code.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._racket%29%29" class="RktStxLink" data-pltdoc="x">racket</a></span> for the instance of a symbol that roughly
defines the use. For an example, try searching for “truncate” to
find <span class="RktVal">'</span><span class="RktVal">truncate</span> as used with <span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=file-ports.html%23%2528def._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._open-output-file%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">open-output-file</a></span>. Do no
use something like <span class="RktPn">(</span><span class="RktSym"><a href="base.html#%28def._%28%28lib._scribble%2Fbase..rkt%29._index%29%29" class="RktValLink" data-pltdoc="x">index</a></span><span class="stt"> </span><span class="RktVal">"'truncate"</span><span class="RktPn">)</span> to index a symbol,
because it will not typeset correctly (i.e., in a fixed-width font
with the color of a literal).</p><p>Use <span class="RktSym"><a href="base.html#%28def._%28%28lib._scribble%2Fbase..rkt%29._index%29%29" class="RktValLink" data-pltdoc="x">index</a></span>, <span class="RktSym"><a href="base.html#%28def._%28%28lib._scribble%2Fbase..rkt%29._as-index%29%29" class="RktValLink" data-pltdoc="x">as-index</a></span>, and <span class="RktSym"><a href="base.html#%28def._%28%28lib._scribble%2Fbase..rkt%29._section-index%29%29" class="RktValLink" data-pltdoc="x">section-index</a></span> as a
last resort. Create index entries for terms that are completely
different from terms otherwise indexed. Do not try to index minor
variations of a term or phrase in an attempt to improve search
results; if search fails to find a word or phrase due to a minor
variation, then the search algorithm should be fixed, not the index
entry.</p><h5 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""examples-style"">4.2.6<tt> </tt><a name="(part._examples-style)"></a>Examples</h5><p>Strive to include examples (using <span class="RktSym"><a href="eval.html#%28form._%28%28lib._scribble%2Feval..rkt%29._examples%29%29" class="RktStxLink" data-pltdoc="x">examples</a></span>) with the
documentation of every function and syntactic form. When writing
examples, refrain from using nonsense words like “foo” and “bar.”
For example, when documenting <span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._member%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">member</a></span>, resist the temptation
to write</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._member%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">member</a></span><span class="hspace"> </span><span class="RktVal">"foo"</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">"bar"</span><span class="hspace"> </span><span class="RktVal">"foo"</span><span class="hspace"> </span><span class="RktVal">"baz"</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">'("foo" "baz")</span></p></td></tr></table></blockquote><p>and instead write something like</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._member%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">member</a></span><span class="hspace"> </span><span class="RktVal">"Groucho"</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">"Harpo"</span><span class="hspace"> </span><span class="RktVal">"Groucho"</span><span class="hspace"> </span><span class="RktVal">"Zeppo"</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">'("Groucho" "Zeppo")</span></p></td></tr></table></blockquote><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="how-to-doc.html" title="backward to "4.1 Getting Started with Documentation"" data-pltdoc="x">← prev</a> <a href="plt-manuals.html" title="up to "4 Scribbling Documentation"" data-pltdoc="x">up</a> <a href="manual.html" title="forward to "4.3 Manual Forms"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|