From 4f96a2ef978a87e685ba6ae7bb714067ca127c4a Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Tue, 22 Apr 2008 18:00:04 +0000
Subject: [PATCH] keyword in methods and apply; procedure-reduce-keyword-arity

svn: r9396

original commit: e25e7a109851e1c64273ad8fb0a69d5075e7b15d
---
 collects/scribblings/scribble/how-to.scrbl | 55 +++++++++++++---------
 1 file changed, 33 insertions(+), 22 deletions(-)

diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl
index e834c39e..97fe5bdd 100644
--- a/collects/scribblings/scribble/how-to.scrbl
+++ b/collects/scribblings/scribble/how-to.scrbl
@@ -54,31 +54,23 @@ To document a collection or @|PLaneT| package:
         the whole right-hand side of the definition is already
         quoted).
 
-        @; [Eli] `name' is not needed, but I think it's used by planet
-        As usual, you may want to add a descriptive
-        @schemeidfont{name} field in your @filepath{info.ss}.  If you
-        do not already have an @filepath{info.ss} module, here's a
-        suitable complete module:
+        If you do not already have an @filepath{info.ss} module,
+        here's a suitable complete module:
 
-        @; [Eli] "Some documentation" is probably not a good name
-        @;   since this is supposed to be documentation for a library
         @schememod[
           setup/infotab
-          (define name "Some documentation")
           (define scribblings '(("manual.scrbl" ())))
         ]}
 
-  @item{@; [Eli] If this is following a planet example, then it should
-        @;   have the correct command line here.  (I don't know what
-        @;   it should be though.)
-        Run @exec{setup-plt} to build your documentation. For a
+  @item{Run @exec{setup-plt} to build your documentation. For a
         collection, optionally supply @Flag{l} followed by the
-        collection name to limit the build process to that collection.}
+        collection name to limit the build process to that
+        collection. For a @|PLaneT| package, optionally supply
+        @Flag{P} followed by the package information to limit the
+        build process to that package.}
 
   @item{The generated documentation is normally
         @filepath{doc/manual/index.html} within the collection or
-        @; [Eli] I "fixed" the obvious typo in the following sentence,
-        @;   but it's still weird and should probably be different.
         @|PLaneT| package directory. If the collection is in PLT
         Scheme's main @filepath{collects} directory, however, then the
         documentation is generated as @filepath{manual/index.html} in
@@ -311,12 +303,31 @@ and they declare hyperlink targets for @scheme[scheme]-based
 hyperlinks.
 
 To document a @scheme[my-helper] procedure that is exported by
-@filepath{helper.ss} in the collection that contains
-@filepath{manual.scrbl}, first use @scheme[(require (for-label ....))]
-to import the binding information of @filepath{helper.ss}. Then add a
-@scheme[defmodule] declaration, which connects the @scheme[for-label]
-binding with the module path as seen by a reader. Finally, use
-@scheme[defproc] to document the procedure:
+@filepath{helper.ss} in the @scheme{my-lib} collection that contains
+@filepath{manual.scrbl}:
+
+@itemize[
+
+ @item{Use @scheme[(require (for-label "helper.ss"))] to import the
+       binding information about the bindings of @filepath{helper.ss}
+       for use when typesetting identifiers. A relative reference
+       @scheme["helper.ss"] works since it is relative to the
+       documentation source.}
+
+ @item{Add a @tt|{@defmodule[my-lib/helper]}| declaration, which
+       specifies the library that is being documented within the
+       section. The @scheme[defmodule] form needs an absolute module
+       name @scheme[mylib/helper], instead of a relative reference
+       @scheme["helper.ss"], since the module path given to
+       @scheme[defmodule] appears verbatim in the generated
+       documentation.}
+
+ @item{Use @scheme[defproc] to document the procedure.}
+
+]
+
+Adding these pieces to @filepath{"manual.scrbl"} gives us the
+following:
 
 @; [Eli] This is also using `my-lib/helper' which doesn't work with
 @; planet libraries
@@ -370,7 +381,7 @@ generates:
 
  @item{If you use @scheme[my-helper] in any documentation now, as long
        as that documentation source also has a @scheme[(require
-       (for-label ....))] of @filepath{my-helper.ss}, then the
+       (for-label ....))] of @filepath{helper.ss}, then the
        reference is hyperlinked to the definition above.}
 
 }