Re^4: Escape newlines in POD / (Selectively) don't generate space characters instead

I think Pod::Simple is pretty complex […] I'm not sure if changes like that are easy to implement and test, especially given the huge amount of POD out in the wild.

Well, I don't care about old documents anyway!
Jokes aside, I took the time and created a new bug report for this. In there, I tried to verbosely explain the problem, the unsatisfactory workarounds that aren't really working universally anyway, and, crucially, ask for new formatter code called M<> to be introduced, that just eats any data/text passed to it. It could also be called H<> for "hide", but these are just specifics. I believe that this is a good option for several reasons:

It doesn't change any previous behavior or markup. That's the main reason why I didn't ask for extending the spec of Z<> to be more lenient and take any text while just consuming it - the behavior of the Z<> formatting code would differ between Perl versions and that can be a real pain.
Parsing formatting codes is already implemented, introducing a new one should be relatively easy. The only exception to that is that, theoretically, any text wrapped in M<> would need to be taken verbatim and not POD-interpreted, but I don't see this as a huge implementation issue.
The documentation for the L<> formatting code can easily be extended to show line-breaking capabilities with the new M<> code.

Yes, I agree, and if you don't mind formatting your POD in a *roff-friendly way […] then that's probably the best solution.

But if you don't mind doing this, then the nice thing about it is your docs will look consistent no matter if read via man, perldoc, or HTML.

I did that for the documentation I've written yesterday and it really hasn't been a big deal. Now, all generated documentation is consistent. man pages have two spaces after each sentence, all the other formats just show up normally. Pretty nice.
I should probably change the perldoc/perldocspec documentation to add this as a recommendation. That won't help "other" people/older documentation to be more consistent, unless they re-read the changed parts, but at least new developers/documentation could benefit.

Personally, I wouldn't put in the effort to do this, because I don't use man to read Perl docs, I always use perldoc, which doesn't do the double space after sentences.

To be honest, I avoid the perldoc command like the plague. So far, whenever I tried it, it just generated plain text, broken at 80 chars per line, with control characters replaced by plain ASCII characters like * and _.
There seem to be multiple weirdnesses:

It seems to default to the Pod::Perldoc::ToText formatter, even though I'm using a capable terminal on a Linux system. This seems to have been introduced in 5.27.5.
Overriding the default formatter via -o man makes it pick the Pod::Perldoc::ToMan formatter, which generates the man page internally and then renders it out as plain text (with a bit of control characters). I'd rather like to get *roff output, though, to pass it to man …
Forcing the Pod::Man formatter via -M Pod::Man actually generates *roff, yay! However, it then goes ahead to call manpager (likely because my environment says MANPAGER=manpager, a Gentoo-specific wrapper to "enable colored man output" and which really just calls $PAGER/less). While GNU less can parse *roff nowadays, I don't want that either …
Finally, I can enforce the usage of man via PERLDOC_PAGER='man -l -'. So, to get the output I'd like, I'd have to replace perldoc with a shell function calling PERLDOC_PAGER='man -l -' perldoc -M 'Pod::Man' "${@}" but that also disables all its internal magic …

I guess I'll just stick to man itself. :)

[…] but you could also access the XML version via the link at the top of the page under the title to get to the original markup.

D'oh, thanks. I tried doing so, but used the XML link while writing the reply, which naturally gave me a pretty empty doctext entry. I should have used it on the parent's node page …

Comment on Re^4: Escape newlines in POD / (Selectively) don't generate space characters instead Select or Download Code

Replies are listed 'Best First'.
Re^5: Escape newlines in POD / (Selectively) don't generate space characters instead by haukex (Archbishop) on Nov 12, 2020 at 20:21 UTC
That's the main reason why I didn't ask for extending the spec of `Z<>` to be more lenient and take any text while just consuming it - the behavior of the `Z<>` formatting code would differ between Perl versions and that can be a real pain. While introducing a new code is certainly an option, the only reason I see not to use `Z<>` is this from perlpodspec - emphasis mine: "This code is unusual in that it should have no content. That is, a processor may complain if it sees `Z<potatoes>`. Whether or not it complains, the potatoes text should ignored." I think allowing `Z<>` to be more lenient could also be an alternative. I should probably change the `perldoc`/`perldocspec` documentation to add this as a recommendation. I agree that this is worth a mention. To be honest, I avoid the `perldoc` command like the plague. I should have been more specific: I use `perldoc` when I'm on the command line. I very much prefer HTML documentation over the command line.	[reply] [d/l] [select]

Replies are listed 'Best First'.

Re^5: Escape newlines in POD / (Selectively) don't generate space characters instead
by haukex (Archbishop) on Nov 12, 2020 at 20:21 UTC

That's the main reason why I didn't ask for extending the spec of Z<> to be more lenient and take any text while just consuming it - the behavior of the Z<> formatting code would differ between Perl versions and that can be a real pain.

While introducing a new code is certainly an option, the only reason I see not to use Z<> is this from perlpodspec - emphasis mine: "This code is unusual in that it should have no content. That is, a processor may complain if it sees Z<potatoes>. Whether or not it complains, the potatoes text should ignored." I think allowing Z<> to be more lenient could also be an alternative.

I should probably change the perldoc/perldocspec documentation to add this as a recommendation.

I agree that this is worth a mention.

To be honest, I avoid the perldoc command like the plague.

I should have been more specific: I use perldoc when I'm on the command line. I very much prefer HTML documentation over the command line.

[reply]
[d/l]
[select]