ASPEER-MakeMaker-Markdown-Pod
view release on metacpan or search on metacpan
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.
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.
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
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
`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 )