view release on metacpan or  search on metacpan

doc/tutorial.pp  view on Meta::CPAN

//
// PerlPoint tutorial. An intro for users.
//
// This is the frame file. It might depend on included docs.
//
// Author: (c) J. Stenzel 2003-2005.
//

// document data
$docAuthor=Jochen Stenzel

$docAuthorMail=perl@jochen-stenzel.de

$docDate=2005-04-30

$docVersion=0.02



// macro definitions
+OREF:\REF{name="__n__" type=linked occasion=1}<__body__>

+BCX:\B<\C<\X<__body__>>>

+IX:\I<\X<__body__>>

+CX:\C<\X<__body__>>

+UB:\U<\B<__body__>>

+CPAN:\C<\X<__body__>>

+RED:\F{color=red}<__body__>

+BLUE:\F{color=blue}<__body__>

+GREEN:\F{color=green}<__body__>

+ILLT:\LOCALTOC{type=linked depth=2}

+FNR:\SUP<\F{size="-2"}<\REF{type=linked name="__n__"}>>

+FN:\F{size="-2"}<\SEQ{type=footnotes name="__n__"}: __body__>

+HR:\EMBED{lang=html}<HR/>\END_EMBED


=Start

.\I<Note: this tutorial is still incomplete, so several sections might be empty. Nevertheless,
the basic parts are there and should allow you to start working with PerlPoint. Enjoy!>

// TOC
\ILLT


// intro
==What is PerlPoint?

When it comes to documentation, there are two base approaches: the WYSIWYG concept that allows
to compose things an interactive way, and the description language concept which "describes"
documents in a special format, which finally is transformed into the visual result. Think of
office applications as examples for the first approach, and HTML, XML or LaTeX for the second
one.

For one or the other reason, people prefer one or the other approach. It depends on their needs
(and preferences) which solution suits them most.

PerlPoint is a "descriptive" toolset. To build a document, it is described in a text file in the
PerlPoint format. As with all descriptive approaches, using a text format makes those sources
very portable.

But PerlPoint is portable in a second way, too: as it is written in pure Perl, the toolset runs
on a wide range of platforms. Whereever Perl runs, PerlPoint runs as well.

So well, but what will this toolset produce? Will the \I<results> be portable, too?
- This depends on what you produce, because there is no special PerlPoint output. Instead,
PerlPoint can produce \I<various> formats. So it is \I<flexible> as well. Produce HTML if you want
to publish via Web or make presentations. Produce PDF if you want to make brochures or handouts
or presentations in this format, or if you are in need for a document that cannot be modified.
Produce LaTeX if you want to print in superb quality,
or to integrate your docs in some sort of LaTeX postprocessing. Or choose SDF as your
intermediate format, to go for POD, PostScript or manpages. Or join the XML community. All these
target formats are at hand right now. And if none of them suits your needs, you can write new
converters.

Besides portability and flexibility, PerlPoint is easy to start with. Basically, docs are
very much like simple text documents, divided into paragraphs. We will see this in a minute.
Nobody needs to be a programming expert to begin, people can start quickly. On the other hand,
\I<if> you are in need of more sophisticated solutions, PerlPoint will support you as well
and offer tags, macros, embedded programming, filters, conditions and more.

==Basics of the document format ~ Format basics

Writing a PerlPoint document is simple. Here is a first document:

 =Documents are simple text files

 Writing PerlPoint can be as easy as writing notes
 to a file. Just open a text editor and start.

 Of course there are more sophisticated features.
 But like Perl, PerlPoint allows you to do easy
 things with ease.

doc/tutorial.pp  view on Meta::CPAN

Active Contents includes

* \OREF{n="Conditional parts"}<conditional parts>,

* \OREF{n="Import filters: embed documents written in other formats"}<import filters>,

* \OREF{n="Paragraph filters: preprocess your paragraphs"}<paragraph filters>,

* \OREF{n="Document parts produced on the fly"}<embedded Perl>.


===Conditional parts

Sometimes not all parts of a source should be in included into a document. Think of handouts
which should not go into a presentation, second language versions which do not have to be
included into a document in the first language, solutions of training exersizes or advanced
parts of a course. PerlPoint allows to include and exclude such parts dynamically, depending
on conditions expressed in Perl code.

\REF{name="Active Contents" type=linked} needs to be activated to make conditions work,
otherwise all conditions will be treated as false.

\ILLT

====Source sections

The first type of conditionals manages complete document parts, including as many paragraphs
as necessary. "Including paragraphs" means "complete paragraphs", it is not possible to
make paragraph \I<parts> conditional this way. The reason for this is that this type uses
special paragraphs to mark where the conditional part begins and ends. The prefix of these
paragraphs is a \IX<question mark>.

  bla bla bla

  \RED<?> 0

  Something that is never included.

  \RED<?> 1

  This part is included in any case.

The question mark is followed by a \IX<Perl expression>. If the value of this expression is
\X<true>, well, then PerlPoint continues to read the document. But if the expression returns a
\X<false> value, all subsequent parts will be skipped until either a new condition paragraph
appears or the file is read completely.

So in our example above, \C<0> of course evaluates to a false value, and so the next paragraph
will never be processed. Then a second condition follows, and this time the condition evaluates
to a true value. So, after this paragraph PerlPoint continues processing.

Condition paragraphs are only seen by PerlPoint itself. As they are just controlling translation,
they do not appear in the results (HTML, XML or whatever).

Conditions of course can be more complex. They can be anything that is valid Perl code, but to
get readable sources it is recommended to hide complexity in function calls, like here

   ? \RED<shouldWeIncludeTheFollowing()>

The function can be declared in any other Active Contents part read before. A well working
technique is to use \CX<\\EMBED{lang=perl}> for this. This tag starts a section of embedded
Perl code which is evaulated only if Active Contents is enabled, and with the same rules.
In our current context, one important rule is that \I<all> Active Contents code lives in the same
namespace (\CX<main::> from the codes point of view), so function definitions, package variables
etc. can be shared.

Here is a definition of our "should-we-include-this" function:

~hints

Note that in the embedded Perl area newlines are allowed.

~main

   \\EMBED{lang=perl}

   \GREEN<# declare a function for conditions>
   sub shouldWeIncludeTheFollowing
    {
     1;
    }

   \GREEN<# supply an empty string as PerlPoint
   code to be processed>
   '';

   \\END_EMBED

I confess this is a rather simple function, but I think you get the point. Define whatever
function you need, of your prefered complexity. An effective way to do this is to have a
special \I<file> with \I<all> definitions etc. that should be used later on in conditions, and
to include this file in all the documents that make use of it.

   \GREEN<// include code>
   \\INCLUDE{type=perl file="code.pp" smart=1}

Some functions of general use are provided without any definition. These are ...


====Conditional tags

\ILLT

=====Failing intentionally (empty)

=====Ready before completion (empty)

===Index management (empty)

===Embedding target fragments (empty)

===Teamwork (empty)

===Embedding text files as examples (empty)

===Import filters: embed documents written in other formats (empty) ~ Import filters

====Existing filters

Several filters are provided via CPAN or the project page.

\UB<POD>



\UB<Open Office / OASIS Open Document>



====Writing a filter (empty)

===Paragraph filters: preprocess your paragraphs (empty) ~ Paragraph filters

===Document parts produced on the fly (empty) ~ Embedded Perl

===PerlPoint applications (empty)

==Macro examples

\ILLT

===Footnotes

Footnotes make a document look professional.\FNR{n="Footnotes: handy"}

Here are two macros that implement footnotes in PerlPoint: