Linting embedded POD documents

[ferki]

First, thanks for maintaining vale!

I noticed it includes some initial support to lint Perl-related files. At least it seems to recognize code comments in files with the .pl, .pm extension, and general text in files with the .pod extension.

The section about Embedding Pods in Perl Modules of the official POD documentation describes support for mixing Perl code with POD documentation. I perceive that as a fairly common practice in the wider Perl community, since it enables code and docs to exist right next to each other, decreasing the related maintenance overhead.

It appears vale does not recognize this type of POD usage yet, and I'd like to learn more about how we might achieve that. Perhaps I merely miss an existing approach for this with vale?

Judging by the HTML support, as well as by the approach of converting some other formats to HTML first, pod2html may prove interesting, which comes with Perl itself.

While I don’t write Go code myself, I’d happily assist enabling such capability in a future release from the Perl/POD and “beta” testing side of the story. Let me know how I may support.

[jdkato]

This should be very possible, as most of the required functionality is already in place.

The steps would be:

1. Add support for Pod markup files. Essentially, this means writing a function that calls pod2html (as done with AsciiDoc & Asciidoctor, for example).
2. Move the handling of Perl files to Tree-sitter. This isn't strictly required since, as you've noted, there is existing support for Perl files. However, the current implementation uses a now-deprecated approach of extracting comments using regex, which is much less accurate than using Tree-sitter.

Then you'll be able to do what you've described by following the embedded markup docs.

I've been meaning to work on (2) anyway since most of the supported programming languages have already been migrated.

[ferki]

The tree-sitter-perl project appears a great match at first glance to handle Perl files with Tree-sitter. Apparently they share some maintainers with Perl core itself.