Bug #94077 for CPAN-Changes: Does not support POD formatting for section headings

Fri Mar 21 06:39:35 2014 TIMB [...] cpan.org - Ticket created

Subject:

Does not support POD formatting for section headings

Compare the rendering of these two: https://metacpan.org/changes/distribution/DBIx-Class https://metacpan.org/changes/distribution/DBI Using pod gives us: * formatted headers * ability to link to a header * cross-reference links * standard way to declare encoding * a table of contents * formatting for section body text * and much more - http://perldoc.perl.org/perlpod.html I'm strongly of the opinion that CPAN::Changes::Spec should at least support POD and ideally be layered over POD so POD can provide a document object model for Changes. Backwards compatibility could be supported by translating files in the old format into pod as it's read. While CPAN::Changes doesn't support pod I'm unlikely to use it.

Fri Mar 21 07:17:18 2014 TIMB [...] cpan.org - Correspondence added

A compromise approach would be to allow section headers to have an optional /^=head\d / prefix.

Fri Mar 21 08:10:40 2014 TIMB [...] cpan.org - Correspondence added

On Fri Mar 21 11:17:18 2014, TIMB wrote: Show quoted text

> A compromise approach would be to allow section headers to have an optional /^=head\d / prefix.

I've implemented that in https://github.com/bricas/cpan-changes/pull/21

Fri Mar 21 12:14:09 2014 rt-cpan [...] trout.me.uk - Correspondence added

On Fri Mar 21 06:39:35 2014, TIMB wrote: Show quoted text

> I'm strongly of the opinion that CPAN::Changes::Spec should at least > support POD and ideally be layered over POD so POD can provide a > document object model for Changes.

Honestly, the way most Changes files are written is more like markdown lists than POD, and I think the additional bureaucracy inherent in the POD format would be enough of a net loss from a user POV that I'd absolutely argue against 'ideally' being an accurate statement. I can absolutely see *allowing* POD being important (and your PR looks as simple as I was hoping so seems pretty reasonable) but I think regarding it as a default is unfortunate; if it was that good an idea then I'd've expected to see a lot more uptake of it as an idea already, and CPAN::Changes is here to reflect a rough consensus from stuff that already exists. I would note, however, that I absolutely do love the idea of having some sort of document object model for changes, I just find it hard to reconcile myself to the idea that POD should be it.

Fri Mar 21 12:14:09 2014 The RT System itself - Status changed from 'new' to 'open'

Fri Mar 21 12:25:41 2014 ether [...] cpan.org - Correspondence added

My feeling here is that the Changes file should be as near to plain text as is possible, with no user-visible markup tokens - so markdown fits the bill (although it might contradict some of the existing CPAN::Changes::Spec elements and so be ruled out anyway), but pod does not -- and keep the pod-formatted document somewhere else, e.g. <mainmodule>::Changes, that actually gets installed as a perldoc (just as DBI does).

Tue Mar 25 00:16:24 2014 ether [...] cpan.org - Cc ETHER added

Fri Dec 05 07:33:01 2014 REHSACK [...] cpan.org - Correspondence added

@TIMB - this ticket has been created because of Test::WriteVariants, Data::Tumbler and maybe DBI ... Any new thoughts - are you convinced by the answers, or not?

Sat May 23 03:27:58 2015 haarg [...] haarg.org - Severity Critical changed to Wishlist