VERSION section in POD

polettix has asked for the wisdom of the Perl Monks concerning the following question:

Replies are listed 'Best First'.
Re: VERSION section in POD by choroba (Cardinal) on May 18, 2016 at 14:16 UTC
I use perl-reversion for my modules. I usually just `-bump` the VERSION and it happens everywhere, I just have not to forget to commit the changes. I still feel there must be a better way (see for example line 27 of Makefile.PL here, it's ugly). There's the third place where you need the version! ++Thanks for asking the question. ($q=q:Sq=~/;[c](.)(.)/;chr(-\|\|-\|5+lengthSq)`"S\|oS2"`map{chr \|+ord }map{substrSq`S_+\|`\|}3E\|-\|`7**2-3:)=~y+S\|`+$1,++print+eval$q,q,a, [download]	[reply] [d/l] [select]
Re^2: VERSION section in POD by polettix (Vicar) on May 18, 2016 at 14:32 UTC
Thanks for pointing out perl-reversion, it's worth trying/considering as a substitute of my munging process. Re the third place, that part is actually taken care automatically by Dist::Zilla or Milla, so that is not a problem in my context. These tools are amazing at freeing my mind from most of the workflow! I get it that you also value a `VERSION` section in the POD. I wonder how useful/used it is though? perl -ple'$_=reverse' <<<ti.xittelop@oivalf Io ho capito... ma tu che hai detto?	[reply] [d/l]
Re^2: VERSION section in POD by perlfan (Vicar) on May 18, 2016 at 15:10 UTC
Interesting. I couldn't help but notice that perl-reversion is not versioned in the source or POD. Maybe that is the right approach?	[reply]
Re^3: VERSION section in POD by choroba (Cardinal) on May 18, 2016 at 15:17 UTC
It's just an example script in the Perl::Version distribution, whose main module is versioned in both the code and pod. ($q=q:Sq=~/;[c](.)(.)/;chr(-\|\|-\|5+lengthSq)`"S\|oS2"`map{chr \|+ord }map{substrSq`S_+\|`\|}3E\|-\|`7**2-3:)=~y+S\|`+$1,++print+eval$q,q,a, [download]	[reply] [d/l]
Re: VERSION section in POD by LanX (Saint) on May 18, 2016 at 15:27 UTC
I once wrote a little script ("podbuilder") creating a .pod file for my module (and manifest, README and so on) from templates. ( because `perldoc <MODULE>` will show the content of `<MODULE>.pod` (if present) instead of `<MODULE>.pm` ) It also does a parsing of my module's POD for comments which are meant to be part of the interface description including `$VERSION` Since the script is part of the test suite and/or commit-hook all files are automatically updated. So instead of "reversioning" all files I only update the main code's $VERSION. ˛ But I have to admit I never really used Pod::Weaver or Dist::Zilla , so I can't tell how many wheels I reinvented, BUT it has no dependenciesł. Cheers Rolf _{(addicted to the Perl Programming Language and ☆☆☆☆ :) Je suis Charlie!} ˛) which shouldn't be done without running the test-suite anyway ł) which means I can distribute it with my module, without blowing up the dependencies.	[reply] [d/l] [select]
Re^2: VERSION section in POD by polettix (Vicar) on May 19, 2016 at 07:31 UTC
It would be interesting to take a look at it, for inspiration... The dependencies observation hits the nail right in the head, as the whole thread started (in my mind at least) from a dependency error I was having in Travis-CI for a corner case. I'm currently using a small templating system to do the job, although it's probably way overkill. I might embed the templating system in the transformation program or... avoid using it. perl -ple'$_=reverse' <<<ti.xittelop@oivalf Io ho capito... ma tu che hai detto?	[reply]
Re: VERSION section in POD by afoken (Chancellor) on May 18, 2016 at 17:51 UTC
Don’t Repeat Your… version number Alexander -- Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)	[reply]
Re^2: VERSION section in POD by polettix (Vicar) on May 19, 2016 at 07:27 UTC
Quite "hacky" but I enjoyed reading the thread - too bad I didn't find it before pestering you monks. I forgot to say (my bad) that lately I like to keep my POD in a separate `.pod` file, so that modules come to be tighter when I do a fatpack-like operation (without the need to do the stripping on the fly, which is mangling the file's contents, which always makes me feel nervous. This is another story though). The testing alternative proposed by tinita in Re: Don't Repeat Your version number has the advantage of forcing me to update the version number in the POD, which is something that really happens only at release time so it's no big deal actually. On the other hand, I'm really lazy and I'm using automatic update in the Perl sources already (so much for my nervousness), so a simple automation on the POD is already below the threshold of what I'm implicitly inclined to accept. All in all, I'm getting from the feedbacks to this thread that a few people find value in keeping `VERSION` in POD too, which is good to know by itself. perl -ple'$_=reverse' <<<ti.xittelop@oivalf Io ho capito... ma tu che hai detto?	[reply] [d/l] [select]
Re^3: VERSION section in POD by RonW (Parson) on May 19, 2016 at 18:04 UTC
All in all, I'm getting from the feedbacks to this thread that a few people find value in keeping VERSION in POD too Having the version number of the module in the module's documentation is important to the reader for knowing which version the documentation applies to.	[reply]
Re: VERSION section in POD by RonW (Parson) on May 18, 2016 at 16:56 UTC
I wrote 1119138 to generate a pod file for my Perl programs and modules. I have since updated it to include a new kind of Perl6 comment. (as LanX pointed out, where there is both a Module.pm and Module.pod perldoc will use Module.pod (same is true for metacpan.org)) Among other things, it parses the `$VERSION = 1.23;` statement to generate the VERSION section in the pod file. It can also parse the `package` statement to generate the NAME section.	[reply] [d/l] [select]
Re^2: VERSION section in POD by polettix (Vicar) on May 19, 2016 at 07:37 UTC
Getting the version number to put in the POD is not a problem, as it's already available in Dist::Zilla/Milla when I call the transformation script in dist.ini (that's `%v` inside the `Run::AfterBuild` section): `abstract = Text and data canalising [CopyFilesFromRelease/Tubergen] filename = script/tubergen [@Milla] Git::Check.allow_dirty = script/tubergen Git::Commit.allow_dirty = script/tubergen [Run::AfterBuild] run = support/podversion.pl "%d" "%v" run = support/tubergen-bundle.pl "%d" "%v" [PruneFiles] filename = cpanfile.snapshot match = ^support/` [download] Good to know that others see value in the `VERSION` section, anyway, so thanks for taking the time! perl -ple'$_=reverse' <<<ti.xittelop@oivalf Io ho capito... ma tu che hai detto?	[reply] [d/l] [select]
Re^3: VERSION section in POD by RonW (Parson) on May 19, 2016 at 18:33 UTC
The reason I wrote the "documentation comments" to POD converter was POD, in Perl5, requires repeating a lot of information that is already present in the code. In Perl6, Pod has an enhanced syntax that allows to referring to information in the surrounding code. Though I didn't know that when I wrote my converter. The reason I chose to convert from Doxygen style comments was that I already use Doxygen for producing the "low level" design documentation in C/C++, which is what is used at many companies producing electronic control modules. Advantages of doing this include most of the function prototypes and data structures are in place by the time the design is approved, and all of the (text of the) documentation is in the comments of the code, so is much easier to keep the docs and code in sync as changes get made. And, of course, no repeating information that's already in the code (unless you count the descriptions of what the code is supposed to do as repeating the code).	[reply]
Re: VERSION section in POD by jandrew (Chaplain) on May 19, 2016 at 00:36 UTC
I've started adding the following badge section to my top level module pod so information is provided but maintenance is not required. This includes the minimum perl supported, current github version, CPAN version, Travis-CI state, Coveralls information, and Kwalitee score for that package. Probably overkill but once it's set up you don't have to mess with it anymore. The down side is it will only display in browsers not in man pages. Inspect the various specific urls for your implementation substitutions. I generally put it right after the NAME section. =begin html <a href="https://www.perl.org"> <img src="https://img.shields.io/badge/perl-5.10+-brightgreen.svg" + alt="perl version"> </a> <a href="https://travis-ci.org/jandrew/p5-spreadsheet-reader-excelxml" +> <img alt="Build Status" src="https://travis-ci.org/jandrew/p5-spre +adsheet-reader-excelxml.png?branch=master" alt='Travis Build'/> </a> <a href='https://coveralls.io/github/jandrew/p5-spreadsheet-reader-exc +elxml?branch=master'> <img src='https://coveralls.io/repos/github/jandrew/p5-spreadsheet +-reader-excelxml/badge.svg?branch=master' alt='Coverage Status' /> </a> <a href='https://github.com/jandrew/p5-spreadsheet-reader-excelxml'> <img src="https://img.shields.io/github/tag/jandrew/p5-spreadsheet +-reader-excelxml.svg?label=github version" alt="github version"/> </a> <a href="https://metacpan.org/pod/Spreadsheet::Reader::ExcelXML"> <img src="https://badge.fury.io/pl/Spreadsheet-Reader-ExcelXML.svg +?label=cpan version" alt="CPAN version" height="20"> </a> <a href='http://cpants.cpanauthors.org/dist/Spreadsheet-Reader-ExcelXM +L'> <img src='http://cpants.cpanauthors.org/dist/Spreadsheet-Reader-Ex +celXML.png' alt='kwalitee' height="20"/> </a> =end html [download] For the github badge to work you have to draft a release with the package version as the 'Tag version'	[reply] [d/l]
Re^2: VERSION section in POD by polettix (Vicar) on May 19, 2016 at 07:15 UTC
This is a very interesting idea. As you correctly point out, it's available in the browser only (so it deviates a bit from what I had in mind in the first place), but it's neat indeed and worth considering (the badges in your modules' pages in metacpan are awesome). Definitely goes into my "Today I Learned..." bucket, thanks! perl -ple'$_=reverse' <<<ti.xittelop@oivalf Io ho capito... ma tu che hai detto?	[reply]
Re^2: VERSION section in POD by RonW (Parson) on May 20, 2016 at 19:27 UTC
Looking at this more closely, it appears to always link to the info about the latest version instead of the version "in hand". Still, this is interesting.	[reply]
Re^3: VERSION section in POD by jandrew (Chaplain) on May 20, 2016 at 20:58 UTC
RonW you are correct that the links as shown will always give the latest versions. It is possible to hard code the versions and links to their repos into each badge. See the perl version badge for an example that does just that. Shields.io is a pretty flexible resource for a lot of things in that area. If you do that you're back to the the original issue of having to hand roll the versions in the pod or use a tool like the one suggested by choroba++ (perl-reversion). All/most/(all the good) Pod readers explicitly strip dynamic code for safety. This includes anything that would import the value for the $VERSION variable. I think that perl-reversion or something like it is a good idea I just went down a different path. I suppose my initial post was mostly responding to the part of the OP that asked how other people handle version in their pod. I don't have any compelling reason to say my way is best practice. It's just the way I do it. I suppose that with some work and a parser you could have both hard coded badges and text versions posted I just never went that far. TIMTOWTDI!!	[reply]


Just another Perl shrine
	PerlMonks