[plt-scheme] scribbling newbie

On Jan 14, Yavuz Arkun wrote:
> Eli Barzilay wrote:
> > To clarify even more, in case anyone is interested: a `@foo[x]{y}'
> > form is read as a sexpr where `foo' is the first item, the (optional)
> > bracketed `x' is parsed as a datum, and the braced (optional) `y' as a
> > string.  This means that @require[whatever], @+[1 2], and @begin[blah
> > blah] are all read the same string-less expressions.  If both the
> > brackets and braces are omitted, then the resulting expression is not
> > put in parens, which is a convenient escape-to-scheme (either a single
> > identifier or an expression).
> >
> > So, when you mean to write some Scheme code, just prefix it with a
> > `@'.  @scheme[...] etc are still the same as @(scheme ...) etc, but
> > they're intended for formatting the contents so the bracketed form is
> > a better expression for this purpose.
> >
> > ]
> 
> Thanks, that clarified some remaining questions for me; this insight
> might be a good addition to the intro section of the scribble docs.

All of that is explained in the syntax part of the scribble
documentation.  Perhaps what's missing is a generic "howto" section
that explains the general intention of the forms when writing
documents.


> I guess, with careful planning, you could use the ability to
> escape-to-scheme to generate documentation

The syntax can be used by itself.  It can be used for anything at all,
not just for documents -- any Scheme code that deals with lots of
free-form text can benefit from using the scribble syntax.


> 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?

In the context of manuals, the `scribble/doc' should provide tools for
dealing with all of that.

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                  http://www.barzilay.org/                 Maze is Life!