tag.scrbl (5369B)
1 #lang scribble/doc 2 @(require scribble/manual "utils.rkt" 3 (for-label setup/main-collects)) 4 5 @title[#:tag "tag"]{Tag Utilities} 6 7 @declare-exporting[scribble/tag scribble/base] 8 9 @defmodule*/no-declare[(scribble/tag)]{The @racketmodname[scribble/tag] 10 library provides utilities for constructing cross-reference 11 @tech{tags}. The library is re-exported by 12 @racketmodname[scribble/base].} 13 14 @; ------------------------------------------------------------------------ 15 16 @defproc[(make-section-tag [name string?] 17 [#:doc doc-mod-path (or/c module-path? #f) #f] 18 [#:tag-prefixes tag-prefixes (or/c #f (listof string?)) #f]) 19 tag?]{ 20 21 Forms a @tech{tag} that refers to a section whose ``tag'' (as provided 22 by the @racket[#:tag] argument to @racket[section], for example) is 23 @racket[name]. If @racket[doc-mod-path] is provided, the @tech{tag} 24 references a section in the document implemented by 25 @racket[doc-mod-path] from outside the document. Additional tag 26 prefixes (for intermediate sections, typically) can be provided as 27 @racket[tag-prefixes].} 28 29 @defproc[(make-module-language-tag [lang symbol?]) tag?]{ 30 Forms a @tech{tag} that refers to a section 31 that contains @racket[defmodulelang] for the language 32 @racket[lang]. 33 } 34 35 @defproc[(taglet? [v any/c]) boolean?]{ 36 37 Returns @racket[#t] if @racket[v] is a @tech{taglet}, @racket[#f] 38 otherwise. 39 40 A @deftech{taglet} is a value that can be combined with a symbol via 41 @racket[list] to form a @tech{tag}, but that is not a 42 @racket[generated-tag]. A @tech{taglet} is therefore useful as a piece 43 of a @tech{tag}, and specifically as a piece of a tag that can gain a 44 prefix (e.g., to refer to a section of a document from outside the 45 document).} 46 47 48 @defproc*[([(doc-prefix [mod-path (or/c #f module-path?)] 49 [taglet taglet?]) 50 taglet?] 51 [(doc-prefix [mod-path (or/c #f module-path?)] 52 [extra-prefixes (or/c #f (listof taglet?))] 53 [taglet taglet?]) 54 taglet?])]{ 55 56 Converts part of a cross-reference @tech{tag} that would work within a 57 document implemented by @racket[mod-path] to one that works from 58 outside the document, assuming that @racket[mod-path] is not 59 @racket[#f]. That is, @racket[mod-path] is converted to a 60 @tech{taglet} and added as prefix to an existing @racket[taglet]. 61 62 If @racket[extra-prefixes] is provided, then its content is added as a 63 extra prefix elements before the prefix for @racket[mod-path] is 64 added. A @racket[#f] value for @racket[extra-prefixes] is equivalent 65 to @racket['()]. 66 67 If @racket[mod-path] is @racket[#f], then @racket[taglet] is returned 68 without a prefix (except adding @racket[extra-prefixes], if provided).} 69 70 71 @defproc[(module-path-prefix->string [mod-path module-path?]) string?]{ 72 73 Converts a module path to a string by resolving it to a path, and 74 using @racket[path->main-collects-relative].} 75 76 @defproc[(module-path-index->taglet [mpi module-path-index?]) taglet?]{ 77 78 Converts a module path index to a @tech{taglet}---a normalized 79 encoding of the path as an S-expression---that is interned via 80 @racket[intern-taglet]. 81 82 The string form of the @tech{taglet} is used as prefix in a @tech{tag} 83 to form cross-references into the document that is implemented by the 84 module referenced by @racket[mpi].} 85 86 @defproc[(intern-taglet [v any/c]) any/c]{ 87 88 Returns a value that is @racket[equal?] to @racket[v], where multiple 89 calls to @racket[intern-taglet] for @racket[equal?] @racket[v]s 90 produce the same (i.e., @racket[eq?]) value.} 91 92 93 @defproc[(definition-tag->class/interface-tag [definition-tag definition-tag?]) 94 class/interface-tag?]{ 95 Constructs a tag like @racket[definition-tag], except that 96 it matches documentation for the class. If @racket[definition-tag] 97 doesn't document a class or interface, this function still returns 98 the tag that the class or interface documentation would have had, 99 as if @racket[definition-tag] had documented a class or interface. 100 101 @history[#:added "1.11"] 102 } 103 @defproc[(class/interface-tag->constructor-tag [class/interface-tag class/interface-tag?]) 104 constructor-tag?]{ 105 Constructs a tag like @racket[definition-tag], except that 106 it matches documentation for the constructor of the class. 107 108 @history[#:added "1.11"] 109 } 110 @defproc[(get-class/interface-and-method [method-tag method-tag?]) 111 (values symbol? symbol?)]{ 112 Returns the class name and method name (respectively) for the method documented 113 by the docs at @racket[method-tag]. 114 115 @history[#:added "1.11"] 116 } 117 @defproc[(definition-tag? [v any/c]) boolean?]{ 118 Recognizes definition tags. If @racket[(definition-tag? _v)] is 119 @racket[#t], then so is @racket[(tag? _v)]. 120 121 @history[#:added "1.11"] 122 } 123 @defproc[(class/interface-tag? [v any/c]) boolean?]{ 124 Recognizes class or interface tags. If @racket[(class/interface-tag? _v)] is 125 @racket[#t], then so is @racket[(tag? _v)]. 126 127 @history[#:added "1.11"] 128 } 129 @defproc[(method-tag? [v any/c]) boolean?]{ 130 Recognizes method tags. If @racket[(method-tag? _v)] is 131 @racket[#t], then so is @racket[(tag? _v)]. 132 133 @history[#:added "1.11"] 134 } 135 @defproc[(constructor-tag? [v any/c]) boolean?]{ 136 Recognizes class constructor tags. If @racket[(constructor-tag? _v)] is 137 @racket[#t], then so is @racket[(tag? _v)]. 138 139 @history[#:added "1.11"] 140 }