view release on metacpan or  search on metacpan

lib/DocSet/Config.pm  view on Meta::CPAN

     },

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 I<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'],


=head2 Hidden Objects


I<docsets> and I<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 I<docsets> and I<chapters> into a special attribute I<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 I<docsets> and I<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 I<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 (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
files must be copied without any modifications, like files including
pure code, archives, etc. There are two attributes to handle this:

=over

=item * copy_glob

Accepts a reference to an array of files and directories to copy. The
items of the array are run through glob(), therefore wild characters