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:

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🔗ℹ

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.

6.3.4 Rendering Documentation Listings🔗ℹ

Added in version 9.0.0.11 of package racket-index.

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.