Allow pod to give syntax highlighting hints for code blocks

[doherty]

It would be nice to be able to provide hints for syntax highlighting a given code block.

For example, executables often have a SYNOPSIS section that doesn't have Perl code in it like a library does, but instead has example command line invocations or a specification of the options and arguments the script accepts. That shouldn't be highlighted as though it were Perl code - it probably shouldn't by highlighted at all.

Similarly, some modules have ASCII art in code blocks to illustrate a data structure, for example. That shouldn't be highlighted either.

And some modules might (heaven forbid) include code blocks in a language other than Perl. It might be nice to provide a hint that "this block is actually Python".

Presumably this would use a =for but I leave it up to others to decide whether this is something that should be metacpan-specific (which might give us =for metacpan txt), or something more generally to do with syntax highlighting (which might give us =for syntax_highlighting txt).

[benkasminbullock]

From the Perl documentation:

Verbatim Paragraph
Verbatim paragraphs are usually used for presenting a codeblock or other text which does not require any special parsing or formatting, and which shouldn't be wrapped. A verbatim paragraph is distinguished by having its first character be a space or a tab. (And commonly, all its lines begin with spaces and/or tabs.) It should be reproduced exactly, with tabs assumed to be on 8-column boundaries. There are no special formatting codes, so you can't italicize or anything like that. A \ means \, and nothing else.

There's nothing in verbatim paragraphs which has to be Perl code, so it shouldn't really be formatted as Perl code. The bug is really that metacpan or its underlying modules makes the assumption that "verbatim paragraph = Perl code" and colours it up as such.

[tobyink]

For what it's worth, in the latest release of TOBYINK::Pod::HTML I use:

=for highlighter language=Haskell

The reason for using a key-value pair is that it allows other hints to be passed to the highlighter too. For example:

=for highlighter language=Perl line_numbers=1

[ranguard]

Moved to wish list: https://github.com/CPAN-API/cpan-api/wiki/Wishlist

[oalders]

After a conversation with @rjbs, I'm re-opening this. Might be a good task for a student. @rwstauner do you have any advice for how to implement this?

[rwstauner]

At the moment I don't have a better suggestion than @tobyink's:

The =for block acts as a marker to say "from this point forward code blocks have the following attributes" and is otherwise empty. Then the verbatim block is regular (it is not attached to the =for), but when looking to classify the block in html you use the most recently specified hints.

It's not ideal, but I'm not aware of anything better that Pod provides so while it may not be "elegant" it is fairly clever.

The only other thing I can think of is to add a marker to the verbatim blocks (like Pod::Elemental::Transformer::VimHTML) but obviously that mucks up the block and will actually be seen by things whereas the =for marker will be ignored by processors that choose not to use it.

[rjbs]

The =for paragraph is what I suggested in conversation at QAH, and I agree with all your points above.

[mauke]

FWIW, some of my modules have started using =for highlighter language=... directives. See e.g. https://metacpan.org/pod/URL::Search and https://metacpan.org/pod/Return::MultiLevel.

I use it mainly for rendering a nice README.md for github, but it would be cool if metacpan DTRT, too.

[haarg]

I think that the front end code will handle this already. The API will need to start using something like Pod::Simple::XHTML::WithHighlightConfig. I should make some changes to that module before integrating it though.