New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

generate README.md and README.pod at build time #9

Closed
wants to merge 5 commits into
base: master
from

Conversation

Projects
None yet
2 participants
@tudorconstantin

tudorconstantin commented Jul 26, 2015

Part of the july's cpan pull request challenge I got your module.

I added the automatic generation of README.md and README.pod when one issues a make dist

I hope you like this and accept my pull-request

@mschilli

This comment has been minimized.

Show comment
Hide comment
@mschilli

mschilli Jul 28, 2015

Owner

Hi Tudor, thanks for your contribution, these cpan pull request challenges are a great!

That being said, I'm not a big fan of providing the same content in several formats in a distribution. If the main .pm file is the source of truth for the README (as in this module), there's no need for the distro to provide README.pod or README.md, as anyone interested in generating those could do so at their end, and without requiring everyone else to pull in dependencies (like Pod::Markdown) they don't need.

Please understand that I'm going to pass on this one, but don't let this stop you from providing much needed improvements to CPAN modules!

Owner

mschilli commented Jul 28, 2015

Hi Tudor, thanks for your contribution, these cpan pull request challenges are a great!

That being said, I'm not a big fan of providing the same content in several formats in a distribution. If the main .pm file is the source of truth for the README (as in this module), there's no need for the distro to provide README.pod or README.md, as anyone interested in generating those could do so at their end, and without requiring everyone else to pull in dependencies (like Pod::Markdown) they don't need.

Please understand that I'm going to pass on this one, but don't let this stop you from providing much needed improvements to CPAN modules!

@mschilli mschilli closed this Jul 28, 2015

@tudorconstantin

This comment has been minimized.

Show comment
Hide comment
@tudorconstantin

tudorconstantin Jul 28, 2015

Hi Mike,

And thank you for your response. That's ok, I don't mind if you won't
accept it. An extra dependency is indeed a thing which I don't like and
yes, anyone can generate those READMEs. The plus side is the fact that a
user who reaches your module on github sees a much friendly formatted
documentation out of the box and as an added bonus, there are also back
links to the metacpan page of the module. Those back links would be
multiplied each time someone forks your repository, adding more SEO juice
to your module and to Perl itself.
These are my considerations for having a rich README, but as I said above,
I don't mind if you don't share my opinion.

On Tue, Jul 28, 2015 at 8:15 AM, Mike Schilli notifications@github.com
wrote:

Hi Tudor, thanks for your contribution, these cpan pull request challenges
are a great!

That being said, I'm not a big fan of providing the same content in
several formats in a distribution. If the main .pm file is the source of
truth for the README (as in this module), there's no need for the distro to
provide README.pod or README.md, as anyone interested in generating those
could do so at their end, and without requiring everyone else to pull in
dependencies (like Pod::Markdown) they don't need.

Please understand that I'm going to pass on this one, but don't let this
stop you from providing much needed improvements to CPAN modules!


Reply to this email directly or view it on GitHub
#9 (comment)
.

Best Regards,
Tudor

tudorconstantin commented Jul 28, 2015

Hi Mike,

And thank you for your response. That's ok, I don't mind if you won't
accept it. An extra dependency is indeed a thing which I don't like and
yes, anyone can generate those READMEs. The plus side is the fact that a
user who reaches your module on github sees a much friendly formatted
documentation out of the box and as an added bonus, there are also back
links to the metacpan page of the module. Those back links would be
multiplied each time someone forks your repository, adding more SEO juice
to your module and to Perl itself.
These are my considerations for having a rich README, but as I said above,
I don't mind if you don't share my opinion.

On Tue, Jul 28, 2015 at 8:15 AM, Mike Schilli notifications@github.com
wrote:

Hi Tudor, thanks for your contribution, these cpan pull request challenges
are a great!

That being said, I'm not a big fan of providing the same content in
several formats in a distribution. If the main .pm file is the source of
truth for the README (as in this module), there's no need for the distro to
provide README.pod or README.md, as anyone interested in generating those
could do so at their end, and without requiring everyone else to pull in
dependencies (like Pod::Markdown) they don't need.

Please understand that I'm going to pass on this one, but don't let this
stop you from providing much needed improvements to CPAN modules!


Reply to this email directly or view it on GitHub
#9 (comment)
.

Best Regards,
Tudor

@mschilli

This comment has been minimized.

Show comment
Hide comment
@mschilli

mschilli Jul 28, 2015

Owner

I totally agree, having a rich README would definitely be a plus (right now, it's actually kind of odd that we generated the README from the source of truth (the .pm) and that it is even worse in terms of markup, but I digress), but instead of patching thousands of CPAN modules, it'd be great if Github (or other hosters) would simply do it for us. This way, we only need to do it once and in one place!

Owner

mschilli commented Jul 28, 2015

I totally agree, having a rich README would definitely be a plus (right now, it's actually kind of odd that we generated the README from the source of truth (the .pm) and that it is even worse in terms of markup, but I digress), but instead of patching thousands of CPAN modules, it'd be great if Github (or other hosters) would simply do it for us. This way, we only need to do it once and in one place!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment