suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

scribble/text documentation, and a few other fixes and comments

Browse Source 
svn: r8821

original commit: 1e32dbd324
This commit is contained in:
Eli Barzilay 2008-02-28 14:27:37 +00:00 committed by Robby Findler
parent 9e38074a60
commit c2cdfd6e3b
1 changed files with 13 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
pkgs/racket-doc/scribblings/style/scribble.scrbl
View File

@ -15,6 +15,8 @@ word. Thus, the
description will often start with ``Produces.'' Refer to arguments and description will often start with ``Produces.'' Refer to arguments and
sub-forms by name. sub-forms by name.
@; [Eli] It's probably a good idea to say here that it's better to
@; refer to "functions" instead of "procedures".
Do not use the word ``argument'' to describe a sub-form in a syntactic Do not use the word ``argument'' to describe a sub-form in a syntactic
form; use the term ``sub-form'' instead, reserving ``argument'' for form; use the term ``sub-form'' instead, reserving ``argument'' for
values or expressions in a function call. Refer to libraries and values or expressions in a function call. Refer to libraries and
@ -67,7 +69,7 @@ typeset as variables. The correct description is
@verbatim[#:indent 2]|{@scheme[(_rator-expr _rand-expr ...)]}| @verbatim[#:indent 2]|{@scheme[(_rator-expr _rand-expr ...)]}|
which produces @scheme[(_rator-expr _rand-expr ...)], where which produces @scheme[(_rator-expr _rand-expr ...)], where
@schemeidfont{rator-expr} @schemeidfont{rand-expr} are typeset as @schemeidfont{rator-expr} and @schemeidfont{rand-expr} are typeset as
meta-variables. The @scheme[defproc], @scheme[defform], @|etc| forms meta-variables. The @scheme[defproc], @scheme[defform], @|etc| forms
greatly reduce this burden in descriptions, since they automatically greatly reduce this burden in descriptions, since they automatically
set up meta-variable typesetting for non-literal identifiers. In set up meta-variable typesetting for non-literal identifiers. In
@ -83,9 +85,11 @@ specific sequence of characters.
When showing example evaluations, use the REPL-snapshot style: When showing example evaluations, use the REPL-snapshot style:
@verbatim[#:indent 2]|{
@interaction[ @interaction[
(+ 1 2) (+ 1 2)
] ]
}|
See also the @scheme[scribble/eval] library. See also the @scheme[scribble/eval] library.
@ -98,6 +102,11 @@ In prose, use @litchar{``} and @litchar{''} quotation marks instead of
@litchar{"}. Use @litchar{---} for an em-dash, and do not include @litchar{"}. Use @litchar{---} for an em-dash, and do not include
spaces on either side, though it will typeset as an en-dash and spaces spaces on either side, though it will typeset as an en-dash and spaces
in HTML output. Use American style for quotation marks and punctuation in HTML output. Use American style for quotation marks and punctuation
@; [Eli] BTW, I've asked several people about this, and the general
@; agreement that I've seen is that this is a rather arbitrary rule
@; and there's no harm in doing the more logical thing of putting
@; the punctuations outside quotations and parens. Just like you
@; did at the end of this sentence...
at the end of quotation marks (i.e., a sentence-terminating period at the end of quotation marks (i.e., a sentence-terminating period
goes inside the quotation marks). Of course, this rule does not apply goes inside the quotation marks). Of course, this rule does not apply
for quotation marks that are part of code. for quotation marks that are part of code.