#lang scribble/manual
@(require (planet cce/scheme:6:0/scribble)
          (for-label scheme
                     (this-package-in package)))

@(define (my-prog . str) (apply verbatim #:indent 5 str))

@title{Lazy Source Documenting and Package Building}

@defmodule/this-package[]

@author{Laurent Orseau}

This package provides tools (see @secref{package}) to easily create and document @PLaneT packages.
It uses the @secref{defs-parser}, built upon a general @secref{simple-parser}, which can be
used for many simple parsing/lexing tasks.

See @secref{example} for a gentle introduction.

@table-of-contents[]

@section[#:tag "example"]{A Simple Example}
The best way to see what this package does is to test by yourself.

Create a directory @filepath{my-package}, then create inside this directory
a @filepath{my-module.ss} file (in plain text, without comment boxes).
In this module, create a few simple functions, for example 
(along with optional textual info):
@my-prog|{
#lang scheme

(provide do-something
         do-something-else)

;[:title Some Functions]

(define (do-something lst str)
  ;: Does something.
  (printf "I'm doing something"))

(define (do-something-else ll num) ;:-> number?
  ;: Does something else but not as well.
  (printf "I'm doing something else"))
}|
save this file, and execute it in DrScheme (F5).
In the interaction window, evaluate:
@schemeblock[(require @#,(schememodname/this-package package))]
Then evaluate:
@schemeblock[(planet-build)]
In the parent directory of @filepath{my-package}, 
you have now a ready-to-send package.

You can look at the generated documentation in the @filepath{planet-docs} sub-directory
(view @filepath{index.html} in a Web browser).

You may want to modify the generated @filepath{info.ss} file before sending, though.

See the @secref{package} for more details on the possible options when
creating packages.

Modules can of course be much more documented while keeping most of the 
process automatic. See @secref{defs-parser} for documenting
source files.
You can create several module files in the root directory of your package,
all will be automatically included and
documented (an exception list be given).

@include-section["package.scrbl"]
@include-section["defs-parser.scrbl"]
@include-section["simple-parser.scrbl"]
@include-section["common.scrbl"]