Render POD =head3 $c->uri

Render POD =head3 $c->uri

[Andreas Vögele]

Hi,

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

Noticed on OpenBSD-current.

Regards,
Andreas
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Render POD =head3 $c->uri

[Kristaps Dzonsons]

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

> 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
>
> Noticed on OpenBSD-current.

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.

Oks?

Thanks,

Kristaps

[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 719 bytes --]

Index: mandoc.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mandoc.c,v
retrieving revision 1.60
diff -r1.60 mandoc.c
372c372,378
< 		if (1 != rlim)
---
> 		/*
> 		 * Pretend that the constant-width font modes are the
> 		 * same as the regular font modes.
> 		 */
> 		if (2 == rlim && 'C' == *rstart)
> 			rstart++;
> 		else if (1 != rlim)
373a380
> 
Index: roff.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/roff.7,v
retrieving revision 1.33
diff -r1.33 roff.7
145a146,147
> The indicator or numerical representative may be preceded by C
> (constant-width), which is ignored.

Re: Render POD =head3 $c->uri

[Kristaps Dzonsons]

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

On 11/03/11 15:57, Kristaps Dzonsons wrote:
>> 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
>>
>> Noticed on OpenBSD-current.
>
> 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.
>
> Oks?

Gah.  Unified diff now (stupid default behaviour of non-unified diff).

[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 1185 bytes --]

Index: mandoc.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mandoc.c,v
retrieving revision 1.60
diff -u -r1.60 mandoc.c
--- mandoc.c	24 Oct 2011 20:30:57 -0000	1.60
+++ mandoc.c	3 Nov 2011 14:59:14 -0000
@@ -369,8 +369,15 @@
 
 	switch (gly) {
 	case (ESCAPE_FONT):
-		if (1 != rlim)
+		/*
+		 * Pretend that the constant-width font modes are the
+		 * same as the regular font modes.
+		 */
+		if (2 == rlim && 'C' == *rstart)
+			rstart++;
+		else if (1 != rlim)
 			break;
+
 		switch (*rstart) {
 		case ('3'):
 			/* FALLTHROUGH */
Index: roff.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/roff.7,v
retrieving revision 1.33
diff -u -r1.33 roff.7
--- roff.7	26 Sep 2011 23:07:31 -0000	1.33
+++ roff.7	3 Nov 2011 14:59:14 -0000
@@ -143,6 +143,8 @@
 (revert to previous mode).
 A numerical representation 3, 2, or 1 (bold, italic, and regular,
 respectively) may be used instead.
+The indicator or numerical representative may be preceded by C
+(constant-width), which is ignored.
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact

Re: Render POD =head3 $c->uri

[Andreas Vögele]

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