Re: Render POD =head3 $c->uri

["Andreas Vögele" <mail@andreasvoegele.com>]

[-- Attachment #1: Type: text/plain, Size: 1859 bytes --]

Hi Kristaps,

>> when I run the following commands, the text "$c->uri" is fully
>> underlined if the manual page is formatted with nroff. If the manual
>> page is formatted with mandoc, only the text "->uri" is underlined.
>>
>> echo '=head3 $c->uri' | pod2man | nroff -man | less -R
>> echo '=head3 $c->uri' | pod2man | mandoc | less -R
> 
> Hi Andreas,
> 
> The enclosed patch fixes this issue: since the 4.9 release, we've become
> more strict.  I've now added the correct magic for `\f(Cx' escapes as
> dictated by groff(7) and your example works fine.

This works very well. I've written a script that compares more than 350
manual pages and with this patch applied there are only few differences
left. Here's one difference. mandoc doesn't underline "isn't".

echo "=head3 What B<isn't> Catalyst?" | pod2man | nroff -man | less -R
echo "=head3 What B<isn't> Catalyst?" | pod2man | mandoc | less -R

And here's another difference. mandoc doesn't emphasise "STRING". Ignore
the error message, that is appended to the output, because of the
missing =over.

echo "=item B<Name: I<STRING>>" | pod2man | nroff -man | less -R
echo "=item B<Name: I<STRING>>" | pod2man | mandoc | less -R

BTW, there's seems to be a bug in groff. Look at the way "is_level()"
and "isLevelEnabled()" are underlined in the attached example. In
groff's output the line stops at the quotation mark and not at the end
of "level".

pod2man Log4perl.pod | mandoc | less -R
pod2man Log4perl.pod | nroff -man | less -R

In 09_FormFu.pod the indented " C<...>" is wrapped differently. I don't
know why that line is indented in the POD file. If the leading space is
removed, groff and mandoc format the output identically.

pod2man 09_FormFu.pod | nroff -man
pod2man 09_FormFu.pod | mandoc

sed 's/^ //' 09_FormFu.pod  | pod2man | nroff -man
sed 's/^ //' 09_FormFu.pod  | pod2man | mandoc

[-- Attachment #2: Log4perl.pod --]
[-- Type: text/plain, Size: 692 bytes --]

=head2 Log Levels

There are six predefined log levels: C<FATAL>, C<ERROR>, C<WARN>, C<INFO>,
C<DEBUG>, and C<TRACE> (in descending priority). Your configured logging level
has to at least match the priority of the logging message.

If you need to find out if the currently configured logging
level would allow a logger's logging statement to go through, use the
logger's C<is_I<level>()> methods:

    $logger->is_trace()    # True if trace messages would go through

Also available are a series of more Java-esque functions which return
the same values. These are of the format C<isI<Level>Enabled()>,
so C<$logger-E<gt>isDebugEnabled()> is synonymous to 
C<$logger-E<gt>is_debug()>.

=cut

[-- Attachment #3: 09_FormFu.pod --]
[-- Type: text/plain, Size: 227 bytes --]

=over 4

=item *

If the form is being displayed for the first time (or has failed 
validation and it being redisplayed), we use
 C<$form-E<gt>model-E<gt>default_values> to populate the form with data from the
database.

=back