how-to.scrbl (12924B)
1 #lang scribble/doc 2 @(require scribble/manual scribble/bnf "utils.rkt") 3 4 @(define pkg-doc '(lib "pkg/scribblings/pkg.scrbl")) 5 6 @title[#:tag "how-to-doc"]{Getting Started with Documentation} 7 8 Although the @exec{scribble} command-line utility generates output 9 from a Scribble document, documentation of Racket libraries is 10 normally built by @exec{raco setup}. This chapter emphasizes the 11 @exec{raco setup} approach, which more automatically supports links 12 across documents. 13 14 @margin-note{See @secref["getting-started"] for information on using the 15 @exec{scribble} command-line utility.} 16 17 @;---------------------------------------- 18 @section[#:tag "setting-up"]{Setting Up Library Documentation} 19 20 To document a collection, including a collection implemented by a 21 @seclink["getting-started" #:doc pkg-doc]{package}: 22 23 @itemize[ 24 25 @item{Create a file in your collection with the 26 file extension @filepath{.scrbl}. Beware that the file name 27 you choose will determine the output directory's name, and 28 the directory name must be unique across all installed documents. The 29 remainder of these instructions assume that the file is called 30 @filepath{manual.scrbl} (but pick a more specific name in practice).} 31 32 @item{Start @filepath{manual.scrbl} like this: 33 @codeblock|{ 34 #lang scribble/manual 35 36 @title{My Library} 37 38 Welcome to my documentation: @racket[(list 'testing 1 2 3)]. 39 }| 40 41 The first line starts the file in ``text'' mode and selects 42 the Racket manual output format. 43 It also introduces bindings like @racket[title] and 44 @racket[racket] for writing Racket documentation.} 45 46 @item{Add the following entry to your collection's 47 @filepath{info.rkt}: 48 49 @racketblock[ 50 (define scribblings '(("manual.scrbl" ()))) 51 ] 52 53 The @racket[()] above is a list of options. When your document 54 gets large enough that you want it split into multiple pages, 55 add the @racket['multi-page] option (omitting the quote, since 56 the whole right-hand side of the definition is already 57 quoted). 58 59 If you do not already have an @filepath{info.rkt} module, 60 here's a suitable complete module: 61 62 @racketmod[ 63 info 64 (define scribblings '(("manual.scrbl" ()))) 65 ]} 66 67 @item{Run @exec{raco setup} to build your documentation. For a 68 collection, optionally supply @Flag{l} followed by the 69 collection name to limit the build process to that 70 collection.} 71 72 @item{For a collection that is installed as user-specific 73 (e.g., the user @tech[#:doc pkg-doc]{package scope}), the generated 74 documentation is @filepath{doc/manual/index.html} within the 75 collection directory. If the collection is installation-wide, 76 however, then the documentation 77 is generated as @filepath{manual/index.html} in the 78 installation's @filepath{doc} directory.} 79 80 ] 81 82 @; ---------------------------------------- 83 @section[#:tag "racket-hyperlinks"]{Racket Typesetting and Hyperlinks} 84 85 In the document source at the start of this chapter 86 (@secref["setting-up"]), the Racket expression 87 @racket[(#,(racketidfont "list") 'testing 1 2 3)] is typeset properly, 88 but the @racketidfont{list} identifier is not hyperlinked to the usual 89 definition. To cause @racketidfont{list} to be hyperlinked, add a 90 @racket[require] form like this: 91 92 @codeblock[#:keep-lang-line? #f]|{ 93 #lang scribble/base 94 @(require (for-label racket)) 95 }| 96 97 This @racket[require] with @racket[for-label] declaration introduces a 98 document-time binding for each export of the @racketmodname[racket] 99 module. When the document is built, the @racket[racket] form detects 100 the binding for @racket[list], and so it generates a reference to the 101 specification of @racket[list]. The setup process detects the 102 reference, and it finds the matching specification in the existing 103 documentation, and ultimately directs the hyperlink to that 104 specification. 105 106 Hyperlinks based on @racket[for-label] and @racket[racket] are the 107 preferred mechanism for linking to information outside of a single 108 document. Such links require no information about where and how a 109 binding is documented elsewhere: 110 111 @codeblock|{ 112 #lang scribble/manual 113 @(require (for-label racket)) 114 115 @title{My Library} 116 117 See also @racket[list]. 118 }| 119 120 The @racket[racket] form typesets a Racket expression for inline text, 121 so it ignores the source formatting of the expression. The 122 @racket[racketblock] form, in contrast, typesets inset Racket code, 123 and it preserves the expression's formatting from the document source. 124 125 @codeblock|{ 126 #lang scribble/manual 127 @(require (for-label racket)) 128 129 @title{My Library} 130 131 Some example Racket code: 132 133 @racketblock[ 134 (define (nobody-understands-me what) 135 (list "When I think of all the" 136 what 137 "I've tried so hard to explain!")) 138 (nobody-understands-me "glorble snop") 139 ] 140 }| 141 142 143 @; ---------------------------------------- 144 @section[#:tag "section-hyperlinks"]{Section Hyperlinks} 145 146 A @racket[section] declaration in a document can include a 147 @racket[#:tag] argument that declares a hyperlink-target tag. The 148 @racket[secref] function generates a hyperlink, using the section name 149 as the text of the hyperlink. Use @racket[seclink] to create a 150 hyperlink with text other than the section title. 151 152 The following example illustrates section hyperlinks: 153 154 @codeblock|{ 155 #lang scribble/manual 156 @(require (for-label racket)) 157 158 159 @title{My Library} 160 161 Welcome to my documentation: @racket[(list 'testing 1 2 3)]. 162 163 @table-of-contents[] 164 165 166 @section[#:tag "chickens"]{Philadelphia Chickens} 167 168 Dancing tonight! 169 170 171 @section{Reprise} 172 173 See @secref{chickens}. 174 }| 175 176 Since the page is so short, the hyperlinks in the above example are 177 more effective if you change the @filepath{info.rkt} file to add the 178 @racket['multi-page] flag: 179 180 @racketblock[ 181 (define scribblings '(("manual.scrbl" (multi-page)))) 182 ] 183 184 A section can have a @techlink{tag prefix} that applies to all tags as 185 seen from outside the section. Such a prefix is automatically given to 186 each top-level document as processed by @exec{raco setup}. Thus, 187 referencing a section tag in a different document requires using a 188 prefix, which is based on the target document's main source file. The 189 following example links to a section in the Racket reference 190 manual: 191 192 @codeblock|{ 193 #lang scribble/manual 194 @(require (for-label racket)) 195 @(define ref-src 196 '(lib "scribblings/reference/reference.scrbl")) 197 198 @title{My Library} 199 200 See also @italic{@secref[#:doc ref-src]{pairs}}. 201 }| 202 203 As mentioned in @secref{racket-hyperlinks}, however, cross-document 204 references based on @racket[(require (for-label ....))] and 205 @racket[racket] are usually better than cross-document references 206 using @racket[secref]. 207 208 @; ---------------------------------------- 209 @section{Defining Racket Bindings} 210 211 Use @racket[defproc] to document a procedure, @racket[defform] to 212 document a syntactic form, @racket[defstruct] to document a structure 213 type, etc. These forms provide consistent formatting of definitions, 214 and they declare hyperlink targets for @racket[racket]-based 215 hyperlinks. 216 217 To document a @racket[my-helper] procedure that is exported by 218 @filepath{helper.rkt} in the @filepath{my-lib} collection that contains 219 @filepath{manual.scrbl}: 220 221 @itemize[ 222 223 @item{Use @racket[(require (for-label "helper.rkt"))] to import the 224 binding information about the bindings of @filepath{helper.rkt} 225 for use when typesetting identifiers. A relative reference 226 @racket["helper.rkt"] works since it is relative to the 227 documentation source.} 228 229 @item{Add a @tt|{@defmodule[my-lib/helper]}| declaration, which 230 specifies the library that is being documented within the 231 section. The @racket[defmodule] form needs an absolute module 232 name @racket[mylib/helper], instead of a relative reference 233 @racket["helper.rkt"], since the module path given to 234 @racket[defmodule] appears verbatim in the generated 235 documentation.} 236 237 @item{Use @racket[defproc] to document the procedure.} 238 239 ] 240 241 Adding these pieces to @filepath{manual.scrbl} gives us the 242 following: 243 244 @codeblock|{ 245 #lang scribble/manual 246 @(require (for-label racket 247 "helper.rkt")) 248 249 @title{My Library} 250 251 @defmodule[my-lib/helper] 252 253 @defproc[(my-helper [lst list?]) 254 (listof 255 (not/c (one-of/c 'cow)))]{ 256 257 Replaces each @racket['cow] in @racket[lst] with 258 @racket['aardvark].} 259 }| 260 261 In @racket[defproc], a contract is specified with each argument to the 262 procedure. In this example, the contract for the @racket[_lst] 263 argument is @racket[list?], which is the contract for a list. After 264 the closing parenthesis that ends the argument sequence, the contract 265 of the result must be given; in this case, @racket[my-helper] 266 guarantees a result that is a list where none of the elements are 267 @racket['cow]. 268 269 Some things to notice in this example and the documentation that it 270 generates: 271 272 @itemize[ 273 274 @item{The @racket[list?], @racket[listof], @|etc| elements of 275 contracts are hyperlinked to their documentation.} 276 277 @item{The result contract is formatted in the generated documentation 278 in the same way as in the source. That is, the source layout of 279 contracts is preserved. (In this case, putting the contract all 280 on one line would be better.)} 281 282 @item{In the prose that documents @racket[my-helper], @racket[_lst] 283 is automatically typeset in italic, matching the typesetting in 284 the blue box. The @racket[racket] form essentially knows that 285 it's used in the scope of a procedure with argument 286 @racket[_lst].} 287 288 @item{If you hover the mouse pointer over @racket[my-helper], a popup 289 reports that it is provided from @racketidfont{my-lib/helper}.} 290 291 @item{If you use @racket[my-helper] in any documentation now, as long 292 as that documentation source also has a @racket[(require 293 (for-label ....))] of @filepath{helper.rkt}, then the 294 reference is hyperlinked to the definition above.} 295 296 ] 297 298 See @racket[defproc*], @racket[defform], @|etc| for more information 299 on forms to document Racket bindings. 300 301 @; ---------------------------------------- 302 @section{Showing Racket Examples} 303 304 The @racket[examples] form from @racket[scribble/eval] helps you 305 generate examples in your documentation. To use @racket[examples], the 306 procedures to document must be suitable for use at documentation time, 307 but the @racket[examples] form does not use any binding introduced 308 into the document source by @racket[require]. Instead, create a new 309 evaluator with its own namespace using @racket[make-base-eval], and 310 use @racket[interaction-eval] to require @filepath{helper.rkt} in that 311 evaluator. Finally, supply the same evaluator to @racket[examples]: 312 313 @codeblock|{ 314 #lang scribble/manual 315 @(require scribble/eval 316 (for-label racket 317 "helper.rkt")) 318 319 @title{My Library} 320 321 @defmodule[my-lib/helper] 322 323 @defproc[(my-helper [lst list?]) 324 (listof 325 (not/c (one-of/c 'cow)))]{ 326 Replaces each @racket['cow] in @racket[lst] with 327 @racket['aardvark]. 328 329 @(define helper-eval (make-base-eval)) 330 @interaction-eval[#:eval helper-eval 331 (require "helper.rkt")] 332 @examples[ 333 #:eval helper-eval 334 (my-helper '()) 335 (my-helper '(cows such remarkable cows)) 336 ]} 337 }| 338 339 @;---------------------------------------- 340 @section{Multi-Page Sections} 341 342 Setting the @racket['multi-page] option (see 343 @secref["section-hyperlinks"]) causes each top-level section of a 344 document to be rendered as a separate HTML page. 345 346 To push sub-sections onto separate pages, use the @racket['toc] style 347 for the enclosing section (as started by @racket[title], 348 @racket[section], @racket[subsection], etc.) and use 349 @racket[local-table-of-contents] to generate hyperlinks to the 350 sub-sections. 351 352 Revising @filepath{cows.scrbl} from the previous section: 353 354 @codeblock|{ 355 #lang scribble/manual 356 357 @title[#:style '(toc)]{Cows} 358 359 @local-table-of-contents[] 360 361 @section[#:tag "singing"]{Singing} 362 Wherever they go, it's a quite a show. 363 364 @section{Dancing} 365 See @secref["singing"]. 366 }| 367 368 To run this example, remember to change @filepath{info.rkt} to add the 369 @racket['multi-page] style. You may also want to add a call to 370 @racket[table-of-contents] in @filepath{manual.scrbl}. 371 372 The difference between @racket[table-of-contents] and 373 @racket[local-table-of-contents] is that the latter is ignored for 374 Latex output. 375 376 When using @racket[local-table-of-contents], it often makes sense to 377 include introductory text before the call of 378 @racket[local-table-of-contents]. When the introductory text is less 379 important and when local table of contents is short, putting the 380 introductory text after the call of @racket[local-table-of-contents] 381 may be appropriate.