Oh, those are some excellent points. I probably should have looked at more code than just Pod::Simple::HTML.
At least for Pod::Simple, this appears to happen deep within the parser, specifically, here.Right, and to specify, both Pod::Man and Pod::Simple::HTML naturally use it.
The preserve_whitespace probably wouldn't help here because it would just preserve the newlines.Yes, it does quite exactly the opposite of what I'm looking for - selectively squash whitespace completely. But, oh, look at what does use preserve_whitespace! Just like Pod::Text, really. But even quickly scanning the code reveals some inconsistencies between code and comments in Pod::Text and Pod::Man - although for a completely different parsing aspect. In recap, Pod::Man seems to handle such line-broken L<> tags correctly, but that's almost not surprising since man doesn't have any (real) notion of (hyper-) links, as far as I know.
To elaborate a bit: I don't even really plan on generating HTML documentation (at least not personally), but the HTML output was a prime candidate for testing my internal and external links within the documentation. podchecker does a basic sanity checks on links, but nothing's better than actually seeing your generated links in a fully generated documentation. I guess I could have also used pod2texi, but I try to avoid GNU Info because I can never remember how to use it correctly …
Unfortunately, it looks to me like the "best" choice is to not break L<>s across multiple lines.Unfortunately it looks like that. However, I think that this could be classified as a bug or at least a somewhat valid intent to add a new feature for escaping capabilities to Pod::Simple.
Looking at the output of pod2man, this appears to be an effect of *roff typesetting, see e.g. Sentences and .ss.Exactly - and I have been misinterpreting this as the same "space instead of newline" behavior, when in reality it's some special property of the roff language family. From the groff manual, I've learned that it's only applying that special rule if the punctuation character is located at exactly the end of the line. Interestingly, and I also learned that, the groff style guide recommends to start each sentence (and thus also end each sentence) on a proper line. Since Pod::Man is not changing whitespace (mostly), this explains why I noticed that behavior at times and didn't at other times.
An argument could be made that Pod::Man should be merging POD paragraphs into one line to avoid the issue you're seeing.Yep, that would help. Either that, or split up sentences on punctuation marks so that each sentence starts/ends on its proper line, to adhere to groff's recommendations (in which case every sentence would get a double space by default - which is fine, since then at least it would be consistent), although that would probably quickly get unwieldy. That would require a parser that is sophisticated enough to detect sentences (and, e.g., ignore mid-sentence punctuation characters or those surrounding the special characters given in the groff manual) and that, frankly, is probably too much to ask for. Instead, I could format my POD directly in a groff-recommended way, which generally shouldn't have any negative impact on other POD renderers.
OT: what's the proper way to quote on PerlMonks? Just copying the text loses all formatting, naturally, so I had to re-add the most important ones. Yes, fetching the data out of the browser would be possible, but then it's processed and not the bare markup any longer.
OT2: [apc://] seems to be broken since the repository was renamed to "perl5". Given that, it's easier to link to GitHub, which is also one of the documented source code locations.
In reply to Re^2: Escape newlines in POD / (Selectively) don't generate space characters instead
by Ionic
in thread Escape newlines in POD / (Selectively) don't generate space characters instead
by Ionic
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |