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:

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

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

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:

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/>

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)