You are using a browser which doesn't fully support Cascading Style Sheets. This site will look much better in a browser that supports web standards, but its content is accessible to any browser or Internet device.

Appendix A: Stream directives

This apendix is only of interest if you plan to implement a converter with the traditional approach.

The following table describes the backends callback interfaces. The very first parameters passed are a directive constant describing the detected items type, and a state constant expressing the item either begins ( DIRECTIVE_START) or is completed ( DIRECTIVE_COMPLETE).

Although in the first design it was intended to make everything being enclosed by a start and a completion directive, it turned out to be more pragmatic to let several very simple tokens (and therefore stream elements) being represented by a DIRECTIVE_START flag only. The table mentions all used flags.

If start and completion are flagged, tokens of various other types may be embedded. A headline, for example, starts by a startup directive, embeds plain string tokens and possibly flags, and is finally closed by completion directive. On the other hand, tokens that only provide a startup flag are completely represented by the token element containing the flag. That means that plain string directives, for example, contain the string as well - nothing more will follow. (That's easier to understand than to describe, hm.)

All parameters beginning with the third one are absolutely type specific.

If there are beginning and completing elements, all parameters will be provided at both places except where noted.

1: type directive	2: used flags (modes)	3...: more parameters
`DIRECTIVE_BLOCK`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	-
`DIRECTIVE_COMMENT`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	-
`DIRECTIVE_DLIST`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	a reserved parameter, two parameters describing type and level of a preceeding list shift if any (0 otherwise, only provided in start directives), two parameters describing type and level of a following list shift if any (0 otherwise, only provided in completion directives)
`DIRECTIVE_DOCUMENT`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	(base)name of source file
`DIRECTIVE_DPOINT`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	a reserved parameter, two parameters describing type and level of a preceeding list shift if any (0 otherwise, only provided in start directives), two parameters describing type and level of a following list shift if any (0 otherwise, only provided in completion directives)
`DIRECTIVE_DPOINT_ITEM`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	-
`DIRECTIVE_DSTREAM_ENTRYPOINT`	`DIRECTIVE_START`	stream name
`DIRECTIVE_HEADLINE`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	Headline level. The full headline title (tags stripped off), a short version of the title and a reference to an array of docstreams used in this chapter are provided additionally in the startup directive only. (If no short title version (or "shortcut") was specified, an empty string is provided.)
`DIRECTIVE_LIST_LSHIFT`	`DIRECTIVE_START`	number of levels to shift
`DIRECTIVE_LIST_RSHIFT`	`DIRECTIVE_START`	number of levels to shift
`DIRECTIVE_NEW_LINE`	`DIRECTIVE_START`	a hash reference: key "file" provides the current source file name, key "line" the new line number
`DIRECTIVE_OLIST`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	A prefered startup number (defaults to 1). Two parameters describing type and level of a preceeding list shift if any (0 otherwise, only provided in start directives), two parameters describing type and level of a following list shift if any (0 otherwise, only provided in completion directives)
`DIRECTIVE_OPOINT`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	-
`DIRECTIVE_SIMPLE`	`DIRECTIVE_START`	a list of strings
`DIRECTIVE_TAG`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	First, the tag name, then a reference to a hash of tag options taken from the source, then the number of stream parts following for the body (0 means: no tag body). Tag options in the open directive might have been modified by a tag finish hook and therefore differ from the options provided in the closing directive, which reflects the original options (before finish hook invokation).
`DIRECTIVE_TEXT`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	-
`DIRECTIVE_ULIST`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	-
`DIRECTIVE_UPOINT`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	-
`DIRECTIVE_VARRESET`	`DIRECTIVE_START`	-
`DIRECTIVE_VARSET`	`DIRECTIVE_START`	a hash reference: key "var" provides the variables name, key "value" the new value
`DIRECTIVE_VERBATIM`	`DIRECTIVE_START`, `DIRECTIVE_COMPLETE`	-

For internal tag options (C<__option__>) passed by the parser, please refer to the parser docs.

And here is how these directives correspond to the PerlPoint source elements. To make reading (and writing ;-) simpler, the string DIRECTIVE_ and the type specific parameters passed to appropriate callbacks are omitted. See the table above fo those details. A directive is illustrated by enclosing brackets.

Block:

    [BLOCK, START]
  
      block contents
  
    [BLOCK, COMPLETED]

Comment:

    [COMMENT, START]
  
      comment text
  
    [COMMENT, COMPLETED]

Description list: The "description point item" is the described thing, marked in PerlPoint by enclosing colons.

    [DLIST, START]
  
      [DPOINT, START]
  
         [DPOINT_ITEM, START]
  
           item elements (text, tags, ...)
  
         [DPOINT_ITEM, COMPLETED]
  
         [DPOINT_TEXT, START]
  
           description elements (text, tags, ...)
  
         [DPOINT_TEXT, COMPLETED]
  
      [DPOINT, COMPLETED]
  
      there may be more points
  
    [DLIST, COMPLETED]

Document:

    [DOCUMENT, START]
  
      main stream
  
    [DOCUMENT, COMPLETED]

Document stream entry point: This directive is extremely simple, so there is no completion directive.

    [DSTREAM_ENTRYPOINT, START]

Headline:

    [HEADLINE, START]
  
      headline text, tags etc.
  
    [HEADLINE, COMPLETED]

List shifts: Because these directives are extremely simple, there are no completion directives.

    [LIST_LSHIFT, START]

    [LIST_RSHIFT, START]

Ordered list:

    [OLIST, START]
  
      [OPOINT, START]
  
        point contents
  
      [OPOINT, COMPLETED]
  
      there may be more points
  
    [OLIST, COMPLETED]

Plain text: the parser tries to provide as much text together as possible. Nevertheless, there's no guarantee that a certain string sequence will be provided by a certain stream sequence of simple token directives. Whatever way a simple token sequence is provided, joining their contents by empty strings will result in the original string sequence.

    [SIMPLE, START]

Tag:

    [TAG, START]
  
      tagged things
  
    [TAG, COMPLETED]

Text:

    [TEXT, START]
  
      text
  
    [TEXT, COMPLETED]

Unordered list:

    [ULIST, START]
  
      [UPOINT, START]
  
        point contents
  
      [UPOINT, COMPLETED]
  
      there may be more points
  
    [ULIST, COMPLETED]

Verbatim block:

    [VERBATIM, START]
  
      block contents
  
    [VERBATIM, COMPLETED]