#lang scribble/doc @(require "common.ss") @title[#:tag "build"]{Building and Installing Documentation} PLT Scheme documentation resides with the source code. The setup process that builds bytecode from Scheme source also renders HTML documentation from Scribble source. The HTML output is accompanied by cross-reference information that is used both for building more documentation when new libraries are installed and for online help in the programming environment. Clicking the @onscreen{Check Syntax} button in DrScheme creates hyperlinks in the code for each identifier that is specified in the documentation. The hyperlink is not a guess from heuristically inspecting the source; it is a precise link to the correct documentation that is based on the same binding information that the compiler uses, so clicking on a @scheme[lambda] that forms a procedure always opens documentation for the right @scheme[lambda]. Since Scribble documents are themselves Scheme programs, this support works just as well on document sources: open any part of this paper's source in DrScheme, click @onscreen{Check Syntax}, and then a right-click on a use of, say, @scheme[title] to directly access the documentation of the @scheme[title] function, even though the surface syntax of the document source looks more like @|latex| than Scheme. @figure["check-syntax.png"]{DrScheme with documentation links and binding arrows in Scribble Code} The document-setup process also takes advantage of the fact that Scribble documents are PLT Scheme modules. Our existing @tt{make} tools can be applied to a Scribble document to determine whether it needs to be re-built, and document re-rendering can use the bytecode form of unchanged portions of the document. If a document uses Scribble extensions, whether functions or syntax, the tool chain for building the document need not change, because PLT Scheme tools are built for extensibility from the ground up. Although many existing PLT Scheme tools help in building documents, the process of generating HTML is significantly different from compilation tasks. The main difference is that mutual dependencies are common in documentation, whereas library modules are strictly layered. For example, the core language reference contains many pointers into the overview and a few pointers to the GUI library and other extensions; all documents, meanwhile, refer back to the core reference. Resolving mutual dependencies directly would require loading all documents into memory at once, which is impractical for the scale of the PLT Scheme documentation. The setup processes therefore builds documents one at a time, reading and writing serialized cross-reference information until it arrives as a fixed point for all documents (which typically takes two iterations). Another challenge in building a unified set of documentation is that individual users might augment the main installation with user-specific libraries. The main installation includes a table of contents that is the default starting point for reading documentation, and this table is updated when a new package is placed into the main installation. When a user-specific library is installed, in contrast, its document is built so that hyperlink references go into the main installation's documentation, but a user-specific table of contents is created. When a user opens the documentation via DrScheme's @onscreen{Help} menu, a user-specific table of contents is opened (if it exists). Instead of explicitly installing a library, a user can implicitly install a package from the @|PLaneT| repository by using a library reference of the form @scheme[(planet ....)]. When a library is installed in this way, its documentation is installed as the library is compiled. @|PLaneT| supports library versioning, and multiple versions of a package can be installed at a time. In that case, multiple versions of the documentation are installed; document references work with versions just as reliably as library references, since they use the same underlying module-import mechanisms.