Have you heard of POD? This is the standard documentation tool in Perl. POD is a simple text documentation format that actually lives in your code. One of the commands that come with perl is perldoc. You can use it to get the information of any Perl command. Try these:
$ perldoc File::Find
$ perldoc -f split
All Perl modules in CPAN are required to incorporate POD documentation. In fact, this is how the CPAN webpages themselves are built.
So, where am I going with this and how is this going to help you?
You should include POD documentation in your Perl program. Then, you can use the pod2text command to create your README for your Perl program:
$ pod2text myperl.pl > README
That handles half of your issue.
The other half is a bit more tricky. You need to install from CPAN the Pod::Markdown on your system. Then, you can run the pod2markdown command that comes with this module to create the markdown version of your file:
$ pod2markdown myperl.pl > README.md
The results:
- Your documentation lives, as it should, in your Perl program.
- Users can use the
perldoc program to print out complete documentation of your program.
- You can use the
pod2text tool to create your README file.
- You can use the
pod2markdown tool to create your README.md file.
- As a bonus, you can use the Pod::Usage module that comes with Perl to show the POD documentation (or bits and pieces of it) as help text that's displayed when a user runs your program with the
-help parameter.
So, one place where your documentation lives, and you're using a couple of helper programs to create the files Github and whatever Perl tools you use need.
