view release on metacpan or  search on metacpan

doc/tutorial.pp  view on Meta::CPAN

    
This is a possible source for the slide that Robert requested. At the beginning of the chapter
(\C<\BLUE<=An Exciting Slide>>) the default stream \CX<main> is entered. Everything belongs to
this stream until the \I<stream start paragraph>, \C<\RED<~notes>>. All subsequent paragraphs
in this chapter now belong to that stream. So, the chapter really has \I<two> parts now.

   =An Exciting Slide

   \BLUE<* Point One>

   \BLUE<* Point Two>

   \BLUE<* Point Three>

   ~notes

   \RED<Point one is important because blah blah>

   \RED<Point two really means that blah ...>

The parts do not have to be defined in blocks, they can be interrupted by others. It's also
possible to have \I<many> streams in a chapter and not only two. Switching back to the main
stream is possible by using a \C<\RED<~main>> paragraph.

   =Streaming chapter

   This goes to the main stream.

   \RED<~notes>

   This is a note.

   \RED<~main>

   Back to the main stream.

   \RED<~secret notes>

   Notes of a special type.

   \RED<~main>

   Back to the main stream.

   \RED<~notes>

   Standard notes again.

Ok, fine, we have divided our chapter into parts. But to translate this into a layout like
Roberts, we have to go through two more steps:
\OREF{n="Document streams | Processing"}<processing> and
\OREF{n="Document streams | Layouts"}<layout definition>.

====Processing

Document streams are a relatively new feature - not all of the traditional converters support
them yet. If you are using another converter than \CX<perlpoint> please refer to its documentation
for docstream support.

With \C<perlpoint>, there are two options that control how docstreams are handled. First,
\CX<-dstreaming> is of interest. By default or with a value of \C<0>, docstreams are handled
as real streams. With a value of \C<1>, they are ignored - which means that all paragraphs
belonging to other docstreams than \CX<main> will be removed from the result as if they were
not written. And with a value of \C<2> streams are converted into subchapters.

The second control option is \CX<-skipstream>, which allows to filter out \C<certain> streams.
Remember Roberts request: he looked for a way to display slides and notes together. But what
if some day he needs only the slides? With \C<-skipstream> he could filter out the notes when
requested, without changes to his source. This makes it easy to produce exactly the version
that is required.

~hints

It is not possible to filter out the \C<main> stream.

~main

   \GREEN<# no streams at all>
   perlpoint \RED<-dstreaming 1>

   \GREEN<# no "notes" stream>
   perlpoint \RED<-skipstream notes>

Now if your options let some document streams intact as streams, it's time to have a look at
formatting and layout.

====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
(\OREF{n="Writing styles"}<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.

~hints

These hints are defined via document streams.

~main

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

   \RED<~hints>

   These hints are defined via document streams.

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

  <div \RED<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

   \GREEN</* hints */>
   \RED<.hints> {
           font-size: x-small;