►Rhombus Scribble
▼3 Core Scribble
On this page:
indexed
as_  indexed
section_  indexed
index_  section
Extras  Map
9.0.0.6
  top  contents    up   

3.7 Indexing🔗ℹ

function

fun indexed(

  words :: (String ||  List.of(String)),

  ~content: content :: (String ||  List.of(String)) = words,

  ~extras: extras :: ExtrasMap = {},

  pre_content :: PreContent

) :: Element

 

function

fun as_indexed(

  pre_content :: PreContent,

  ~extras: extras :: ExtrasMap = {}

) :: Element

The indexed funciton creates an element that renders as pre_content and that registers a link to the rendered text as an index entry keyed by words. The content argument supplieds the rendered for of the index entry as it appears in the index generated by index_section.

If words is a list of strings, then the first string in the list names the general index entry, the second is a more specific refinment of that entry, and so on. As index keys, the strings are “cleaned” by trimming leading and trailing whitespace, and also by converting non-empty sequences of whitespace to a single space character.

The extras argument provides optional information about an index entry. See ExtrasMap for more information.

The as_indexed function is a shorthand for calling indexed with the same text for pre_content and words. Specifically, Content.to_string is used to convert post-decoding pre_content to a single string to supply as words.

Use indexed or as_indexed when an index entry should point to a specific word or phrase within the typeset document. Use section_index, instead, to create an index entry that leads to a section, instead of a specific word or phrase within the section.

function

fun section_indexed(

  words :: String || List.of(String),

  ~extras: extras :: ExtrasMap = {}

) :: PartDecl

Similar to indexed, but without a directly rendered form. Instead, the added index entry refers to the enclosing section. The words serve as both the keys and as the rendered forms of the keys within the index.

More precisely, section_indexed creates a PartDecl that is recognized during decoding in part mode.

function

fun index_section(~tag : tag :: (False || String) = "doc-index")

  :: Part

Generates a part to that renders all index entries for the enclosing document. The optional tag argument is used for the section’s tag.

annotation

ExtrasMap

Recognizes a map that provide optional information about an index entry. All keys in the map are symbols. All values in the map should be writeable in the sense that Racket’s read will reconstruct the value. Any symbol is allowed as a key in extras, but some are well-known, and ExtrasMap recognizes maps that have these keys only when they have the values matching the noted annotations:

  • #'#{language-family}: A PairList.of(ReadableString) describing language families for which this entry is relevant. If this key is missing, the default language-family list is PairList["Racket"], but title effectively makes the default PairList["Rhombus"] via part context (see below).

  • #'#{sort-order}: A Real that is used to order this entry with respect to others that have the same key. Smaller values of #'sort_order are shown before later values, and the default is 0.

  • #'kind: A ReadableString describing the binding’s category, such as "function" or "class". Like most other values in extras, this string is not added to the index entry’s main text as shown to a user, but it may be rendered by some interfaces, such as to the side or in hover text.

  • #'#{module-kind}: A Symbol indicating an entry for a module as documented with docmodule, where the symbol is #'lang for a module documented with ~lang and #'lib otherwise.

  • #'#{part?}: A Boolean indicating whether the index entry describes a section within a document.

  • #'#{hidden?}: A Boolean indicating that the index entry describes a binding that is covered from a user’s perspective by a different index entry. These are considered redundant and filtered from index rendering.

When index entries are recorded, the entry’s extras table can receive additional key–value mappings via part context using the #'#{index-extras} key. The title function puts a mapping for #'#{language-family} to PairList["Rhombus"] into the part context.

  top  contents    up