[plt-scheme] scribbling newbie

At Mon, 14 Jan 2008 16:55:18 +0200, Yavuz Arkun wrote:
> I guess, with careful planning,  you could use the ability to 
> escape-to-scheme to generate documentation that is tailored to the 
> actual installation, e.g. by replacing the generic installation paths 
> used in the normal documentation with the actual paths of the installation?

Yes, but...

The old Help Desk was designed, in part, around the idea that
installation-specific documentation was important. That is, you should
be able to escape to Scheme code at the time that the docs are read to
include installation-specific information, such as paths to
executables.

Our experience so far, though, has been that this installation-specific
information is less important than other constraints, such as making
the documentation easy to read in your favorite browser. And experience
trying to use browsers has convinced us that the documentation must be
static HTML pages.

Finally, other bits of experience taught us that it was important to be
able to move an installation around in the filesystem. This happens
either explicitly, when the user moves a directory, or implicitly, when
a filesystem is mounted in different ways (e.g., a flash drive mounted
on different machines).

So, there have to be static HTML pages for the documentation that are
independent of the installation details. That means that you shouldn't
compute installation-specific information in documentation that is part
of the main distribution. In fact, the documentation is built once, and
then included in various distribution archives, so it needs to be both
installation- and platform-independent.


When you install new packages, such as through Planet, then the
starting page for `plt-help' will get rebuilt with user-specific
information. But that goes to a user-specific place (like installed
Planet packages themselves), instead of the main installation.

So, for Planet-based packages or other things that aren't part of the
distribution, it might make sense to compute installation-specific
information in documentation. Then again, documentation for Planet
packages will appear on the Planet server, so it might not make sense
there, either.

Matthew