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/
_________________________________________________
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/users
