ASPEER-MakeMaker-Markdown-Pod

 view release on metacpan or  search on metacpan

LICENSE  view on Meta::CPAN

    you changed the files and the date of any change; and

    b) cause the whole of any work that you distribute or publish, that
    in whole or in part contains the Program or any part thereof, either
    with or without modifications, to be licensed at no charge to all
    third parties under the terms of this General Public License (except
    that you may choose to grant warranty protection to some or all
    third parties, at your option).

    c) If the modified program normally reads commands interactively when
    run, you must cause it, when started running for such interactive use
    in the simplest and most usual way, to print or display an
    announcement including an appropriate copyright notice and a notice
    that there is no warranty (or else, saying that you provide a
    warranty) and that users may redistribute the program under these
    conditions, and telling the user how to view a copy of this General
    Public License.

    d) You may charge a fee for the physical act of transferring a
    copy, and you may at your option offer warranty protection in
    exchange for a fee.

LICENSE  view on Meta::CPAN

                     END OF TERMS AND CONDITIONS

        Appendix: How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to humanity, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

  To do so, attach the following notices to the program.  It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) 19yy  <name of author>

    This program 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 1, or (at your option)
    any later version.

LICENSE  view on Meta::CPAN

    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 this program; if not, see <https://www.gnu.org/licenses/>.


Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19xx name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your

README  view on Meta::CPAN


make readme : Builds README from an existing README.md. When neither
README file exists, it first creates a regular README.md from sidecar or
embedded Markdown in the VERSION_FROM file. An existing plain README
without README.md is left unchanged, and no file is created when
VERSION_FROM has no Markdown.

Status output is written to STDERR. Normal output is intentionally
compact:

    markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
    markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod

DOGFOODING

This distribution uses its own sidecar workflow. The important modules
and the public integration classes have adjacent Markdown files:

    lib/ASPEER/MakeMaker/Markdown/Pod.pm.md
    lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm.md
    lib/ASPEER/MakeMaker/Markdown/Pod/Constant.pm.md

README.md  view on Meta::CPAN


`make readme`
: Builds `README` from an existing `README.md`. When neither README file exists,
  it first creates a regular `README.md` from sidecar or embedded Markdown in
  the `VERSION_FROM` file. An existing plain `README` without `README.md` is
  left unchanged, and no file is created when `VERSION_FROM` has no Markdown.

Status output is written to STDERR. Normal output is intentionally compact:

```text
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod
```

# DOGFOODING

This distribution uses its own sidecar workflow. The important modules and the
public integration classes have adjacent Markdown files:

```text
lib/ASPEER/MakeMaker/Markdown/Pod.pm.md

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm  view on Meta::CPAN

        #

        #
        (my $target_fn=$fn)=~s/\.md$//;

        if ($target_fn=~/\.pm$/ || $target_fn=~/\.pl$/ || $exe_files{$target_fn}) {
            unless (-f $target_fn) {
                verbose("markpod: %s -> %s: skipped, missing target", $fn, $target_fn);
                next;
            }
            msg("markpod: %s -> %s: starting merge", $fn, $target_fn);
            my $markpod_or=Markdown::Pod::Embed->new();
            my $pod_changed=$markpod_or->markpod_process_and_update($target_fn);
            if (!defined $pod_changed) {
                msg("markpod: %s -> %s: finished, skipped", $fn, $target_fn);
            }
            elsif ($pod_changed) {
                msg("markpod: %s -> %s: finished, updated pod", $fn, $target_fn);
            }
            else {
                msg("markpod: %s -> %s: finished, no changes", $fn, $target_fn);

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm  view on Meta::CPAN

            msg('markpod: %s -> %s: skipped, no markdown source', $version_from_fn, $readme_fn);
            return undef;
        }
        my $readme_md=$md;
        $readme_md.=$/ unless $readme_md=~/\n\z/;
        blurp($readme_md_fn, $readme_md) ||
            return err();
        push @manifest_add, $readme_md_fn unless exists $manifest_hr->{$readme_md_fn};
        $source_fn=$readme_md_fn;
    }
    msg('markpod: %s -> %s: starting render', $source_fn, $readme_fn);


    #  No markdown means nothing to render
    #
    unless (defined $md && length $md) {
        msg('markpod: %s -> %s: finished, skipped empty markdown source', $source_fn, $readme_fn);
        manifest_add(\@manifest_add) if @manifest_add;
        return undef;
    }

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm  view on Meta::CPAN

  files listed in `MANIFEST`, derives each target by removing the trailing
  `.md`, and merges supported sidecars into matching `.pm`, `.pl`, or executable
  files. Markdown files under `t/` are ignored so test fixtures are not rewritten.

`readme`
: Builds `README` from the best available Markdown source.

The generated status output is concise and goes to STDERR:

```text
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod
```

Unsupported or missing targets are reported only when verbose output has been
enabled.

# README SOURCE PRECEDENCE

README generation observes the existing project files before creating anything:

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm  view on Meta::CPAN

  files listed in C<MANIFEST>, derives each target by removing the trailing
  C<.md>, and merges supported sidecars into matching C<.pm>, C<.pl>, or executable
  files. Markdown files under C<t/> are ignored so test fixtures are not rewritten.

C<readme>
: Builds C<README> from the best available Markdown source.

The generated status output is concise and goes to STDERR:


 markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
 markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod
Unsupported or missing targets are reported only when verbose output has been
enabled.


=head1 README SOURCE PRECEDENCE

README generation observes the existing project files before creating anything:

=over

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm.md  view on Meta::CPAN

  files listed in `MANIFEST`, derives each target by removing the trailing
  `.md`, and merges supported sidecars into matching `.pm`, `.pl`, or executable
  files. Markdown files under `t/` are ignored so test fixtures are not rewritten.

`readme`
: Builds `README` from the best available Markdown source.

The generated status output is concise and goes to STDERR:

```text
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod
```

Unsupported or missing targets are reported only when verbose output has been
enabled.

# README SOURCE PRECEDENCE

README generation observes the existing project files before creating anything:

t/04-mm-readme.t  view on Meta::CPAN

        '',
        '',
        '',
        '',
        '',
    );

}


sub start_fixture {

    my ($cwd)=@_;
    chdir($cwd) || die "unable to chdir $cwd, $!";
    my $temporary_dn=tempdir(CLEANUP => 1);
    chdir($temporary_dn) || die "unable to chdir $temporary_dn, $!";
    make_path('lib/Sample');
    return 'lib/Sample/Readme.pm';

}


my $cwd=getcwd();


#  Preserve an author-supplied plain README when no Markdown README exists
#
my $version_from=start_fixture($cwd);
spew($version_from, "package Sample::Readme;\nour \$VERSION='0.001';\n1;\n");
spew("${version_from}.md", "# NAME\n\nSidecar text that must not replace README\n");
spew('README', "Author supplied plain README\n");
spew('MANIFEST', "README\n${version_from}\n${version_from}.md\n");
run_readme($version_from);
is(slurp('README'), "Author supplied plain README\n",
    'plain README is preserved when README.md is absent');
ok(!-e 'README.md' && !-l 'README.md', 'README.md is not created beside a plain README');


#  Create a regular README.md from a VERSION_FROM sidecar
#
$version_from=start_fixture($cwd);
spew($version_from, "package Sample::Readme;\nour \$VERSION='0.001';\n1;\n");
my $sidecar_md="# NAME\n\nSample::Readme - README generated from sidecar\n";
spew("${version_from}.md", $sidecar_md);
spew('MANIFEST', "${version_from}\n${version_from}.md\n");
run_readme($version_from);
ok(-f 'README.md' && !-l 'README.md', 'regular README.md is created from sidecar markdown');
is(slurp('README.md'), $sidecar_md, 'README.md contains the sidecar markdown');
like(slurp('README'), qr/Sample::Readme - README generated from sidecar/,
    'plain README is rendered from the new README.md');
my $manifest_hr=ExtUtils::Manifest::maniread();

t/04-mm-readme.t  view on Meta::CPAN

ok(exists $manifest_hr->{'README'}, 'plain README is added to MANIFEST');
run_readme($version_from);
is(slurp('README.md'), $sidecar_md, 'existing README.md remains the markdown source');
my @readme_md_manifest=grep {/^README\.md(?:\s|$)/} split(/\n/, slurp('MANIFEST'));
is(scalar(@readme_md_manifest), 1,
    'repeated generation does not duplicate README.md in MANIFEST');


#  Create README.md from embedded VERSION_FROM markdown without a sidecar
#
$version_from=start_fixture($cwd);
spew($version_from, <<'PERL_MODULE');
package Sample::Readme;
our $VERSION='0.001';
1;
__END__

=begin markdown

# NAME

t/04-mm-readme.t  view on Meta::CPAN

spew('MANIFEST', "${version_from}\n");
run_readme($version_from);
ok(-f 'README.md' && !-l 'README.md', 'regular README.md is created from embedded markdown');
like(slurp('README.md'), qr/Sample::Readme - README generated from embedded markdown/,
    'README.md contains embedded VERSION_FROM markdown');
ok(!-e "${version_from}.md", 'VERSION_FROM sidecar is not created');


#  Leave the project unchanged when VERSION_FROM has no markdown
#
$version_from=start_fixture($cwd);
spew($version_from, "package Sample::Readme;\nour \$VERSION='0.001';\n1;\n");
spew('MANIFEST', "${version_from}\n");
run_readme($version_from);
ok(!-e 'README.md' && !-l 'README.md', 'README.md is not created without markdown');
ok(!-e 'README' && !-l 'README', 'plain README is not created without markdown');


#  Leave the project unchanged when VERSION_FROM is not configured
#
$version_from=start_fixture($cwd);
spew('MANIFEST', '');
run_readme('');
ok(!-e 'README.md' && !-l 'README.md', 'README.md is not created without VERSION_FROM');
ok(!-e 'README' && !-l 'README', 'plain README is not created without VERSION_FROM');

chdir($cwd) || die "unable to chdir $cwd, $!";
done_testing();



( run in 2.083 seconds using v1.01-cache-2.11-cpan-234fa220139 )