From cfb700a85f5494bff408cd78d2a770552e54d1c8 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 2 Jul 2014 09:01:21 +0100 Subject: [PATCH] raco setup: constrain Scribbled document names Contrain the fourth element of a list describing a document in `scribblings` (in "info.rkt") to a collection-path element, instead of allowing an arbitrary relative path. This constraint is needed by various parts of the build system, which assume (for example) that all documents are rendered to an immediate subdirectory. --- .../racket-doc/scribblings/raco/setup.scrbl | 30 +++++++++++-------- .../racket-index/setup/scribble.rkt | 3 +- 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl index a75a155fa6..05bce79db3 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl @@ -287,16 +287,7 @@ Optional @filepath{info.rkt} fields trigger additional actions by A list of documents to build. Each document in the list is itself represented as a list, where each document's list starts with a string that is a collection-relative path to the document's source - file. A directory for pre-rendered documentation is computed from the - source file name by starting with the directory of the @filepath{info.rkt} - file, adding @filepath{doc}, and then using the source file's name without - a suffix; if such a directory exists and does not have a - @filepath{synced.rktd} file, then it is treated as pre-rendered - documentation and moved into place, in which case the documentation source file - need not be present. (Moving documentation into place may require no movement - at all, depending on the way that the enclosing collection is installed, but - movement includes adding a @filepath{synced.rktd} file to represent - the installation.) + file. More precisely a @racketidfont{scribblings} entry must be a value that can be generated from an expression matching the following @@ -326,7 +317,10 @@ Optional @filepath{info.rkt} fields trigger additional actions by (described further below). If a document's list contains a fourth item, @racket[_name], it is a name to use for the generated documentation, instead of defaulting to the source file's name - (sans extension), where @racket[#f] means to use the default. If a + (sans extension), where @racket[#f] means to use the default; a + non-@racket[#f] value for @racket[_name] must fit the grammar + of a colelction-name element as checked by + @racket[collection-name-element?]. If a document's list contains a fifth item, @racket[_out-k], it is used a hint for the number of files to use for the document's cross-reference information; see below. If a document's list @@ -467,7 +461,19 @@ Optional @filepath{info.rkt} fields trigger additional actions by less disables running the document in parallel to other documents. The main Racket reference is given a value of @racket[-11], the search page is given a value of @racket[10], and the default is - @racket[0].} + @racket[0]. + + A directory for pre-rendered documentation is computed from the + source file name by starting with the directory of the + @filepath{info.rkt} file, adding @filepath{doc}, and then using the + document name (which is usually the source file's name without a + suffix); if such a directory exists and does not have a + @filepath{synced.rktd} file, then it is treated as pre-rendered + documentation and moved into place, in which case the documentation + source file need not be present. Moving documentation into place + may require no movement at all, depending on the way that the + enclosing collection is installed, but movement includes adding a + @filepath{synced.rktd} file to represent the installation.} @item{@as-index{@racketidfont{release-note-files}} : @racket[(listof (cons/c string? (cons/c string? list?)))] --- A list of release-notes text files to link from the main documentation pages. diff --git a/pkgs/racket-pkgs/racket-index/setup/scribble.rkt b/pkgs/racket-pkgs/racket-index/setup/scribble.rkt index 8c8f2ca21f..e781b62325 100644 --- a/pkgs/racket-pkgs/racket-index/setup/scribble.rkt +++ b/pkgs/racket-pkgs/racket-index/setup/scribble.rkt @@ -5,6 +5,7 @@ setup/path-to-relative "private/doc-path.rkt" setup/collects + setup/collection-name setup/main-doc setup/parallel-do setup/doc-db @@ -154,7 +155,7 @@ (define (validate path [flags '()] [cat '(library)] [name #f] [out-count 1] [order-hint 0]) (and (string? path) (relative-path? path) (list? flags) (andmap scribblings-flag? flags) - (or (not name) (and (path-string? name) (relative-path? name) name)) + (or (not name) (collection-name-element? name)) (and (list? cat) (<= 1 (length cat) 2) (symbol? (car cat))