Stas Bekman > DocSet-0.19 > DocSet::Config

Download:
DocSet-0.19.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Source  

NAME ^

DocSet::Config - A superclass that handles object's configuration and data

SYNOPSIS ^

  use DocSet::Config ();
  
  my $mime = $self->ext2mime($ext);
  my $class = $self->conv_class($src_mime, $dst_mime);
  
  $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();
  
  $self->set($key => $val);
  $self->set_dir($dir_name => $val);
  $val = $self->get($key);
  $self->get_file($key);
  $self->get_dir($dir_name);

#XXX my @docsets = $self->docsets(); #XXX my @links = $self->links(); #XXX my @chapters = $self->src_chapters(); my @chapters = $self->trg_chapters();

  my $sitemap = $self->sitemap();
  
  $self->cache($cache); 
  my $cache = $self->cache(); 
  
  $package = $self->path2package($path);
  $self->object_store($object);
  my @objects = $self->stored_objects();

DESCRIPTION ^

This objects lays in the base of the DocSet class and provides configuration and internal data storage/retrieval methods.

At the end of this document the generic configuration file is explained.

METHODS

META: to be completed (see SYNOPSIS meanwhile)

CONFIGURATION FILE ^

Each DocSet has its own configuration file.

Structure

Currently the configuration file is a simple perl script that is expected to declare an array @c with all the docset properties in it. Later on more configuration formats will be supported.

We use the @c array because some of the configuration attributes may be repeated, so the hash datatype is not suitable here. Otherwise this array looks exactly like a hash:

  key1 => val1,
  key2 => val2,
  ...
  keyN => valN

Of course you can declare any other perl variables and do whatevery you want, but after the config file is run, it should have @c set.

Don't forget to end the file with 1;.

Declare once attributes

The following attributes must be declared at least in the top-level config.cfg file:

Generally you should specify these only in the top-level config file, and only specify these again in sub-level config files, if you want to override things for the sub-docset and its successors.

DocSet must attributes

The following attributes must be declared in every docset configuration:

DocSet Components

Any DocSet components can be repeated as many times as wanted. This allows to mix various types of nodes and still have oredered the way you want. You can have a chapter followed by a docset and followed by a few more chapters and ended with a link.

The value of each component can be either a single item or a reference to an array of items.

This is an example:

     docsets =>  ['docs', 'cool_docset'],
  
     chapters => [
         qw(
            about/about.html
           )
     ],
  
     docsets => [
         qw(
            download
           )
     ],
  
     chapters => 'foo/bar/zed.pod',
  
     changes => 'Changes.pod',
  
     links => [
         {
          id       => 'asf',
          link     => 'http://apache.org/foundation/projects.html',
          title    => 'The ASF Projects',
          abstract => "There many other ASF Projects",
         },
     ],
  
     sitemap => {
         id       => 'sitemap',
         link     => 'sitemap.html',
         title    => "The Site Map",
         abstract => "You reach any document on our site from this sitemap",
     },

Since normally books consist of parts which group chapters by a common theme, we support this feature as well. So the index can now be generated as:

  part I: Installation
  * Starting
  * Installing

  part II: Troubleshooting
  * Debugging
  * Errors
  * ASF
  * Offline Help

This happens only if this feature is used, otherwise a plain flat toc is used: to enable this feature simply splice nodes with declaration of a new group using the group attribute:

  group => 'Installation',
  chapters => [qw(start.pod install.pod)],

  group => 'Troubleshooting',
  chapters => [qw(debug.pod errors.pod)],
  links    => [
         {
          id       => 'asf',
          link     => 'http://apache.org/foundation/projects.html',
          title    => 'The ASF Projects',
          abstract => "There many other ASF Projects",
         },
  ],
  chapters => ['offline_help.pod'],

Hidden Objects

docsets and chapters can be marked as hidden. This means that they will be normally processed but won't be linked from anywhere.

Since the hidden objects cannot belong to any group and it doesn't matter when they are listed in the config file, you simply put one or more docsets and chapters into a special attribute hidden which of course can be repeated many times just like most of the attributes.

For example:

  ...
  chapters => [qw(start.pod install.pod)],
  hidden => {
      chapters => ['offline_help.pod'],
      docsets  => ['hidden_docset'],
  },
  ...

The cool thing is that the hidden docsets and chapters will see all the unhidden objects, so those who know the "secret" URL will be able to navigate back to the non-hidden objects transparently.

This feature could be useful for example to create pages normally not accessed by users. For example if you want to create a page used for the Apache's ErrorDocument handler, you want to mark it hidden, because it shouldn't be linked from anywhere, but once the user hit it (because a non-existing URL has been entered) the user will get a perfect page with all the proper navigation widgets (menu, etc) in it.

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 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 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 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 %options in bin/docset_build.

Copy unmodified

Usually the generated UI includes images, CSS files and of course some files must be copied without any modifications, like files including pure code, archives, etc. There are two attributes to handle this:

Extra Features

If you want in the index file include a special top and bottom sections in addition to the linked list of the docset contents, you can do:

     body => {
         top => 'index_top.html',
         bot => 'index_bot.html',
     },

any of top and 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. 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.

AUTHORS ^

Stas Bekman <stas (at) stason.org>

syntax highlighting: