PerlPoint-Package
view release on metacpan or search on metacpan
systems can be used in parallel by just switching the template engine. A
general template layer is provided.
* \I<All> generators can use styles.
* General style format with parts for configuration, templates, docs and screenshots.
* Subclasses can be defined even in a style, so a style can come with its
own formatters and template systems if necessary.
* Most of the docstreaming and index work is now done a central place, so
all generators can use it and do not have to deal with it themselves.
* \I<The "old" approach is still available and supported>, and existing converters
will continue to run, as the old part of the framework is the base of the new part.
The new generator part just adds an additional level of abstraction, making it easier
to focus on the target format and layout.
===New SDF generator
* Avoiding more backslashes in paragraphs starting with an SDF command.
* New option \BC<-result> to specify an output file.
* Supports document streams by three modes: docstreams can be ignored,
entry points can be made headlines, or \C<pp2sdf> can produce one
document per docstream.
* Provides new conventional converter options \BC<-includelib>,
\BC<-docstreaming> and \BC<-skipstream>.
===Misc
* Slightly improved the \C<README> file.
* \BC<flagSet()> now takes a \I<list> of flag names and checks if at least one
of the flags is set (implicit \I<or> condition). This makes it more handy
to write combined conditions. Thanks to Helmut Steinbach to make me
thinking about this.
demo/pp2sdf view on Meta::CPAN
cache because of a special perl behaviour).
=item -cacheCleanup
PerlPoint parser cache files grow (with every modified version of a source parsed)
because they store expressions for every parsed variant of a paragraph. This is usually
uncritical but you may wish to clean up the cache occasionally. Use this option to
perform the task (or remove the cache file manually).
=item -docstreaming <mode>
sets up the mode the converter handles document streams. Document streams are document
parts belonging to the last recent headline and starting with a document stream entry
point (which is a special paragraph):
=This is the main stream
Bla bla
~A special document stream starts here
demo/pp2sdf view on Meta::CPAN
=The next headline switches back to the main stream
Bla bla
You might think of these streams as "document threads" or "docs in docs".
Now, the transformations of those streams are controled by this option.
B<Mode 0> is the default. It is entered automatically if a document contains
docstreams and C<-docstreaming> is not set.
This mode causes C<pp2sdf> to produce one document per document stream, each of
them containing only the main stream and the parts written of one certain stream.
For example, the first produced document according to the code above would be
equivalent to the following source:
=This is the main stream
Bla bla
demo/pp2sdf view on Meta::CPAN
# resolve option files
argvFile(default=>1, home=>1);
# get options
GetOptions(\%options,
"activeContents", # evaluation of active contents;
"cache", # control the cache;
"cacheCleanup", # cache cleanup;
"docstreaming=s", # document stream handling;
"help", # online help, usage;
"includelib=s@", # library pathes;
"nocopyright", # suppress copyright message;
"noinfo", # suppress runtime informations;
"nowarn", # suppress runtime warnings;
"quiet", # suppress all runtime messages except of error ones;
"sdffile=s", # result file;
"safeOpcode=s@", # permitted opcodes in active contents;
"set=s@", # user settings;
"skipstream=s@", # skip certain document streams;
demo/pp2sdf view on Meta::CPAN
predeclaredVars => {
CONVERTER_NAME => basename($0),
CONVERTER_VERSION => do {no strict 'refs'; ${join('::', __PACKAGE__, 'VERSION')}},
},
libpath => exists $options{includelib} ? $options{includelib} : [],
docstreams2skip => exists $options{skipstream} ? $options{skipstream} : [],
docstreaming => (exists $options{docstreaming} and ($options{docstreaming}==DSTREAM_HEADLINES or $options{docstreaming}==DSTREAM_IGNORE)) ? $options{docstreaming} : DSTREAM_DEFAULT,
vispro => 1,
headlineLinks => 1,
cache => (exists $options{cache} ? CACHE_ON : CACHE_OFF)
+ (exists $options{cacheCleanup} ? CACHE_CLEANUP : 0),
display => DISPLAY_ALL
+ (exists $options{noinfo} ? DISPLAY_NOINFO : 0)
+ (exists $options{nowarn} ? DISPLAY_NOWARN : 0),
demo/pp2sdf view on Meta::CPAN
# init several variables
@flags{qw(listlevel sdf html textstart headline)}=(1, 0, 0, 0, 0);
# bind the backend to the stream (to enable access to its data *before* backend invokation)
$backend->bind(\@streamData);
# open result file(s): docstreams to handle?
if (
(
not exists $options{docstreaming}
or $options{docstreaming}==DSTREAM_DEFAULT
)
and $backend->docstreams
)
{
# scopies
my ($c, $d)=(0, 1);
# open a target file for each handle
foreach my $docstream (sort $backend->docstreams)
{
doc/tutorial.pp view on Meta::CPAN
\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
doc/writing-converters-formatters.pp view on Meta::CPAN
===Options declared on this level
The \CX<Generator> module is the base of all generators, so these options are generally
available.
@|
option | arguments | example | description
\BCX<activeContents> | | \C<-activeContents> | enables active contents
\BCX<cache> | | \C<-cache> | activates the cache
\BCX<cacheCleanup> | | \C<-cacheCleanup> | performs a cache cleanup
\BCX<docstreaming> | method code | \C<-docstreaming 1> | configures the document stream handling
\BCX<help> | | \C<-help> | displays online help ("usage")
\BCX<includelib> | directory | \C<-includelib inc> | Adds a directory to the path searched for files to be included via \CX<\\INCLUDE>. Can be used multiply.
\BCX<nocopyright> | | \C<-nocopyright> | suppress copyright message
\BCX<noinfo> | | \C<-noinfo> | suppress runtime informations
\BCX<nowarn> | | \C<-nowarn> | suppress runtime warnings
\BCX<quiet> | | \C<-quiet> | suppress all runtime messages except of errors
\BCX<safeOpcode> | an opcode or "ALL" | \C<-safeOpcode ALL> | specifies permitted opcodes in active contents (see the Opcode manpage for details), can be used multiply
\BCX<set> | a user setting | \C<-set test> | allows user settings which can be evaluated in documents
\BCX<skipstream> | the stream name | \C<-skipstream left> | skip a certain document stream
\BCX<tagset> | the set | \C<-tagset HTML> | adds a tag set to the scripts own tag declarations (making those tags available)
doc/writing-converters-traditional.pp view on Meta::CPAN
===Common options
I personally prefer \BC<Getopt::Long> for option handling. Your preferences may vary, but please provide at least the options specified in this example statement:
\GREEN<# get options>
GetOptions(\%options,
"activeContents", \GREEN<# evaluation of active contents;>
"cache", \GREEN<# control the cache;>
"cacheCleanup", \GREEN<# cache cleanup;>
"docstreaming=s", \GREEN<# document stream handling;>
"help", \GREEN<# online help, usage;>
"includelib=s@", \GREEN<# library pathes;>
"nocopyright", \GREEN<# suppress copyright message;>
"noinfo", \GREEN<# suppress runtime informations;>
"nowarn", \GREEN<# suppress runtime warnings;>
"quiet", \GREEN<# suppress all runtime messages except of error ones;>
"safeOpcode=s@", \GREEN<# permitted opcodes in active contents;>
"set=s@", \GREEN<# user settings;>
"skipstream=s@", \GREEN<# skip certain document streams;>
"tagset=s@", \GREEN<# add a tag set to the scripts own tag declarations;>
"trace:i", \GREEN<# activate trace messages;>
);
:\BC<activeContents>: flags if active contents shall be evaluated or not.
:\BC<cache>: allows user to activate and deactivate the cache.
:\BC<cacheCleanup>: enforces a cleanup of existing cache files.
:\BC<docstreaming>: specifies how document streams shall be handled.
:\BC<help>: displays a usage message, which is usually the complete converter manpage.
The converter is stopped after performing the display task.
:\BC<includelib>: specifies a directory to be scanned for files included via an
\C<\\INCLUDE> tag - think of \C<perl>'s \C<-I> option. Users are
allowed to specify as many directories as necessary, to be investigated
in the specified order. (Note: the environment variable \C<PERLPOINTLIB>
can be used for the same purpose, but \C<-includelib> pathes will be
scanned first.)
doc/writing-converters-traditional.pp view on Meta::CPAN
predeclaredVars => {
CONVERTER_NAME => basename($0),
CONVERTER_VERSION => do {no strict 'refs'; ${join('::', __PACKAGE__, 'VERSION')}},
},
libpath => exists $options{includelib} ? $options{includelib} : [],
docstreams2skip => exists $options{skipstream} ? $options{skipstream} : [],
docstreaming => (exists $options{docstreaming} and ($options{docstreaming}==DSTREAM_HEADLINES or $options{docstreaming}==DSTREAM_IGNORE)) ? $options{docstreaming} : DSTREAM_DEFAULT,
vispro => 1,
cache => (exists $options{cache} ? CACHE_ON : CACHE_OFF)
+ (exists $options{cacheCleanup} ? CACHE_CLEANUP : 0),
display => DISPLAY_ALL
+ (exists $options{noinfo} ? DISPLAY_NOINFO : 0)
+ (exists $options{nowarn} ? DISPLAY_NOWARN : 0),
doc/writing-converters-traditional.pp view on Meta::CPAN
\C<$main::\PP>. The keys \C<targetLanguage> and \C<userSettings> are
provided by convention, but you may add whatever keys you need.
:\BC<libpath>: passes the library pathes a user specified via \C<-includelib>, see above
for details. Please copy this code.
:\BC<docstreams2skip>: passes the names of document streams to skip which are specified via
user option \C<-skipstream>, see above for details. Please copy this
code.
:\BC<docstreaming>: specifies how document streams shall be handled. It is up to you
which fashions of docstream handling your converter will provide.
Nevertheless, two styles are supported directly by the parser (which
makes them available in all converters), so please pass \C<DSTREAM_HEADLINE>
and \C<DSTREAM_IGNORE> directly to the parser if they are specified by a user.
\C<DSTREAM_HEADLINES> transforms stream entry points into headlines,
while \C<DSTREAM_IGNORE> ignores all streams except the "main stream".
In all other cases, please set the value of this parameter to
\C<DSTREAM_DEFAULT>, which makes the parser supply all stream entry points
in the intermediate data so your converter can deal with them itself.
A final hint: for user convenience, your converter could allow to specify
streaming modes by strings instead of by numbers. (And it is recommended
to do so because the internal constants are subject to changes, but the
user interface should be as stable as possible.) So please adapt this
code appropriately.
:\BC<vispro>: if set to a true value, the parser will display runtime informations.
Please copy this code.
:\BC<cache>: used to pass the cache settings. Please copy this code.
:\BC<display>: used to pass the display settings. Please copy this code.
lib/PerlPoint/Generator.pm view on Meta::CPAN
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
# declare options
(
# added options
[
"acceptedFormat=s@", # more accepted formats (embedded or included);
"activeContents", # evaluation of active contents;
"cache", # control the cache;
"cacheCleanup", # cache cleanup;
"dstreaming|docstreaming=s", # document stream handling (allow "docstreaming" for backwards compatibility);
"help", # online help, usage;
"imagedir|image_dir=s", # target image directory (allow "image_dir" for backwards compatibility with pp2html);
"imageref|image_ref=s", # target image directory reference (allow "image_ref" for backwards compatibility with pp2html);
"includelib=s@", # library pathes;
"nocopyright", # suppress copyright message;
"noinfo", # suppress runtime informations;
"nowarn", # suppress runtime warnings;
"prefix|slide_prefix=s", # target file prefix (slide_prefix for pp2html backwards compatibility);
"quiet", # suppress all runtime messages except of error ones;
"reloadStream", # reload stream from -streamBuffer file;
lib/PerlPoint/Generator.pm view on Meta::CPAN
Note: in most cases you can skip this option.
EOO
cacheCleanup => <<EOO,
Cleans up the cache. Mostly invoked automatically. See docs for details.
EOO
dstreaming => <<EOO,
Document stream handling (for backwards compatibility, C<-docstreaming> can still be used).
Takes a numerical flag value as argument.
Example: -dstreaming 2
By default (or when 0 is passed as value), document streams are evaluated as streams. A value
of 1 ignores all docstreams, while a value of 2 treats docstream entry points as headlines.
For details about document streams please see the parser documentation and the tutorial.
Docstreams are "inlined documents" embedded into the main document and can be used in
various ways. We recommend to try them out!
EOO
lib/PerlPoint/Generator.pm view on Meta::CPAN
skipstream => <<EOO,
Implements a document stream filter. The stream specified by the option argument will be
ignored. The option can be used multiply.
Example: -skipstream details
Note: you cannot skip the "main" stream.
Note: to skip document streams I<in general>, use C<-dstreaming 1>.
EOO
streamBuffer => <<EOO,
With this option, the stream produced by the parser will be stored in the specified file.
This is useful to bypass parsing later on with option C<-reloadStream>.
Please note that stream buffering is an "all or nothing" operation. While you can contineously
buffer streams, only the I<complete> last buffered stream can be reloaded. On the other hand,
lib/PerlPoint/Generator.pm view on Meta::CPAN
CONVERTER_NAME => basename($0),
CONVERTER_VERSION => $main::VERSION,
},
libpath => exists $me->{options}{includelib} ? $me->{options}{includelib} : [],
skipcomments => exists $me->{options}{skipcomments},
docstreams2skip => exists $me->{options}{skipstream} ? $me->{options}{skipstream} : [],
docstreaming => (exists $me->{options}{dstreaming} and ($me->{options}{dstreaming}==DSTREAM_HEADLINES or $me->{options}{dstreaming}==DSTREAM_IGNORE)) ? $me->{options}{dstreaming} : DSTREAM_DEFAULT,
nestedTables => $me->{build}{nestedTables},
vispro => 1,
headlineLinks => 1,
cache => (exists $me->{options}{cache} ? CACHE_ON : CACHE_OFF)
+ (exists $me->{options}{cacheCleanup} ? CACHE_CLEANUP : 0),
display => DISPLAY_ALL
lib/PerlPoint/Generator/SDF/Default.pm view on Meta::CPAN
(my __PACKAGE__ $me)=@_;
confess "[BUG] Missing object parameter.\n" unless $me;
confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__);
# don't forget the base class
$me->SUPER::initBackend;
# open result file(s): docstreams to handle?
if (
(
not exists $me->{options}{dstreaming}
or $me->{options}{dstreaming}==DSTREAM_DEFAULT
)
and $me->{backend}->docstreams
)
{
# scopies
my ($c, $d)=(0, 1);
# open a target file for each handle
foreach my $docstream (grep(($_ ne 'main'), sort $me->{backend}->docstreams))
{
lib/PerlPoint/Parser.pm view on Meta::CPAN
# |26.04.2003| JSTENZEL | added "no utf8" to avoid errors under perl 5.8;
# |01.05.2003| JSTENZEL | adding *all* composite anchors for headlines, not only
# | | | for the full path;
# 0.38 |07.06.2002| JSTENZEL | restoring doubled backslashes in filtered paragraphs,
# | | | restoring ">" characters as if they were guarded;
# |04.07.2002| JSTENZEL | simplified several array field access codes;
# | | JSTENZEL | bugfix: empty headlines caused an infinite loop
# | | | when trailing whitespaces should be removed;
# | | JSTENZEL | bugfix: empty headlines caused a failure when headline
# | | | anchors should be stored, skipping them now;
# |20.08.2002| JSTENZEL | improved tag streaming: stream now contains a body hint;
# | | JSTENZEL | bugfix: paragraph filters restored tag bodies even if
# | | | there was no body;
# | | JSTENZEL | old caches need to be updated - adapted compatibility hint;
# |27.08.2002| JSTENZEL | started to use precompiled lexer patterns;
# |31.08.2002| JSTENZEL | \INCLUDE, \EMBED and \TABLE now support the _cnd_ option,
# | | | like tags defined externally;
# |04.12.2002| JSTENZEL | bugfix in pfilter retranslation: backslash reinsertion was
# | | | not performed multiply;
# | | JSTENZEL | pfilter retranslation: backslash reinsertion now suppressed
# | | | in verbatim blocks;
lib/PerlPoint/Parser.pm view on Meta::CPAN
# trace, if necessary
warn "[Trace] $sourceFile, line $_[5][1]: Stream entry point completed.\n" if $flags{trace} & TRACE_PARAGRAPHS;
# deactivate caching
$flags{checksummed}=0;
# reply data as wished
my $streamTitle=join('', @{$_[3][0]});
unless (
$flags{docstreaming}==DSTREAM_IGNORE
or (
$flags{docstreams2skip}
and exists $flags{docstreams2skip}{$streamTitle}
)
)
{
# store stream title (both globally and locally)
$resultStreamRef->[STREAM_DOCSTREAMS]{$streamTitle}=$flags{chapterDocstreams}{$streamTitle}=undef;
# special handling requested?
if ($flags{docstreaming}==DSTREAM_HEADLINES)
{
# make this docstream entry point a headline
# one level below the last real headline level
my %hints=(nr=>++$directiveCounter, shortcut=>'');
[
[
# opener directive (including headline level)
[\%hints, DIRECTIVE_HEADLINE, DIRECTIVE_START, $flags{headlineLevel}+1],
# the stream title becomes the "headline"
$streamTitle,
lib/PerlPoint/Parser.pm view on Meta::CPAN
by default, all document streams are made part of the result, but by this
parameter one can I<exclude> certain streams (all remaining ones will be
streamed as usual).
The list should be supplied by an array reference.
It is suggested to take the values of this parameter from a user option,
which by convention should be named C<-skipstream>.
=item docstreaming
specifies the way the parser handles stream entry points. The value passed
might be either C<DSTREAM_DEFAULT>, C<DSTREAM_IGNORE> or C<DSTREAM_HEADLINES>.
C<DSTREAM_HEADLINES> instructs the parser to transform the entry points
into I<headlines>, one level below the current real headline level. This
is an easy to implement and convenient way of docstream handling seems to
make sense in most target formats.
C<DSTREAM_IGNORE> hides all streams except of the main stream. The effect
is similar to a call with I<docstreams2skip> set for all document streams
in a source.
C<DSTREAM_DEFAULT> treats the entry points as entry points and streams
them as such. This is the default if the parameter is omitted.
Please note that filters applied by I<docstream2skip> work regardless of
the I<docstreaming> configuration which only affects the way the parser
passes docstream data to a backend.
It is recommended to take the value of this parameter from a user option,
which by convention should be named C<-docstreaming>. (A converter can
define various more modes than provided by the parser and implement them
itself, of course. See C<pp2sdf> for a reference implementation.)
=item files
a reference to an array of files to be scanned.
Files are treated as PerlPoint sources except when their name has the
prefix C<IMPORT:>, as in C<IMPORT:podsource.pod>. With this prefix, the
lib/PerlPoint/Parser.pm view on Meta::CPAN
$flags{var2stream}, # 7
$flags{cache}, # 8
$flags{cached}, # 9
$flags{vis}, # 10
$flags{activeBaseData}, # 11
$flags{activeDataInit}, # 12
$flags{nestedTables}, # 13
$flags{headlineLinks}, # 14
$flags{skipcomments}, # 15
$flags{docstreams2skip}, # 16
$flags{docstreaming}, # 17
$flags{criticalSemantics}, # 18
$macroChecksum, # 19
$varChecksum, # 20
$anchors, # 21
)=(
$pars{stream}, # 1
( # 2
exists $pars{safe}
and defined $pars{safe}
) ? ref($pars{safe}) eq 'Safe' ? $pars{safe}
lib/PerlPoint/Parser.pm view on Meta::CPAN
(exists $pars{var2stream} and $pars{var2stream}), # 7
exists $pars{cache} ? $pars{cache} : CACHE_OFF, # 8
0, # 9
exists $pars{vispro} ? $pars{vispro} : 0, # 10
exists $pars{activeBaseData} ? $pars{activeBaseData} : 0, # 11
exists $pars{activeDataInit} ? $pars{activeDataInit} : 0, # 12
exists $pars{nestedTables} ? $pars{nestedTables} : 0, # 13
exists $pars{headlineLinks} ? $pars{headlineLinks} : 0, # 14
(exists $pars{skipcomments} and $pars{skipcomments}), # 15
exists $pars{docstreams2skip} ? {map {($_ => undef)} @{$pars{docstreams2skip}}} : 0, # 16
exists $pars{docstreaming} ? $pars{docstreaming} : DSTREAM_DEFAULT, # 17
exists $pars{criticalSemanticErrors} ? $pars{criticalSemanticErrors} : 0, # 18
0, # 19
0, # 20
PerlPoint::Anchors->new, # 21
);
# prepare stream data structure and appropriate handlers
unless (@$resultStreamRef and $resultStreamRef->[STREAM_IDENT] eq '__PerlPoint_stream__')
{
# empty stream
lib/PerlPoint/Parser.pm view on Meta::CPAN
$shortcutPath[$level]=$ref->[0]{shortcut} ? $ref->[0]{shortcut} : $title;
$levelPath[$level]++;
$pagenumPath[$level]=$index+1; # real page number, no index
my $docstreams=delete($ref->[0]{docstreams});
my $variables=delete($ref->[0]{vars});
push (
@$ref,
$toc->[$index][1],
delete($ref->[0]{shortcut}),
$flags{docstreaming}==DSTREAM_DEFAULT ? [sort keys %$docstreams] : {},
# store headline path data in the streamed token
[
dclone([@headlinePath[1..$level]]),
dclone([@shortcutPath[1..$level]]),
dclone([@levelPath[1..$level]]),
dclone([@pagenumPath[1..$level]]),
$variables,
],
);
ppParser.yp view on Meta::CPAN
# |26.04.2003| JSTENZEL | added "no utf8" to avoid errors under perl 5.8;
# |01.05.2003| JSTENZEL | adding *all* composite anchors for headlines, not only
# | | | for the full path;
# 0.38 |07.06.2002| JSTENZEL | restoring doubled backslashes in filtered paragraphs,
# | | | restoring ">" characters as if they were guarded;
# |04.07.2002| JSTENZEL | simplified several array field access codes;
# | | JSTENZEL | bugfix: empty headlines caused an infinite loop
# | | | when trailing whitespaces should be removed;
# | | JSTENZEL | bugfix: empty headlines caused a failure when headline
# | | | anchors should be stored, skipping them now;
# |20.08.2002| JSTENZEL | improved tag streaming: stream now contains a body hint;
# | | JSTENZEL | bugfix: paragraph filters restored tag bodies even if
# | | | there was no body;
# | | JSTENZEL | old caches need to be updated - adapted compatibility hint;
# |27.08.2002| JSTENZEL | started to use precompiled lexer patterns;
# |31.08.2002| JSTENZEL | \INCLUDE, \EMBED and \TABLE now support the _cnd_ option,
# | | | like tags defined externally;
# |04.12.2002| JSTENZEL | bugfix in pfilter retranslation: backslash reinsertion was
# | | | not performed multiply;
# | | JSTENZEL | pfilter retranslation: backslash reinsertion now suppressed
# | | | in verbatim blocks;
ppParser.yp view on Meta::CPAN
# trace, if necessary
warn "[Trace] $sourceFile, line $_[5][1]: Stream entry point completed.\n" if $flags{trace} & TRACE_PARAGRAPHS;
# deactivate caching
$flags{checksummed}=0;
# reply data as wished
my $streamTitle=join('', @{$_[3][0]});
unless (
$flags{docstreaming}==DSTREAM_IGNORE
or (
$flags{docstreams2skip}
and exists $flags{docstreams2skip}{$streamTitle}
)
)
{
# store stream title (both globally and locally)
$resultStreamRef->[STREAM_DOCSTREAMS]{$streamTitle}=$flags{chapterDocstreams}{$streamTitle}=undef;
# special handling requested?
if ($flags{docstreaming}==DSTREAM_HEADLINES)
{
# make this docstream entry point a headline
# one level below the last real headline level
my %hints=(nr=>++$directiveCounter, shortcut=>'');
[
[
# opener directive (including headline level)
[\%hints, DIRECTIVE_HEADLINE, DIRECTIVE_START, $flags{headlineLevel}+1],
# the stream title becomes the "headline"
$streamTitle,
ppParser.yp view on Meta::CPAN
by default, all document streams are made part of the result, but by this
parameter one can I<exclude> certain streams (all remaining ones will be
streamed as usual).
The list should be supplied by an array reference.
It is suggested to take the values of this parameter from a user option,
which by convention should be named C<-skipstream>.
=item docstreaming
specifies the way the parser handles stream entry points. The value passed
might be either C<DSTREAM_DEFAULT>, C<DSTREAM_IGNORE> or C<DSTREAM_HEADLINES>.
C<DSTREAM_HEADLINES> instructs the parser to transform the entry points
into I<headlines>, one level below the current real headline level. This
is an easy to implement and convenient way of docstream handling seems to
make sense in most target formats.
C<DSTREAM_IGNORE> hides all streams except of the main stream. The effect
is similar to a call with I<docstreams2skip> set for all document streams
in a source.
C<DSTREAM_DEFAULT> treats the entry points as entry points and streams
them as such. This is the default if the parameter is omitted.
Please note that filters applied by I<docstream2skip> work regardless of
the I<docstreaming> configuration which only affects the way the parser
passes docstream data to a backend.
It is recommended to take the value of this parameter from a user option,
which by convention should be named C<-docstreaming>. (A converter can
define various more modes than provided by the parser and implement them
itself, of course. See C<pp2sdf> for a reference implementation.)
=item files
a reference to an array of files to be scanned.
Files are treated as PerlPoint sources except when their name has the
prefix C<IMPORT:>, as in C<IMPORT:podsource.pod>. With this prefix, the
ppParser.yp view on Meta::CPAN
$flags{var2stream}, # 7
$flags{cache}, # 8
$flags{cached}, # 9
$flags{vis}, # 10
$flags{activeBaseData}, # 11
$flags{activeDataInit}, # 12
$flags{nestedTables}, # 13
$flags{headlineLinks}, # 14
$flags{skipcomments}, # 15
$flags{docstreams2skip}, # 16
$flags{docstreaming}, # 17
$flags{criticalSemantics}, # 18
$macroChecksum, # 19
$varChecksum, # 20
$anchors, # 21
)=(
$pars{stream}, # 1
( # 2
exists $pars{safe}
and defined $pars{safe}
) ? ref($pars{safe}) eq 'Safe' ? $pars{safe}
ppParser.yp view on Meta::CPAN
(exists $pars{var2stream} and $pars{var2stream}), # 7
exists $pars{cache} ? $pars{cache} : CACHE_OFF, # 8
0, # 9
exists $pars{vispro} ? $pars{vispro} : 0, # 10
exists $pars{activeBaseData} ? $pars{activeBaseData} : 0, # 11
exists $pars{activeDataInit} ? $pars{activeDataInit} : 0, # 12
exists $pars{nestedTables} ? $pars{nestedTables} : 0, # 13
exists $pars{headlineLinks} ? $pars{headlineLinks} : 0, # 14
(exists $pars{skipcomments} and $pars{skipcomments}), # 15
exists $pars{docstreams2skip} ? {map {($_ => undef)} @{$pars{docstreams2skip}}} : 0, # 16
exists $pars{docstreaming} ? $pars{docstreaming} : DSTREAM_DEFAULT, # 17
exists $pars{criticalSemanticErrors} ? $pars{criticalSemanticErrors} : 0, # 18
0, # 19
0, # 20
PerlPoint::Anchors->new, # 21
);
# prepare stream data structure and appropriate handlers
unless (@$resultStreamRef and $resultStreamRef->[STREAM_IDENT] eq '__PerlPoint_stream__')
{
# empty stream
ppParser.yp view on Meta::CPAN
$shortcutPath[$level]=$ref->[0]{shortcut} ? $ref->[0]{shortcut} : $title;
$levelPath[$level]++;
$pagenumPath[$level]=$index+1; # real page number, no index
my $docstreams=delete($ref->[0]{docstreams});
my $variables=delete($ref->[0]{vars});
push (
@$ref,
$toc->[$index][1],
delete($ref->[0]{shortcut}),
$flags{docstreaming}==DSTREAM_DEFAULT ? [sort keys %$docstreams] : {},
# store headline path data in the streamed token
[
dclone([@headlinePath[1..$level]]),
dclone([@shortcutPath[1..$level]]),
dclone([@levelPath[1..$level]]),
dclone([@pagenumPath[1..$level]]),
$variables,
],
);
t/l0_cache-fill.t view on Meta::CPAN
# = HISTORY SECTION =====================================================================
# ---------------------------------------------------------------------------------------
# version | date | author | changes
# ---------------------------------------------------------------------------------------
# 0.09 |26.12.2004| JSTENZEL | adapted to new headline path data and table hints;
# |28.12.2004| JSTENZEL | adapted to dotted texts;
# |27.02.2005| JSTENZEL | adapted to fixed variable handling, see parser log;
# |01.11.2005| JSTENZEL | each document needs a headline now;
# 0.08 |20.08.2002| JSTENZEL | adapted to extended tag streaming (body hint);
# 0.07 |< 14.04.02| JSTENZEL | blocks got rid of a trailing newline;
# | | JSTENZEL | added paragraph filter tests using new do() strategy;
# | | JSTENZEL | adapted to headline shortcuts;
# | | JSTENZEL | added document stream tests;
# |15.04.2002| JSTENZEL | adapted to chapter docstream hints;
# 0.06 |18.08.2001| JSTENZEL | switched from Test to Test::More;
# |13.10.2001| JSTENZEL | adapted to headline title providing;
# |27.11.2001| JSTENZEL | adapted to additional shift hints in list directives;
# |01.12.2001| JSTENZEL | adapted to TABLEs modified parameter passing
# | | | (which was built in to support retranslations
t/l0_cache-fill.t view on Meta::CPAN
# build parser
my ($parser)=new PerlPoint::Parser;
# and call it
$parser->run(
stream => \@streamData,
files => ['t/cache.pp'],
safe => new Safe,
docstreams2skip => ['The ignored docstream'],
docstreaming => DSTREAM_DEFAULT,
cache => CACHE_ON+CACHE_CLEANUP,
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO,
);
# build a backend
my $backend=new PerlPoint::Backend(
name => 'installation test: cache init',
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO,
t/l0_cache-hits.t view on Meta::CPAN
# = HISTORY SECTION =====================================================================
# ---------------------------------------------------------------------------------------
# version | date | author | changes
# ---------------------------------------------------------------------------------------
# 0.09 |26.12.2004| JSTENZEL | adapted to new headline path data and table hints;
# |28.12.2004| JSTENZEL | adapted to dotted texts;
# |27.02.2005| JSTENZEL | adapted to fixed variable handling, see parser log;
# |01.11.2005| JSTENZEL | each document needs a headline now;
# 0.08 |31.08.2002| JSTENZEL | adapted to extended tag streaming (body hint);
# 0.07 |< 14.04.02| JSTENZEL | blocks got rid of a trailing newline;
# | | JSTENZEL | added paragraph filter tests using new do() strategy;
# | | JSTENZEL | adapted to headline shortcuts;
# | | JSTENZEL | added document stream tests;
# |15.04.2002| JSTENZEL | adapted to chapter docstream hints;
# 0.06 |18.08.2001| JSTENZEL | switched from Test to Test::More;
# |13.10.2001| JSTENZEL | adapted to headline title providing;
# |27.11.2001| JSTENZEL | adapted to additional shift hints in list directives;
# |01.12.2001| JSTENZEL | adapted to TABLEs modified parameter passing
# | | | (which was built in to support retranslations
t/l0_cache-hits.t view on Meta::CPAN
# build parser
my ($parser)=new PerlPoint::Parser;
# and call it
$parser->run(
stream => \@streamData,
files => ['t/cache.pp'],
safe => new Safe,
docstreams2skip => ['The ignored docstream'],
docstreaming => DSTREAM_DEFAULT,
cache => CACHE_ON,
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO,
);
# build a backend
my $backend=new PerlPoint::Backend(
name => 'installation test: cache init',
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO,
t/l0_docstreams1.t view on Meta::CPAN
# build parser
my ($parser)=new PerlPoint::Parser;
# and call it
$parser->run(
stream => \@streamData,
files => ['t/docstreams.pp'],
filter => 'pp|perl|anything',
docstreams2skip => ['The ignored docstream'],
docstreaming => DSTREAM_DEFAULT,
safe => new Safe,
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO+DISPLAY_NOWARN,
);
# build a backend
my $backend=new PerlPoint::Backend(
name => 'installation test: document streams',
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO,
t/l0_docstreams2.t view on Meta::CPAN
# build parser
my ($parser)=new PerlPoint::Parser;
# and call it
$parser->run(
stream => \@streamData,
files => ['t/docstreams.pp'],
filter => 'pp|perl|anything',
docstreams2skip => ['The ignored docstream'],
docstreaming => DSTREAM_HEADLINES,
safe => new Safe,
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO+DISPLAY_NOWARN,
);
# build a backend
my $backend=new PerlPoint::Backend(
name => 'installation test: document streams, entry points transformed into headlines',
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO,
t/l0_docstreams3.t view on Meta::CPAN
# build parser
my ($parser)=new PerlPoint::Parser;
# and call it
$parser->run(
stream => \@streamData,
files => ['t/docstreams.pp'],
filter => 'pp|perl|anything',
docstreams2skip => ['The ignored docstream'],
docstreaming => DSTREAM_IGNORE,
safe => new Safe,
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO+DISPLAY_NOWARN,
);
# build a backend
my $backend=new PerlPoint::Backend(
name => 'installation test: document streams (except for the main stream)',
trace => TRACE_NOTHING,
display => DISPLAY_NOINFO,
t/l0_headlines.t view on Meta::CPAN
# = HISTORY SECTION =====================================================================
# ---------------------------------------------------------------------------------------
# version | date | author | changes
# ---------------------------------------------------------------------------------------
# 0.08 |27.12.2004| JSTENZEL | adapted to new headline path data;
# |27.02.2005| JSTENZEL | adapted to fixed variable handling, see parser log;
# 0.07 |31.08.2002| JSTENZEL | adapted to extended tag streaming (body hint);
# 0.06 |27.09.2001| JSTENZEL | switched to Test::More;
# | | JSTENZEL | tests were really basic, improved;
# | | JSTENZEL | adapted to shortcuts;
# |15.04.2002| JSTENZEL | adapted to chapter docstream hints;
# 0.05 |16.08.2001| JSTENZEL | no need to build a Safe object;
# 0.04 |20.03.2001| JSTENZEL | adapted to tag templates;
# 0.03 |09.12.2000| JSTENZEL | new namespace: "PP" => "PerlPoint";
# 0.02 |05.10.2000| JSTENZEL | parser takes a Safe object now;
# 0.01 |08.04.2000| JSTENZEL | new.
# ---------------------------------------------------------------------------------------
t/l0_macros.t view on Meta::CPAN
# = HISTORY SECTION =====================================================================
# ---------------------------------------------------------------------------------------
# version | date | author | changes
# ---------------------------------------------------------------------------------------
# 0.08 |07.03.2006| JSTENZEL | adapted to removal of dummy tokens;
# 0.07 |31.08.2002| JSTENZEL | adapted to extended tag streaming (body hint);
# |01.11.2005| JSTENZEL | each document needs a headline now;
# 0.06 |16.08.2001| JSTENZEL | no need to build a Safe object;
# |23.11.2001| JSTENZEL | switched to Test::More;
# | | JSTENZEL | added option default tests;
# 0.05 |22.07.2001| JSTENZEL | adapted to perl 5.005;
# 0.04 |20.03.2001| JSTENZEL | adapted to tag templates;
# |24.05.2001| JSTENZEL | adapted to paragraph reformatting: text paragraphs
# | | | no longer contain a final whitespace string;
# |01.06.2001| JSTENZEL | adapted to modified lexing algorithm which takes
# | | | "words" as long as possible;
t/l0_tags.t view on Meta::CPAN
# = HISTORY SECTION =====================================================================
# ---------------------------------------------------------------------------------------
# version | date | author | changes
# ---------------------------------------------------------------------------------------
# 0.13 |27.12.2004| JSTENZEL | adapted to new headline path data, DPOINT_TEXT and new
# | | | \REF options;
# |27.02.2005| JSTENZEL | adapted to fixed variable handling, see parser log;
# |01.11.2005| JSTENZEL | each document needs a headline now;
# 0.12 |31.08.2002| JSTENZEL | adapted to extended tag streaming (body hint);
# 0.11 |< 14.04.02| JSTENZEL | blocks got rid of a trailing newline;
# | | JSTENZEL | adapted to headline shortcuts;
# |15.04.2002| JSTENZEL | adapted to chapter docstream hints;
# 0.10 |16.08.2001| JSTENZEL | no need to build a Safe object;
# |13.10.2001| JSTENZEL | switched to Test::More;
# | | JSTENZEL | added tests to check finish hook interface
# | | | (and parsers anchor management by the way);
# |27.11.2001| JSTENZEL | adapted to additional shift hints in list directives;
# 0.09 |22.07.2001| JSTENZEL | adapted to perl 5.005;
# 0.08 |20.03.2001| JSTENZEL | adapted to tag templates;
t/l0_tags.t view on Meta::CPAN
# |24.05.2001| JSTENZEL | adapted to paragraph reformatting: text paragraphs
# | | | no longer contain a final whitespace string;
# |01.06.2001| JSTENZEL | adapted to modified lexing algorithm which takes
# | | | "words" as long as possible;
# 0.07 |30.01.2001| JSTENZEL | ordered lists now provide the entry level number;
# 0.06 |09.12.2000| JSTENZEL | new namespace: "PP" => "PerlPoint";
# 0.05 |05.10.2000| JSTENZEL | parser takes a Safe object now;
# 0.04 |03.10.2000| JSTENZEL | adapted to new definition list grammar: definition item
# | | | is now made of base elements like tags;
# 0.03 |16.08.2000| JSTENZEL | added a demonstration of string parameters;
# 0.02 |27.05.2000| JSTENZEL | adapted to modified list streaming (leading spaces);
# 0.01 |15.04.2000| JSTENZEL | new.
# ---------------------------------------------------------------------------------------
# PerlPoint test script
# pragmata
use strict;
use lib qw(t);
( run in 0.339 second using v1.01-cache-2.11-cpan-4d50c553e7e )