I have a Perl module with a L<...> link like this:
=head1 ...
See L<RFC 8250|https://datatracker.ietf.org/doc/html/rfc8259#section-4>.
=cut
1;
When I run podlinkcheck (version 15) on it, it complains:
themodule.pm:3:5: no module/program/pod "https:"
even though perldoc perlpod says:
Or you can link to a web page:
Lscheme:...
L<text|scheme:...>
Links to an absolute URL. For example, Lhttp://www.perl.org/ or L<The Perl Home Page|http://www.perl.org/>.
I want to keep using podlinkcheck for all my actual Perl module links, but how do I tell it to treat links that start with https:// as hyperlinks instead of looking for a Perl module by that name?
(It seems to work when I remove the fragment (i.e., See L<RFC 8250|https://datatracker.ietf.org/doc/html/rfc8259> but especially for long documents I want to link to a particular section, not just the whole thing. Escaping the # with a backslash and putting double quotes around it did not help.)
Related
I have this POD file:
=head1 Create professional slideshows with Mojolicious::Plugin::RevealJS
=head2 Install and run a Mojolicious server
Santa's elf had a problem. He had to write very fast a presentation and show it to a bunch of new elf's.
The email assigning this to him was sent by Santa himself.
The elf started to look on Metacpan and found this module: L<Mojolicious::Plugin::RevealJS|https://metacpan.org/pod/Mojolicious::Plugin::RevealJS>
He quickly typed the following commands:
C<cpanm Mojolicius Mojolicious::Plugin::RevealJS>
Now he could generate an mojo lite app using:
C<mojo generate lite-app slide_show>
Because the elf was trained in the ancient arts of the elders
he cloud open new file with vim and paste this code in:
=begin perl
use Mojolicious::Lite -signatures;
app->static->paths(['.']);
plugin 'RevealJS';
any '/' => { template => 'presentation', layout => 'revealjs' };
app->start;
=end perl
When I run perldoc t.pod, the code between '=begin perl' and '=end perl' is not visible. I don't understand what I'm doing wrong.
The perlpod documentation says ...
For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.
The formatter in this case is the thing that perldoc uses to render your POD into text. I suspect it doesn't know what to do with the format perl, so it ignores it.
A formatter that produces HTML might know what to do with the perl format, and might replace this with a code block that has syntax highlighting.
If you want your code examples in the POD to always show up as code, use a verbatim paragraph instead. This is done by adding indentation at the front.
=head2 frobnicate($foo)
This function frobnicates the C<$foo>.
my $bar = frobnicate($foo)
=cut
sub frobnicate { ... }
The description of a =begin <format>/=end <format> in perlpod starts by saying this:
=begin formatname
=end formatname
=for formatname text...
For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.
Anything between =begin perl and =end perl is ignored by the standard Pod formatter and will only be processed by a specialised "perl" formatter (and no such formatter exists in the standard Perl toolset - you'd need to write your own).
You don't say what you expect this syntax to achieve, but it seems likely that you're looking for a verbatim paragraph.
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.
I'm trying to figure out how to modify an XML file with NSIS. So I'm trying to learn how to use the XML plugin. The examples on the forum page often use the format ${plugin::command} like:
${xml::LoadFile}
The documentation gives no indication that you need the dollar sign and curly braces. As I understand it, just plugin::command will do. So I've been trying to figure out what that syntax means.
The documentation says a $ is for variables and the {} are for code blocks, but I can't find anything about what it means when they're used together. My Internet searches have revealed that it's used for something called template literals in JavaScript. But what does it mean in NSIS?
EDIT: I should mention that the NSIS documentation does show examples of this syntax, especially in the Predefines section, but it still doesn't explain what the syntax means in general.
EDIT: Okay, now I see that the syntax is for the compiler to replace things using !define and !macro. But... what about this specific case? Is it valid to use colons in such a symbol? Why are some people writing ${xml::LoadFile}and some people just writing xml::LoadFile?
It's a !define. There is a header file for this plugin that defines it. The plugin probably needs to do more than one thing, so they wrapped a few lines together with a define that inserts a macro. Either that or it has some default parameters for the plugin call. Either way, it's trying to save you some typing with this syntax.
I'm currently working on a Perl script and I use the CPAN module WWW:Mechanize to get HTML pages from websites.
However, I would like to be able to work on offline HTML files as well (that I would save myself beforehand most likely) so I don't need the internet each time I'm trying a new script.
So basically my question is how can I transform this :
$mech->get( 'http://www.websiteadress.html' );
into this :
$mech->get( 'C:\User\myfile.html' );
I've seen that file:// could be useful but I obviously don't know how to use it as I get errors every time.
The get() method from WWW::Mechanize takes a URL as its argument. So you just need to work out what the correct URL is for your local file. You're on the right lines with the "file://" scheme.
I think you will need:
$mech->get( 'file:///C:/User/myfile.html' );
Note two important things that people often get wrong.
URLs only understand forward slashes (/), so you need to convert Windows' warped backslash (\) monstrosities. Update: As Borodin points out in a comment, this isn't true - you can use backslashes in URLs. However, backslashes often have special meanings in Perl strings, so I'd advise using forward slashes whenever possible.
The scheme is file, which is followed by :// (with two slashes), then the hostname (which is an empty string) a slash (/) and then your local path (C:/). So that means that there are three slashes after file:. That seems wrong, so people often omit one of them. Update: description made more accurate following advice from Borodin in a comment.
Wikipedia (as always) has a lot more information - file URI scheme
In Perl, you call modules using :: as path separator. So, if you have a module on site/lib/GD/Image.pm, you call use GD::Image.
However, long time ago I found out that you can also call use GD'Image and things like my $img = new GD'Image;, and there are also modules on CPAN using that syntax on ther names/documentation.
What is the purpose or logic behind that? Is it maybe, as many things in Perl, just a feature intended to humanize sentences and allow you to create and use modules like Acme::Don't?
Does it have any other intention different to ::?
See perlmod for explanation:
The old package delimiter was a single quote, but double colon is now the preferred delimiter
So, the reason is history.
The single quote is an old ADA separator. However, it didn't play well with Emacs, so the double colon became used.
Good God! ADA? Emacs? I am old.
Most PHP Developers are likely familar with the Syntax Highlighter called "GeSHi", which takes code, highlights it, with the use of HTML and CSS:
include('geshi.php');
$source = 'echo "hello, world!";
$language = 'php';
$path = 'geshi/';
$geshi = new GeSHi($source, $language, $path);
echo $geshi->parse_code();
GeSHi Supports a wide range of languages.
I wonder, is there a similar Module for Perl?
Perl has a port of Kate highlighting system: Syntax::Highlight::Engine::Kate which seems to be somewhat close to what you need. It appears to be part of Padre.
You also have an option of HTML client side highlighters (logic is obviously JS), such as Google's code prettifyer
Two good lists of syntax highlighting engines are:
Wiki syntax highlighting article - among the ones it lists, the Perl ports/APIs seem to exist for Kate and Colorer (Syntax::Highlight::Universal)
This very good review of HTML syntax highlighters, which contains a lot of client-side ones such as SHJS and many others.
Please be aware that NONE of those generic highlighters work "100% correctly", the way the syntax highlighters work in good IDEs, because they use regular expressions for approximate parsing instead of lexers for actual language grammar parsing. More details on the Wiki
You can also consider this for client side syntax highlighting.
http://alexgorbatchev.com/SyntaxHighlighter/
I have had some very good results with the PPI::HTML package. It uses PPI to parse the Perl before converting the text to HTML.
Pure Perl: Syntax::Highlight::Engine::Kate (there is Kate plugin for Padre IDE).
Wrappers for C libraries: Syntax::Highlight::Universal, Syntax::SourceHighlight.
Using external tools: Text::VimColor, Text::EmacsColor.
Also there are many one-language highlighters on CPAN.
You can always write a small php script to make GeSHi usable from command line and then call it within your perl script.
I did this for gitweb so I could leave svn (and websvn) behind for good.
My search brought me here, because I was looking for a 'Perl Syntax Highlighter' like the title said and not an general highlighter implemented in Perl.
To highlight only Perl, perltidy --html can be used. It belongs to the Perl::Tidy distribution the main module can be imported and used without spawning a process.
https://metacpan.org/dist/Perl-Tidy/view/bin/perltidy#HTML-OPTIONS
So not what the OP actually wanted to know, but hopefully of help for others coming here for the same reasons like me ... :)