NAME

PerlPoint::Tags::Basic - declares basic PerlPoint tags

VERSION

This manual describes version 0.08.

SYNOPSIS

  # declare basic tags
  use PerlPoint::Tags::Basic;

DESCRIPTION

This module declares several basic PerlPoint tags. Tag declarations are used by the parser to determine if a used tag is valid, if it needs options, if it needs a body and so on. Please see \PerlPoint::Tags for a detailed description of tag declaration.

Every PerlPoint translator willing to handle the tags of this module can declare this by using the module in the scope where it built the parser object.

  # declare basic tags
  use PerlPoint::Tags::Basic;

  # load parser module
  use PerlPoint::Parser;

  ...

  # build parser
  my $parser=new PerlPoint::Parser(...);

  ...

It is also possible to select certain declarations.

  # declare basic tags
  use PerlPoint::Tags::Basic qw(I C);

A set name is provided as well to declare all the flags at once.

  # declare basic tags
  use PerlPoint::Tags::Basic qw(:basic);

TAGS

B

marks text as bold. No options, but a mandatory tag body.

C

marks text as code. No options, but a mandatory tag body.

F

This is a generalized font tag, introduced by "pp2html" and made generally available. It sets up the formatting of a selected text. Traditionally, these are font settings like text color and font size, but there can be more formattings.

Both options and body are mandatory.

Please note that this tag is fairly general. Accepted options and their meaning are defined by the converters, but there are conventions that make documents portable between converters.

So, by convention, options "color" and "size" set up the color and font size of the selected text, in the tradition and argument syntax of HTML.

 A \F{color=red}<red> colored text.

FORMAT

is a container tag to configure result formatting. Configuration settings are received via tag options and are intended to remain valid until another modification. For example, one may set the default text color of examples to green. This would remain valid until the next text color setting.

Please note that this tag is very general. Accepted options and their meaning are defined by the converters. Nevertheless, certain settings are commonly used by convention.

If used as the only contents of a text paragraph the paragraph wrapper will be removed from the stream and the tag is streamed standalone.

HIDE

hides everything in its body. Makes most sense when used with a tag condition.

If used as the only contents of a text paragraph the paragraph wrapper will be removed from the stream and the tag is streamed standalone.

I

marks text as italic. No options, but a mandatory tag body.

IMAGE

includes an image. No tag body, but a mandatory option "src" to pass the image file, and an optional option "alt" to store text alternatively to be displayed. The option set is open - there can be more options but they will not be checked by the parser. If "alt" is not set it defaults to an empty string (added automatically).

The image source file name will be supplied absolutely in the stream.

If used as the only contents of a text paragraph the paragraph wrapper will be removed from the stream and the tag is streamed standalone.

INDEX

Generates an index listing all keywords collected via X. Index formatting is up to the converters.

If used as the only contents of a text paragraph the paragraph wrapper will be removed from the stream and the tag is streamed standalone.

INDEXCLOUD

Generates a "cloud" of the index entries. The term is inspired by the "tag clouds" which became popular in the Internet, but the final formatting might be different, as it is up to the converters. Not all target formats might have features to present a cloud, but finally one should get a kind of a ranking that shows which index entries were used frequently.

If used as the only contents of a text paragraph the paragraph wrapper will be removed from the stream and the tag is streamed standalone.

This tag can be configured by options. All options are optional, except where stated.

chapterDelimiter

A supplementary option to "chapters". Defines the delimiter string used to separate multiple chapter names in the "chapters" value.

Without this parameter the value of "chapters" is treated as one chapter title.

This option has no effect if "chapters" is not used.

Example:

  chapterDelimiter="==" chapters="One Chapter==Another Chapter"

chapters

This mandatory parameter specifies the chapters of which index entries should be taken into account, including all their subchapters. A chapter is specified by its title, as with "\REF". To list more than one chapter, delimit the titles by a string that is not contained in them, and declare this delimiter string with the "chapterDelimiter" option.

Example:

  chapterDelimiter="==" chapters="One Chapter==Another Chapter"

coolestColor

The color that should be used for index entries that have the least references. The color is specified the HTML way, hexadecimal with a "#" prefix.

As colorization strongly depends on the target format, converters can ignore this setting.

This parameter is optional. The default value is subject of converter definitions.

Example:

  coolestColor="#ff3c5d"

hottestColor

This is the color that should be used for index entries that are referenced most. It is specified as a hexadecimal RGB value, preceded by "#" (as in HTML).

As colorization strongly depends on the target format, converters can ignore this setting.

This parameter is optional. The default value is subject of converter definitions.

Example:

  hottestColor="#ff3c5d"

intro

An optional text to be displayed before the cloud. If there are no index entries found in the chapters specified, this text will not be displayed.

This parameter is optional.

Example:

  intro="Index entries in this chapter:"

largestFont

An optional parameter configuring the font size for index entries referenced most, in pixels. The default size is up the converters.

Depending on their capabilities converters might ignore this setting.

Example:

  largestFont=40

smallestFont

This option specifies the minimal font size to be used in the cloud. The default value is up to the converters.

Depending on their capabilities converters might ignore this setting.

Example:

  smallestFont=10

top

Limits the number of index entries visualized by the cloud to the specified number of top rated entries.

Example:

  top=20

INDEXRELATIONS

Inserts a chapter "cross reference" based on the keywords found in all chapters using this tag.

So, the tag has two functions. First, it collects all index entries made in its chapters (and optionally all its subchapters). Second, it includes a reference to other chapters with INDEXRELATIONS which match the own index entries according to the configuration.

If used as the only contents of a text paragraph the paragraph wrapper will be removed from the stream and the tag is streamed standalone.

Configuration is done via options.

format: This setting configures what kind of list will be generated. The following values are specified:

bullets: produces an unordered (bullet) list,
enumerated: produces an ordered list,
numbers: produces a list where each chapter is preceeded by its chapter number, according to the documents hierarchy (1.1.5, 2.3. etc.).

If this option is omitted, the setting defaults to "bullets".

intro: A text that can optional preceed the list of related chapters. This text is not displayed if the list is empty.
readdepth: Configures where keywords shall be collected - startpage includes only the chapter where the tag is located in, while full includes all the subchapters as well.
Defaults to "full".
reldepth: Determines which keywords of other chapters shall be taken into account: keywords found in the chapters containing INDEXRELATIONS directly (startpage), or all their subchapters as well (full).
Defaults to "full".
threshold: Sets up what chapters shall be counted as "related", basing on the matching index entries: can be set up absolutely (e.g. "3 similar entries at least") or by a percentage (e.g. "50% of my entries shall be marked there at least").
Defaults to 100%.
type: linked makes each listed chapter title a link to the related chapter. Note that this feature depends on the target formats link support, so results may vary.
By default, titles are displayed as plain text - plain can be used to specify this explicitly.

Examples:

  \INDEXRELATIONS{format=numbers}

  \INDEXRELATIONS{threshold="100%"
                  format=enumerated
                  type=plain}

  \INDEXRELATIONS{readdepth=full
                  reldepth=startpage
                  threshold="50%"
                  format=bullets
                  type=linked}

LOCALTOC

inserts a list of subchapters, which means a list of the plain subchapter titles. This is especially useful at the beginning of a greater document section, or on an introduction page where you want to preview what the audience can expect in the following talk section.

Using a tag relieves the documents author from writing and maintaining this list manually.

If used as the only contents of a text paragraph the paragraph wrapper will be removed from the stream and the tag is streamed standalone.

There is no tag body, but the result can be configured by options.

depth

Subchapters may have subchapters as well. By default, the whole tree is displayed, but this can be limited by this option. Pass the number of sublevels that shall be included. The lowest possible value is 1. Invalid option values will cause syntax errors.

Consider you are in a level 1 headline with these subchapters:

  ==Details 1
  ==Details 2
  ===Details 2 explained
  ===Details 2 furtherly explained
  ==Conclusion

Depth 1 will result in listing "Details 1", "Details 2" and "Conclusion". Depth 2 or greater will add the explanation subchapters of level 3.

Note that the option expects an offset value. The list depth is independend of the absolute levels of subchapters. This way, your settings will remain valid even if absolute levels change (which might happen when the document is included, for example).

format

This setting configures what kind of list will be generated. The following values are specified:

bullets: produces an unordered list,
enumerated: produces an ordered list,
numbers: produces a list where each chapter is preceeded by its chapter number, according to the documents hierarchy (1.1.5, 2.3. etc.).

If this option is omitted, the setting defaults to "bullets".

type: linked makes each listed subchapter title a link to the related chapter. Note that this feature depends on the target formats link support, so results may vary.
By default, titles are displayed as plain text - plain can be used to specify this explicitly.

Examples:

  \LOCALTOC

  \LOCALTOC{depth=2}

  \LOCALTOC{format=enumerated type=linked}

READY

declares the document to be read completely. No options, no body. Works instantly. Not even the current paragraph will become part of the result. This tag is still experimental, and its behaviour may change in future versions. It is suggested to use it in a single text paragraph, usually embedded into conditions.

  ? ready

  \READY

? 1

REF

This is a very general and highly configurable reference. It can be used both to make linked and unlinked references, it can fallback to alternative references if necessary, and it can finally be that optional that the specified reference does not even has to exist.

There are various options. Please note that several options are filled by the parser. They are not intended to be propagated to document authors.

To make best use of \REF it is recommended to register all anchors at parsing time (with the parsers anchor object passed to all tag hooks).

name

specifies the name of the target anchor. A missing link is an error unless "occasion" is set to a true value or an "alt"ternative address can be found.

Links are verified using the parsers anchor object which is passed to all tag hooks.

type

configures which way the result should be produced:

linked: The result is made a link to the referenced object.

plain: This is the default and means that the result is supplied as plain text. (This is the body text. For bodyless use, option valueformat determines which text this is.)

valueformat

This option configures which text to display if the tag has no body. If there is a tag body, this option is ignored and the body text is used.

pure

This is the default. The text displayed is the value of the referenced object. The value of a referenced object highly depends on its construction method. Please refer to the specific elements documentation for details or just find it out be a trial.

  Headline anchors made by the parser have an value
  of the "headline string", which means the pure title
  without any included tags.

  Sequence numbers made by C<\SEQ> are evaluated
  with their respective numbers.

pagetitle

The title of the page the referenced object is located in.

pagenr

The number of the page the referenced object is located in, e.g. "1.2.3.4.". (Note that the format depends on the documents numbering scheme, which might be determined by the used converter and calling options.)

alt

If the anchor specified by "name" cannot be found, the tag will try all entries of a comma separated list specified by this options value. (For readability, commata may be surrounded by whitespaces.) Trials follow the listed link order, the first valid address found will be used.

If an alternative contains commata itself, guard them by a preceeding backslash.

Links are verified using the parsers anchor object which is passed to all tag hooks.

occasion

If the tag cannot find a valid address (either by "name" or by trying <alt>), usually an error occurs. By setting this option to a true value a missing link will be ignored. The result is equal to a non specified "\REF" tag.

__body__

A flag saying there was a body specified or not. This information can help converters to start a translation before having read the tag body tokens (producing links, a tag without body means that we have to use the value of the referenced object (see "__value__") our text, otherwise, the body text must be used).

__value__

The value of the (finally) referenced object. This only works if the referenced anchor was registered to the parsers "PerlPoint::Anchors" object which is passed to all tag hooks.

__chapter__

The absolute number of the chapter the reference points to. Again, this only works if the referenced anchor was registered to the parsers "PerlPoint::Anchors" object.

SEQ

Inserts the next value of a certain numerical sequence. Optionally, the generated number can be made an anchor to reference it at another place.

There is no tag body, but there are several options. Please note that the parser passes informations by internal options as well.

type: This specifies the sequence the number shall belong to. If the specified string is not already registered as a sequence, a new sequence is opened. The first number in a new sequence is 1. If the sequence is already known, the next number in it will be supplied.
name: If passed, this option sets an anchor name which is registered to the parsers "PerlPoint::Anchors" object (which is passed to all tag hooks). This makes it easy to reference the generated number at another place (by \REF or another referencing tag). The value of such a link is the sequence number.
By default, no anchor is generated.
__nr__: This is the generated sequence number, inserted by the parser. No user option.

STOP

Enforces an syntactical error which stops document processing immediately. Most useful when used with tag conditions.

X

Marks the body to included into the index. Formatting of the index is up to the converters, as is its location unless the INDEX tag is used to include it explicitly.

There are no basic options, but usually converters declare their own, so please refer to the docs of your preferred converter for option details.

TAG SETS

There is only one set "basic" including all the tags.

SUPPORT

A PerlPoint mailing list is set up to discuss usage, ideas, bugs, suggestions and translator development. To subscribe, please send an empty message to perlpoint-subscribe@perl.org.

If you prefer, you can contact me via perl@jochen-stenzel.de as well.

AUTHOR

This module is free software, you can redistribute it and/or modify it under the terms of the Artistic License distributed with Perl version 5.003 or (at your option) any later version. Please refer to the Artistic License that came with your Perl distribution for more details.

The Artistic License should have been included in your distribution of Perl. It resides in the file named "Artistic" at the top-level of the Perl source tree (where Perl was downloaded/unpacked - ask your system administrator if you dont know where this is). Alternatively, the current version of the Artistic License distributed with Perl can be viewed on-line on the World-Wide Web (WWW) from the following URL: http://www.perl.com/perl/misc/Artistic.html

DISCLAIMER

This software is distributed in the hope that it will be useful, but is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or implied, INCLUDING, without limitation, the implied warranties of MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.

The ENTIRE RISK as to the quality and performance of the software IS WITH YOU (the holder of the software). Should the software prove defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE, MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even if they arise from known or unknown flaws in the software).

Please refer to the Artistic License that came with your Perl distribution for more details.