Run Time Options

• registers_reset()

  This function resets various run-time registers, used for validations.

  If the runtime is run more than once remember to always run first this function and even better always run it before using the runtime. e.g.:

    DocSet::RunTime::registers_reset();
    my $docset = DocSet::DocSet::HTML->new($config_file);
    $docset->set_dir(abs_root => ".");
    $docset->scan;
    $docset->render;
      

• register

    my @entries = register($register_name, $key, $val);
      

  Push into the register for a given key the supplied value.

  Return an array of the given register's key.

  For example used to track duplicated docset ids with:

      my @entries = DocSet::RunTime::register('unique_docset_id', $id,
                                             $self->{config_file});
      die if @entries > 1;
      

  because if the register returns two value for the same key, someone has already registered that key before. The values in @entries include the config files in this example.

• set_opt(\%args)
• get_opts()

Hosting System Capabilities Testing

• has_storable_module
• can_create_ps
• can_create_pdf

Source Documents Lookup

    dir => {
             # search path for pods, etc. must put more specific paths first!
             search_paths => [qw(
                 foo/bar
                 foo
                 .
             )],
             # what extensions to search for
             search_exts => [qw(pod pm html)],
            },

So for example if the base path is ~/myproject/src, the files with extensions .pod, .pm and .html will be searched in ~/myproject/src/foo/bar, ~/myproject/src/foo and ~/myproject/src.

Notice that you must specify more specific paths first, since for optimization the seen paths are skipped. Therefore in our example the more explicit path foo/bar was listed before the more general foo.

When the POD parser finds a L<> sequence it indentifies the resource part and passes it to the find_src_doc() which looks up for this file in the cache and returns its original (src) location, which can be then easily converted to the final location and optionally adjusting the extension, e.g. when the POD file is converted to HTML.

As a special extension this function automatically assumes that "index.html" will be generated in each directory containing items of an interest. Therefore in find_src_doc() it'll automatically find things like: the guide, even though there was no source index.pod or index.html in first place.

Only the find_src_doc() function is exported by default.

• scan_src_docs($base_path, \@search_paths, \@search_exts);
• find_src_doc($resource_rel_path);

  returns "undef" if nothing was found. See the description above.

Rendering Object Singleton

Notice that this is all possible in the program which is not threaded, or/and only one rendering process exists at any given time from its start to its end.

All three methods are exported by default.

• set_render_obj($obj)

  Sets the current rendering object.

  You cannot set a new rendering object before the previous one is unset. This is in order to make sure that one document won't use by mistake a rendering object of another document. So when the rendering is done remember to call the unset_render_obj() function.

• unset_render_obj()

  Unsets the currently set rendering object.

• get_render_obj()

  Retrieves the currently set rendering object or complains aloud if it cannot find one.