#   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#
#   file: lib/Dist/Zilla/Plugin/Manifes/Read/Manual.pod

#pod =encoding UTF-8
#pod
#pod =head1 COPYRIGHT AND LICENSE
#pod
#pod Copyright © 2015 Van de Bugger
#pod
#pod This file is part of perl-Dist-Zilla-Plugin-Manifest-Read.
#pod
#pod perl-Dist-Zilla-Plugin-Manifest-Read is free software: you can redistribute it and/or modify it
#pod under the terms of the GNU General Public License as published by the Free Software Foundation,
#pod either version 3 of the License, or (at your option) any later version.
#pod
#pod perl-Dist-Zilla-Plugin-Manifest-Read is distributed in the hope that it will be useful, but
#pod WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
#pod PARTICULAR PURPOSE. See the GNU General Public License for more details.
#pod
#pod You should have received a copy of the GNU General Public License along with
#pod perl-Dist-Zilla-Plugin-Manifest-Read. If not, see <http://www.gnu.org/licenses/>.
#pod
#pod =cut

# --------------------------------------------------------------------------------------------------

# PODNAME: Dist::Zilla::Plugin::Manifest::Read::Manual
# ABSTRACT: C<Manifest::Read> plugin user manual

#pod =for :this This is C<Manifest::Read> plugin user manual. Read this if you want to
#pod have annotated manifest in your source.
#pod
#pod =for :those If you are going to hack or extend C<Manifest::Read>, read the L<module
#pod documentation|Dist::Zilla::Plugin::Manifest::Read>. General topics like getting source, building, installing, bug
#pod reporting and some others are covered in the F<README>.
#pod
#pod =cut

#pod =head1 SYNOPSIS
#pod
#pod In your F<dist.ini>:
#pod
#pod     # Manifest::Read is a FileGatherer:
#pod     [Manifest::Read]        # Read source MANIFEST,
#pod                             # add files to the distribution.
#pod     …
#pod     [Manifest]              # Write distribution MANIFEST.
#pod     # or [Manifest::Write] to write annotated MANIFEST.
#pod     …
#pod     # Manifest::Read is a FileFinder:
#pod     [Test::EOL]
#pod         # Check eols only in your source files,
#pod         # ignore automatically genenared files.
#pod         finder = Manifest::Read
#pod
#pod In your source F<MANIFEST>:
#pod
#pod     # Files marked with "+" will be included into distribution,
#pod     # files marked with "-" will *not* be included into distribution,
#pod     # but all the files regardless of marker must be present on disk.
#pod     # Entries marked with "/" are directories,
#pod     # they serve for documentation purposes.
#pod
#pod     Changes             + Release history log.
#pod     COPYING             + License.
#pod     MANIFEST            - Exclude *source* manifest.
#pod     dist.ini            - Exclude Dist-Zilla config.
#pod     weaver.ini          - Exclude PodWeaver config.
#pod
#pod     lib/                / Modules to install:
#pod     lib/Foo.pm          + Perl module
#pod     lib/Foo/Manual.pod  + and user manual.
#pod
#pod =head1 DESCRIPTION
#pod
#pod C<Manifest::Read> reads the source manifest. Default manifest name is F<MANIFEST>, but it may be
#pod changed with C<manifest> option.
#pod
#pod Manifest enlists all the source files and directories. C<Manifest::Read> ensures all the manifested
#pod files and directories exist, and adds files marked with C<+> to the distribution. Files marked with
#pod C<-> marker and directories (must be marked with C</>) should exist, but they are I<not> added to
#pod the distribution.
#pod
#pod =head2 File Format
#pod
#pod Manifest is a plain text file in UTF-8 encoding. Empty and whitespace-only lines are ignored.
#pod Comment line should have hash (C<#>) as the first non-whitespace character, comment lines are
#pod ignored too. Other lines must meet the format:
#pod
#pod     ^ \s* filename ( \s+ marker ( \s+ comment )? )? \s* $
#pod
#pod (C<^>, C<\s*>, etc. are Perl regular expressions.)
#pod
#pod =over
#pod
#pod =item I<filename>
#pod
#pod Filename should be Perl single-quoted string, or should not contain whitespaces, start with hash
#pod or apostrophe:
#pod
#pod     lib/Assa.pm
#pod     '/Program Files/Common Files/Dummy File.txt'
#pod     'That\'s all, folks!'
#pod
#pod Within single-quoted string C<\\> denotes backslash, C<\'> denotes apostrophe, all other characters
#pod are treated literally: C<\n> denotes two characters C<\> and C<n>, I<not> newline (i. e. regular
#pod Perl rules work).
#pod
#pod =item I<marker>
#pod
#pod Marker should be either plus (C<+>) or minus (C<->) sign, or slash (C</>). Plus sign is also used
#pod as default marker if no marker is explicitly specified.
#pod
#pod =item I<comment>
#pod
#pod Comment is arbitrary text.
#pod
#pod =back
#pod
#pod =option manifest
#pod
#pod Name of manifest file to read. Default value is F<MANIFEST>.
#pod
#pod The option may be used if you want to differentiate source and distribution manifest, e. g.:
#pod
#pod     [Manifest::Read]
#pod         manifest = Manifest.lst
#pod     [Manifest::Write]
#pod
#pod In such a case the source manifest has name F<Manifest.lst>, while distribution manifest has
#pod default name F<MANIFEST>.
#pod
#pod =head1 SEE ALSO
#pod
#pod =for :list
#pod = L<Dist::Zilla>
#pod = L<Dist::Zilla::Plugin::GatherDir>
#pod = L<Dist::Zilla::Plugin::GatherFromManifest>
#pod
#pod =cut

#pod =pod
#pod
#pod =encoding UTF-8
#pod
#pod =head1 WHAT?
#pod
#pod C<Dist-Zilla-Plugin-Manifest-Read> is a C<Dist::Zilla> plugin. It reads F<MANIFEST> file, checks existence of all
#pod listed files and directories, and adds marked files to the distribution. C<Dist-Zilla-Plugin-Manifest-Read> also does
#pod C<FileFinder> role, providing list of added files for latter use.
#pod
#pod =cut
#pod =pod
#pod
#pod =encoding UTF-8
#pod
#pod =head1 WHY?
#pod
#pod C<Dist::Zilla> advertises using C<GatherDir> plugin to populate the distribution. However,
#pod C<GatherDir> has disadvantage: it grabs really all the files from the source directory, including
#pod files which are not meant to be added to distribution, like previously built distribution tarball.
#pod You have to use either C<GatherDir> parameters or dedicated plugins (e. g. C<PruneCruft>) to
#pod exclude unwanted files from distribution. However, risk to grab unwanted files remains.
#pod
#pod There is another (better to my taste) approach: grab only files explicitly listed in F<MANIFEST>
#pod file. This is implemented by nice C<GatherFromManifest> plugin.
#pod
#pod However I want a bit more. I also want to specify (and document) files which should not be included
#pod into distribution, but expected to be in the source tree, and directories, for example:
#pod
#pod     Changes         + Release history log.
#pod     COPYING         + License.
#pod     README          - Source documentation.
#pod     TODO            - Plans and ideas.
#pod     VERSION         +
#pod
#pod     lib/            / Modules to install.
#pod     lib/Assa.pm     + The primary module.
#pod
#pod     t/              / Tests.
#pod     t/basic.t       +
#pod     t/advanced.t    +
#pod
#pod =cut


# end of file #

__END__

=pod

=encoding UTF-8

=head1 NAME

Dist::Zilla::Plugin::Manifest::Read::Manual - C<Manifest::Read> plugin user manual

=head1 VERSION

Version v0.3.1, released on 2015-09-23 11:45 UTC.

=head1 WHAT?

C<Dist-Zilla-Plugin-Manifest-Read> is a C<Dist::Zilla> plugin. It reads F<MANIFEST> file, checks existence of all
listed files and directories, and adds marked files to the distribution. C<Dist-Zilla-Plugin-Manifest-Read> also does
C<FileFinder> role, providing list of added files for latter use.

This is C<Manifest::Read> plugin user manual. Read this if you want to
have annotated manifest in your source.

If you are going to hack or extend C<Manifest::Read>, read the L<module
documentation|Dist::Zilla::Plugin::Manifest::Read>. General topics like getting source, building, installing, bug
reporting and some others are covered in the F<README>.

=head1 SYNOPSIS

In your F<dist.ini>:

    # Manifest::Read is a FileGatherer:
    [Manifest::Read]        # Read source MANIFEST,
                            # add files to the distribution.
    …
    [Manifest]              # Write distribution MANIFEST.
    # or [Manifest::Write] to write annotated MANIFEST.
    …
    # Manifest::Read is a FileFinder:
    [Test::EOL]
        # Check eols only in your source files,
        # ignore automatically genenared files.
        finder = Manifest::Read

In your source F<MANIFEST>:

    # Files marked with "+" will be included into distribution,
    # files marked with "-" will *not* be included into distribution,
    # but all the files regardless of marker must be present on disk.
    # Entries marked with "/" are directories,
    # they serve for documentation purposes.

    Changes             + Release history log.
    COPYING             + License.
    MANIFEST            - Exclude *source* manifest.
    dist.ini            - Exclude Dist-Zilla config.
    weaver.ini          - Exclude PodWeaver config.

    lib/                / Modules to install:
    lib/Foo.pm          + Perl module
    lib/Foo/Manual.pod  + and user manual.

=head1 DESCRIPTION

C<Manifest::Read> reads the source manifest. Default manifest name is F<MANIFEST>, but it may be
changed with C<manifest> option.

Manifest enlists all the source files and directories. C<Manifest::Read> ensures all the manifested
files and directories exist, and adds files marked with C<+> to the distribution. Files marked with
C<-> marker and directories (must be marked with C</>) should exist, but they are I<not> added to
the distribution.

=head2 File Format

Manifest is a plain text file in UTF-8 encoding. Empty and whitespace-only lines are ignored.
Comment line should have hash (C<#>) as the first non-whitespace character, comment lines are
ignored too. Other lines must meet the format:

    ^ \s* filename ( \s+ marker ( \s+ comment )? )? \s* $

(C<^>, C<\s*>, etc. are Perl regular expressions.)

=over

=item I<filename>

Filename should be Perl single-quoted string, or should not contain whitespaces, start with hash
or apostrophe:

    lib/Assa.pm
    '/Program Files/Common Files/Dummy File.txt'
    'That\'s all, folks!'

Within single-quoted string C<\\> denotes backslash, C<\'> denotes apostrophe, all other characters
are treated literally: C<\n> denotes two characters C<\> and C<n>, I<not> newline (i. e. regular
Perl rules work).

=item I<marker>

Marker should be either plus (C<+>) or minus (C<->) sign, or slash (C</>). Plus sign is also used
as default marker if no marker is explicitly specified.

=item I<comment>

Comment is arbitrary text.

=back

=head1 OPTIONS

=head2 manifest

Name of manifest file to read. Default value is F<MANIFEST>.

The option may be used if you want to differentiate source and distribution manifest, e. g.:

    [Manifest::Read]
        manifest = Manifest.lst
    [Manifest::Write]

In such a case the source manifest has name F<Manifest.lst>, while distribution manifest has
default name F<MANIFEST>.

=head1 WHY?

C<Dist::Zilla> advertises using C<GatherDir> plugin to populate the distribution. However,
C<GatherDir> has disadvantage: it grabs really all the files from the source directory, including
files which are not meant to be added to distribution, like previously built distribution tarball.
You have to use either C<GatherDir> parameters or dedicated plugins (e. g. C<PruneCruft>) to
exclude unwanted files from distribution. However, risk to grab unwanted files remains.

There is another (better to my taste) approach: grab only files explicitly listed in F<MANIFEST>
file. This is implemented by nice C<GatherFromManifest> plugin.

However I want a bit more. I also want to specify (and document) files which should not be included
into distribution, but expected to be in the source tree, and directories, for example:

    Changes         + Release history log.
    COPYING         + License.
    README          - Source documentation.
    TODO            - Plans and ideas.
    VERSION         +

    lib/            / Modules to install.
    lib/Assa.pm     + The primary module.

    t/              / Tests.
    t/basic.t       +
    t/advanced.t    +

=head1 SEE ALSO

=over 4

=item L<Dist::Zilla>

=item L<Dist::Zilla::Plugin::GatherDir>

=item L<Dist::Zilla::Plugin::GatherFromManifest>

=back

=head1 AUTHOR

Van de Bugger <van.de.bugger@gmail.com>

=head1 COPYRIGHT AND LICENSE

Copyright © 2015 Van de Bugger

This file is part of perl-Dist-Zilla-Plugin-Manifest-Read.

perl-Dist-Zilla-Plugin-Manifest-Read is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free Software Foundation,
either version 3 of the License, or (at your option) any later version.

perl-Dist-Zilla-Plugin-Manifest-Read is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
perl-Dist-Zilla-Plugin-Manifest-Read. If not, see <http://www.gnu.org/licenses/>.

=cut
