#   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#
#   file: lib/Dist/Zilla/Plugin/Manifes/Read/Manual.pod
#
#   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/>.
#
#   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

# 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 source manifest.
#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 =for test_synopsis BEGIN { die "SKIP: Not Perl code.\n" };
#pod
#pod =head1 SYNOPSIS
#pod
#pod In your F<dist.ini>:
#pod
#pod     ...
#pod     ; Add files listed in source MANIFEST to the distribution
#pod     ;     (Manifest::Read does FileGatherer role):
#pod     [Manifest::Read]        ; Read *source* MANIFEST
#pod                             ;     and add files to the distribution.
#pod     ...
#pod     [Manifest::Write]       ; Write *distribution* MANIFEST.
#pod         ; or [Manifest]
#pod     ...
#pod     ; Use files listed in source MANIFEST
#pod     ;     (Manifest::Read does FileFinder role):
#pod     [Templates]                     ; Treat as templates
#pod         templates = Manifest::Read  ;     *your* files.
#pod     [Test::EOL]                     ; Check line endings are consistent
#pod         finder = Manifest::Read     ;     in *your* files.
#pod     [Test::NoTabs]                  ; Ensure there are no tabs
#pod         finder = Manifest::Read     ;     in *your* files.
#pod     ...
#pod
#pod In your source F<MANIFEST>:
#pod
#pod     # Files marked with "+" will be added to distribution.
#pod     # Files marked with "-" will *not* be added to distribution.
#pod     # Entries marked with "/" are directories.
#pod     # All the enlisted entities must exist, regardless of mark.
#pod
#pod     lib/                / Modules to install:
#pod     lib/Foo.pm          + Perl module
#pod     lib/Foo/Manual.pod  + and user manual.
#pod
#pod     t/                  / Tests.
#pod     t/basic.t           + Test basic functionality.
#pod     t/extended.t        - Do not include, not ready yet.
#pod
#pod     Changes             + Release history.
#pod     COPYING             + License.
#pod     MANIFEST            - Exclude *source* manifest.
#pod     dist.ini            - Exclude Dist-Zilla config.
#pod     weaver.ini          - Exclude PodWeaver config.
#pod
#pod =head1 DESCRIPTION
#pod
#pod C<Manifest::Read> reads the I<annotated source manifest>. Default manifest name is F<MANIFEST>, but
#pod it may be 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<-> mark and directories marked with C</> should exist, but they are I<not> added to the
#pod 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 match  the following regular expression:
#pod
#pod     ^ \s* filename ( \s+ mark ( \s+ comment )? )? \s* $
#pod
#pod =over
#pod
#pod =item I<filename>
#pod
#pod Filename should be Perl single-quoted string, or should not contain whitespaces. It should not
#pod start with hash or apostrophe. Example of valid filenames:
#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 (these are
#pod regular Perl rules for single-quoted strings).
#pod
#pod =item I<mark>
#pod
#pod Either plus (C<+>) or minus (C<->) sign, or slash (C</>). Plus sign is also used as default mark if
#pod no mark 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 name differently source and distribution manifests, 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 =note Source manifest can enlist itself
#pod
#pod Source manifest can enlist itself but normally it should I<not> be included to distribution:
#pod
#pod     ...
#pod     MANIFEST        - Source manifest, this file.
#pod     ...
#pod
#pod because source and distribution manifests (may) have the same name but they are distinctly
#pod different files with different content. Source manifest enlists source files and itself is a part
#pod of source, while distribution manifest enlists distribution files (including automatically
#pod generated files like F<Build.PL>, F<META.json>, F<META.yml>) and itself is a part of distribution.
#pod Distribution manifest may be a part of source, but usually it is generated by C<Manifest> (or
#pod C<Manifest::Write>) plugin.
#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 = L<Dist::Zilla::Role::FileFinder>
#pod
#pod =head1 COPYRIGHT AND LICENSE
#pod
#pod Copyright (C) 2015 Van de Bugger
#pod
#pod License GPLv3+: The GNU General Public License version 3 or later
#pod <http://www.gnu.org/licenses/gpl-3.0.txt>.
#pod
#pod This is free software: you are free to change and redistribute it. There is
#pod NO WARRANTY, to the extent permitted by law.
#pod
#pod
#pod =cut

#pod =pod
#pod
#pod =encoding UTF-8
#pod
#pod =head1 WHAT?
#pod
#pod C<Dist-Zilla-Plugin-Manifest-Read> (or C<Manifest::Read> for brevity) is a C<Dist::Zilla> plugin. It reads
#pod I<annotated source> manifest, checks existence of all listed files and directories, and adds
#pod selected files to the distribution. C<Manifest::Read> also does C<FileFinder> role, providing the
#pod list of added files for other plugins.
#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 (and directories) which are
#pod part of source, but should not be included to distribution. For example:
#pod
#pod     ex/                     / Examples.
#pod     ex/Assa/                / Very basic example.
#pod     ex/Assa/dist.ini        - dzil config file.
#pod     ex/Assa/dzil.out        - dzil output, included into user manual.
#pod
#pod     lib/                    / Modules to install:
#pod     lib/Assa.pm             + The primary module.
#pod
#pod     t/                      / Tests:
#pod     t/advanced.t            - Not ready yet, do not distribute.
#pod     t/basic.t               + Basic functional test.
#pod
#pod     tools/                  / Build tools:
#pod     tools/run-examples.sh   - Run examples, refresh dzil.out files.
#pod
#pod     Changes                 + Release history.
#pod     COPYING                 + License text.
#pod     README                  - Source documentation.
#pod     TODO                    - Plans and ideas.
#pod     VERSION                 + Version number.
#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.4, released on 2015-10-22 13:20 UTC.

=head1 WHAT?

C<Dist-Zilla-Plugin-Manifest-Read> (or C<Manifest::Read> for brevity) is a C<Dist::Zilla> plugin. It reads
I<annotated source> manifest, checks existence of all listed files and directories, and adds
selected files to the distribution. C<Manifest::Read> also does C<FileFinder> role, providing the
list of added files for other plugins.

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

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>:

    ...
    ; Add files listed in source MANIFEST to the distribution
    ;     (Manifest::Read does FileGatherer role):
    [Manifest::Read]        ; Read *source* MANIFEST
                            ;     and add files to the distribution.
    ...
    [Manifest::Write]       ; Write *distribution* MANIFEST.
        ; or [Manifest]
    ...
    ; Use files listed in source MANIFEST
    ;     (Manifest::Read does FileFinder role):
    [Templates]                     ; Treat as templates
        templates = Manifest::Read  ;     *your* files.
    [Test::EOL]                     ; Check line endings are consistent
        finder = Manifest::Read     ;     in *your* files.
    [Test::NoTabs]                  ; Ensure there are no tabs
        finder = Manifest::Read     ;     in *your* files.
    ...

In your source F<MANIFEST>:

    # Files marked with "+" will be added to distribution.
    # Files marked with "-" will *not* be added to distribution.
    # Entries marked with "/" are directories.
    # All the enlisted entities must exist, regardless of mark.

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

    t/                  / Tests.
    t/basic.t           + Test basic functionality.
    t/extended.t        - Do not include, not ready yet.

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

=head1 DESCRIPTION

C<Manifest::Read> reads the I<annotated 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<-> mark and directories 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 match  the following regular expression:

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

=over

=item I<filename>

Filename should be Perl single-quoted string, or should not contain whitespaces. It should not
start with hash or apostrophe. Example of valid filenames:

    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 (these are
regular Perl rules for single-quoted strings).

=item I<mark>

Either plus (C<+>) or minus (C<->) sign, or slash (C</>). Plus sign is also used as default mark if
no mark 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 name differently source and distribution manifests, 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 NOTES

=head2 Source manifest can enlist itself

Source manifest can enlist itself but normally it should I<not> be included to distribution:

    ...
    MANIFEST        - Source manifest, this file.
    ...

because source and distribution manifests (may) have the same name but they are distinctly
different files with different content. Source manifest enlists source files and itself is a part
of source, while distribution manifest enlists distribution files (including automatically
generated files like F<Build.PL>, F<META.json>, F<META.yml>) and itself is a part of distribution.
Distribution manifest may be a part of source, but usually it is generated by C<Manifest> (or
C<Manifest::Write>) plugin.

=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 (and directories) which are
part of source, but should not be included to distribution. For example:

    ex/                     / Examples.
    ex/Assa/                / Very basic example.
    ex/Assa/dist.ini        - dzil config file.
    ex/Assa/dzil.out        - dzil output, included into user manual.

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

    t/                      / Tests:
    t/advanced.t            - Not ready yet, do not distribute.
    t/basic.t               + Basic functional test.

    tools/                  / Build tools:
    tools/run-examples.sh   - Run examples, refresh dzil.out files.

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

=for test_synopsis BEGIN { die "SKIP: Not Perl code.\n" };

=head1 SEE ALSO

=over 4

=item L<Dist::Zilla>

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

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

=item L<Dist::Zilla::Role::FileFinder>

=back

=head1 AUTHOR

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

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015 Van de Bugger

License GPLv3+: The GNU General Public License version 3 or later
<http://www.gnu.org/licenses/gpl-3.0.txt>.

This is free software: you are free to change and redistribute it. There is
NO WARRANTY, to the extent permitted by law.

=cut
