Markup inside verbatim blocks in POD (was Re: Reasons to not use quote signs directly?)

[Guillem Jover <guillem@debian.org>]

Hi!

Coming back to unearth this now that I'm looking again at converting
the man pages to POD, and most of the hurdles except this one have been
fixed in supporting tools or in the man pages.

On Thu, 2016-10-27 at 16:58:38 -0700, Russ Allbery wrote:
> Guillem Jover <guillem@debian.org> writes:
> > In deb-changelog(5) there is currently this:
> 
> > ,---
> > .nf
> > \fIpackage\fP (\fIversion\fP) \fIdistributions\fP; \fImetadata\fP
> >           [optional blank line(s), stripped]
> >   * \fIchange-details\fP
> >     \fImore-change-details\fP
> >           [blank line(s), included in output of \fBdpkg\-parsechangelog\fP(1)]
> >   * \fIeven-more-change-details\fP
> >           [optional blank line(s), stripped]
> >  \-\- \fImaintainer-name\fP <\fIemail-address\fP>  \fIdate\fP
> > .fi
> > `---
> 
> > which I had to convert by surrounding with «=begin man» and «=end man».
> > If you know of a better way, I'm interested!
> 
> Oh, markup inside verbatim.  Yeah, this is a topic of some discussion in
> the Perl community.  There was occasionally some talk of a =begin verbatim
> block that would act like a verbatim block but markup sequences would be
> allowed, but nothing really came of it.

While fiddling with this I stumbled over a behavior in Pod::Man that
gives exactly what I want, but it might be "undefined behavior" that
I should probably not be relying on? (I'd love to be wrong here :).

,---
=head1 NAME

verbatim - test verbatim formatted hack

=head1 EXAMPLE

Some text here.

The verbatim formatted hack:
 Z<>
 This is a C<verbatim block>
 with B<bold> and I<italics>,
 and F<filename> or
 even L<man-page(1)> references.
`---

The key here is the first line in the paragraph starting at column 0,
while the rest having leading spaces. Pod::Man then outputs these
lines as is, respecting the spacing, only formatting the text, which
makes groff add the usual line breaks at those leading space points
(this can be changed with the .lsm macro). Also po4a also parser this
as desired and marks this paragraph as 'no-wrap' in the resulting msgid.
The first line and the Z<> are a bit of wart, but oh well.

This of course does not work with other formatters, but then I'm not
sure I care about those as the purpose in this case is to just create
man pages.

Is this something I could rely on? Because that'd be lovely. :D

Thanks,
Guillem