perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/lib/DocSet/Source POD.pm
Date Mon, 19 Aug 2002 06:56:44 GMT
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


Mime
View raw message