Re: Markup inside verbatim blocks in POD (was Re: Reasons to not use quote signs directly?)
Guillem Jover <guillem@debian.org> writes:
> 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
Oh, huh. Interesting.
I think you can rely on the preservation of the line breaks and formatting
through Pod::Man. I philosophically don't believe in changing things like
that when it can be avoided and try to pass through the original file as
much as possible while making markup transformations.
The whitespace there has no semantic meaning in POD, so it's *possible*
that a future version of Pod::Simple, which is doing the underlying
parsing, might throw away the whitespace for some reason. But it seems
relatively unlikely.
So this is undefined behavior, but I suspect in practice it's relatively
unlikely to break.
--
Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>
Reply to: