[plt-dev] Documenting planet packages

Yesterday I released (planet cce/scheme:3:0), including three new
macros for Scribble documentation: schememodname/this-package,
defmodule/this-package, and declare-exporting/this-package.  These are
variants of schememodname, defmodule, and declare-exporting that add
the owner, name, and major/minor version numbers of the current planet
package to a path.  For instance, within that package, they would
expand as follows:

(schememodname/this-package foo/bar)
==>
(schememodname (planet cce/scheme:3:0/foo/bar))

(defmodule/this-package foo/bar #:use-sources [abc] [def])
==>
(defmodule (planet cce/scheme:3:0/foo/bar) #:use-sources [(planet
cce/scheme:3:0/abc) def])

(declare-exporting/this-package [foo] [bar] #:use-sources [abc] [def])
==>
(declare-exporting (planet cce/scheme:3:0/foo) bar #:use-sources
[(planet cce/scheme:3:0/abc) def])

These are really helpful for creating links and documentation that
refer to the planet package including its version number, so you know
precisely what it's talking about, without the potential for
forgetting to update version numbers when you release.

I propose we add something like these to the trunk, possibly in
planet/util or perhaps in a new scribble/planet module.  The current
versions are a bit clunky -- notice that I had to split all sequences
of module paths into two parts for defmodule and declare-exporting so
I knew which parts to put (planet ...) around.  There's probably a
better way to specify that.  Alternately, if we added unsyntax escapes
to the schememodname, defmodule, and declare-exporting forms (or
versions of them), a single tool for generating planet require specs
would suffice.  (I included that too; this-package-version-symbol for
run-time symbols and syntax-source-planet-package-symbol for
compile-time symbols.)

Meanwhile, if you have a planet package and want to include its path
(including version number) in your documentation, feel free to use
these macros from my package.  Get 'em like this:

(require (planet cce/scheme:3:0/planet))

-- 
Carl Eastlund