[plt-scheme] Scribble and indented paragraphs

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Sat Jul 4 10:26:44 EDT 2009

For those writing documents other than language and library
documentation, Scribble now supports paragraphs that span blocks, which
is useful with rendering styles that indent paragraphs.

For example, to typeset something like

     To typeset a Scheme expression
   such as

     (+ 1 2)

   you can use the `schemeblock' form
   that is provided by Scribble.

with just the first block of text indented, avoid a blank line between
the blocks that compose the paragraph in the source, like this:

   To typeset a Scheme expression
   such as
   @blockquote[(+ 1 2)]
   you can use the @scheme[schemeblock] form
   that is provided by Scribble.

or, as I prefer, like this:

   To typeset a Scheme expression
   such as
   @;
   @blockquote[(+ 1 2)]
   @;
   you can use the @scheme[schemeblock] form
   that is provided by Scribble.

In the second form, the "@;" comment lines just break up the blocks in
the source without breaking the paragraph.


If you're just writing documentation, or if you're sure that you'll
always want something like the default style, then it's still ok to use
blank links in the source:

   To typeset a Scheme expression
   such as

   @blockquote[(+ 1 2)]

   you can use the @scheme[schemeblock] form
   that is provided by Scribble.

Using blank lines technically generates three paragraphs. But since
there's no difference in rendering for the style that we've chosen for
documentation, we're not going to worry about the fine details of
paragraphs in documentation sources.


Support for paragraphs that span blocks is reflected in the Scribble
API as a new "compound paragraph" datatype. A compound paragraph
contains a sequence of blocks to be rendered as one conceptual
paragraph, while the Scribble "paragraph" datatype still refers to a
single block of text that contains no other blocks. A "blockquote",
meanwhile, also groups a sequences of blocks, but its blocks are
rendered as separate paragraphs (usually inset relative to the
surrounding text, or with some other style change).



Posted on the users mailing list.