On this page:
3.1 A Simple Example
package-name
major-version
minor-version
package-username
planet-create
parse-module
write-doc
write-main-src
write-main-doc
write-info
write-docs
delete-bak-files
planet-hard-link
planet-remove-hard-link
planet-build
Version: 4.2.2

3 Package Utilities

 (require (planet orseau/lazy-doc:1:0/package))

This module provides definitions to easily create PLaneT packages along with their documentation (using the automatic scribble parser, see defs-parser).

All the functions of this module are meant to be used when current-directory is correctly set to the directory of your package. This is generally true when evaluating a file of your package in DrScheme.

3.1 A Simple Example

The best way to see what this package does is to test by yourself.

Create a directory "my-package", then create inside this directory a "my-module.ss" file (in plain text, without comment boxes). In this module, create a few simple functions and execute this file in DrScheme (F5). In the interaction window, evaluate:

(require (schememodname/this-package package))

Then evaluate:
You have now a (poorly documented, but still documented) ready-to-send package. You can look at the generated documentation in the "planet-docs" sub-directory (view "index.html" in a Web browser).

See the functions below 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 Scribble Definition Parser for documenting source files. You can create several modules, all will be automatically included and documented (an exception list be given).
(package-name)  string?
(package-name name)  void?
  name : string?
A parameter controlling the name of the patckage. By default it is the name of the current directory.

(major-version)  number?
(major-version number)  void?
  number : number?
A parameter controlling the major-version number of the current package (default: 1).

(minor-version)  number?
(minor-version number)  void?
  number : number?
A parameter controlling the minor-version number of the current package (default: 0).

(package-username)  string?
(package-username username)  void?
  username : string?
A parameter controlling the username number of the current package By default it is the username of the OS environment.

Launches the "planet" executable with the "create" option. I prefer this solution to make-planet-archive because it seems to provide more debug info.

(parse-module package-name    
  filename    
  [extension])  string?
  package-name : string?
  filename : string?
  extension : string? = "ss"
Creates the whole scribble string associated with filename, automatically looking for the provided definitions (using quote-require).

(write-doc file [dir #:exists exists])  void?
  file : string?
  dir : (or/c path-string? 'up 'same) = 'same
  exists : (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace)
   = 'error
Writes the ".scrbl" file asociated with file in the directory dir. The exists argument is the same as for with-output-to-file, and the dir argument is the same as for build-path.

(write-main-src main files [#:exists exists])  void?
  main : path-string?
  files : (listof path-string?)
  exists : (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace)
   = 'replace
(Re)writes the main source file of the package, using require-provide for each file of the package.

(write-main-doc main    
  dir    
  files    
  [#:exists exists])  void?
  main : path-string?
  dir : (or/c path-string? 'up 'same)
  files : (listof path-string?)
  exists : (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace)
   = 'error
Writes the main ".scrbl" file in the dir directory with a table of contents. If exists is 'error, write-main-doc only displays a warning and does not overwrite the file. If modules have been added to the package since the last execution of (planet-build), either the user should delete the main file so that it will be rewritten, or the user should add the inclusion of the modules himself in the main file.

(write-info dir    
  main-src    
  main-doc    
  [#:exists exists])  void?
  dir : (or/c path-string? 'up 'same)
  main-src : string?
  main-doc : string?
  exists : (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace)
   = 'error
Writes a stub of the the "info.ss" file that ought to be modified by the user. The argument dir is the sub-directory of the documentation. See write-main-doc for information about the exists option.

(write-docs [#:dir dir    
  #:main-src main-src    
  #:main-doc main-doc    
  #:info? info?    
  #:except except])  void?
  dir : path-string? = "reference"
  main-src : (or/c #f string?) = "main.ss"
  main-doc : (or/c #f string?) = "manual"
  info? : boolean? = #t
  except : (listof string?) = '()
Calls write-main-src on main-src, write-main-doc on main-doc, if they are provided. Calls write-info if info? is #t, and creates the documentation directory dir if it does not already exist.

(Re)writes the ".scrbl" file for all other ".ss" or ".scm" file in the directory (but not in sub-directories), without warning. An exception list of files that must not be included in the process can be given through except.

Deletes all ".bak" files, in the current directory and its sub-directories, that may have been created by DrScheme.

Creates a PLaneT hard link to the current directory so that it is considered as a package.

Removes the planet hard link of the current package.

(planet-build [#:dir dir    
  #:main-src main-src    
  #:main-doc main-doc    
  #:info? info?    
  #:except except])  void?
  dir : path-string? = "reference"
  main-src : (or/c #f string?) = "main.ss"
  main-doc : (or/c #f string?) = "manual"
  info? : boolean? = #t
  except : (listof string?) = '()
Creates a hard-link, calls write-docs with the except exception list of files, calls delete-bak-files, and then calls planet-create. See write-docs for the description of the keyword options.