EMBED results from the CPAN

PerlPoint-Package
==The whole picture

So there are two main tasks to perform when writing a converter: define the tags you want to use and write backend callbacks which generate one or more documents in the target format. These pieces are then put together by an application that loads ta...


The following chapters will describe this work in detail.


=Tag definition

It's up to you to define your tag meanings. Tags are usually used to mark up text. This may be a logical markup (index entry, code sequence, ...) or a formatting one (bold, italics, ...), for example.

  \RED<\\B<something\>> marks "something" to
  be formatted bold.

  The pp2html tag \RED<\\X> declares index entries
  like \RED<\\X<here>>.

Note that the common (and recommended) way of markup is to expect the marked text part in the tags body. However, it is also possible to declare begin and end tags which enclose the marked parts, like the builtin \C<\\TABLE> and \C<\\END_TABLE> do. T...

  \\TABLE

  Column   | Column
  contents | contents

  \\END_TABLE

Note that a tag does note necessarily need to have a body part. \C<\\END_TABLE>, for example, has not.

Depending on the tag meaning (or "semantics"), a tag may need options. These are parameters passed to the tag, specifying how it shall be evaluated. Tag options can be optional or mandatory.

  The \\IMAGE tag uses options to specify
  what file should be loaded, as in

  \\IMAGE{src="image.png"}

As a general rule, tag options control tag processing, while the tag body contains parts of the document. Keep in mind that your tags might be processed by \I<other> converters as well which do not handle them. In such a case, only the tag body will ...

The same is true vice versa:

  Theoretically, the image tag could use the
  tags \I<body> as well to declare the image file:

  \\IMAGE\RED<<image.png\>>

  But if a converter ignores \\IMAGE, this
  would result in the \I<text> "image.png" which
  will usually make no sense to a reader.

So, when you design your tags, make sure that nothing of them remains visible in the result in case they will be ignored.


==Finding tag names

New tag names can be freely chosen, with two exceptions: first, certain tag names are already used (and therefore reserved) by the base system:

@|
tag                                                      | description
\BC<\\B>, \BC<\\C>, \BC<\\HIDE>, \BC<\\I>, \BC<\\IMAGE>, \BC<\\READY>, \BC<\\REF>, \BC<\\SEQ> | Base tags defined by \BC<\PP::Tags::Basic>. By convention, \I<all> converters support these tags. (The list might be incomplete, please look at the latest...
\BC<\\TABLE>, \BC<\\END_TABLE>                           | construct tables
\BC<\\EMBED>, \BC<\\END_EMBED>                           | embed other languages into a \PP source, e.g. to directly include parts in the target format, or to call Perl code which produces \PP on the fly
\BC<\\INCLUDE>                                           | loads additional files which are made part of the source (in various ways)

Second, please have a look at existing converters and \I<their> tags. It might confuse users if one and the same tag name has completely different meanings in different converters. So if your prefered name is already used, please invent another one. ...

All tag names are made of uppercased letters. Underscores and digits are allowed as well. The parser does not recognize a tag if its name does not match these rules.


==Tag option conventions

You are free to invent whatever option names you prefer. Well, almost. There are a few
simple conventions:

* Options \I<presented to a user> (the documented ones ;-)
  should not begin or end with an underscore.

* \I<Special option tags> evaluated by the parser begin
  and end with \I<one> underscore. They are made known
  to the user, and this convention distinguishs them
  from the tags own options. \C<\\REF>'s option
  \C<_cnd_> is an example.

* Informations intended to be used \I<internally only>
  (to pass informations between various tag hooks
  or to the backend) begin and end with \I<two>
  underscores.

That's all to take care of here.


==Writing a tag module

Now when your \GREEN<tags> are designed, you need to define them \I<by a module> in the \BC<PerlPoint::Tags> namespace and make it a subclass of \BC<PerlPoint::Tags>:

  \GREEN<# declare a tag declaration package>
  package PerlPoint::Tags::New;

  \GREEN<# declare base "class">
  use base qw(PerlPoint::Tags);

The base module \BC<\PP::Tags> contains a special \C<import()> method which arranges that the parser learns new tag definitions when a tag module is loaded by \C<use>. \BC<\PP::Tags> is provided as part of the converter framework \BC<\PP::Package>.

It is recommended to have a "top level" tag declaration module for each \PP converter, so there could be a \C<PerlPoint::Tags::\I<HTML>>, a \C<PerlPoint::Tags::\I<Latex>>, \C<PerlPoint::Tags::\I<SDF>>, a \C<PerlPoint::Tags::\I<XML>> and so on. (These...

To complete the intro, configure variable handling:

  \GREEN<# pragmata>
  use strict;
  use vars qw(%tags %sets);

\C<%tags> and \C<%sets> are important variables used by convention. They will be explained in the next sections.


===Tag definition

Now the tags can be declared really.

Tag declarations are expected in a global hash named \BC<%tags>. Each key is the name of a tag, while the tag descriptions are nested structures stored as related values.

  \GREEN<# tag declarations>
  %tags=(
( run in 0.479 second using v1.01-cache-2.11-cpan-71847e10f99 )