From c4f4ba4ca38c05e8beff1546a8df69617c25821c Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 8 Jan 2014 07:30:59 -0700 Subject: [PATCH] scribblings config: 'keep-style and 'no-search flag, 'omit-start section The 'keep-style avoids imposing the Racket manual style on a document, while 'no-search omits the search box. The 'omit-start section is like 'omit, but the document is still indexed and available for cross-references. Also, recognize a 'prefixable tag shape so that the set of tags hat support prefixing is extensible. --- .../racket-doc/scribblings/raco/setup.scrbl | 12 +++++- .../scribblings/main/private/manuals.rkt | 4 +- .../racket-index/setup/scribble.rkt | 24 +++++++----- .../scribblings/scribble/core.scrbl | 37 +++++++++++++------ .../scribble-lib/scribble/base-render.rkt | 6 ++- 5 files changed, 60 insertions(+), 23 deletions(-) diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl index f5d479eb4f..fe6bf3caca 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl @@ -379,6 +379,12 @@ Optional @filepath{info.rkt} fields trigger additional actions by that currently has this mode should be the only one with the mode.} + @item{@racket['keep-style] : Leave the document's style as-is, + instead of imposing the document style for manuals.} + + @item{@racket['no-search] : Build the document without a search + box.} + ] The @racket[_category] list specifies how to show the document in @@ -425,7 +431,11 @@ Optional @filepath{info.rkt} fields trigger additional actions by @item{@racket['other] : Other documentation.} @item{@racket['omit] : Documentation that should not be listed on - the root page.} + the root page or indexed for searching.} + + @item{@racket['omit-start] : Documentation that should not be + listed on the root page but should be indexed for + searching.} ] diff --git a/pkgs/racket-pkgs/racket-index/scribblings/main/private/manuals.rkt b/pkgs/racket-pkgs/racket-index/scribblings/main/private/manuals.rkt index 8a44466c61..ab86227480 100644 --- a/pkgs/racket-pkgs/racket-index/scribblings/main/private/manuals.rkt +++ b/pkgs/racket-pkgs/racket-index/scribblings/main/private/manuals.rkt @@ -55,7 +55,9 @@ ;; Category (let ([the-cat (if (pair? new-cat) (car new-cat) 'unknown)]) - (or (and (eq? the-cat 'omit) the-cat) + (or (and (or (eq? the-cat 'omit) + (eq? the-cat 'omit-start)) + the-cat) (ormap (lambda (sec) (and (eq? the-cat (sec-cat sec)) the-cat)) diff --git a/pkgs/racket-pkgs/racket-index/setup/scribble.rkt b/pkgs/racket-pkgs/racket-index/setup/scribble.rkt index 04c2e09927..28550e7b2d 100644 --- a/pkgs/racket-pkgs/racket-index/setup/scribble.rkt +++ b/pkgs/racket-pkgs/racket-index/setup/scribble.rkt @@ -147,7 +147,7 @@ (define (scribblings-flag? sym) (memq sym '(main-doc main-doc-root user-doc-root user-doc multi-page depends-all depends-all-main depends-all-user - no-depend-on always-run))) + no-depend-on always-run keep-style no-search))) (define (validate-scribblings-infos infos) (define (validate path [flags '()] [cat '(library)] [name #f] [out-count 1] [order-hint 0]) (and (string? path) (relative-path? path) @@ -768,8 +768,12 @@ ((if multi? html:render-multi-mixin values) (html:render-mixin render%))) ;; Use PLT manual style: - [style-file (collection-file-path "manual-style.css" "scribble")] - [extra-files (list (collection-file-path "manual-fonts.css" "scribble"))] + [style-file (if (memq 'keep-style flags) + #f + (collection-file-path "manual-style.css" "scribble"))] + [extra-files (if (memq 'keep-style flags) + null + (list (collection-file-path "manual-fonts.css" "scribble")))] ;; See also `style-extra-files`, below [dest-dir (if multi? (let-values ([(base name dir?) (split-path ddir)]) base) @@ -810,13 +814,15 @@ ;; be moved into a binary package: [root-path (and allow-indirect? ddir)] - [style-extra-files (cons - (collection-file-path "manual-racket.css" "scribble") - (map (lambda (s) - (collection-file-path s "scribble")) - shared-empty-style-files))] + [style-extra-files (if (memq 'keep-style flags) + null + (cons + (collection-file-path "manual-racket.css" "scribble") + (map (lambda (s) + (collection-file-path s "scribble")) + shared-empty-style-files)))] - [search-box? #t])) + [search-box? (not (memq 'no-search flags))])) (for ([s (in-list shared-empty-script-files)]) (send r add-extra-script-file (collection-file-path s "scribble"))) (when allow-indirect? diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl index 9e60cfd78a..be1e837f7e 100644 --- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl +++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl @@ -243,17 +243,32 @@ of the second half of the tag. A part can have a @deftech{tag prefix}, which is effectively added onto the second item within each tag whose first item is -@racket['part] or @racket['tech]. The prefix is added to a string -value by creating a list containing the prefix and string, and it is -added to a list value using @racket[cons]; a prefix is not added to a -@racket[generated-tag] instance. The prefix is used for reference -outside the part, including the use of tags in the part's -@racket[tags] field. Typically, a document's main part has a tag -prefix that applies to the whole document; references to sections and -defined terms within the document from other documents must include the prefix, -while references within the same document omit the prefix. Part -prefixes can be used within a document as well, to help disambiguate -references within the document. +@racket['part], @racket['tech], or @racket['cite], or whose second +item is a list that starts with @racket['prefixable]: + +@itemlist[ + + @item{The prefix is added to a string second item by creating a list + containing the prefix and string.} + + @item{The prefix is added to a list second item after @racket['part], + @racket['tech], or @racket['cite] using @racket[cons].} + + @item{The prefix is added to a second item that starts + @racket['prefixable] by adding it to the list after + @racket['prefixable].} + + @item{A prefix is not added to a @racket[generated-tag] item.} + +] + +The prefix is used for reference outside the part, including the use +of tags in the part's @racket[tags] field. Typically, a document's +main part has a tag prefix that applies to the whole document; +references to sections and defined terms within the document from +other documents must include the prefix, while references within the +same document omit the prefix. Part prefixes can be used within a +document as well, to help disambiguate references within the document. Some procedures accept a ``tag'' that is just the string part of the full tag, where the symbol part is supplied automatically. For diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/base-render.rkt b/pkgs/scribble-pkgs/scribble-lib/scribble/base-render.rkt index 955d0af686..00f15c0a85 100644 --- a/pkgs/scribble-pkgs/scribble-lib/scribble/base-render.rkt +++ b/pkgs/scribble-pkgs/scribble-lib/scribble/base-render.rkt @@ -583,7 +583,11 @@ [(index-entry) (let ([v (convert-key prefix (cadr k))]) (if (eq? v (cadr k)) k (list 'index-entry v)))] - [else k])) + [else + (if (and (pair? (cadr k)) + (eq? 'prefixable (caadr k))) + (list (car k) (list* 'prefixable prefix (cdadr k))) + k)])) (define/public (collect-part-tags d ci number) (for ([t (part-tags d)])