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

hierlist docs; fix latex/pdf output when a paragraph starts with n hspace

Browse Source 
svn: r9276

original commit: 02fbaca2b7
This commit is contained in:
Matthew Flatt 2008-04-12 14:42:02 +00:00 committed by Robby Findler
parent c2cdfd6e3b
commit 10d48bf427
1 changed files with 16 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -10,13 +10,10 @@
In the descriptive body of @scheme[defform], @scheme[defproc], etc., In the descriptive body of @scheme[defform], @scheme[defproc], etc.,
do not start with ``This ...'' Instead, start with a sentence whose do not start with ``This ...'' Instead, start with a sentence whose
implicit subject is the form or value being described. Capitalize the first implicit subject is the form or value being described. Capitalize the
word. Thus, the first word. Thus, the description will often start with ``Returns'' or
description will often start with ``Produces.'' Refer to arguments and ``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
@ -25,6 +22,7 @@ typeset a library or language name is called @scheme[schememodname]).
Do not call an identifier (i.e., a syntactic element) a ``variable'' 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 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. a definition or might be a definition; use the word ``form,'' instead.
Prefer ``function'' to ``procedure.''
Avoid cut-and-paste for descriptive text. If two functions are Avoid cut-and-paste for descriptive text. If two functions are
similar, consider documenting them together with similar, consider documenting them together with
@ -117,3 +115,15 @@ noun; use it as an annotation.
Do not start a sentence with a Scheme variable name, since it is Do not start a sentence with a Scheme variable name, since it is
normally lowercase. For example, use ``The @scheme[_thing] argument normally lowercase. For example, use ``The @scheme[_thing] argument
is...'' instead of ``@scheme[_thing] is...'' is...'' instead of ``@scheme[_thing] is...''
@section{Section Titles}
Capitalize all words except articles (``the,'' ``a,'' etc.),
prepositions, and conjunctions that are not at the start of the title.
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 @scheme[exec]
instead of @scheme[bold]. Optionally add further descriptive text in
the title after a colon, where the text starting with the colon is not
in boldface.