diff --git a/collects/scribble/basic.ss b/collects/scribble/basic.ss index 44ed7128..d3124678 100644 --- a/collects/scribble/basic.ss +++ b/collects/scribble/basic.ss @@ -122,7 +122,7 @@ (provide section-index index index* as-index index-section) (define (section-index . elems) - (make-section-index-decl (map element->string elems) elems)) + (make-part-index-decl (map element->string elems) elems)) (define (gen-target) (format "index:~s:~s" (current-inexact-milliseconds) (gensym))) diff --git a/collects/scribble/decode.ss b/collects/scribble/decode.ss index 7aa101df..8959a9f9 100644 --- a/collects/scribble/decode.ss +++ b/collects/scribble/decode.ss @@ -20,8 +20,8 @@ [tag (or/c false/c string?)] [title list?])] [splice ([run list?])] - [section-index-decl ([plain-seq (listof string?)] - [entry-seq list?])]) + [part-index-decl ([plain-seq (listof string?)] + [entry-seq list?])]) (define (decode-string s) (let loop ([l '((#rx"---" mdash) @@ -68,8 +68,8 @@ #f null `(part ,tag) - (section-index-decl-plain-seq k) - (section-index-decl-entry-seq k))) + (part-index-decl-plain-seq k) + (part-index-decl-entry-seq k))) keys tags)]) (if title (cons (make-index-element @@ -152,7 +152,7 @@ [(splice? (car l)) (loop (append (splice-run (car l)) (cdr l)) next? keys accum title tag style)] [(null? (cdr l)) (loop null #f keys (cons (car l) accum) title tag style)] - [(section-index-decl? (car l)) + [(part-index-decl? (car l)) (loop (cdr l) next? (cons (car l) keys) accum title tag style)] [(and (pair? (cdr l)) (splice? (cadr l))) diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index 8d89ae9d..2111e096 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.ss @@ -1088,17 +1088,6 @@ ;; ---------------------------------------- - (provide where-is-one-of - is-one-of) - - (define (where-is-one-of id) - (make-element #f (list "where " id " is one of"))) - - (define (is-one-of id) - (make-element #f (list id " is one of"))) - - ;; ---------------------------------------- - (provide math) (define (math . s) (let ([c (decode-content s)]) diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl index 6cf092ff..bce5f6fd 100644 --- a/collects/scribblings/scribble/basic.scrbl +++ b/collects/scribblings/scribble/basic.scrbl @@ -42,17 +42,31 @@ Although the procedures are mostly design to be used from @elem["@"] mode, they are easier to document in Scheme mode (partly because we have Scribble's @file{scheme.ss} and @file{manual.ss}). +@; ------------------------------------------------------------------------ + @section{Document Structure} @defproc[(title [#:tag tag (or/c false/c string?) #f] [#:style style any/c #f] [pre-content any/c] ...+) - title-decl?]{ Generates a @scheme[title-decl] to - be picked up by @scheme[decode] or @scheme[decode-part]. The - @scheme[pre-content]s list is parsed with @scheme[decode-content] for - the title content. If @scheme[tag] is @scheme[#f], a tag string is - generated automatically from the content. The tag string is combined - with the symbol @scheme['part] to form the full tag.} + title-decl?]{ + +Generates a @scheme[title-decl] to be picked up by @scheme[decode] or +@scheme[decode-part]. The @scheme[pre-content]s list is parsed with +@scheme[decode-content] for the title content. If @scheme[tag] is +@scheme[#f], a tag string is generated automatically from the +content. The tag string is combined with the symbol @scheme['part] to +form the full tag. + +A style of @scheme['toc] causes sub-sections to be generated as +separate pages in multi-page HTML output. A style of @scheme['index] +indicates an index section whose body is rendered in two columns for +Latex output. + +The section title is automatically indexed. For the index key, a +leading ``A'', ``An'', or ``The'' (followed by whitespace) is +removed.} + @def-section-like[section part-start?]{ Like @scheme[title], but generates a @scheme[part-start] of depth @scheme[0] to be by @@ -87,6 +101,8 @@ have Scribble's @file{scheme.ss} and @file{manual.ss}). visible to the enclosing context). Since this form expands to @scheme[require], it must be used in a module or top-level context.} +@; ------------------------------------------------------------------------ + @section{Text Styles} @def-elem-proc[elem]{ Parses the @scheme[pre-content] list using @@ -114,6 +130,8 @@ and produces an element with style @scheme[style-name]. } +@; ------------------------------------------------------------------------ + @section{Indexing} @defproc[(index [words (or/c string? (listof string?))] @@ -143,15 +161,37 @@ the list of contents render in the index (in parallel to index-element?]{ Like @scheme[index], but the word to index is determined by applying -@scheme[content->string] on the parsed @scheme[pre-content] list. +@scheme[content->string] on the parsed @scheme[pre-content] list.} -} +@defproc[(section-index [word string?] ...)]{ + +Creates a @scheme[part-index-decl] to be associated with the enclosing +section by @scheme[decode]. The @scheme[word]s serve as both the keys +and as the rendered forms of the keys.} + + +@defproc[(index-section [tag string?])]{ + +Produces a section that shows the index the enclosing document. The +@scheme[tag] is required to be unique for each index among a set of +documents that share ``collected'' information.} + + +@; ------------------------------------------------------------------------ @section{Tables of Contents} @defproc[(table-of-contents) delayed-flow-element?]{ - Returns a flow element that expands to a table of contents for the - enclosing section. For LaTeX output, however, the table of contents - currently spans the entire enclosing document. -} + +Returns a delayed flow element that expands to a table of contents for +the enclosing section. For LaTeX output, however, the table of +contents currently spans the entire enclosing document.} + + +@defproc[(local-table-of-contents) delayed-flow-element?]{ + +Returns a delayed flow element that may expand to a table of contents +for the enclosing section, depending on the output type. For +multi-page HTML output, the flow element is a table of contents; for +Latex output, the flow element is empty.} diff --git a/collects/scribblings/scribble/decode.scrbl b/collects/scribblings/scribble/decode.scrbl index 19becfb3..3d3c94b4 100644 --- a/collects/scribblings/scribble/decode.scrbl +++ b/collects/scribblings/scribble/decode.scrbl @@ -34,10 +34,12 @@ special text conversions: Decodes a document, producing a part. In @scheme[lst], instances of @scheme[splice] are inlined into the list. An instance of @scheme[title-decl] supplies the title for the part. Instances of -@scheme[part-start] at level 0 trigger sub-part parsing. Instances of -@scheme[section] trigger are used as-is as subsections, and instances -of @scheme[paragraph] and other flow-element datatypes are used as-is -in the enclosing flow. +@scheme[index-section-decl] (that preceed any sub-part) add index +entries that point to the section. Instances of @scheme[part-start] at +level 0 trigger sub-part parsing. Instances of @scheme[section] +trigger are used as-is as subsections, and instances of +@scheme[paragraph] and other flow-element datatypes are used as-is in +the enclosing flow. } @@ -103,6 +105,13 @@ See @scheme[decode] and @scheme[decode-part]. } +@defstruct[part-index-decl ([plain-seq (listof string?)] + [content-seq list?])]{ + +See @scheme[decode]. The two fields are as for @scheme[index-element]. + +} + @defstruct[splice ([run list?])]{ See @scheme[decode], @scheme[decode-part], and @scheme[decode-flow]. diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index cd800ce4..6e025a14 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -9,7 +9,7 @@ The @file{manual.ss} module provides all of @file{basic.ss}, and more... @; ------------------------------------------------------------------------ -@section{Typesetting Code} +@section[#:tag "scribble:manual:code"]{Typesetting Code} @defform[(schemeblock datum ...)]{ @@ -109,6 +109,13 @@ module whose language is @scheme[lang].} a single line and wrapped with its enclosing paragraph, independent of the formatting of @scheme[datum].} +@defform[(indexed-scheme datum ...)]{ + +A combination of @scheme[scheme] and @scheme[as-index], with the +special case that if a single @scheme[datum] is provided and it is a +@scheme[quote] form, then the quote is removed from the key (so that +it's sorted using its unquoted form).} + @defform[(schemeresult datum ...)]{Like @scheme[scheme], but typeset as a REPL value (i.e., a single color with no hyperlinks).} @@ -145,9 +152,16 @@ for typesetting things like @scheme{#module}, which are not @defproc[(schemekeywordfont [pre-content any/c] ...) element?]{Like @scheme[schemefont], but colored as a syntactic form name.} +@defproc[(schemeparenfont [pre-content any/c] ...) element?]{Like +@scheme[schemefont], but colored like parentheses.} + +@defproc[(schememetafont [pre-content any/c] ...) element?]{Like +@scheme[schemefont], but colored as meta-syntax, such as backquote or +unquote.} + @defproc[(procedure [pre-content any/c] ...) element?]{Typesets the given content as a procedure name in a REPL result (e.g., in typewriter font -with a @schemefont{#} suffix.).} +with a @litchar{#} suffix.).} @defform[(var datum)]{Typesets @scheme[var] as an identifier that is an argument or sub-form in a procedure being @@ -167,9 +181,10 @@ in a form definition.} pre-flow ...)]{ Produces a sequence of flow elements (encaptured in a @scheme[splice]) -to document a procedure named @scheme[id]. The @scheme[id] is -registered so that @scheme[scheme]-typeset uses of the identifier -(with the same lexical binding) are hyperlinked to this documentation. +to document a procedure named @scheme[id]. The @scheme[id] is indexed, +and it also registered so that @scheme[scheme]-typeset uses of the +identifier (with the same lexical binding) are hyperlinked to this +documentation. Each @scheme[arg-spec] must have one of the following forms: @@ -222,9 +237,9 @@ Like @scheme[defproc], but for multiple cases with the same Produces a a sequence of flow elements (encaptured in a @scheme[splice]) to document a syntatic form named by @scheme[id]. The -@scheme[id] is registered so that @scheme[scheme]-typeset uses of the -identifier (with the same lexical binding) are hyperlinked to this -documentation. +@scheme[id] is indexed, and it is also registered so that +@scheme[scheme]-typeset uses of the identifier (with the same lexical +binding) are hyperlinked to this documentation. The @scheme[pre-flow]s list is parsed as a flow that documents the procedure. In this description, a reference to any identifier in @@ -240,24 +255,33 @@ layout, like @scheme[schemeblock], and unlike @scheme[defproc].} Like @scheme[defform], but for multiple forms using the same @scheme[id].} -@defform/subs[(defform/subs maybe-literals (id . datum) - ([nonterm-id clause-datum ...+] ...) - pre-flow ...) - ([maybe-literals code:blank - (code:line #:literals (literal-id ...))])]{ +@defform[(defform/subs maybe-literals (id . datum) + ([nonterm-id clause-datum ...+] ...) + pre-flow ...)]{ + Like @scheme[defform], but including an auxiliary grammar of non-terminals shown with the @scheme[id] form. Each @scheme[nonterm-id] is specified as being any of the corresponding @scheme[clause-datum]s, where the formatting of each @scheme[clause-datum] is preserved.} -@defform/subs[(specform maybe-literals (id . datum) pre-flow ...) - ([maybe-literals code:blank - (code:line #:literals (literal-id ...))])]{ -Like @scheme[defform], with without registering a definition, and with -indenting on the left for both the specification and the -@scheme[pre-flow]s.} +@defform[(defform/none datum pre-flow ...)]{ + +Like @scheme[defform], but without registering a definition.} + + +@defform[(defidform id pre-flow ...)]{ + +Like @scheme[defform], but with a plain @scheme[id] as the form.} + + +@defform[(specform maybe-literals (id . datum) pre-flow ...)]{ + +Like @scheme[defform], with without indexing or registering a +definition, and with indenting on the left for both the specification +and the @scheme[pre-flow]s.} + @defform[(specsubform maybe-literals datum pre-flow ...)]{ @@ -272,18 +296,64 @@ The @scheme[pre-flow]s list is parsed as a flow that documents the procedure. In this description, a reference to any identifier in @scheme[datum] is typeset as a sub-form non-terminal.} + +@defform[(specsubform/subs maybe-literals datum + ([nonterm-id clause-datum ...+] ...) + pre-flow ...)]{ + +Like @scheme[specsubform], but with a grammar like +@scheme[defform/subs].} + + +@defform[(specspecsubform maybe-literals datum pre-flow ...)]{ + +Like @scheme[specsubform], but indented an extra level. Since using +@scheme[specsubform] within the body of @scheme[specsubform] already +nests indentation, @scheme[specspecsubform] is for extra indentation +without nesting a description.} + + +@defform[(specspecsubform/subs maybe-literals datum + ([nonterm-id clause-datum ...+] ...) + pre-flow ...)]{ + +Like @scheme[specspecsubform], but with a grammar like +@scheme[defform/subs].} + + +@defform[(defparam id arg-id contract-expr-datum pre-flow ...)]{ + +Like @scheme[defproc], but for a parameter. The +@scheme[contract-expr-datum] serves as both the result contract on the +parameter and the contract on values supplied for the parameter. The +@scheme[arg-id] refers to the parameter argument in the latter case.} + +@defform[(defboolparam id arg-id pre-flow ...)]{ + +Like @scheme[defparam], but the contract on a parameter argument is +@scheme[any/c], and the contract on the parameter result is +@scheme[boolean?].} + + @defform[(defthing id contract-expr-datum pre-flow ...)]{ Like @scheme[defproc], but for a non-procedure binding.} + @defform/subs[(defstruct struct-name ([field-name contract-expr-datum] ...) + flag-keywords pre-flow ...) ([struct-name id - (id super-id)])]{ + (id super-id)] + [flag-keywords code:blank + #:immutable + (code:line #:inspector #f) + (code:line #:immutable #:inspector #f)])]{ Similar to @scheme[defform] or @scheme[defproc], but for a structure definition.} + @defform/subs[(schemegrammar maybe-literals id clause-datum ...+) ([maybe-literals code:blank (code:line #:literals (literal-id ...))])]{ @@ -293,6 +363,7 @@ mentioned in a @scheme[clause-datum] is typeset as a non-terminal, except for the identifiers listed as @scheme[literal-id]s, which are typeset as with @scheme[scheme].} + @defform[(schemegrammar* maybe-literals [id clause-datum ...+] ...)]{ Like @scheme[schemegrammar], but for typesetting multiple productions @@ -301,8 +372,10 @@ at once, aligned around the @litchar{=} and @litchar{|}.} @; ------------------------------------------------------------------------ @section{Various String Forms} -@defproc[(defterm [pre-content any/c] ...) element?]{Typesets the given -content as a defined term (e.g., in italic).} +@defproc[(defterm [pre-content any/c] ...) element?]{Typesets the +given content as a defined term (e.g., in italic). Consider using +@scheme[deftech] instead, though, so that uses of @scheme[tech] can +hyper-link to the definition.} @defproc[(onscreen [pre-content any/c] ...) element?]{ Typesets the given content as a string that appears in a GUI, such as the name of a @@ -317,30 +390,135 @@ as a file name (e.g., in typewriter font and in in quotes).} @defproc[(exec [pre-content any/c] ...) element?]{Typesets the given content as a command line (e.g., in typewriter font).} +@defproc[(envvar [pre-content any/c] ...) element?]{Typesets the given +content as an environment variable (e.g., in typewriter font).} + +@defproc[(Flag [pre-content any/c] ...) element?]{Typesets the given +content as a flag (e.g., in typewriter font with a leading hyphen).} + +@defproc[(DFlag [pre-content any/c] ...) element?]{Typesets the given +content a long flag (e.g., in typewriter font with two leading +hyphens).} + +@defproc[(math [pre-content any/c] ...) element?]{The content form of +@scheme[pre-content] is transformed: + + @itemize{ + + @item{Any immediate @scheme['rsquo] is converted to @scheme['prime].} + + @item{Parentheses and sequences of decimal digits in immediate + strings are left as-is, but any other immediate string is + italicized.} + } + +Extensions to @scheme[math] are likely, such as recognizing @litchar{_} +and @litchar{^} for subscripts and superscripts.} + @; ------------------------------------------------------------------------ -@section[#:tag "scribble:manual:section-links"]{Section Links} +@section[#:tag "scribble:manual:section-links"]{Links} -@defproc[(secref [tag string?]) element?]{Inserts the hyperlinked -title of the section tagged @scheme[tag], but @scheme{aux-element} -items in the title content are omitted in the hyperlink label.} +@defproc[(secref [tag string?]) element?]{ -@defproc[(seclink [tag string?] [pre-content any/c] ...) element?]{The content from -@scheme[pre-content] is hyperlinked to the section tagged @scheme[tag].} +Inserts the hyperlinked title of the section tagged @scheme[tag], but +@scheme{aux-element} items in the title content are omitted in the +hyperlink label.} -@defproc[(schemelink [id symbol?] [pre-content any/c] ...) element?]{The content from -@scheme[pre-content] is hyperlinked to the definition of @scheme[id].} +@defproc[(seclink [tag string?] [pre-content any/c] ...) element?]{ + +The content from @scheme[pre-content] is hyperlinked to the section +tagged @scheme[tag].} + + +@defproc[(schemelink [id symbol?] [pre-content any/c] ...) element?]{ + +The content from @scheme[pre-content] is hyperlinked to the definition +of @scheme[id].} + + +@defproc[(link [url string?] [pre-content any/c] ...) element?]{ + +The content from @scheme[pre-content] is hyperlinked to @scheme[url].} + + +@defproc[(elemtag [t tag?] [pre-content any/c] ...) element?]{ + +The tag @scheme[t] refers to the content form of +@scheme[pre-content].} + + +@defproc[(elemref [t tag?] [pre-content any/c] ...) element?]{ + +The content from @scheme[pre-content] is hyperlinked to @scheme[t], +which is normally defined using @scheme[elemtag].} + + +@defproc[(deftech [pre-content any/c] ...) element?]{ + +Produces an element for the content form of @scheme[pre-content], and +also defines a term that can be referenced elsewhere using +@scheme[tech]. + +The @scheme[content->string] result of the content form of +@scheme[pre-content] is used as a key for references, but normalized +as follows: + +@itemize{ + + @item{A trailing ``ies'' is replaced by ``y''.} + + @item{A trailing ``s'' is removed.} + + @item{Consecutive hyphens and whitespaces are all replaced by a + single space.} + +} + +These normalization steps help support natural-language references +that differ slightly from a defined form. For example, a definition of +``bananas'' can be referenced with a use of ``banana''.} + +@defproc[(tech [pre-content any/c] ...) element?]{ + +Produces an element for the content form of @scheme[pre-content], and +hyperlinks it to the definition of the content as established by +@scheme[deftech]. The content's string form is normalized in the same +way as for @scheme[deftech]. + +The hyperlink is relatively quiet, in that underlining in HTML output +appears only when the mouse is moved over the term. + +In some cases, combining both natural-language uses of a term and +proper linking can require some creativity, even with the +normalization performed on the term. For example, if ``bind'' is +defined, but a sentence uses the term ``binding,'' the latter can be +linked to the former using @schemefont["@tech{bind}ing"].} + +@defproc[(techlink [pre-content any/c] ...) element?]{ + +Like @scheme[tech], but the link is not a quiet. For example, in HTML +output, a hyperlink underline appears even when the mouse is not over +the link.} @; ------------------------------------------------------------------------ @section{Indexing} @defproc[(idefterm [pre-content any/c] ...) element?]{Combines @scheme[as-index] and @scheme[defterm]. The content normally should be -plurarl, rather than singular.} +plural, rather than singular. Consider using @scheme[deftech], +instead, which always indexes.} @defproc[(pidefterm [pre-content any/c] ...) element?]{Like @scheme[idefterm], but plural: adds an ``s'' on the end of the content -for the index entry.} +for the index entry. Consider using @scheme[deftech], instead.} + +@defproc[(indexed-file [pre-content any/c] ...) element?]{A +combination of @scheme[file] and @scheme[as-index], but where the sort +key for the index iterm does not include quotes.} + +@defproc[(indexed-envvar [pre-content any/c] ...) element?]{A +combination of @scheme[envvar] and @scheme[as-index].} @; ------------------------------------------------------------------------ @section{Miscellaneous} @@ -358,3 +536,6 @@ centered table with the @scheme[pre-flow] parsed by @defproc[(commandline [pre-content any/c] ...) paragraph?]{Produces an inset command-line example (e.g., in typewriter font).} + +@defproc[(margin-code [pre-content any/c] ...) paragraph?]{Produces +a paragraph to be typeset in the margin instead of inlined.} diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl index 0317949e..2a1d40c7 100644 --- a/collects/scribblings/scribble/scribble.scrbl +++ b/collects/scribblings/scribble/scribble.scrbl @@ -88,3 +88,4 @@ information. @include-section["basic.scrbl"] @include-section["manual.scrbl"] @include-section["eval.scrbl"] +@include-section["style.scrbl"] diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl index a2789f3b..120eeda0 100644 --- a/collects/scribblings/scribble/struct.scrbl +++ b/collects/scribblings/scribble/struct.scrbl @@ -8,12 +8,15 @@ A single document is represented as a @defterm{part}: @itemize{ - @item{A @defterm{part} is an instance of @scheme[part]; it has a - title @defterm{content}, an initial @defterm{flow}, and a list - of subsection @defterm{part}s. After the ``collect'' phase of - rendering, it also has @defterm{collected info}. An - @scheme[unnumbered-part] is the same as a @scheme[part], but it - isn't numbered.} + @item{A @defterm{part} is an instance of @scheme[part]; it has a list + of @defterm{tags} used as link targets, a title + @defterm{content}, a list of @defterm{elements} that supply + information during the ``collect'' phase but are not rendered, + an initial @defterm{flow}, and a list of subsection + @defterm{part}s. After the ``collect'' phase of rendering, it + also has @defterm{collected info}. A @scheme[styled-part] + includes an extra style flag. An @scheme[unnumbered-part] is + the same as a @scheme[styled-part], but it isn't numbered.} @item{A @defterm{flow} is an instance of @scheme[flow]; it has a list of @defterm{flow element}s.} @@ -61,9 +64,9 @@ A single document is represented as a @defterm{part}: @item{A symbol element is either @scheme['mdash], @scheme['ndash], @scheme['ldquo], - @scheme['lsquo], @scheme['rsquo], or - @scheme['rarr]; it is drawn as the - corresponding HTML entity.} + @scheme['lsquo], @scheme['rsquo], + @scheme['rarr], or @scheme['prime]; it is + drawn as the corresponding HTML entity.} @item{An instance of @scheme[element] has a list of @defterm{element}s plus a style. The style's @@ -83,7 +86,11 @@ A single document is represented as a @defterm{part}: @item{An instance of @scheme[target-element] has a @defterm{tag} to be referenced by - @scheme[link-element]s.} + @scheme[link-element]s. An instance of the + subtype @scheme[toc-target-element] is + treated like a kind of section label, to be + shown in the ``on this page'' table for HTML + output.} @item{An instance of @scheme[index-element] has a @defterm{tag} (as a target), a list of @@ -97,6 +104,10 @@ A single document is represented as a @defterm{part}: @defterm{element}. The ``collect'' phase of rendering ignores delayed flow elements.} + @item{An instance of @scheme[aux-element] is + excluded in the text of a link when it + appears in a referenced section name.} + }}}} @item{A @defterm{delayed flow element} is an instance of @@ -119,21 +130,40 @@ Note that there's no difference between a part and a full document. A particular source module just as easily defines a subsection (incoprated via @scheme[include-section]) as a document. -@defstruct[part ([tag (or/c false/c tag?)] +@defstruct[part ([tags (listof tag?)] [title-content (or/c false/c list?)] [collected-info (or/c false/c collected-info?)] + [to-collect list?] [flow flow?] [parts (listof part?)])]{ -} - - -@defstruct[(unnumbered-part part) ()]{ +Each element of @scheme[tags] is actually wrapped as @scheme[`(part +,_tag)] as a target for links; functions like @scheme[seclink] +similarly insert the @scheme[`(part ,_tag)] wrapper. } + @defstruct[(styled-part part) ([style any/c])]{ +The currently recognized values for @scheme[style] are as follows: + +@itemize{ + + @item{@scheme['toc] --- sub-parts of the part are rendered on separate + pages for multi-page HTML mode.} + + @item{@scheme['index] --- the part represents an index.} + +} + +} + +@defstruct[(unnumbered-part styled-part) ()]{ + +Although a section number is computed for an ``unnumbered'' section +during the ``collect'' phase, the number is not rendered. + } @defstruct[flow ([paragraphs (listof flow-element?)])]{ @@ -182,6 +212,10 @@ section, and the last argument correspond to global information } +@defstruct[(toc-target-element target-element) ()]{ + +} + @defstruct[(link-element element) ([tag any/c] [complain-if-fail? boolean?])]{ @@ -192,6 +226,12 @@ section, and the last argument correspond to global information [plain-seq (listof string?)] [entry-seq list?])]{ +The @scheme[plain-seq] specifies the keys for sorting, where the first +element is the main key, the second is a sub-key, etc. The +@scheme[entry-seq] list must have the same length, and it provides the +form of each key to render in the final document. See also +@scheme[index]. + } @defstruct[(aux-element element) ()]{ @@ -202,7 +242,9 @@ example, @scheme[secref]. } -@defstruct[delayed-element ([render (any/c part? any/c . -> . list?)])]{ +@defstruct[delayed-element ([render (any/c part? any/c . -> . list?)] + [sizer (-> any/c)] + [plain (-> any/c)])]{ The @scheme[render] procedure's arguments are the same as for @scheme[delayed-flow-element]. Unlike @scheme[delayed-flow-element], @@ -211,12 +253,21 @@ on the first call. Furthemore, the element can be marshelled (e.g., for an index entry or a section-title entry) only if it has been rendered first. +The @scheme[sizer] field is a procedure that produces a substitute +element for the delayed element for the purposes of determine the +element's width (see @scheme[element-width]). + +The @scheme[plain] field is a procedure that produces a substitute for +the element when needed before the ``collect'' phase. + } @defstruct[collected-info ([number (listof (or/c false/c integer?))] [parent (or/c false/c part?)] [info any/c])]{ +Computed for each part by the ``collect'' phase. + } @defproc[(flow-element? [v any/c]) boolean?]{ @@ -227,18 +278,28 @@ Returns @scheme[#t] if @scheme[v] is a @scheme[paragraph], } + @defproc[(tag? [v any/c]) boolean?]{ Returns @scheme[#t] if @scheme[v] is acceptable as a link tag, @scheme[#f], otherwise. Currently, an acceptable tag is either a -string or a list containing a symbol and a string. +string or a list containing a symbol and a string.} -} -@defproc[(content->string (content list?)) string?]{ +@defproc*[([(content->string (content list?)) string?] + [(content->string (content list?) (p part?) (info any/c)) string?])]{ Converts a list of elements to a single string (essentially rendering the content as ``plain text''). -} +If @scheme[p] and @scheme[info] arguments are not supplied, then a +pre-``collect'' substitute is obtained for delayed +elements. Otherwise, the two arguments are used to force the delayed +element (if it has not been forced already).} + +@defproc*[([(element->string (element any/c)) string?] + [(element->string (element any/c) (p part?) (info any/c)) string?])]{ + +Like @scheme[content->string], but for a single element. +} diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl new file mode 100644 index 00000000..d8f535b8 --- /dev/null +++ b/collects/scribblings/scribble/style.scrbl @@ -0,0 +1,70 @@ +#reader(lib "docreader.ss" "scribble") +@require[(lib "manual.ss" "scribble")] +@require["utils.ss"] + +@title[#:tag "reference-style"]{PLT Reference Style Guide} + +@italic{Notes toward an eventual guide chapter...} + +In the descriptive body of @scheme[defform], @scheme[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 @schemeidfont{id} or something that ends @schemeidfont{-id} in a +syntactic form to mean an identifier, not @schemeidfont{identifier}, +@schemeidfont{name}, or @schemeidfont{symbol}. Similarly, use +@schemeidfont{expr} or something that ends @schemeidfont{-expr} for an +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 +example, + +@verbatim[" @scheme[(rator-expr rand-expr ...)]"] + +would be the wrong way to refer to the grammar of a function call, +because it produces @scheme[(rator-expr rand-expr ...)], where +@schemeidfont{rator-expr} and @schemeidfont{rand-expr} are +typeset as variables. The correct description is + +@verbatim[" @scheme[(_rator-expr _rand-expr ...)]"] + +which produces @scheme[(_rator-expr _rand-expr ...)], where +@schemeidfont{rator-expr} @schemeidfont{rand-expr} are typeset as +meta-variables. The @scheme[defproc], @scheme[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 @scheme[schemeidfont] (e.g., as in +@schemeidfont{rand-expr} above). Otherwise, use @scheme[litchar], +not merely @scheme[schemefont] or @scheme[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.