[racket] planet/scribble and versions

I should give more context about where I'm coming from.

It seems that Scribble does a "require" of the module being documented.

PLaneT's notion of backward-compatible is a big simplification, and is 
not foolproof.  The author can make a mistake, or there can be a 
difference of understanding on what is specified behavior and what is 
not, and new information can arise after release.  Plus, changing 
versioned documentation is just bad engineering.

For one example: if you're using the Scribble "eval" stuff, some 
difference considered unspecified by the author, might be reflected in 
the documentation and actually be considered relevant: such as the 
format of port output (possibly then used by some other program), or 
simply how objects display (user confusion), might actually affect how 
the documentation is rendered.  Of course, people should not rely on 
things that aren't specified, but the author might have inadvertently 
given a fairly standard-practice specification by saying "...produces 
the output..." or "...looks like...".  This is more a specification if 
user is *not* a hardcore engineer, who should recognize it as ambiguous 
and throw it back at you if it's relevant, but typical developers are 
more vulnerable.

The Scribble "title" form has a "#:version" argument, which causes the 
version number of the package being documented to be included as part of 
the documentation.  For PLaneT packages, that presumably is the version 
number of the exact package in which the documentation is included, and 
the version number to which the documentation pertains.

If substantial content of a versioned document varies based on who 
formatted it, when, on what computer, and what phase of the moon, then 
that creates engineering process problems.  It might even create civil 
liability problems, if something fails due to the magic changing 
versioned documentation, and there are costs or it is considered a 
failure to meet contractual obligations.  And keeping a documentation 
trail is usually part of an engineer's professional and contractual 
responsibilty.  And it simply doesn't look good if your versioned 
documentation changes on its own.  (Yes, you can make the normative 
documents be PDFs or paper, and refuse to let your partners access any 
Scribble-generated hypertext documentation that might be construed as 
documentation furnished by you.  You can also switch to COBOL and strike 
your typing fingers repeatedly with a hammer.)

I would like for the *displayed* form in the formatted documentation to 
be ":MAJOR:MINOR", and the form that Scribble uses for "require" to be 
":MAJOR:=MINOR".

That way, typical developers who copy&paste "require" forms form the 
documentation will get supposedly backward-compatible newer versions by 
default (hardcore engineers will know they have to control the versions 
more anyway, as I've mentioned recently), but versioned documentation 
will not be changing on anyone.  (Though there are still remote 
possibilities of significant changes due to typography and such, that is 
actually a recognized possibility, unlike, say, the text of output in 
code examples changing.)

So, going back to my original question, I'm wondering whether I should 
change McFly to use "planet/scribble", or, if that will not reliably do 
the versions like I think is most appropriate, then I should continue to 
do it in McFly.

I don't feel quite as strongly about this as the above text suggests, 
but I wanted to give people an idea of why I think this sometimes 
matters, and why I don't want McFly to punt on this detail.  It's a very 
easy detail to get right.

-- 
http://www.neilvandyke.org/