You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2002/08/19 08:56:44 UTC
cvs commit: modperl-docs/lib/DocSet/Source POD.pm
stas 2002/08/18 23:56:44
Modified: lib DocSet.pm
lib/DocSet Config.pm DocSet.pm RunTime.pm
lib/DocSet/Source POD.pm
Log:
sync with DocSet 0.14
Revision Changes Path
1.7 +66 -29 modperl-docs/lib/DocSet.pm
Index: DocSet.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet.pm,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- DocSet.pm 14 May 2002 05:24:57 -0000 1.6
+++ DocSet.pm 19 Aug 2002 06:56:44 -0000 1.7
@@ -8,7 +8,7 @@
=head1 SYNOPSIS
- pod2hpp [options] base_full_path relative_to_base_configuration_file_location
+ docset_build [options] base_full_path relative_to_base_config_file_location
Options:
@@ -80,63 +80,94 @@
=item 1
-META: not ported yet!
-
If you turn the slides mode on, it automatically turns the C<-i> (C<*>
-preprocessing) mode and does a page break before each =head tag.
+bullets preprocessing) mode and does a page break before each =head
+tag.
+
+=back
+
+=head2 Examples
+
+The package includes two fully working examples in the I<examples/>
+directory.
+
+=over
+
+=item site
+
+This example demonstrates a shrinked version of perl.apache.org (which
+is genrated entirely by DocSet), with many docs removed or reduced to
+the mininumum. There are still quite a lot of documents left so you
+can see the big picture. Read I<examples/site/README> for more
+information.
+
+=item presentation
+
+This example demonstrates how to build presentations handouts and
+slides using DocSet. Read I<examples/presentation/README> for more
+information.
=back
=head2 Look-n-Feel Customization
You can customise the look and feel of the ouput by adjusting the
-templates in the directory I<example/tmpl/custom>.
+templates in the directory I<examples/site/tmpl/custom>.
You can change look and feel of the PS (PDF) versions by modifying
-I<example/conf/html2ps.conf>. Be careful that if your documentation
-that you want to put in one PS or PDF file is very big and you tell
-html2ps to put the TOC at the beginning you will need lots of memory
-because it won't write a single byte to the disk before it gets all
-the HTML markup converted to PS.
+I<examples/site/conf/html2ps.conf>. Be careful that if your
+documentation that you want to put in one PS or PDF file is very big
+and you tell html2ps to put the TOC at the beginning you will need
+lots of memory because it won't write a single byte to the disk before
+it gets all the HTML markup converted to PS.
=head1 CONFIGURATION
All you have to prepare is a single config file that you then pass as
-an argument to C<pod2hpp>:
+an argument to C<docset_build>:
- pod2hpp [options] /abs/project/root/path /full/path/to/config/file
+ % docset_build [options] base_full_path relative_to_base_config_file_location
Every directory in the source tree may have a configuration file,
which designates a docset's root. See the I<config> files for
-examples. Usually the file in the root (I<example/src>) sets
+examples. Usually the file in the root (I<examples/site/src>) sets
operational directories and other arguments, which you don't have to
-repeat in sub-docsets. Modify these files to suit your documentation
-project layout.
+repeat in sub-docsets. You want to redefine the build attributes in
+nested docsets if you want to override certain configuration
+attributes. Modify these files to suit your documentation project
+layout.
+
+Note that the smart I<examples/site/bin/build> script automatically
+locates your project's directory, so you can move your project around
+filesystem without changing anything. So you really build with:
-Note that I<example/bin/build> script automatically locates your
-project's directory, so you can move your project around filesystem
-without changing anything.
+ % bin/build [options]
-I<example/README> explains the layout of the directories.
+I<examples/site/README> explains the layout of the directories.
C<DocSet::Config> manpage explains the layout of the configuration
file.
+=head1 Extending
+
+Read the other manpages for more information about how to extend
+Docset.
+
=head1 PREREQUISITES
-All these are not required if all you want is to generate only the
-html version.
+The following are the optional prerequisites:
=over 4
=item * ps2pdf
-Needed to generate the PDF version
+Needed to generate the PDF version.
=item * Storable
-Perl module available from CPAN (http://cpan.org/)
+Available from CPAN (http://cpan.org/) and is a part of the core Perl
+distribution of the Perl 5.8.0 and higher.
Allows source modification control, so if you modify only one file you
will not have to rebuild everything to get the updated HTML/PS/PDF
@@ -146,26 +177,32 @@
=head1 SUPPORT
-Notice that this tool relies on two tools (ps2pdf and html2ps) which I
-don't support. So if you have any problem first make sure that it's
-not a problem of these tools.
+Notice that this tool relies on two tools (C<ps2pdf> and C<html2ps>)
+which I don't support, since I didn't write them. So if you have any
+problem first make sure that it's not a problem of these tools.
Note that while C<html2ps> is included in this distribution, it's
written in the old style Perl, so if you have patches send them along,
-but I won't try to fix/modify this code otherwise. I didn't write this
-utility.
+but I won't try to fix/modify this code otherwise. For more info see:
+http://www.tdb.uu.se/~jan/html2ps.html
=head1 BUGS
Huh? Probably many...
+=head1 QUESTIONS
+
+Questions can be asked at the template-docset mailing list. For
+mailing list archives and subscription information please see:
+http://template-toolkit.org/mailman/listinfo/template-docset
+
=head1 AUTHORS
Stas Bekman E<lt>stas (at) stason.orgE<gt>
=head1 SEE ALSO
-perl(1), Pod::HTML(3), html2ps(1), ps2pod(1), Storable(3)
+perl(1), Pod::POM(3), Pod::HTML(3), html2ps(1), ps2pod(1), Storable(3)
=head1 COPYRIGHT
1.10 +90 -18 modperl-docs/lib/DocSet/Config.pm
Index: Config.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/Config.pm,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- Config.pm 29 Jun 2002 19:13:49 -0000 1.9
+++ Config.pm 19 Aug 2002 06:56:44 -0000 1.10
@@ -20,19 +20,19 @@
my %conv_class = (
'text/pod' => {
- 'text/html' => 'DocSet::Doc::POD2HTML',
- 'text/htmlps' => 'DocSet::Doc::POD2HTMLPS',
- 'text/ps' => 'DocSet::Doc::POD2PS',
- },
+ 'text/html' => 'DocSet::Doc::POD2HTML',
+ 'text/htmlps' => 'DocSet::Doc::POD2HTMLPS',
+ 'text/ps' => 'DocSet::Doc::POD2PS',
+ },
'text/html' => {
- 'text/html' => 'DocSet::Doc::HTML2HTML',
- 'text/htmlps' => 'DocSet::Doc::HTML2HTMLPS',
- 'text/ps' => 'DocSet::Doc::HTML2PS',
- },
+ 'text/html' => 'DocSet::Doc::HTML2HTML',
+ 'text/htmlps' => 'DocSet::Doc::HTML2HTMLPS',
+ 'text/ps' => 'DocSet::Doc::HTML2PS',
+ },
'text/plain' => {
- 'text/html' => 'DocSet::Doc::Text2HTML',
- 'text/pdf' => 'DocSet::Doc::Text2PDF',
- },
+ 'text/html' => 'DocSet::Doc::Text2HTML',
+ 'text/pdf' => 'DocSet::Doc::Text2PDF',
+ },
);
sub ext2mime {
@@ -54,12 +54,13 @@
my %node_attr = map {$_ => 1} qw(chapters docsets links sitemap);
my %hidden_attr = map {$_ => 1} qw(chapters docsets);
-# the rest of the valid attributes in addition to 'hidden', 'changes'
+# the rest of the valid attributes in addition to 'hidden', 'changes',
# and %node_attr
my %other_attr = map {$_ => 1} qw(id stitle title abstract body
- copy_glob copy_skip dir file);
+ options copy_glob copy_skip dir
+ file);
sub read_config {
- my($self, $config_file) = @_;
+ my($self, $config_file, $parent_o) = @_;
die "Configuration file is not specified" unless defined $config_file;
$self->{config_file} = $config_file;
@@ -67,6 +68,8 @@
my $package = path2package($config_file);
$self->{package} = $package;
+ $parent_o->croak("can't read $config_file: $!")
+ unless -r $config_file;
my $content;
read_file($config_file, \$content);
@@ -142,6 +145,15 @@
$self->croak("Either 'title' or 'stitle' must appear in $config_file")
unless $self->{title};
+
+ # XXX: some options expansion logic, consider refactoring with
+ # similar logic in docset_build
+ # XXX: also this logic should probably go directly to
+ # DocSet::Source::POD, which is the only place it's used.
+ if ($self->{options}{slides_mode}) {
+ $self->{options}{podify_items} = 1;
+ }
+
# merge_config will adjust this value, for nested docsets
# so this value is relevant only for the real top parent node
$self->{dir}{abs_doc_root} = '.';
@@ -175,10 +187,15 @@
$self->{file}{$k} = $v unless $files->{$k};
}
- # inherit 'dir' attributes if not set in the child
+ # inherit the 'dir' attributes if not set in the child
my $dirs = $self->{dir} || {};
while ( my($k, $v) = each %{ $parent_o->{dir}||{} }) {
- $self->{dir}{$k} = $v unless $dirs->{$k};
+ $self->{dir}{$k} = $v unless exists $dirs->{$k};
+ }
+
+ # inherit/override the 'options' attr unless explicitly set
+ while ( my($k, $v) = each %{ $parent_o->{options}||{} }) {
+ $self->{options}{$k} = $v unless exists $self->{options}{$k};
}
# a chapter object won't set this one
@@ -207,6 +224,16 @@
}
+# merge the global run-time options with object scoped options by a
+# simple OR, so if any of the sides sets an option to 1, this method
+# will return 1 otherwise 0
+sub options {
+ my($self, $option) = @_;
+ $option ||= '';
+ return ($self->{options}{$option} || DocSet::RunTime::get_opts($option))
+ ? 1 : 0;
+}
+
# this sub controls the docset's 'modified' attribute which specifies
# whether the docset is in a "dirty" state and need to be rebuilt or
# not.
@@ -502,7 +529,9 @@
$self->read_config($config_file);
$self->merge_config($src_rel_dir);
$self->check_duplicated_docset_ids();
-
+
+ $self->options('slides_mode');
+
$self->files_to_scan_copy();
my @files = $self->files_to_copy(files_to_copy);
my @files = $self->expand_dir();
@@ -549,6 +578,8 @@
=item * merge_config
+=item * options
+
=item * files_to_copy
=item * expand_dir
@@ -885,6 +916,45 @@
perfect page with all the proper navigation widgets (I<menu>, etc) in
it.
+=head2 Options
+
+Sometimes you want different docsets to be run under different command
+line options. This is impossible to accomplish from the command line,
+therefore the options that are different from the default can be set
+inside the I<config.cfg> files. For example if we have a project which
+includes two docsets: one to be rendered as slides and the other as
+handouts. Since the slides mode is off by default, all we need to do
+is to add:
+
+ options => {
+ slides_mode => 1,
+ },
+
+in the I<config.cfg> file of that docset. Now when the whole project
+is built without specifying the slides mode on the command line, this
+docset and its sub-docsets will be built using the slides mode. Of
+course sub-sets can override their parent's setting, for example in
+our example by saying:
+
+ options => {
+ slides_mode => 0,
+ },
+
+Note that merging of the global (command line options) and local
+(docset specific options) is done using the OR operator, meaning that
+if either of the two or both set an option, it's set. Otherwise it's
+not set. This works in that way, because the command line options only
+turn options on, they don't turn them off.
+
+Therefore with our example, if the slides mode will be turned on the
+command line, the whole project will be built in the slides mode. So
+essentially the command line options override the local options.
+
+META: currently the merging happens only in C<DocSet::Source::POD>,
+other places only check the global command line options. This can be
+adjusted as needed, without breaking anything. To find out the list of
+options see C<%options> in I<bin/docset_build>.
+
=head2 Copy unmodified
Usually the generated UI includes images, CSS files and of course some
@@ -957,7 +1027,9 @@
any of I<top> and I<bot> sub-attributes are optional. If these source
docs are for example in HTML, they have to be written in a proper
-HTML, so the parser will be able to extract the body.
+HTML, so the parser will be able to extract the body. Of course these
+can be POD or other formats as well. But all is taken from these files
+are their bodies, so the title and other meta-data are ignored.
=back
1.14 +1 -1 modperl-docs/lib/DocSet/DocSet.pm
Index: DocSet.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/DocSet.pm,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- DocSet.pm 29 Jun 2002 19:13:49 -0000 1.13
+++ DocSet.pm 19 Aug 2002 06:56:44 -0000 1.14
@@ -24,7 +24,7 @@
sub init {
my($self, $config_file, $parent_o, $src_rel_dir) = @_;
- $self->read_config($config_file);
+ $self->read_config($config_file, $parent_o);
# are we inside a super docset?
if ($parent_o and ref($parent_o)) {
1.11 +2 -7 modperl-docs/lib/DocSet/RunTime.pm
Index: RunTime.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/RunTime.pm,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- RunTime.pm 29 Jun 2002 19:13:49 -0000 1.10
+++ RunTime.pm 19 Aug 2002 06:56:44 -0000 1.11
@@ -23,12 +23,6 @@
my %exts = ();
my $render_obj;
-# = (
-# 'docs/2.0' => {
-# 'devel/core_explained/core_explained.pod' => 1,
-# },
-# );
-
sub registers_reset {
%registers = ();
}
@@ -107,7 +101,8 @@
my %seen;
for my $rel_path (@search_paths) {
my $full_base_path = catdir $base, $rel_path;
- die "$full_base_path is not a dir" unless -d $full_base_path;
+ die "'search_paths' attr: $full_base_path is not a dir"
+ unless -d $full_base_path;
my @seen_pattern = map {"^".quotemeta($_)} keys %seen;
my $rsub_skip_seen = build_matchmany_sub(\@seen_pattern);
1.7 +41 -3 modperl-docs/lib/DocSet/Source/POD.pm
Index: POD.pm
===================================================================
RCS file: /home/cvs/modperl-docs/lib/DocSet/Source/POD.pm,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- POD.pm 10 Jun 2002 17:57:57 -0000 1.6
+++ POD.pm 19 Aug 2002 06:56:44 -0000 1.7
@@ -128,8 +128,6 @@
# already parsed
return if exists $self->{parsed_tree} && $self->{parsed_tree};
- $self->podify_items() if get_opts('podify_items');
-
# print ${ $self->{content} };
use Pod::POM;
@@ -153,7 +151,9 @@
$self->extract_pod;
- $self->podify_items if get_opts('podify_items');
+ $self->head2page_breaks() if $self->{docset}->options('slides_mode');
+
+ $self->podify_items() if $self->{docset}->options('podify_items');
}
sub extract_pod {
@@ -223,6 +223,34 @@
}
+
+# add a page break for =headX in slides mode
+sub head2page_breaks {
+ my($self) = @_;
+
+ # we want the source in paragraphs
+ my @content = split /\n\n/, ${ $self->{content} };
+
+ my $count = 0;
+ my @paras = ();
+ foreach (@content) {
+ # add a page break starting from the third head (since the
+ # first is removed anyway, and we don't want to start a new
+ # page on the very first page)
+ if (/^=head/) {
+ $count++;
+ if ($count > 2) {
+ push @paras, qq{=for html <?page-break>};
+ }
+ }
+ push @paras, $_;
+ }
+
+ my $content = join "\n\n", @paras;
+ $self->{content} = \$content;
+
+}
+
1;
__END__
@@ -329,6 +357,16 @@
where the second mark is which tells whether to use a ball bullet or a
numbered item.
+=item head2page_breaks
+
+in the I<slides_mode> we want each =headX to start a new slide, so
+this mode inserts the page-breaks:
+
+ =for html <?page-break>
+
+starting from the second header (well actually from the third in the
+raw POD, because the first one (NAME) gets stripped before it's seen
+by the rendering engine.
=back
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org