suzanne.soy/hyper-literate
1
0
Fork 0
Code Issues 4 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

scribble docs: tweak language related to collections and packages

Browse Source 
original commit: f94dc32329e7b303e92feba736f33b3484b281b3
This commit is contained in:
Matthew Flatt 2014-03-15 15:58:45 -06:00
parent 7c81ef7f75
commit fdb4bb99d0
1 changed files with 16 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/how-to.scrbl
View File

@ -1,6 +1,8 @@
#lang scribble/doc #lang scribble/doc
@(require scribble/manual scribble/bnf "utils.rkt") @(require scribble/manual scribble/bnf "utils.rkt")
@(define pkg-doc '(lib "pkg/scribblings/pkg.scrbl"))
@title[#:tag "how-to-doc"]{Getting Started with Documentation} @title[#:tag "how-to-doc"]{Getting Started with Documentation}
Although the @exec{scribble} command-line utility generates output Although the @exec{scribble} command-line utility generates output
@ -15,16 +17,17 @@ across documents.
@;---------------------------------------- @;----------------------------------------
@section[#:tag "setting-up"]{Setting Up Library Documentation} @section[#:tag "setting-up"]{Setting Up Library Documentation}
To document a collection or Racket To document a collection, including a collection implemented by a
@seclink["getting-started" #:doc '(lib "pkg/scribblings/pkg.scrbl") "package"]: @seclink["getting-started" #:doc pkg-doc]{package}:
@itemize[ @itemize[
@item{Create a file in your collection or package with the @item{Create a file in your collection with the
file extension @filepath{.scrbl}. Beware that the file name file extension @filepath{.scrbl}. Beware that the file name
you choose will determine the output file's name. The you choose will determine the output directory's name, and
the directory name must be unique across all installed documents. The
remainder of these instructions assume that the file is called remainder of these instructions assume that the file is called
@filepath{manual.scrbl}.} @filepath{manual.scrbl} (but pick a more specific name in practice).}
@item{Start @filepath{manual.scrbl} like this: @item{Start @filepath{manual.scrbl} like this:
@verbatim[#:indent 2]|{ @verbatim[#:indent 2]|{
@ -40,7 +43,7 @@ To document a collection or Racket
It also introduces bindings like @racket[title] and It also introduces bindings like @racket[title] and
@racket[racket] for writing Racket documentation.} @racket[racket] for writing Racket documentation.}
@item{Add the following entry to your collect or package's @item{Add the following entry to your collection's
@filepath{info.rkt}: @filepath{info.rkt}:
@racketblock[ @racketblock[
@ -66,12 +69,13 @@ To document a collection or Racket
collection name to limit the build process to that collection name to limit the build process to that
collection.} collection.}
@item{The generated documentation is normally @item{For a collection that is installed as user-specific
@filepath{doc/manual/index.html} within the collection or (e.g., the user @tech[#:doc pkg-doc]{package scope}), the generated
package directory. If the collection is in documentation is @filepath{doc/manual/index.html} within the
Racket's main @filepath{collects} directory, however, then the collection directory. If the collection is installation-wide,
documentation is generated as @filepath{manual/index.html} in however, then the documentation
the installation's main @filepath{doc} directory.} is generated as @filepath{manual/index.html} in the
installation's @filepath{doc} directory.}
] ]