Extend perlpodspec (and POD parsers) to allow escaping text #18305
Labels
Comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
{{ message }}
Currently, there's no (good) way to escape whitespace (or other text) in a POD.
This is problematic if you have to (or rather, want to) wrap long lines, especially those containing formatting codes.
Example 1:
Formatters that don't support hyperlinks, like
Pod::Man, won't run into issues here because they ignore hyperlinks to begin with, but others, likePod::Simple::HTMLwill be unable to generate a reference to(note the leading space character), which certainly can be classified as a bug.
The good folks at PerlMonks were nice enough to help me debug this and pointed me to
Pod::Simple::BlackBox, which either (hard-codedly) replaces newlines with space characters or doesn't transform the input at all.Apparently, modules/tools such as
Pod::ManandPod::Textare not mangling whitespace and newlines at all (which creates a different set of problems), whilePod::Simple::HTMLuses the default setting, which seems to be0/false(i.e., to squash newlines into spaces).If it were possible to escape whitespace (and especially newlines, but I really do mean whitespace in general), this issue could be worked around.
There are also some other problems with the interaction between POD parser behaviors and typesetting languages. For instance, when using
Pod::Manto generatemanpages from POD,{n,t}roffoutput will be generated, and at leastGNU troffhas a special quirk documented in Sentences, which by default doubles the whitespace generated after a punctuation character IFF it's immediately followed by a newline, but the paragraph continues.Example 2:
This will, when viewed with
GNU man, generate such output:Admittedly, this is just a stylistic "issue" and there are probably other ways to fix it, but one workaround would likewise to manually escape the newline in order to make the output more consistent. Let's not talk about this in THIS ticket, though, I'm just providing it as an example of inconsistencies that could be fixed manually with a proper escaping mechanism.
Now, there is a workaround for these sort of problems, but it isn't exactly satisfactory.
The
Z<>formatting code can be abused to such an effect, but the abuse is greeted with either errors or data loss:This makes
pod2htmlterminate correctly and also generate a valid link, but leads to errors (both textual and in the return value) frompod2man,podcheckerand the likes.With a bit of, err, "creative interpretation" of the whitespace requirement when using multiple angle brackets with formatting characters, we can come up with something like this:
This, however, let's
podchecker(andpod2man) generate error messages such asUnterminated L<Z< ... >> sequence at line ...andA non-empty Z<> at line. Obviously, even though theperlpoddocumentation says thatZ<<and>>must be separated bywhitespace, newlines don't seem to satisfy this condition.Not a big deal, we can slightly amend this:
(I've put the space right before the closing angle brackets to make it more visible, but it would have the same effect if placed right after
Z<<.)This does silence errors from
podchecker,pod2manandperldocand likewise doesn't lead to (direct) errors frompod2html, but breaks the latter output.This is the generated HTML output for this paragraph:
The obvious observation is that the link is broken, because it doesn't contain any location. The not-so-obvious observation is that any data in the paragraph after the
L<>code is stripped and essentially lost.For instance, the same HTML output is generated by that input:
Hence, neither is a universally working/usable workaround.
Therefore, I propose a new formatting code like
M<>, which does optionally accept text and just... munges it.With that, any data, but also whitespace, could just be "eaten"/hidden away.
The text was updated successfully, but these errors were encountered: