6.3 Controlling raco setup with "info.rkt" Files

► |  | raco: Racket Command-Line Tools

1 | raco make: Compiling Source to Bytecode
2 | raco exe: Creating Stand-Alone Executables
3 | raco distribute: Sharing Stand-Alone Executables
4 | raco planet: Automatic Package Distribution
5 | raco pkg: Package Management
6 | raco setup: Installation Management
7 | raco decompile: Decompiling Bytecode
8 | raco demod: Demodularizing Programs
9 | raco link: Library Collection Links
10 | raco pack: Packing Library Collections
11 | raco unpack: Unpacking Library Collections
12 | raco ctool: Working with C Code
13 | raco test: Run tests
14 | raco docs: Documentation Search
15 | raco expand: Macro Expansion
16 | raco read: Reading and Pretty-Printing
17 | raco scribble: Building Documentation
18 | Adding a raco Command
19 | Installation Configuration and Search Paths

▼ | 6 | raco setup: Installation Management

6.1 | Running raco setup
6.2 | Installing ".plt" Archives
6.3 | Controlling raco setup with "info.rkt" Files
6.4 | "info.rkt" File Format
6.5 | Package Dependency Checking
6.6 | API for Setup
6.7 | API for Installing ".plt" Archives
6.8 | API for Finding Installation Directories
6.9 | API for Reading "info.rkt" Files
6.10 | API for Relative Paths
6.11 | API for Collection Names
6.12 | API for Collection Searches
6.13 | API for Platform Specifications
6.14 | API for Cross-Platform Configuration
6.15 | API for Cross-References for Installed Manuals
6.16 | API for Materializing User-Specific Documentation
6.17 | Layered Installations
6.18 | Tethered Installations

► | 6.3 | Controlling raco setup with "info.rkt" Files

6.3.1 | Document Descriptions in "info.rkt" Files
6.3.2 | Document Setup Adjustments
6.3.3 | Documentation Language Families
6.3.4 | Rendering Documentation Listings

On this page:

6.3.1 Document Descriptions in "info.rkt" Files
6.3.2 Document Setup Adjustments
6.3.3 Documentation Language Families
get-language-families
6.3.4 Rendering Documentation Listings
build-contents
make-default-doc-properties

Racket
top contents ← prev up next →

### 6.3 Controlling raco setup with "info.rkt" Files🔗ℹ

To compile a collection’s files to bytecode, raco setup uses the compile-collection-zos procedure. That procedure, in turn, consults the collection’s "info.rkt" file, if it exists, for specific instructions on compiling the collection. See compile-collection-zos for more information on the fields of "info.rkt" that it uses, and see "info.rkt" File Format for information on the format of an "info.rkt" file.

Additional fields are used by the Racket package manager and are documented in Package Metadata. The raco test command also recognizes additional fields, which are documented in Test Configuration by "info.rkt".

Optional "info.rkt" fields trigger additional actions by raco setup:

- scribblings : (listof (cons/c string? list?)) — 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 document name (which is derived from the source module’s name by default) is intended to be globally unique in the same way as a package or module name. See Document Descriptions in "info.rkt" Files for more information about a scribblings value. Before a document is rendered by raco setup, the document’s main part is adjusted in several ways; see Document Setup Adjustments.

- release-note-files : (listof (cons/c string? (cons/c string? list?))) — A list of release-notes text files to link from the main documentation pages. Each note is itself represented as a list, and the list can specify auxiliary notes that are grouped with the main note.

  A release-note-files entry must be a value that can be generated from an expression matching the following entry grammar:

  entry |  | = |  | (list note ...)
  doc |  | = |  | (list label-string note-path)
  |  | | |  | (list label-string note-path order-integer)
  (list label-string note-path order-integer
  (list sub-note ...))
  sub-note |  | = |  | (list label-string note-path)

  The order-integer is used to order notes and defaults to 0.

- racket-launcher-names : (listof string?) — A list of executable names to be generated in the installation’s executable directory to run Racket-based programs implemented by the collection. A parallel list of library names must be provided by racket-launcher-libraries or racket-launcher-flags.

  For each name, a launching executable is set up using make-racket-launcher. The arguments are -l- and ‹colls›/.../‹file›, where ‹file› is the file named by racket-launcher-libraries and ‹colls›/... are the collections (and subcollections) of the "info.rkt" file.

  In addition,

  > (build-aux-from-path
  > (build-path (collection-path ‹colls› ...) ‹suffixless-file›))

  is provided for the optional aux argument (for icons, etc.) to make-racket-launcher, where ‹suffixless-file› is ‹file› without its suffix.

  If racket-launcher-flags is provided, it is used as a list of command-line arguments passed to racket instead of the above default, allowing arbitrary command-line arguments. If racket-launcher-flags is specified together with racket-launcher-libraries, then the flags will override the libraries, but the libraries can still be used to specify a name for build-aux-from-path (to find related information like icon files etc).

- racket-launcher-libraries : (listof path-string?) — A list of library names in parallel to racket-launcher-names.

- racket-launcher-flags : (listof string?) — A list of command-line flag lists, in parallel to racket-launcher-names.

- mzscheme-launcher-names, mzscheme-launcher-libraries, and mzscheme-launcher-flags — Backward-compatible variant of racket-launcher-names, etc.

- gracket-launcher-names : (listof string?) — Like racket-launcher-names, but for GRacket-based executables. The launcher-name list is treated in parallel to gracket-launcher-libraries and gracket-launcher-flags.

- gracket-launcher-libraries : (listof path-string?) — A list of library names in parallel to gracket-launcher-names.

- gracket-launcher-flags : (listof string?) — A list of command-line flag lists, in parallel to gracket-launcher-names.

- mred-launcher-names, mred-launcher-libraries, and mred-launcher-flags — Backward-compatible variant of gracket-launcher-names, etc.

- copy-foreign-libs : (listof (and/c path-string? relative-path?)) — Files to copy into a directory where foreign libraries are found by ffi-lib. If install-platform is defined, then the files are copied only if the current platform matches the definition.

  On Mac OS, when a Mach-O file is copied, if the copied file includes a library reference that starts @loader_path/, and if the referenced library exists in a different location among the paths listed by (get-lib-search-dirs), then the library reference is updated to an absolute path.

  On Unix, when an ELF file is copied, if the copied file includes an RPATH setting of $ORIGIN and the file is being installed to a user-specific location, then the file’s RPATH is adjusted to $ORIGIN: followed by the path to the main installation’s library directory as reported by (find-lib-dir).

  On Windows, deleting a previously installed foreign library may be complicated by a lock on the file, if it is in use. To compensate, raco setup deletes a foreign-library file by first renaming the file to have the prefix "raco-setup-delete-"; it then attempts to delete the renamed file and merely issues a warning on a failure to delete the renamed file. Meanwhile, in modes where raco setup removes uninstalled libraries, it attempts to delete any file in the foreign-library directory whose name starts with "raco-setup-delete-" (in an attempt to clean up after previous failures).

- move-foreign-libs : (listof (and/c path-string? relative-path?)) — Like copy-foreign-libs, but the original file is removed after it is copied (which makes sense for precompiled packages).

- copy-shared-files : (listof (and/c path-string? relative-path?)) — Files to copy into a directory where shared files are found. If install-platform is defined, then the files are copied only if the current platform matches the definition.

  On Windows, uninstalled files are deleted in the same way as for copy-foreign-libs, and the name prefix "raco-setup-delete-" is similarly special.

- move-shared-files : (listof (and/c path-string? relative-path?)) — Like copy-shared-files, but the original file is removed after it is copied (which makes sense for precompiled packages).

- copy-man-pages : (listof (and/c path-string? relative-path? filename-extension)) — Files to copy into a man directory. The file suffix determines its category; for example, .1 should be used for a man page describing an executable.

  On Windows, uninstalled files are deleted in the same way as for copy-foreign-libs, and the name prefix "raco-setup-delete-" is similarly special.

- move-man-pages : (listof (and/c path-string? relative-path? filename-extension)) — Like copy-man-pages, but the original file is removed after it is copied (which makes sense for precompiled packages).

- install-platform : platform-spec? If this specification matches the current platform, the foreign libraries associated with this package are copied or moved into useful locations. See copy-foreign-libs, move-foreign-libs, copy-shared-files, and move-shared-files. Also see matching-platform? for information on the way that the specification is compared to (system-type) and (system-library-subpath #f).

- install-collection : path-string? — A library module relative to the collection that provides installer. The installer procedure must accept one, two, three, or four arguments:

  - The first argument is a directory path to the parent of the Racket installation’s "collects" directory.

  - The second argument, if accepted, is a path to the collection’s own directory.

  - The third argument, if accepted, is a boolean indicating whether the collection is installed as user-specific (#t) or installation-wide (#f).

  - The fourth argument, if accepted, is a boolean indicating whether the collection is installed as installation-wide and should nevertheless avoid modifying the installation; an installer procedure that does not accept this argument is never called when the argument would be #t. An installer that does accept this argument is called with #t to that it can perform user-specific work, even though the collection is installed installation-wide.

- pre-install-collection : path-string? — Like install-collection, except that the corresponding installer procedures are called before the normal ".zo" build, instead of after. The provided procedure is pre-installer, so it can be provided by the same file that provides an installer procedure.

- post-install-collection : path-string? — Like install-collection for a procedure that is called right after the install-collection procedure is executed. The --no-install flag can be provided to raco setup to disable install-collection and pre-install-collection, but not post-install-collection. The post-install-collection function is therefore expected to perform operations that are always needed, even after an installation that contains pre-compiled files. The provided procedure is post-installer, so it can be provided by the same file that provides an installer procedure.

- assume-virtual-sources : any/c — A true value indicates that bytecode files without a corresponding source file should not be removed from "compiled" directories, and no files should not be removed when the --clean or -c flag is passed to raco setup.

- clean : (listof path-string?) — A list of pathnames to be deleted when the --clean or -c flag is passed to raco setup. The pathnames must be relative to the collection. If any path names a directory, each of the files in the directory are deleted, but none of the subdirectories of the directory are checked. If the path names a file, the file is deleted. The default, if this flag is not specified, is to delete all files in the "compiled" subdirectory, and all of the files in the platform-specific subdirectory of the compiled directory for the current platform.

  Just as compiling ".zo" files will compile each module used by a compiled module, deleting a module’s compiled image will delete the ".zo" of each module that is used by the module. More specifically, used modules are determined when deleting a ".dep" file, which would have been created to accompany a ".zo" file when the ".zo" was built by raco setup or raco make (see Dependency Files). If the ".dep" file indicates another module, that module’s ".zo" is deleted only if it also has an accompanying ".dep" file. In that case, the ".dep" file is deleted, and additional used modules are deleted based on the used module’s ".dep" file, etc. Supplying a specific list of collections to raco setup disables this dependency-based deletion of compiled files.

- compile-omit-paths, compile-omit-files, and compile-include-files — Used indirectly via compile-collection-zos.

- module-suffixes and doc-module-suffixes — Used indirectly via get-module-suffixes.

- language-family — A list of hash tables, where each hash table describes a language family. See Documentation Language Families for information about the content of ach hash table.

  Added in version 9.0.0.11.

- main-doc-index — A collection name (in the sense of collection-name?) or a list of collection names to be added to a raco setup request when --doc-index is specified without --avoid-main.

  Added in version 9.0.0.11.

- user-doc-index — A collection name (in the sense of collection-name?) or a list of collection names to be added to a raco setup request when --doc-index is specified without --no-user.

  Added in version 9.0.0.11.

#### 6.3.1 Document Descriptions in "info.rkt" Files🔗ℹ

A scribblings entry is introduced in Controlling raco setup with "info.rkt" Files as having the shape (listof (cons/c string? list?)), but it more precisely must be a value that can be generated from an expression matching the following entry grammar:

entry |  | = |  | (list doc ...)
doc |  | = |  | (list src-string)
|  | | |  | (list src-string flags)
|  | | |  | (list src-string flags category)
|  | | |  | (list src-string flags category name)
|  | | |  | (list src-string flags category name out-k)
|  | | |  | (list src-string flags category name out-k order-n)
flags |  | = |  | (list mode-symbol ...)
category |  | = |  | (list category-name)
|  | | |  | (list category-name sort-number)
|  | | |  | (list category-name sort-number lang-fam)
category-name |  | = |  | symbol
|  | | |  | string
|  | | |  | (box string)
lang-fam |  | = |  | (list string ...)
name |  | = |  | string
|  | | |  | #f

A document entry doc must have at least a src-string, and it optionally continues with information on how to build the document. If a document’s list contains a second item, flags, it must be a list of mode symbols (described below). If a document’s list contains a third item, category, it must be a list that categorizes the document (described further below). If a document’s list contains a fourth item, name, it is a name to use for the generated documentation, instead of defaulting to the source file’s name (sans extension), where #f means to use the default; a non-#f value for name must fit the grammar of a collection-name element as checked by collection-name-element?. If a document’s list contains a fifth item, 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 contains a fourth item, order-n, it is used a hint for the order of rendering; see below.

Each mode symbol in flags can be one of the following, where only 'multi-page is commonly used:

- 'multi-page : Generates multi-page HTML output, instead of the default single-page format.

- 'main-doc : Indicates that the generated documentation should be written into the main installation directory, instead of to a user-specific directory. This mode is the default for a collection that is itself located in the main installation.

- 'user-doc : Indicates that the generated documentation should be written a user-specific directory. This mode is the default for a collection that is not itself located in the main installation.

- 'depends-all : Indicates that the document should be rebuilt if any other document is rebuilt—except for documents that have the 'no-depend-on flag.

- 'depends-all-main : Indicates that the document should be rebuilt if any other document is rebuilt that is installed into the main installation—except for documents that have the 'no-depend-on flag.

- 'depends-all-user : Indicates that the document should be rebuilt if any other document is rebuilt that is installed into the user’s space—except for documents that have the 'no-depend-on flag.

- 'depend-family : Indicates that the document should be rebuilt if the set of registered language families changes. This flag normally should be combined with 'depends-all, 'depends-all-main, or 'depends-all-user; if it is combined with 'depends-all-main, then it depends only on language families in the main installation.

- 'always-run : Build the document every time that raco setup is run, even if none of its dependencies change.

- 'no-depend-on : Removes the document for consideration for other dependencies. Furthermore, references from the document to other documents are always direct, instead of potentially indirect (i.e., resolved at document-viewing time and potentially redirected to a remote site).

- 'main-doc-root : Designates the root document for the main installation. The document that currently has this mode should be the only one with the mode.

- 'user-doc-root : Designates the root document for the user-specific documentation directory. The document that currently has this mode should be the only one with the mode.

- 'keep-style : Leave the document’s style as-is, instead of imposing the document style for manuals.

- 'no-search : Build the document without a search box.

- 'every-main-layer : With 'main-doc, indicates that the document should be rendered separately at every installation layer (see Layered Installations).

The category list specifies how to show the document in the root table of contents and, for the lang-fam part, how to classify the documentation’s content for searching. This information can be extended or overridden through a 'doc-properties table within the tag-prefix of the document’s main part, but we first consider category on its own:

- A category list must start with a category-name, which determines where the manual appears in a document listing such as the root documentation page. A category is a symbol, string, or a boxed string. If it is a string or a boxed string, then the string is the category label on the root page (when the document’s language families include the language family used for the listing, which is "Racket" for the root documentation page). If it is a symbol, then it should be one of the following categories listed below:

  - 'getting-started : High-level, introductory documentation, typeset at the same level as other category titles.

  - 'core : A core reference or library for a language family as may be specified with a lang-fam.

  - 'racket-core : A core reference or library for Racket. This category normally should be used only by specific packages in the main Racket distribution. When rendering a listing for a language family other than "Racket", these documents appear after 'library instead of after 'core.

  - 'teaching : Documentation for a teaching language or library. Documents in this category appear after 'language if 'racket-core is moved to later.

  - 'language : Documentation for a prominent programming language. If 'racket-core is moved to later, documents in this category appear immediately after 'racket-core and before 'teaching.

  - 'tool : Documentation for an executable.

  - 'gui-library : Documentation for GUI and graphics libraries.

  - 'net-library : Documentation for networking libraries.

  - 'parsing-library : Documentation for parsing libraries.

  - 'tool-library : Documentation for programming-tool libraries (i.e., not important enough for the more prominent 'tool category).

  - 'interop : Documentation for interoperability tools and libraries.

  - 'drracket-plugin : Documentation for DrRacket Plugins.

  - All string and boxed-string categories as ordered by string<=? appear at this point relative to other categories.

  - 'library : Documentation for miscellaneous libraries.

  - All documents whose language families do not include the current language family appear at this point, at least for most categories. Documents are ordered by string<=? on the first family name; within a language family, they are ordered as in a documentation listing for that language family. A document whose category is 'language, 'teaching, 'experimental, 'legacy, or 'racket-core is always listed independent of its language family, however.

    Unless a document’s category is a boxed string, the label used for the category in this section is prefixed by the first family name in the document’s families. A boxed string avoid this prefixing.

  - 'legacy : Documentation for deprecated libraries, languages, and tools.

  - 'experimental : Documentation for an experimental language or library.

  - 'other : Other documentation.

  - 'omit : Documentation that should not be listed on the root page or indexed for searching.

  - 'omit-start : Documentation that should not be listed on the root page but should be indexed for searching.

  If the category list is not given, or if the category symbol is unrecognized, the documentation is added to the ('library) category.

- If the category list has a second element, sort-number, it must be a real number that designates the manual’s sorting position with the category; manuals with the same sorting position are ordered alphabetically. For a pair of manuals with sorting numbers n and m, the groups for the manuals are separated by space if (truncate (/ n 10))and (truncate (/ m 10)) are different.

- If the category list has a third element, lang-fam, then it must be a list of strings, where each string names a language family. The default for lang-fam is (list "Racket"). This language family list is used to organize a listing of all documentation, and is also used for index entries that are extracted from the document and used for searching. For index entries, the document, a part within the document, or an individual index entry may specify its own language family, and lang-fam provides only a default for entries that do not otherwise specify a language family.

- If a document’s main part has a tag-prefix hash table that maps 'doc-properties to another hash table, the inner hash table can override and generalize the category list:

  - If 'language-family is mapped to a list of strings, it provides a replacement for lang-fam.

  - If 'category is mapped to a hash table cat-ht, it is used to get a category replacement specific to a language family. If cat-ht maps the listing’s language family name to a list, that list is used of category. Otherwise, if cat-ht maps 'default to a list, that list is used instead of category. In either case, the replacement list cannot contain a lang-fam component; a 'language-family mapping (as described in the previous bullet) is the only way to replace a lang-fam component.

The out-k specification is a hint on whether to break the document’s cross-reference information into multiple parts, which can reduce the time and memory use for resolving a cross-reference into the document. It must be a positive, exact integer, and the default is 1.

The order-n specification is a hint for ordering document builds, since documentation references can be mutually recursive. The order hint can be any real number. A value of -10 or less disables running the document in parallel to other documents. The main Racket reference is given a value of -11, the search page is given a value of 10, and the default is 0.

A directory for pre-rendered documentation is computed from the source file name by starting with the directory of the "info.rkt" file, adding "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 "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 "synced.rktd" file to represent the installation.

The destination for a rendered document depends on whether the enclosing collection is part of a Racket installation or installed as a package in user package scope. When the document is in user scope, then it is rendered within the package in the same location as for pre-rendered documentation. An exception is when the documentation is declared in scribblings with 'depends-all, 'depends-all-main, or 'depends-all-user and without 'every-main-layer; in that case, it is rendered in a more central location (and not included in a pre-rendered form) as part of the strategy described in Rendering Documentation Listings.

If the a document’s main part’s has a tag-prefix as a hash table, if that hash table has 'doc-properties mapped to another hash table, and if the inner table maps 'supplant to a string, then raco setup copies a rendered "index.html" to a sibling directory name by the 'supplant string. This step, which is performed at the end of the raco setup document-rendering phase, is intended to support document listing as described in Rendering Documentation Listings.

Changed in version 6.4: Allow a category to be a string instead of a symbol.
Changed in version 8.9.0.6: Add the 'drracket-plugin category symbol.
Changed in version 8.14.0.5: Added optional lang-fam within category.
Changed in version 9.0.0.11: Added support for 'depend-family and for 'doc-properties in a document’s main part and for boxed-string category names.

#### 6.3.2 Document Setup Adjustments🔗ℹ

Before a document is rendered by raco setup, its main part is adjusted in several ways:

- The tag-prefix field of the part is adjusted to have the named document’s module path as its 'tag-prefix, which means that other documents can refer to the rendered document via secref or other-doc.

- A '(part "top") tag is added to the part’s tag field if it is not present already.

- A document-version style property is added using (version) if no document-version property is present already.

- A body-id style property is added with "doc-racket-lang-org" if no body-id property is present already.

- A document-source style property is added with the document’s module path.

- A 'show-language-family style property is added.

- A default language family is determined as lang-fam from category in a scribblings entry or (if not present) the value of a 'default-language-family key in the part’s tag-prefix as a hash table (perhaps originally supplied to title). That list of strings, if either, is added as 'language-family to a new table that is paired with 'index-extras (if any) already in the table. That way, category or the main part of a document can supply the default language family for all index entries generated from the document.

- When the part’s tag-prefix is a hash table with 'doc-properties mapped to a hash table value, the value is recorded for cross references using the tag `(doc-properties "top") combined with the document’s module path. This addition allows a 'doc-properties table to configure the document’s listing in more general ways than a category specification within scribblings as described in Document Descriptions in "info.rkt" Files.

The document’s rendering may be further adjusted at the renderer level (see Renderers), including configuration at the level of CSS or Latex.

#### 6.3.3 Documentation Language Families🔗ℹ

(require setup/language-family) | package: base

Added in version 9.0.0.11 of package base.

A language family is a classification used in documentation that affects the way that search results are shown and filtered, and it also affects the way that documentation is categorized and shown in a listing of all documentation. A language family is not merely a module-based language, but instead stands for a set of languages that share a module-naming convention. As a rule of thumb, a language family is distinct enough that it might have its own downloadable distribution.

Language families are declared and used in several ways and places:

- A Racket installation is configured with a default language family, where the default is "Racket"; see get-main-language-family. This default is used by the main documentation listing, and it is used by the documentation-search page as the default language family.

- A language-family definition in an "info.rkt" file in a collection can declare a language family. This declaration is used in rendered documentation to list language families for navigation, and it is used by raco docs to map a language family name to an entry point into documentation and configuration for navigation.

  A language-family definition’s value is a list of hash tables, where each table can have the following keys:

  - 'family: The language-family name as a string—technically optional, but effectively required.

  - 'describe-doc: A module path for the source of a document that describes the language family or its representative language. If 'describe-doc is not mapped, then 'doc (if mapped) is used for the description document, or else no description link is provided for the language family.

  - 'start-doc: A module path for the starting document for the language family or its representative language. If 'start-doc is not mapped, then 'doc (if mapped) is used for the starting document. If neither 'start-doc nor 'doc is mapped, but 'family-root is present, then 'family-root determines the starting page. If none of those keys are mapped, a default starting page is used.

  - 'doc: A module path for a document used as 'describe-doc and/or 'start-doc when those are not mapped.

  - 'order: A real number that orders the family relative to other families (higher is earlier in the list, the Racket language is 100, and the default is 0).

  - 'family-root: The name of the document (if any) that should be considered the starting listing for the language family, so that “top” and “up” navigations arrive at this document. It must be a document with the 'main-doc style and also a 'user-doc plus 'supplant in the 'doc-properties table in tag-prefix for the document’s main part.

- Each regular document rendered via raco setup declares a list of language families. The document is considered in each of those families for the purposes of generating a listing, prioritizing search results, or filtering search results. A document’s language family can be declared by the lang-fam part of the document’s scribblings entry in an "info.rkt" file (see Document Descriptions in "info.rkt" Files), or it can be declared with the document source via the document’s main part, and specifically within the tag-prefix of the part. The default is normally (list "Racket"), but the analog of title for Rhombus’s Scribble dialect injects (list "Rhombus") by default, for example. Individual index entries in a document, which correspond to different results that can be shown by a search, can specify their own language families, so a document that bridges languages can declare different language families for different parts of the document; per-entry information is in a index-desc, where a function like index picks up configuration via part context.

- A module-based language used via #lang can specify a language family for navigating from a programming environment to documentation. See ’documentation-language-family in DrRacket’s documentation for more information.

Navigation and searching for HTML can be adapted to a language family at viewing time (as opposed to rendering time) via query parameters:

- fam: A language family, normally a capitalized name like Racket or Rhombus. This query parameter adjust the prioritization and printing of search results, but it does not filter those results.

- famroot: A document name, normally a case-folded name like rhombus, representing an entry point for a language family. This query parameter adjust the document to be reached by following “up” or “top” links while navigating documents, and it is used only when a fam query is also present.

> > procedure
> > (get-language-families | [ | #:user? user? |  |  |  |
> > |  | #:namespace namespace]) |  | → |  | (listof hash?)
> user? : any/c = #t
> namespace : (or/c #f namespace?) = #f

Finds language-family declarations in "info.rkt" files and returns the hash tables for well-formed entries. The user? argument determines whether user-scope language families are included as well as installation-scope declarations. The namespace argument is passed along to get-info/full.

#### 6.3.4 Rendering Documentation Listings🔗ℹ

(require scribblings/main/contents) | package: racket-index

Added in version 9.0.0.11 of package racket-index.

> > procedure
> > (build-contents |
> > | [ | #:user? user? |
> > |  | #:supplant supplant |
> > |  | #:style style |
> > |  | #:main-language-family language-family |
> > |  | #:title-content title-content |
> > |  | #:self-path self-path |
> > |  | #:bug-url bug-url |
> > |  | #:default-category default-category |
> > |  | #:doc-properties doc-properties |
> > |  | #:default-language-family default-language-family |
> > |  | #:version doc-version |
> > |  | #:date doc-date]) |
> → pre-part?
> user? : any/c = #f
> supplant : (or/c #f string?) = #f
> style : (or/c style? #f string? symbol? (listof symbol?)) = #f
> language-family : string? = (get-main-language-family)
> | title-content |  | : |  | content?
> |  |  | = |  |
> (list language-family
> (element (style #f '(aux)) " Documentation"))
> self-path : (or/c #f path-string?) = #f
> bug-url : (or/c #f string?) = #f
> default-category : list? = '(language)
> | doc-properties |  | : |  | hash? |  | = |  |
> (make-default-doc-properties
> main-family
> default-category
> supplant)
> | default-language-family |  | : |  | (or/c #f (nonempty-listof string?))
> |  |  | = |  | #f
> doc-version : (or/c #f string?) = #f
> doc-date : (or/c #f string?) = #f

Creates the content of a document that lists all installed documentation from the perspective of main-family.

The language-family argument selects the language family used to render the document (i.e., compared to language families of listed documents), while the default-language-family argument specifies the language families that the document listing declares for itself.

Use this function as follows:

- Create a subcollection (say, "my-language/scribblings/main") with an "info.rkt" file and a sub-collectiopn of that one (say, "my-language/scribblings/main/user") with its own "info.rkt" file. Each layer will have one document.

- In the outer subcollection, create a document (say, "my-language.scrbl") that renders on the assumption that it’s in installation scope (i.e., the user? argument to build-contents should be #f). This is the document that secref might reasonably refer to, in case that’s useful. Make sure that the document is listed in scribblings for the subcollection’s "info.rkt", and include the 'depends-all or 'depends-all-main flag and the 'no-depend-on flag.

- In the nested collection, create another document (say, "user-my-language.scrbl") that also has the flags 'user-doc, 'depends-all-user, and 'no-depend-on in the nested subcollection’s "info.rkt" as scribblings. Use the category '(omit). The document should render as in user scope (i.e., the user? argument to build-contents should be #t). If the containing package is in installation scope, this document will be rendered only when there are some other user-scope documents installed. This documentation generally should not be the target of a cross-reference, because it won’t always get rendered.

- In the latter document (perhaps "user-my-language.scrbl"), include the 'supplant key in a 'doc-properties table in tag-prefix for the document’s main part. The value of 'supplant should be the name of the destination for the former document (perhaps "my-language"). A raco setup that builds documentation will arrange for the "index.html" of the supplanting document to be added or to overrwite "index.html" for the supplanted document. That way, when user-scope documentation exists at all, there will be a user-scope document using the name of the main document, whether or not the main document would render into user scope. It’s also important that a 'depends-all flag puts a document in the user-scope root documentation directory, instead of keeping it in the installed package’s directory.

- In the outer subcollection’s "info.rkt", include a main-doc-index entry with the subcollection’s own name. That entry cases the document to be rerendered when packages are installed. Putting the document in a fresh subcollection minimize the work that this rebuild triggers.

- In the nested subcollection’s "info.rkt", include a user-doc-index entry with the subcollection’s own name.

> > procedure
> > (make-default-doc-properties |
> > | [ | #:language-family language-family |
> > |  | #:default-category default-category |
> > |  | #:supplant supplant]) |
> → hash?
> language-family : string? = (get-main-language-family)
> default-category : list? = '(language)
> supplant : (or/c #f string?) = #f

Constructs a hash table suitable for the #:doc-properties argument of build-contents.
top contents ← prev up next →