view release on metacpan or  search on metacpan

lib/App/Pods2Site/Args.pod  view on Meta::CPAN

=head1 NAME

App::Pods2Site::Args

Commandline options and arguments understood for Pods2Site processing

=head1 VERSION

Version 1.003

=head1 SYNOPSIS

 pods2site
    [
        --usage | -?
            |
        --help
            |
        --manual
            |
        --version
    ]
    [ -v | --verbose [ -v ... ] | --quiet]
    [ --workdirectory <path> ]
    [ --bindirectory <location> [ --bindirectory ... ] ]
    [ --libdirectory <location> [ --libdirectory ... ] ]
    [ --group name=<query> [ --group name2=<query> ... ] ]
    [ --css <file> ]
    [ --title <title> ]
    [ --style <name> ]
    { <sitedirectory> || :std }

=head1 OPTIONS AND ARGUMENTS

All options can be abbreviated, as long as they are unambiguous. Option matching is case
sensitive. Forcibly end option parsing using '--'.

=head3 EXPANDING FILES IN ARGUMENT LIST

The command line may at any place contain arguments of the form F<@filename>, and which means that the F<filename>
will be read for arguments to insert in place. This will help if the command line is very long or is just nicely
persisted for reuse.

Further, this will work recursively, i.e. a any resulting argument of the same form, will be read. If the filename
is relative, it's assumed relative to the directory the previous file was in.

The example command line C<pods2site --verbose @myargs> will be expanded by reading the F<myargs> file (in the current
directory, obviously). The F<myargs> file may contain a line of C<@/some/path/to/globalargs>, and assuming that file in
turn contains C<@extraargs>, that file is expected to exist as F</some/path/to/extraargs>.

Each line in such a file will become a single argument using the following rules:

=over

=item * Line continuation

To avoid physical lines in the file to be extremely long, it can be continued on the next
physical (to any length) by ending the line with a backslash (\).

  Example:
    fee \
    fie \
    foo

Will become the argument 'fee fie foo'.

=item * Comments

Any line (after completed line continuation and not counting inital whitespace) having
a '#' as the first character, will be ignored as being a comment.

=item * Trimming

Any beginning and ending whitespace will be trimmed away.

=item * Empty lines

Any empty line will be ignored.
 
=back

=over

=item B<INFORMATION OPTIONS>

lib/App/Pods2Site/Args.pod  view on Meta::CPAN

=item B<Sticky options>

The options below are considered 'sticky options' as they are only allowed when a new site is B<created>.
After the site has been created, the options are saved in the site and reused when an update is made.

Note that this also means that they can't be used when updating a site.

=over

=item B<--title E<lt>titleE<gt>>

The title to use for the page and text in header frame. Defaults to 'Pods2Site'.

=item B<--mainpage E<lt>pagenameE<gt>>

The page to use as the main page (main frame in the framed styles). It defaults to ':std',
which makes the autogenerated 'about' page as the main page. If given, must match to
a normal page name in the searched directories, e.g. a module found in Some/Path/Module.pm
should be referred to as 'Some::Path::Module'.

=item B<--style E<lt>nameE<gt>>

Apart from the pod2html mechanism which is not controlled by this app, a couple of things will be generated
in order to make the pod docs navigatable. At minimum an F<index.html> is generated, but typically also
at least a TOC and possibly other pages. As this can be done in different fashions, this option allows
you to select some different styles of viewing the pod docs.

It uses 'style' names to select different internal implementations. The following are currently available:
 
=over

=item * :std

This special name will use the currently defined default style. At present this is 'basicframes-tree-toc'.

=item * none

This 'style' does nothing; useful if you want to process the site with something external. 

=item * basicframes-simple-toc

This style uses a simple frames layout. The left-hand TOC is implemented as a static indented tree list.

=item * basicframes-tree-toc

This style is very similar to the above, but the TOC is rendered with the HTML5 'details' element
in order to create a simple open/close tree control. May need a newer browser to display correctly.

=back

=item B<--css E<lt>fileE<gt>>

If you want to provide your own CSS file, use '--css'. The file given will be copied to the site
and used as an import in the CSS generated by the system and thus may override anything defined in that.

It will be included as a stylesheet in the generated file, and also by passing the '--css' option to the pod2html command.

Note that different 'styles' may generate different things possible to tweak.  

=item B<--bindirectory E<lt>locationE<gt>>

By default, the code will automatically try to ascertain where the running Perl distro places executable scripts, e.g.
generally in the vendor, site and core 'bin' locations in the tree (ascertained from L<Config> values).

In case you manually want to add to, or manipulate the order of, the locations, you may provide one or more '--bindirectory'
options and they will be searched in the given order. Any locations not existing are silently skipped. 

The 'location' is generally a normal path, but some special values have special meaning:

=over

=item * :none

Since the default locations are automatically searched if no '--bindirectory' option is given, this code is provided to
completely turn off searching any locations for scripts - just give a single invocation of '--bindirectory :none'. 

=item * :path

Search paths in the PATH environment variable in order to find possible scripts with pod.

=item * :std

This will insert the default locations. Useful if you want insert one or more custom paths first, and then add 'all the 
default places'.

=back

=item B<--libdirectory E<lt>locationE<gt>>

This is exactly like '--bindirectory', except for lib locations (e.g. where to find core pods, pragmas and ordinary modules).

Aside from taking regular paths, this also handles some special values:

=over

=item * :none

Since the default locations are automatically searched if no '--libdirectory' option is given, this code is provided to
completely turn off searching any locations for core/pragma/module pods - just give a single invocation of '--libdirectory :none'. 

=item * :std

This will insert the default locations. Useful if you want insert one or more custom paths first, and then add 'all the 
default places'.

=item * :inc

This will insert the default locations, like :std, but will use the @INC list, which means it will also pick up locations
like paths listed in PERL5LIB etc.

=back

=item B<--group E<lt>name[=query]E<gt>>

The pods may be separated into groups. By default a grouping loosely similar to an ActivePerl installation
will be used, e.g. 'Core', 'Scripts', 'Pragmas' and 'Modules'.

Any number of groups can be specified, and the query will be able to use fields to select which pods go where
(see L<Grep::Query> for details of the query language).

It's allowable to have an unnamed group (e.g. E<lt>queryE<gt>) which means matches will not be under any group name
and thus left justified directly in the TOC. It is recommended to only match to document with single level names
e.g. just the 'Foo' document rather than the 'Bar::Foo' document as the latter would produce an effect looking like
a group of 'Bar'.

=over

=item * type

Contains a value of either 'bin', 'lib', for pods found in the bin, lib directories.

Pods found in root or 'pods::' using 'perl' as prefix gets a value of 'corepod'.

=item * name

The package name for the pod.

NOTE: pods::perlxxx will be placed in the root as 'perlxxx'.

=item * path

The full path to the pod file.

=back

Note that the groups are independent, i.e. it's possible to have overlapping groups so if this is not desired,
the queries must implement that (see the default group queries for examples).

A common situation is to add a group with 'favourites', but keep the default grouping. Just place your own group(s)
first and then add a '--group :std' for automatically filling in all the others. For a bit more control, each of the