From d7dbdc7334c61abed326a74969d1386df5ad5f40 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sun, 2 Sep 2007 17:39:32 +0000 Subject: [PATCH] 371.2 svn: r7263 original commit: e4cbc4e6a938fd5bd90aab305ca39d61e7eae151 --- .../scribblings/style/scribble.scrbl | 24 ++----------------- 1 file changed, 2 insertions(+), 22 deletions(-) diff --git a/pkgs/racket-doc/scribblings/style/scribble.scrbl b/pkgs/racket-doc/scribblings/style/scribble.scrbl index d8f535b8c3..23eb243ef7 100644 --- a/pkgs/racket-doc/scribblings/style/scribble.scrbl +++ b/pkgs/racket-doc/scribblings/style/scribble.scrbl @@ -2,12 +2,10 @@ @require[(lib "manual.ss" "scribble")] @require["utils.ss"] -@title[#:tag "reference-style"]{PLT Reference Style Guide} - -@italic{Notes toward an eventual guide chapter...} +@title[#:tag "reference-style"]{Style Guide} 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. Thus, the description will often start with ``Produces.'' Refer to arguments by name. @@ -20,24 +18,6 @@ expression position within a syntactic form. Use @schemeidfont{body} for a form (definition or expression) in an internal-definition position. -Break up HTML documents into multiple pages by using the @scheme['toc] -section style in combination with -@scheme[local-table-of-contents]. The @scheme[local-table-of-contents] -should go after a short introduction, if any. In some cases, a longer -introduction is better placed after the -@scheme[local-table-of-contents] call, especially if the contents are -short. - -Favor hyperlinks installed by @scheme[scheme] instead of explicit -section links produced by @scheme[secref]. In particular, there's -rarely a need to have both links (e.g., ``see @scheme[scheme] in -@secref["scribble:manual: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 @litchar["mz:"]. - Pay attention to the difference between identifiers and meta-variables when using @scheme[scheme], especially outside of @scheme[defproc] or @scheme[defform]. Prefix a meta-variable with @litchar{_}; for