From 187b466bf6bc431bf8b8ba8e9914ddec8f121515 Mon Sep 17 00:00:00 2001 From: Nick Loadholtes Date: Thu, 31 Dec 2020 11:44:44 -0500 Subject: [PATCH 1/3] Refactor blueboxes name to signature-box Simple find-and-replace to change the name for blueboxes to signature-box --- .../scribblings/scribble/blueboxes.scrbl | 59 ----------- .../scribblings/scribble/internals.scrbl | 2 +- .../scribblings/scribble/renderer.scrbl | 4 +- .../scribblings/scribble/signature-box.scrbl | 59 +++++++++++ scribble-lib/scribble/contract-render.rkt | 4 +- .../{blueboxes.rkt => signature-box.rkt} | 98 +++++++++---------- ...-info.rkt => valid-signature-box-info.rkt} | 4 +- 7 files changed, 115 insertions(+), 115 deletions(-) delete mode 100644 scribble-doc/scribblings/scribble/blueboxes.scrbl create mode 100644 scribble-doc/scribblings/scribble/signature-box.scrbl rename scribble-lib/scribble/{blueboxes.rkt => signature-box.rkt} (66%) rename scribble-lib/scribble/{valid-blueboxes-info.rkt => valid-signature-box-info.rkt} (73%) diff --git a/scribble-doc/scribblings/scribble/blueboxes.scrbl b/scribble-doc/scribblings/scribble/blueboxes.scrbl deleted file mode 100644 index 3aff0092ec..0000000000 --- a/scribble-doc/scribblings/scribble/blueboxes.scrbl +++ /dev/null @@ -1,59 +0,0 @@ -#lang scribble/doc -@(require scribble/manual "utils.rkt" - (for-label scribble/core - scribble/blueboxes - racket/contract - setup/xref)) - -@title[#:tag "blueboxes"]{Blue Boxes Utilities} - -@defmodule[scribble/blueboxes]{ - The @racketmodname[scribble/blueboxes] provides access - to the content of the ``blue boxes'' that describe - some module's export (but without any styling).} - -@defproc[(fetch-blueboxes-strs [tag tag?] - [#:blueboxes-cache blueboxes-cache - blueboxes-cache? - (make-blueboxes-cache #t)]) - (or/c #f (non-empty-listof string?))]{ - Returns a list of strings that show the content of the blue box - (without any styling information) for the documentation referenced - by @racket[tag]. - - The first string in the list describes the export (e.g. @racket["procedure"] - when @racket[defproc] is used, or @racket["syntax"] when @racket[defform] - was used to document the export). -} - -@defproc[(fetch-blueboxes-method-tags [method-name symbol?] - [#:blueboxes-cache blueboxes-cache - blueboxes-cache? - (make-blueboxes-cache #t)]) - (listof method-tag?)]{ - Returns the list of tags for all methods that are documented in the documentation - in @racket[blueboxes-cache]. - - @history[#:added "1.11"] -} - -@defproc[(make-blueboxes-cache - [populate? boolean?] - [#:blueboxes-dirs blueboxes-dirs (listof path?) (get-doc-search-dirs)]) - blueboxes-cache?]{ - Constructs a new (mutable) blueboxes cache. - - If @racket[populate?] is @racket[#f], the cache is initially - unpopulated, in which case it is filled in the first time the cache - is passed to @racket[fetch-bluebxoes-strs]. Otherwise, the cache is - populated immediately. - - The @racket[blueboxes-dirs] argument is a list of directories that are - looked inside for @filepath{blueboxes.rktd} files. The default value - is only an approximation for where those files usually reside. See - also @racket[get-rendered-doc-directories]. -} - -@defproc[(blueboxes-cache? [v any/c]) boolean?]{ - Determines if @racket[v] is a blueboxes cache. -} diff --git a/scribble-doc/scribblings/scribble/internals.scrbl b/scribble-doc/scribblings/scribble/internals.scrbl index 9c8ca23805..720f32ada6 100644 --- a/scribble-doc/scribblings/scribble/internals.scrbl +++ b/scribble-doc/scribblings/scribble/internals.scrbl @@ -14,6 +14,6 @@ @include-section["docreader.scrbl"] @include-section["xref.scrbl"] @include-section["tag.scrbl"] -@include-section["blueboxes.scrbl"] +@include-section["signature-box.scrbl"] @include-section["config.scrbl"] diff --git a/scribble-doc/scribblings/scribble/renderer.scrbl b/scribble-doc/scribblings/scribble/renderer.scrbl index 4dfd9dc240..c92f4e02d9 100644 --- a/scribble-doc/scribblings/scribble/renderer.scrbl +++ b/scribble-doc/scribblings/scribble/renderer.scrbl @@ -744,7 +744,7 @@ via a @racketmodname[scribble/text-render] renderer). It saves this information in three pieces in a file inside the @racket[dests] directories called -@filepath{blueboxes.rktd}. The first piece is +@filepath{signature-box.rktd}. The first piece is a single line containing a (decimal, ASCII) number. That number is the number of bytes that the second piece of information occupies in the file. The second piece of information @@ -771,7 +771,7 @@ it saves the resulting files in a different place. [ri render-info?]) void?]{ Just like @method[override-render-mixin-multi render], except - that it saves the file @filepath{blueboxes.rktd} in + that it saves the file @filepath{signature-box.rktd} in the same directory where each @racket[dests] element resides. }} } diff --git a/scribble-doc/scribblings/scribble/signature-box.scrbl b/scribble-doc/scribblings/scribble/signature-box.scrbl new file mode 100644 index 0000000000..9a502f3d04 --- /dev/null +++ b/scribble-doc/scribblings/scribble/signature-box.scrbl @@ -0,0 +1,59 @@ +#lang scribble/doc +@(require scribble/manual "utils.rkt" + (for-label scribble/core + scribble/signature-box + racket/contract + setup/xref)) + +@title[#:tag "signature-box"]{Blue Boxes Utilities} + +@defmodule[scribble/signature-box]{ + The @racketmodname[scribble/signature-box] provides access + to the content of the ``blue boxes'' that describe + some module's export (but without any styling).} + +@defproc[(fetch-signature-box-strs [tag tag?] + [#:signature-box-cache signature-box-cache + signature-box-cache? + (make-signature-box-cache #t)]) + (or/c #f (non-empty-listof string?))]{ + Returns a list of strings that show the content of the blue box + (without any styling information) for the documentation referenced + by @racket[tag]. + + The first string in the list describes the export (e.g. @racket["procedure"] + when @racket[defproc] is used, or @racket["syntax"] when @racket[defform] + was used to document the export). +} + +@defproc[(fetch-signature-box-method-tags [method-name symbol?] + [#:signature-box-cache signature-box-cache + signature-box-cache? + (make-signature-box-cache #t)]) + (listof method-tag?)]{ + Returns the list of tags for all methods that are documented in the documentation + in @racket[signature-box-cache]. + + @history[#:added "1.11"] +} + +@defproc[(make-signature-box-cache + [populate? boolean?] + [#:signature-box-dirs signature-box-dirs (listof path?) (get-doc-search-dirs)]) + signature-box-cache?]{ + Constructs a new (mutable) signature-box cache. + + If @racket[populate?] is @racket[#f], the cache is initially + unpopulated, in which case it is filled in the first time the cache + is passed to @racket[fetch-bluebxoes-strs]. Otherwise, the cache is + populated immediately. + + The @racket[signature-box-dirs] argument is a list of directories that are + looked inside for @filepath{signature-box.rktd} files. The default value + is only an approximation for where those files usually reside. See + also @racket[get-rendered-doc-directories]. +} + +@defproc[(signature-box-cache? [v any/c]) boolean?]{ + Determines if @racket[v] is a signature-box cache. +} diff --git a/scribble-lib/scribble/contract-render.rkt b/scribble-lib/scribble/contract-render.rkt index 6785cae551..929a4727a8 100644 --- a/scribble-lib/scribble/contract-render.rkt +++ b/scribble-lib/scribble/contract-render.rkt @@ -28,10 +28,10 @@ (define cb.rktd (cond [multi? - (build-path dest "blueboxes.rktd")] + (build-path dest "signature-box.rktd")] [else (define-values (base name dir?) (split-path dest)) - (build-path base "blueboxes.rktd")])) + (build-path base "signature-box.rktd")])) (call-with-output-file cb.rktd (λ (port) (fprintf port "~a\n" (string-utf-8-length table-str)) diff --git a/scribble-lib/scribble/blueboxes.rkt b/scribble-lib/scribble/signature-box.rkt similarity index 66% rename from scribble-lib/scribble/blueboxes.rkt rename to scribble-lib/scribble/signature-box.rkt index 5e42a1237e..02b8c70748 100644 --- a/scribble-lib/scribble/blueboxes.rkt +++ b/scribble-lib/scribble/signature-box.rkt @@ -11,52 +11,52 @@ [definition-tag->class/interface-tag (Definition-Tag -> Class/Interface-Tag)] [get-class/interface-and-method (Method-Tag -> (values Symbol Symbol))] ) -(require/typed "valid-blueboxes-info.rkt" [valid-blueboxes-info? (Any -> Boolean)]) +(require/typed "valid-signature-box-info.rkt" [valid-signature-box-info? (Any -> Boolean)]) -(provide fetch-blueboxes-strs - make-blueboxes-cache - blueboxes-cache? - fetch-blueboxes-method-tags +(provide fetch-signature-box-strs + make-signature-box-cache + signature-box-cache? + fetch-signature-box-method-tags ) (define-type Bluebox-Info bluebox-info) (struct bluebox-info - ([blueboxes.rktd : Path-String] + ([signature-box.rktd : Path-String] [offset : (U Natural #f)] - [tag-ht : (U Blueboxes-Info-Hash #f)] ; (or/c valid-blueboxes-info? #f) + [tag-ht : (U Signature-box-Info-Hash #f)] ; (or/c valid-signature-box-info? #f) [mod-time : (U Natural #f)]) #:mutable) -(define-type Blueboxes-Cache blueboxes-cache) -(struct blueboxes-cache +(define-type Signature-box-Cache signature-box-cache) +(struct signature-box-cache ([info-or-paths : (U (Listof Path) (Listof Bluebox-Info))] [method->tags : (U (HashTable Symbol (Listof Method-Tag)) #f)]) #:mutable) -(: make-blueboxes-cache : +(: make-signature-box-cache : Boolean - [#:blueboxes-dirs (Listof Path)] + [#:signature-box-dirs (Listof Path)] -> - Blueboxes-Cache) -(define (make-blueboxes-cache + Signature-box-Cache) +(define (make-signature-box-cache populate? - #:blueboxes-dirs - [blueboxes-dirs (for*/list ([d (in-list (get-doc-search-dirs))] + #:signature-box-dirs + [signature-box-dirs (for*/list ([d (in-list (get-doc-search-dirs))] [c (in-list (if (directory-exists? d) (directory-list d) '()))]) : (Listof Path) (build-path d c))]) - (define cache (blueboxes-cache blueboxes-dirs #f)) + (define cache (signature-box-cache signature-box-dirs #f)) (when populate? (populate-cache! cache)) cache) -(: fetch-blueboxes-strs : +(: fetch-signature-box-strs : Tag - [#:blueboxes-cache Blueboxes-Cache] + [#:signature-box-cache Signature-box-Cache] -> (U #f (List* String (Listof String)))) -(define (fetch-blueboxes-strs tag #:blueboxes-cache [cache (make-blueboxes-cache #f)]) +(define (fetch-signature-box-strs tag #:signature-box-cache [cache (make-signature-box-cache #f)]) (define plain-strs (fetch-strs-for-single-tag tag cache)) (cond [(and plain-strs (definition-tag? tag)) @@ -70,15 +70,15 @@ (if constructor-strs (cdr constructor-strs) '()))] [else plain-strs])) -(: fetch-strs-for-single-tag : Tag Blueboxes-Cache -> (U #f (List* String (Listof String)))) +(: fetch-strs-for-single-tag : Tag Signature-box-Cache -> (U #f (List* String (Listof String)))) (define (fetch-strs-for-single-tag tag cache) (populate-cache! cache) - (for/or ([ent (in-list (blueboxes-cache-info-or-paths cache))]) + (for/or ([ent (in-list (signature-box-cache-info-or-paths cache))]) : (U #f (List* String (Listof String))) (when (bluebox-info? ent) (check-and-update-bluebox-info! ent)) (match ent - [(bluebox-info blueboxes.rktd offset tag-ht _) + [(bluebox-info signature-box.rktd offset tag-ht _) (define offset+lens (and tag-ht (hash-ref tag-ht tag #f))) (cond [offset+lens @@ -87,7 +87,7 @@ append (for/list ([offset+len (in-list offset+lens)]) : (Listof (Listof (U String EOF))) - (call-with-input-file blueboxes.rktd + (call-with-input-file signature-box.rktd (λ ([port : Input-Port]) (port-count-lines! port) (file-position port (+ (car offset+len) (or offset 0))) @@ -102,22 +102,22 @@ [_ (log-warning "expected bluebox-info?, given: ~v" ent) #f]))) -(: fetch-blueboxes-method-tags : Symbol [#:blueboxes-cache Blueboxes-Cache] -> (Listof Method-Tag)) -(define (fetch-blueboxes-method-tags sym #:blueboxes-cache [cache (make-blueboxes-cache #f)]) +(: fetch-signature-box-method-tags : Symbol [#:signature-box-cache Signature-box-Cache] -> (Listof Method-Tag)) +(define (fetch-signature-box-method-tags sym #:signature-box-cache [cache (make-signature-box-cache #f)]) (populate-cache! cache) - (define ht (blueboxes-cache-method->tags cache)) + (define ht (signature-box-cache-method->tags cache)) (or (and ht (hash-ref ht sym (λ () '()))) '())) (define listof-path? (make-predicate (Listof Path))) -(: populate-cache! : Blueboxes-Cache -> Void) +(: populate-cache! : Signature-box-Cache -> Void) (define (populate-cache! cache) - (define cache-content (blueboxes-cache-info-or-paths cache)) + (define cache-content (signature-box-cache-info-or-paths cache)) (when (listof-path? cache-content) - (define the-cache (build-blueboxes-cache cache-content)) + (define the-cache (build-signature-box-cache cache-content)) (define mtd-table (compute-methods-table the-cache)) - (set-blueboxes-cache-method->tags! cache mtd-table) - (set-blueboxes-cache-info-or-paths! cache the-cache))) + (set-signature-box-cache-method->tags! cache mtd-table) + (set-signature-box-cache-info-or-paths! cache the-cache))) (: compute-methods-table : (Listof Bluebox-Info) -> (HashTable Symbol (Listof Method-Tag))) (define (compute-methods-table lst) @@ -125,7 +125,7 @@ (define meth-ht (make-hash)) (for ([a-bluebox-info (in-list lst)]) (match a-bluebox-info - [(bluebox-info blueboxes.rktd offset tag-ht mod-time) + [(bluebox-info signature-box.rktd offset tag-ht mod-time) (when tag-ht (for ([(tag val) (in-hash tag-ht)]) (when (method-tag? tag) @@ -133,32 +133,32 @@ (hash-set! meth-ht meth (cons tag (hash-ref meth-ht meth (λ () '())))))))])) meth-ht) -(: build-blueboxes-cache : (Listof Path) -> (Listof Bluebox-Info)) -(define (build-blueboxes-cache blueboxes-dirs) +(: build-signature-box-cache : (Listof Path) -> (Listof Bluebox-Info)) +(define (build-signature-box-cache signature-box-dirs) (filter values - (for*/list ([doc-dir-name (in-list blueboxes-dirs)]) + (for*/list ([doc-dir-name (in-list signature-box-dirs)]) : (Listof Bluebox-Info) - (define blueboxes.rktd (build-path doc-dir-name "blueboxes.rktd")) - (define a-bluebox-info (bluebox-info blueboxes.rktd #f #f #f)) + (define signature-box.rktd (build-path doc-dir-name "signature-box.rktd")) + (define a-bluebox-info (bluebox-info signature-box.rktd #f #f #f)) (populate-bluebox-info! a-bluebox-info) a-bluebox-info))) (: check-and-update-bluebox-info! : bluebox-info -> Void) (define (check-and-update-bluebox-info! a-bluebox-info) (match a-bluebox-info - [(bluebox-info blueboxes.rktd offset tag-ht mod-time) + [(bluebox-info signature-box.rktd offset tag-ht mod-time) (when (or (not mod-time) - (and (file-exists? blueboxes.rktd) - (not (mod-time . = . (file-or-directory-modify-seconds blueboxes.rktd))))) + (and (file-exists? signature-box.rktd) + (not (mod-time . = . (file-or-directory-modify-seconds signature-box.rktd))))) (populate-bluebox-info! a-bluebox-info))])) (: populate-bluebox-info! : Bluebox-Info -> Void) (define (populate-bluebox-info! a-bluebox-info) - (define blueboxes.rktd (bluebox-info-blueboxes.rktd a-bluebox-info)) + (define signature-box.rktd (bluebox-info-signature-box.rktd a-bluebox-info)) (cond - [(file-exists? blueboxes.rktd) - (call-with-input-file blueboxes.rktd + [(file-exists? signature-box.rktd) + (call-with-input-file signature-box.rktd (λ ([port : Input-Port]) (port-count-lines! port) (define first-line (read-line port)) @@ -170,11 +170,11 @@ (exn-message x)) #f)]) (define candidate (deserialize (read port))) - (unless (valid-blueboxes-info? candidate) - (error 'build-blueboxes-cache - "blueboxes info didn't have the right shape: ~s" + (unless (valid-signature-box-info? candidate) + (error 'build-signature-box-cache + "signature-box info didn't have the right shape: ~s" candidate)) - (cast candidate Blueboxes-Info-Hash))) + (cast candidate Signature-box-Info-Hash))) (define first-line-num (and (string? first-line) (string->number first-line))) (cond [(exact-nonnegative-integer? first-line-num) @@ -184,13 +184,13 @@ first-line-num)]) (set-bluebox-info-tag-ht! a-bluebox-info desed) (set-bluebox-info-mod-time! a-bluebox-info - (file-or-directory-modify-seconds blueboxes.rktd))))] + (file-or-directory-modify-seconds signature-box.rktd))))] [else (set-bluebox-info-offset! a-bluebox-info #f) (set-bluebox-info-tag-ht! a-bluebox-info #f) (set-bluebox-info-mod-time! a-bluebox-info #f)])) -(define-type Blueboxes-Info-Hash +(define-type Signature-box-Info-Hash (HashTable Tag (Listof (Pairof Natural diff --git a/scribble-lib/scribble/valid-blueboxes-info.rkt b/scribble-lib/scribble/valid-signature-box-info.rkt similarity index 73% rename from scribble-lib/scribble/valid-blueboxes-info.rkt rename to scribble-lib/scribble/valid-signature-box-info.rkt index d26f657aa8..08ccded7a3 100644 --- a/scribble-lib/scribble/valid-blueboxes-info.rkt +++ b/scribble-lib/scribble/valid-signature-box-info.rkt @@ -1,10 +1,10 @@ #lang racket/base -(provide valid-blueboxes-info?) +(provide valid-signature-box-info?) (require scribble/core racket/contract/base) -(define valid-blueboxes-info? +(define valid-signature-box-info? (hash/c tag? (listof (cons/c exact-nonnegative-integer? From e79afb0e34730dd949c5232089f7e0a45a23f16a Mon Sep 17 00:00:00 2001 From: Nick Loadholtes Date: Thu, 31 Dec 2020 14:38:06 -0500 Subject: [PATCH 2/3] Fixing a typo --- scribble-doc/scribblings/scribble/signature-box.scrbl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scribble-doc/scribblings/scribble/signature-box.scrbl b/scribble-doc/scribblings/scribble/signature-box.scrbl index 9a502f3d04..aba1b2ac6a 100644 --- a/scribble-doc/scribblings/scribble/signature-box.scrbl +++ b/scribble-doc/scribblings/scribble/signature-box.scrbl @@ -45,7 +45,7 @@ If @racket[populate?] is @racket[#f], the cache is initially unpopulated, in which case it is filled in the first time the cache - is passed to @racket[fetch-bluebxoes-strs]. Otherwise, the cache is + is passed to @racket[fetch-signature-box-strs]. Otherwise, the cache is populated immediately. The @racket[signature-box-dirs] argument is a list of directories that are From cd293735e7332b9115211c009e2be0cfd62f9230 Mon Sep 17 00:00:00 2001 From: Nick Loadholtes Date: Thu, 31 Dec 2020 14:45:06 -0500 Subject: [PATCH 3/3] More spots where blue boxes were refrenced turned into signature box --- scribble-doc/scribblings/scribble/how-to.scrbl | 2 +- scribble-doc/scribblings/scribble/renderer.scrbl | 8 ++++---- scribble-doc/scribblings/scribble/signature-box.scrbl | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/scribble-doc/scribblings/scribble/how-to.scrbl b/scribble-doc/scribblings/scribble/how-to.scrbl index f96639d638..aaf5f06b58 100644 --- a/scribble-doc/scribblings/scribble/how-to.scrbl +++ b/scribble-doc/scribblings/scribble/how-to.scrbl @@ -281,7 +281,7 @@ generates: @item{In the prose that documents @racket[my-helper], @racket[_lst] is automatically typeset in italic, matching the typesetting in - the blue box. The @racket[racket] form essentially knows that + the signature box. The @racket[racket] form essentially knows that it's used in the scope of a procedure with argument @racket[_lst].} diff --git a/scribble-doc/scribblings/scribble/renderer.scrbl b/scribble-doc/scribblings/scribble/renderer.scrbl index c92f4e02d9..f2f04dd29a 100644 --- a/scribble-doc/scribblings/scribble/renderer.scrbl +++ b/scribble-doc/scribblings/scribble/renderer.scrbl @@ -722,7 +722,7 @@ Like @racket[render-mixin], but generates PDF output via @exec{xelatex}. @; ---------------------------------------- -@section{Contract (Blue boxes) Renderer} +@section{Contract (Signature boxes) Renderer} @defmodule/local[scribble/contract-render]{ @@ -730,7 +730,7 @@ Like @racket[render-mixin], but generates PDF output via @exec{xelatex}. Overrides the @method[render<%> render] method of given renderer to record the content of the -blue boxes (generated by @racket[defproc], @racket[defform], etc) +signature boxes (generated by @racket[defproc], @racket[defform], etc) that appear in the document. @defmethod[#:mode override @@ -739,7 +739,7 @@ that appear in the document. [ri render-info?]) void?]{ In addition to doing whatever the @racket[super] method -does, also save the content of the blue boxes (rendered +does, also save the content of the signature boxes (rendered via a @racketmodname[scribble/text-render] renderer). It saves this information in three pieces in a file @@ -756,7 +756,7 @@ For example, if the @racket[hash] maps for the @racket[abcdef] export from the @racket[x] collection starts 10 bytes after the end of the hash table and continues for @racket[3] lines. Multiple elements in the list mean that that -@racket[tag?] has multiple blue boxes and each shows where one +@racket[tag?] has multiple signature boxes and each shows where one of the boxes appears in the file. }} diff --git a/scribble-doc/scribblings/scribble/signature-box.scrbl b/scribble-doc/scribblings/scribble/signature-box.scrbl index aba1b2ac6a..5c43744349 100644 --- a/scribble-doc/scribblings/scribble/signature-box.scrbl +++ b/scribble-doc/scribblings/scribble/signature-box.scrbl @@ -5,11 +5,11 @@ racket/contract setup/xref)) -@title[#:tag "signature-box"]{Blue Boxes Utilities} +@title[#:tag "signature-box"]{Signature Boxes Utilities} @defmodule[scribble/signature-box]{ The @racketmodname[scribble/signature-box] provides access - to the content of the ``blue boxes'' that describe + to the content of the ``signature boxes'' that describe some module's export (but without any styling).} @defproc[(fetch-signature-box-strs [tag tag?] @@ -17,7 +17,7 @@ signature-box-cache? (make-signature-box-cache #t)]) (or/c #f (non-empty-listof string?))]{ - Returns a list of strings that show the content of the blue box + Returns a list of strings that show the content of the signature box (without any styling information) for the documentation referenced by @racket[tag].