Mailing List Archive

Re: Pod people - I need your wisdom (fwd)
In the message below, Larry mentions the " problem in pod2man. Was this
ever fixed in a patch? If not, could someone run up a fix for 5.001m
style pod2man? roff isn't my forte.

> Example:
> =item C<sprintf(interp-E<gt>result, "%d %d %d %d",...)>

--
Kenneth Albanowski (kjahds@kjahds.com, CIS: 70705,126)


---------- Forwarded message ----------
Date: Tue, 5 Sep 1995 07:38:16 -0400
From: Larry W. Virden <lvirden@cas.org>
To: tchrist@mox.perl.com, kjahds@kjahds.com
Subject: Re: Pod people - I need your wisdom

Your names were provided by a reliable source as being potential
sources for resolution to this problem I am encountering with some of
the pTk doc.


----- Begin Included Message -----

id AA25251; Fri, 1 Sep 95 16:55:29 PDT
In article <1995Aug23.140451.21203@chemabs.uucp> you write:
:
: I am trying to correct a problem in a .pod file that I am using.
:
: Currently it says:
:
: =item C<sprintf(interp-E<gt>result, "%d %d %d %d",...)>
:
: The problem is that " in the string. The reason it is a problem is
that
: when pod2man converts the file, it generates:
: .Ip "\f(CWsprintf(interp->result, "%d %d %d %d",...)\fR " 20
:
: Now, the " beginning the .Ip is terminated incorrectly.
:
: Is there something special that I need to do in the pod file to quote
: double quotes? If not, then I need to change pod2man so that it
generates
: 4 double quote characters for each single quote character in the
original
: string. I suspect however that similar changes will be necessary for
the
: other pod2* filters.
:
: Who would be the best person with whom to discuss this?

-


--
:s Larry W. Virden INET: larry.virden@cas.org
:s A good scientist always hedges his bets. Ramos
:s Unless explicitly stated to the contrary, nothing in this posting should
:s be construed as representing my employer's opinions.
Re: Pod people - I need your wisdom (fwd) [ In reply to ]
>>Date: Tue, 5 Sep 1995 10:44:00 -0400 (EDT)
>>From: Kenneth Albanowski <kjahds@kjahds.com>
>>To: perl5-porters@africa.nicoh.com
>>Subject: Re: Pod people - I need your wisdom (fwd)
>>Message-Id: <Pine.LNX.3.91.950905104158.2169D-100000@kjahds.com>
>>
>>
>>In the message below, Larry mentions the " problem in pod2man. Was this
>>ever fixed in a patch? If not, could someone run up a fix for 5.001m
>>style pod2man? roff isn't my forte.
>>
>>> Example:
>>> =item C<sprintf(interp-E<gt>result, "%d %d %d %d",...)>
>>
>>--
>>Kenneth Albanowski (kjahds@kjahds.com, CIS: 70705,126)
>>
>>
>>---------- Forwarded message ----------
>>Date: Tue, 5 Sep 1995 07:38:16 -0400
>>From: Larry W. Virden <lvirden@cas.org>
>>To: tchrist@mox.perl.com, kjahds@kjahds.com
>>Subject: Re: Pod people - I need your wisdom
>>
>>Your names were provided by a reliable source as being potential
>>sources for resolution to this problem I am encountering with some of
>>the pTk doc.
>>
>>
>>----- Begin Included Message -----
>>
>> id AA25251; Fri, 1 Sep 95 16:55:29 PDT
>>In article <1995Aug23.140451.21203@chemabs.uucp> you write:
>>:
>>: I am trying to correct a problem in a .pod file that I am using.
>>:
>>: Currently it says:
>>:
>>: =item C<sprintf(interp-E<gt>result, "%d %d %d %d",...)>
>>:
>>: The problem is that " in the string. The reason it is a problem is
>>that
>>: when pod2man converts the file, it generates:
>>: .Ip "\f(CWsprintf(interp->result, "%d %d %d %d",...)\fR " 20
>>:
>>: Now, the " beginning the .Ip is terminated incorrectly.
>>:
>>: Is there something special that I need to do in the pod file to quote
>>: double quotes? If not, then I need to change pod2man so that it
>>generates
>>: 4 double quote characters for each single quote character in the
>>original
>>: string. I suspect however that similar changes will be necessary for
>>the
>>: other pod2* filters.
>>:
>>: Who would be the best person with whom to discuss this?
>>
>>-
>>
>>
>>--
>>:s Larry W. Virden INET: larry.virden@cas.org
>>:s A good scientist always hedges his bets. Ramos
>>:s Unless explicitly stated to the contrary, nothing in this posting should
>>:s be construed as representing my employer's opinions.
>>
>>

Kenneth, I posted a patch for this back in April, which I had tested on
SunOS (4.1.1 and 4.1.3). Appended to this message are the original
message containing my patch, and a follow-up to a comment by Tom Christiansen.

Hope this helps...

TD
--------------------------------------------------------------------------

----- Begin Included Message -----

(1.37.109.15/16.2) id AA094339480; Tue, 25 Apr 1995 07:31:20 -0400
Date: Tue, 25 Apr 95 05:59:16 EDT
From: tom@edc.com (Tom Dinger on Feste)
Message-Id: <9504250959.AA23419@feste.edc.com>
To: perlbug@perl.com
Subject: Perl 5 pod2man fix
Cc: perl5-porters@isu.edu, tom@edc.com

Pete Peterson reported on March 15 that the man files generated by pod2man
have a problem, which he noticed in perlvar.pod/man. It relates to
handling double-quotes. Having just found this problem myself, I now have
a fix for it.

The problem occurs for =head or =item lines that have double-quotes on them.
When pod2man finds a double-quote, it replaces it with \*(L" or \*(R"
*roff macros. This works fine for troff (these macros translate into
`` or '') but under nroff this only works for "running" text. For text
used in =head or =item lines, that text is translated into *roff .SH or
.IP macros, and the text is "interpreted" multiple times. So different
*roff macros need to be used for these lines.

Worse, the number of levels of interpretation is different for each
*roff macro, so that .SH (for SunOS 4.1.1) needs one additional level
of quoting, while .IP needs two.

So, the following patch adds some new macros to pod2man, and changes
the logic for =head and =item a little, to select the right macro for
the job.

This patch is for Perl 5.001e.

*** orig/pod2man.SH Sat Apr 22 13:40:15 1995
--- pod2man.SH Mon Apr 24 11:34:45 1995
***************
*** 93,100 ****
--- 93,112 ----
.if (\\n(.H=4u)&(1m=20u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-8u'-\\" diablo 12 pitch
.ds L" ""
.ds R" ""
+ ''' \\*(M", \\*(S", \\*(N" and \\*(T" are the equivalent of
+ ''' \\*(L" and \\*(R", except that they are used on ".xx" lines,
+ ''' such as .IP and .SH, which do another additional levels of
+ ''' double-quote interpretation
+ .ds M" """
+ .ds S" """
+ .ds N" """""
+ .ds T" """""
.ds L' '
.ds R' '
+ .ds M' '
+ .ds S' '
+ .ds N' '
+ .ds T' '
'br\\}
.el\\{\\
.ds -- \\(em\\|
***************
*** 101,108 ****
--- 113,128 ----
.tr \\*(Tr
.ds L" ``
.ds R" ''
+ .ds M" ``
+ .ds S" ''
+ .ds N" ``
+ .ds T" ''
.ds L' `
.ds R' '
+ .ds M' `
+ .ds S' '
+ .ds N' `
+ .ds T' '
.if t .ds PI \\(*p
.if n .ds PI PI
'br\\}
***************
*** 373,380 ****

($Cmd, $_) = split(' ', $_, 2);

if (defined $_) {
! &escapes;
s/"/""/g;
}

--- 393,411 ----

($Cmd, $_) = split(' ', $_, 2);

+ $dotlevel = 1;
+ if ($Cmd eq 'head1') {
+ $dotlevel = 1;
+ }
+ elsif ($Cmd eq 'head2') {
+ $dotlevel = 1;
+ }
+ elsif ($Cmd eq 'item') {
+ $dotlevel = 2;
+ }
+
if (defined $_) {
! &escapes($dotlevel);
s/"/""/g;
}

***************
*** 410,416 ****
if ($needspace) {
&makespace;
}
! &escapes;
clear_noremap(1);
print $_, "\n";
$needspace = 1;
--- 441,447 ----
if ($needspace) {
&makespace;
}
! &escapes(0);
clear_noremap(1);
print $_, "\n";
$needspace = 1;
***************
*** 431,436 ****
--- 462,468 ----
}

sub escapes {
+ my $indot = shift;

# translate the minus in foo-bar into foo\-bar for roff
s/([^0-9a-z-])-([^-])/$1\\-$2/g;
***************
*** 441,449 ****
s/([^"])--"/$1\\*(--"/g;

# fix up quotes; this is somewhat tricky
if (!/""/) {
! s/(^|\s)(['"])/noremap("$1\\*(L$2")/ge;
! s/(['"])($|[\-\s,;\\!?.])/noremap("\\*(R$1$2")/ge;
}

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;
--- 473,491 ----
s/([^"])--"/$1\\*(--"/g;

# fix up quotes; this is somewhat tricky
+ my $dotmacroL = 'L';
+ my $dotmacroR = 'R';
+ if ( $indot == 1 ) {
+ $dotmacroL = 'M';
+ $dotmacroR = 'S';
+ }
+ elsif ( $indot >= 2 ) {
+ $dotmacroL = 'N';
+ $dotmacroR = 'T';
+ }
if (!/""/) {
! s/(^|\s)(['"])/noremap("$1\\*($dotmacroL$2")/ge;
! s/(['"])($|[\-\s,;\\!?.])/noremap("\\*($dotmacroR$1$2")/ge;
}

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;


-------------------------------------------
Tom Dinger tom@edc.com

This space reserved for a pithy comment, a JAPH, or some other Net-witticism.


----- End Included Message -----


----- Begin Included Message -----

Date: Tue, 25 Apr 95 13:00:29 EDT
From: tom (Tom Dinger on Feste)
Message-Id: <9504251700.AA23823@feste.edc.com>
To: tchrist@mox.perl.com, tom@edc.com
Subject: Re: Perl 5 pod2man fix
Cc: perlbug@perl.com, recipients<

>>To: tom@edc.com (Tom Dinger on Feste)
>>Cc: perlbug@perl.com
>>Subject: Re: Perl 5 pod2man fix
>>In-Reply-To: Tom Dinger on Feste's message <9504250959.AA23419@feste.edc.com> of Tue, 25 Apr 95 05:59:16 EDT.
>>Date: Tue, 25 Apr 95 06:19:22 MDT
>>Message-Id: <9540.798812362@mox>
>>From: Tom Christiansen <tchrist@mox.perl.com>
>>Sender: owner-perl5-porters@nicoh.com
>>List-Name: perl5-porters
>>Precedence: bulk
>>Status: R
>>
>>Wow, if this really fixed it, I'll be thrilled. It was um bugging
>>me for quite a long time.
>>
>>--tom
>>

Well, I've opnly tested it on SunOS 4.1.1 on a Sun3 and 4.1.3 on Sun 4.
So, if the tmac.an macros are significantly different on other architectures
then it might not work quite right.

I tested it with perldiag.pod, perlguts.pod and perlvar.pod.

TD
-------------------------------------------
Tom Dinger tom@edc.com

This space reserved for a pithy comment, a JAPH, or some other Net-witticism.


----- End Included Message -----

------------------------------------------------------
Tom Dinger
Phone: (h) 617/894-8295 Kurzweil 617/893-5151 x392
e-mail: (h) tom@edc.com Kurzweil tomd@kurz-ai.com
Telepathy: just think real hard...
Re: Pod people - I need your wisdom (fwd) [ In reply to ]
Larry, here's a patch that may fix up the immediate problem. I have no
idea when this or some other fix will get put into the distribution.

(Thanks, Tom, for coming up with the patch.)

--
Kenneth Albanowski (kjahds@kjahds.com, CIS: 70705,126)


----- Begin Included Message -----

(1.37.109.15/16.2) id AA094339480; Tue, 25 Apr 1995 07:31:20 -0400
Date: Tue, 25 Apr 95 05:59:16 EDT
From: tom@edc.com (Tom Dinger on Feste)
Message-Id: <9504250959.AA23419@feste.edc.com>
To: perlbug@perl.com
Subject: Perl 5 pod2man fix
Cc: perl5-porters@isu.edu, tom@edc.com

Pete Peterson reported on March 15 that the man files generated by pod2man
have a problem, which he noticed in perlvar.pod/man. It relates to
handling double-quotes. Having just found this problem myself, I now have
a fix for it.

The problem occurs for =head or =item lines that have double-quotes on them.
When pod2man finds a double-quote, it replaces it with \*(L" or \*(R"
*roff macros. This works fine for troff (these macros translate into
`` or '') but under nroff this only works for "running" text. For text
used in =head or =item lines, that text is translated into *roff .SH or
.IP macros, and the text is "interpreted" multiple times. So different
*roff macros need to be used for these lines.

Worse, the number of levels of interpretation is different for each
*roff macro, so that .SH (for SunOS 4.1.1) needs one additional level
of quoting, while .IP needs two.

So, the following patch adds some new macros to pod2man, and changes
the logic for =head and =item a little, to select the right macro for
the job.

This patch is for Perl 5.001e.

*** orig/pod2man.SH Sat Apr 22 13:40:15 1995
--- pod2man.SH Mon Apr 24 11:34:45 1995
***************
*** 93,100 ****
--- 93,112 ----
.if (\\n(.H=4u)&(1m=20u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-8u'-\\" diablo 12 pitch
.ds L" ""
.ds R" ""
+ ''' \\*(M", \\*(S", \\*(N" and \\*(T" are the equivalent of
+ ''' \\*(L" and \\*(R", except that they are used on ".xx" lines,
+ ''' such as .IP and .SH, which do another additional levels of
+ ''' double-quote interpretation
+ .ds M" """
+ .ds S" """
+ .ds N" """""
+ .ds T" """""
.ds L' '
.ds R' '
+ .ds M' '
+ .ds S' '
+ .ds N' '
+ .ds T' '
'br\\}
.el\\{\\
.ds -- \\(em\\|
***************
*** 101,108 ****
--- 113,128 ----
.tr \\*(Tr
.ds L" ``
.ds R" ''
+ .ds M" ``
+ .ds S" ''
+ .ds N" ``
+ .ds T" ''
.ds L' `
.ds R' '
+ .ds M' `
+ .ds S' '
+ .ds N' `
+ .ds T' '
.if t .ds PI \\(*p
.if n .ds PI PI
'br\\}
***************
*** 373,380 ****

($Cmd, $_) = split(' ', $_, 2);

if (defined $_) {
! &escapes;
s/"/""/g;
}

--- 393,411 ----

($Cmd, $_) = split(' ', $_, 2);

+ $dotlevel = 1;
+ if ($Cmd eq 'head1') {
+ $dotlevel = 1;
+ }
+ elsif ($Cmd eq 'head2') {
+ $dotlevel = 1;
+ }
+ elsif ($Cmd eq 'item') {
+ $dotlevel = 2;
+ }
+
if (defined $_) {
! &escapes($dotlevel);
s/"/""/g;
}

***************
*** 410,416 ****
if ($needspace) {
&makespace;
}
! &escapes;
clear_noremap(1);
print $_, "\n";
$needspace = 1;
--- 441,447 ----
if ($needspace) {
&makespace;
}
! &escapes(0);
clear_noremap(1);
print $_, "\n";
$needspace = 1;
***************
*** 431,436 ****
--- 462,468 ----
}

sub escapes {
+ my $indot = shift;

# translate the minus in foo-bar into foo\-bar for roff
s/([^0-9a-z-])-([^-])/$1\\-$2/g;
***************
*** 441,449 ****
s/([^"])--"/$1\\*(--"/g;

# fix up quotes; this is somewhat tricky
if (!/""/) {
! s/(^|\s)(['"])/noremap("$1\\*(L$2")/ge;
! s/(['"])($|[\-\s,;\\!?.])/noremap("\\*(R$1$2")/ge;
}

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;
--- 473,491 ----
s/([^"])--"/$1\\*(--"/g;

# fix up quotes; this is somewhat tricky
+ my $dotmacroL = 'L';
+ my $dotmacroR = 'R';
+ if ( $indot == 1 ) {
+ $dotmacroL = 'M';
+ $dotmacroR = 'S';
+ }
+ elsif ( $indot >= 2 ) {
+ $dotmacroL = 'N';
+ $dotmacroR = 'T';
+ }
if (!/""/) {
! s/(^|\s)(['"])/noremap("$1\\*($dotmacroL$2")/ge;
! s/(['"])($|[\-\s,;\\!?.])/noremap("\\*($dotmacroR$1$2")/ge;
}

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;


-------------------------------------------
Tom Dinger tom@edc.com

This space reserved for a pithy comment, a JAPH, or some other Net-witticism.


----- End Included Message -----


----- Begin Included Message -----

Date: Tue, 25 Apr 95 13:00:29 EDT
From: tom (Tom Dinger on Feste)
Message-Id: <9504251700.AA23823@feste.edc.com>
To: tchrist@mox.perl.com, tom@edc.com
Subject: Re: Perl 5 pod2man fix
Cc: perlbug@perl.com, recipients<

>>To: tom@edc.com (Tom Dinger on Feste)
>>Cc: perlbug@perl.com
>>Subject: Re: Perl 5 pod2man fix
>>In-Reply-To: Tom Dinger on Feste's message <9504250959.AA23419@feste.edc.com> of Tue, 25 Apr 95 05:59:16 EDT.
>>Date: Tue, 25 Apr 95 06:19:22 MDT
>>Message-Id: <9540.798812362@mox>
>>From: Tom Christiansen <tchrist@mox.perl.com>
>>Sender: owner-perl5-porters@nicoh.com
>>List-Name: perl5-porters
>>Precedence: bulk
>>Status: R
>>
>>Wow, if this really fixed it, I'll be thrilled. It was um bugging
>>me for quite a long time.
>>
>>--tom
>>

Well, I've opnly tested it on SunOS 4.1.1 on a Sun3 and 4.1.3 on Sun 4.
So, if the tmac.an macros are significantly different on other architectures
then it might not work quite right.

I tested it with perldiag.pod, perlguts.pod and perlvar.pod.

TD
-------------------------------------------
Tom Dinger tom@edc.com

This space reserved for a pithy comment, a JAPH, or some other Net-witticism.


----- End Included Message -----

------------------------------------------------------
Tom Dinger
Phone: (h) 617/894-8295 Kurzweil 617/893-5151 x392
e-mail: (h) tom@edc.com Kurzweil tomd@kurz-ai.com
Telepathy: just think real hard...
Re: Pod people - I need your wisdom (fwd) [ In reply to ]
Larry, here's a patch that may fix up the immediate problem. I have no
idea when this or some other fix will get put into the distribution.

(Thanks, Tom, for coming up with the patch.)

--
Kenneth Albanowski (kjahds@kjahds.com, CIS: 70705,126)


----- Begin Included Message -----

(1.37.109.15/16.2) id AA094339480; Tue, 25 Apr 1995 07:31:20 -0400
Date: Tue, 25 Apr 95 05:59:16 EDT
From: tom@edc.com (Tom Dinger on Feste)
Message-Id: <9504250959.AA23419@feste.edc.com>
To: perlbug@perl.com
Subject: Perl 5 pod2man fix
Cc: perl5-porters@isu.edu, tom@edc.com

Pete Peterson reported on March 15 that the man files generated by pod2man
have a problem, which he noticed in perlvar.pod/man. It relates to
handling double-quotes. Having just found this problem myself, I now have
a fix for it.

The problem occurs for =head or =item lines that have double-quotes on them.
When pod2man finds a double-quote, it replaces it with \*(L" or \*(R"
*roff macros. This works fine for troff (these macros translate into
`` or '') but under nroff this only works for "running" text. For text
used in =head or =item lines, that text is translated into *roff .SH or
.IP macros, and the text is "interpreted" multiple times. So different
*roff macros need to be used for these lines.

Worse, the number of levels of interpretation is different for each
*roff macro, so that .SH (for SunOS 4.1.1) needs one additional level
of quoting, while .IP needs two.

So, the following patch adds some new macros to pod2man, and changes
the logic for =head and =item a little, to select the right macro for
the job.

This patch is for Perl 5.001e.

*** orig/pod2man.SH Sat Apr 22 13:40:15 1995
--- pod2man.SH Mon Apr 24 11:34:45 1995
***************
*** 93,100 ****
--- 93,112 ----
.if (\\n(.H=4u)&(1m=20u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-8u'-\\" diablo 12 pitch
.ds L" ""
.ds R" ""
+ ''' \\*(M", \\*(S", \\*(N" and \\*(T" are the equivalent of
+ ''' \\*(L" and \\*(R", except that they are used on ".xx" lines,
+ ''' such as .IP and .SH, which do another additional levels of
+ ''' double-quote interpretation
+ .ds M" """
+ .ds S" """
+ .ds N" """""
+ .ds T" """""
.ds L' '
.ds R' '
+ .ds M' '
+ .ds S' '
+ .ds N' '
+ .ds T' '
'br\\}
.el\\{\\
.ds -- \\(em\\|
***************
*** 101,108 ****
--- 113,128 ----
.tr \\*(Tr
.ds L" ``
.ds R" ''
+ .ds M" ``
+ .ds S" ''
+ .ds N" ``
+ .ds T" ''
.ds L' `
.ds R' '
+ .ds M' `
+ .ds S' '
+ .ds N' `
+ .ds T' '
.if t .ds PI \\(*p
.if n .ds PI PI
'br\\}
***************
*** 373,380 ****

($Cmd, $_) = split(' ', $_, 2);

if (defined $_) {
! &escapes;
s/"/""/g;
}

--- 393,411 ----

($Cmd, $_) = split(' ', $_, 2);

+ $dotlevel = 1;
+ if ($Cmd eq 'head1') {
+ $dotlevel = 1;
+ }
+ elsif ($Cmd eq 'head2') {
+ $dotlevel = 1;
+ }
+ elsif ($Cmd eq 'item') {
+ $dotlevel = 2;
+ }
+
if (defined $_) {
! &escapes($dotlevel);
s/"/""/g;
}

***************
*** 410,416 ****
if ($needspace) {
&makespace;
}
! &escapes;
clear_noremap(1);
print $_, "\n";
$needspace = 1;
--- 441,447 ----
if ($needspace) {
&makespace;
}
! &escapes(0);
clear_noremap(1);
print $_, "\n";
$needspace = 1;
***************
*** 431,436 ****
--- 462,468 ----
}

sub escapes {
+ my $indot = shift;

# translate the minus in foo-bar into foo\-bar for roff
s/([^0-9a-z-])-([^-])/$1\\-$2/g;
***************
*** 441,449 ****
s/([^"])--"/$1\\*(--"/g;

# fix up quotes; this is somewhat tricky
if (!/""/) {
! s/(^|\s)(['"])/noremap("$1\\*(L$2")/ge;
! s/(['"])($|[\-\s,;\\!?.])/noremap("\\*(R$1$2")/ge;
}

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;
--- 473,491 ----
s/([^"])--"/$1\\*(--"/g;

# fix up quotes; this is somewhat tricky
+ my $dotmacroL = 'L';
+ my $dotmacroR = 'R';
+ if ( $indot == 1 ) {
+ $dotmacroL = 'M';
+ $dotmacroR = 'S';
+ }
+ elsif ( $indot >= 2 ) {
+ $dotmacroL = 'N';
+ $dotmacroR = 'T';
+ }
if (!/""/) {
! s/(^|\s)(['"])/noremap("$1\\*($dotmacroL$2")/ge;
! s/(['"])($|[\-\s,;\\!?.])/noremap("\\*($dotmacroR$1$2")/ge;
}

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;


-------------------------------------------
Tom Dinger tom@edc.com

This space reserved for a pithy comment, a JAPH, or some other Net-witticism.


----- End Included Message -----


----- Begin Included Message -----

Date: Tue, 25 Apr 95 13:00:29 EDT
From: tom (Tom Dinger on Feste)
Message-Id: <9504251700.AA23823@feste.edc.com>
To: tchrist@mox.perl.com, tom@edc.com
Subject: Re: Perl 5 pod2man fix
Cc: perlbug@perl.com, recipients<

>>To: tom@edc.com (Tom Dinger on Feste)
>>Cc: perlbug@perl.com
>>Subject: Re: Perl 5 pod2man fix
>>In-Reply-To: Tom Dinger on Feste's message <9504250959.AA23419@feste.edc.com> of Tue, 25 Apr 95 05:59:16 EDT.
>>Date: Tue, 25 Apr 95 06:19:22 MDT
>>Message-Id: <9540.798812362@mox>
>>From: Tom Christiansen <tchrist@mox.perl.com>
>>Sender: owner-perl5-porters@nicoh.com
>>List-Name: perl5-porters
>>Precedence: bulk
>>Status: R
>>
>>Wow, if this really fixed it, I'll be thrilled. It was um bugging
>>me for quite a long time.
>>
>>--tom
>>

Well, I've opnly tested it on SunOS 4.1.1 on a Sun3 and 4.1.3 on Sun 4.
So, if the tmac.an macros are significantly different on other architectures
then it might not work quite right.

I tested it with perldiag.pod, perlguts.pod and perlvar.pod.

TD
-------------------------------------------
Tom Dinger tom@edc.com

This space reserved for a pithy comment, a JAPH, or some other Net-witticism.


----- End Included Message -----

------------------------------------------------------
Tom Dinger
Phone: (h) 617/894-8295 Kurzweil 617/893-5151 x392
e-mail: (h) tom@edc.com Kurzweil tomd@kurz-ai.com
Telepathy: just think real hard...
Re: Pod people - I need your wisdom (fwd) [ In reply to ]
Larry, here's a patch that may fix up the immediate problem. I have no
idea when this or some other fix will get put into the distribution.

(Thanks, Tom, for coming up with the patch.)

--
Kenneth Albanowski (kjahds@kjahds.com, CIS: 70705,126)


----- Begin Included Message -----

(1.37.109.15/16.2) id AA094339480; Tue, 25 Apr 1995 07:31:20 -0400
Date: Tue, 25 Apr 95 05:59:16 EDT
From: tom@edc.com (Tom Dinger on Feste)
Message-Id: <9504250959.AA23419@feste.edc.com>
To: perlbug@perl.com
Subject: Perl 5 pod2man fix
Cc: perl5-porters@isu.edu, tom@edc.com

Pete Peterson reported on March 15 that the man files generated by pod2man
have a problem, which he noticed in perlvar.pod/man. It relates to
handling double-quotes. Having just found this problem myself, I now have
a fix for it.

The problem occurs for =head or =item lines that have double-quotes on them.
When pod2man finds a double-quote, it replaces it with \*(L" or \*(R"
*roff macros. This works fine for troff (these macros translate into
`` or '') but under nroff this only works for "running" text. For text
used in =head or =item lines, that text is translated into *roff .SH or
.IP macros, and the text is "interpreted" multiple times. So different
*roff macros need to be used for these lines.

Worse, the number of levels of interpretation is different for each
*roff macro, so that .SH (for SunOS 4.1.1) needs one additional level
of quoting, while .IP needs two.

So, the following patch adds some new macros to pod2man, and changes
the logic for =head and =item a little, to select the right macro for
the job.

This patch is for Perl 5.001e.

*** orig/pod2man.SH Sat Apr 22 13:40:15 1995
--- pod2man.SH Mon Apr 24 11:34:45 1995
***************
*** 93,100 ****
--- 93,112 ----
.if (\\n(.H=4u)&(1m=20u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-8u'-\\" diablo 12 pitch
.ds L" ""
.ds R" ""
+ ''' \\*(M", \\*(S", \\*(N" and \\*(T" are the equivalent of
+ ''' \\*(L" and \\*(R", except that they are used on ".xx" lines,
+ ''' such as .IP and .SH, which do another additional levels of
+ ''' double-quote interpretation
+ .ds M" """
+ .ds S" """
+ .ds N" """""
+ .ds T" """""
.ds L' '
.ds R' '
+ .ds M' '
+ .ds S' '
+ .ds N' '
+ .ds T' '
'br\\}
.el\\{\\
.ds -- \\(em\\|
***************
*** 101,108 ****
--- 113,128 ----
.tr \\*(Tr
.ds L" ``
.ds R" ''
+ .ds M" ``
+ .ds S" ''
+ .ds N" ``
+ .ds T" ''
.ds L' `
.ds R' '
+ .ds M' `
+ .ds S' '
+ .ds N' `
+ .ds T' '
.if t .ds PI \\(*p
.if n .ds PI PI
'br\\}
***************
*** 373,380 ****

($Cmd, $_) = split(' ', $_, 2);

if (defined $_) {
! &escapes;
s/"/""/g;
}

--- 393,411 ----

($Cmd, $_) = split(' ', $_, 2);

+ $dotlevel = 1;
+ if ($Cmd eq 'head1') {
+ $dotlevel = 1;
+ }
+ elsif ($Cmd eq 'head2') {
+ $dotlevel = 1;
+ }
+ elsif ($Cmd eq 'item') {
+ $dotlevel = 2;
+ }
+
if (defined $_) {
! &escapes($dotlevel);
s/"/""/g;
}

***************
*** 410,416 ****
if ($needspace) {
&makespace;
}
! &escapes;
clear_noremap(1);
print $_, "\n";
$needspace = 1;
--- 441,447 ----
if ($needspace) {
&makespace;
}
! &escapes(0);
clear_noremap(1);
print $_, "\n";
$needspace = 1;
***************
*** 431,436 ****
--- 462,468 ----
}

sub escapes {
+ my $indot = shift;

# translate the minus in foo-bar into foo\-bar for roff
s/([^0-9a-z-])-([^-])/$1\\-$2/g;
***************
*** 441,449 ****
s/([^"])--"/$1\\*(--"/g;

# fix up quotes; this is somewhat tricky
if (!/""/) {
! s/(^|\s)(['"])/noremap("$1\\*(L$2")/ge;
! s/(['"])($|[\-\s,;\\!?.])/noremap("\\*(R$1$2")/ge;
}

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;
--- 473,491 ----
s/([^"])--"/$1\\*(--"/g;

# fix up quotes; this is somewhat tricky
+ my $dotmacroL = 'L';
+ my $dotmacroR = 'R';
+ if ( $indot == 1 ) {
+ $dotmacroL = 'M';
+ $dotmacroR = 'S';
+ }
+ elsif ( $indot >= 2 ) {
+ $dotmacroL = 'N';
+ $dotmacroR = 'T';
+ }
if (!/""/) {
! s/(^|\s)(['"])/noremap("$1\\*($dotmacroL$2")/ge;
! s/(['"])($|[\-\s,;\\!?.])/noremap("\\*($dotmacroR$1$2")/ge;
}

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;


-------------------------------------------
Tom Dinger tom@edc.com

This space reserved for a pithy comment, a JAPH, or some other Net-witticism.


----- End Included Message -----


----- Begin Included Message -----

Date: Tue, 25 Apr 95 13:00:29 EDT
From: tom (Tom Dinger on Feste)
Message-Id: <9504251700.AA23823@feste.edc.com>
To: tchrist@mox.perl.com, tom@edc.com
Subject: Re: Perl 5 pod2man fix
Cc: perlbug@perl.com, recipients<

>>To: tom@edc.com (Tom Dinger on Feste)
>>Cc: perlbug@perl.com
>>Subject: Re: Perl 5 pod2man fix
>>In-Reply-To: Tom Dinger on Feste's message <9504250959.AA23419@feste.edc.com> of Tue, 25 Apr 95 05:59:16 EDT.
>>Date: Tue, 25 Apr 95 06:19:22 MDT
>>Message-Id: <9540.798812362@mox>
>>From: Tom Christiansen <tchrist@mox.perl.com>
>>Sender: owner-perl5-porters@nicoh.com
>>List-Name: perl5-porters
>>Precedence: bulk
>>Status: R
>>
>>Wow, if this really fixed it, I'll be thrilled. It was um bugging
>>me for quite a long time.
>>
>>--tom
>>

Well, I've opnly tested it on SunOS 4.1.1 on a Sun3 and 4.1.3 on Sun 4.
So, if the tmac.an macros are significantly different on other architectures
then it might not work quite right.

I tested it with perldiag.pod, perlguts.pod and perlvar.pod.

TD
-------------------------------------------
Tom Dinger tom@edc.com

This space reserved for a pithy comment, a JAPH, or some other Net-witticism.


----- End Included Message -----

------------------------------------------------------
Tom Dinger
Phone: (h) 617/894-8295 Kurzweil 617/893-5151 x392
e-mail: (h) tom@edc.com Kurzweil tomd@kurz-ai.com
Telepathy: just think real hard...
Re: Pod people - I need your wisdom (fwd) [ In reply to ]
> Larry, here's a patch that may fix up the immediate problem. I have no
> idea when this or some other fix will get put into the distribution.


> Pete Peterson reported on March 15 that the man files generated by pod2man
> have a problem, which he noticed in perlvar.pod/man. It relates to
> handling double-quotes. Having just found this problem myself, I now have
> a fix for it.


thanks much. that one annoyed me, but i never tracked it down.

--tom