Layouts

Document streams just label chapter parts, but they do not imply formatting. Robert, for example, wished to display notes below the slide contents. But this is a matter of his special layout, others might want to place their notes in a row besides the main text, or in a special font. And of course there can be completely different needs as in this layout scheme:

    -------------------------------------
    |                                   |
    |            main stream            |
    |                                   |
    -------------------------------------
    |                 |                 |
    |  item 1 stream  |  item 2 stream  |
    |                 |                 |
    -------------------------------------
    |              stream 3             |
    -------------------------------------

Here two items are compared, each in its row, embedded into a common header and footer. So, in fact the only way to control that is in the layout definition itself. To make this possible the certain target language and formatter plugins mark streams a way that layout definitions ( styles) can access them. So, yes, one needs to read the language and formatter module docs. As an example, we show how to do it in XHTML styles.

Did you notice the short hints in this tutorial, displayed in light blue boxes like the example at the right side? These hints are defined via document streams. The source of the example simply is

     ~hints
  
     These hints are defined via document streams.

The XHTML pages are generated with -target XML -format XHTML::Paged. The XHTML::Paged formatter stores docstreams in a <div> section, so that the example above is translated into

    <div class="hints">
      <p>These hints are defined via document streams.</p>
    </div>

Now with CSS, it's easy to format this part special. In the tutorials style there's one CSS rule that says

     /* hints */
     .hints {
             font-size: x-small;
             background-color: LightBlue;
             border: 5px solid LightBlue;
             margin: 3px;
             width: 400px;
             float: right;
            }

And that is all that is required. So, for XHTML output the key to formatting document streams is CSS.