| Subject: | C<> in the NAME section |
Hi Russ,
we've got an old bug against the Debian perl package (#304143) about this:
% echo "=head1 NAME\n\ntest -- C<test>"|pod2man - | lexgrog -w -
-: "test - - *(C`test*(C'"
Quoting Colin Watson in the bug:
---
Right now, lexgrog is not even close to being able to parse
*roff at this level. Even if I were to implement that, other
implementations of whatis can't handle this either.
For portability, you should avoid constructs like that in the NAME
section.
---
The one-line patch provided by Rafael Laboissiere doesn't quite work
with podlators-2.2.2. The IN_NAME property is reset for the C<> element
processing by _handle_element_start(), and so the fix doesn't trigger.
Maybe just special-casing "C" like "Para" in _handle_element_start()
would work? See the attached patch.
--
Niko Tyni
ntyni@debian.org
| Subject: | 0001-Translate-C-to-quotes-in-the-NAME-section.patch |
From 3bdae622f7dffb71b69d7bd9da51f078a7b32d04 Mon Sep 17 00:00:00 2001
From: Niko Tyni <ntyni@debian.org>
Date: Fri, 6 Feb 2009 15:49:47 +0200
Subject: [PATCH] Translate C<> to quotes in the NAME section
As discussed in <http://bugs.debian.org/304143>, markup in
the NAME section is non-portable because some whatis generation
tools (particularly 'lexgrog') cannot handle it properly.
Expanding C<foo> to "foo" fixes the most common problem;
possibly other markup should be filtered away altogether.
---
lib/Pod/Man.pm | 7 ++++++-
t/man.t | 4 ++--
2 files changed, 8 insertions(+), 3 deletions(-)
diff --git a/lib/Pod/Man.pm b/lib/Pod/Man.pm
index 71a4d7a..0b6d0a3 100644
--- a/lib/Pod/Man.pm
+++ b/lib/Pod/Man.pm
@@ -259,7 +259,7 @@ sub _handle_element_start {
# NAME heading.
if ($self->can ("cmd_$method")) {
DEBUG > 2 and print "<$element> starts saving a tag\n";
- $$self{IN_NAME} = 0 if ($element ne 'Para');
+ $$self{IN_NAME} = 0 if ($element ne 'Para' && $element ne 'C');
# How we're going to format embedded text blocks depends on the tag
# and also depends on our parent tags. Thankfully, inside tags that
@@ -396,6 +396,11 @@ sub quote_literal {
# several places in the following regex.
my $index = '(?: \[.*\] | \{.*\} )?';
+ # If in NAME section, just return an ascii quoted string, to avoid
+ # confusing tools like whatis
+
+ return qq{"$_"} if $$self{IN_NAME};
+
# Check for things that we don't want to quote, and if we find any of
# them, return the string with just a font change and no quoting.
m{
diff --git a/t/man.t b/t/man.t
index 419cce3..fa22f09 100755
--- a/t/man.t
+++ b/t/man.t
@@ -83,14 +83,14 @@ __DATA__
###
=head1 NAME
-gcc - GNU project C and C++ compiler
+gcc - GNU project C<C> and C++ compiler
=head1 C++ NOTES
Other mentions of C++.
###
.SH "NAME"
-gcc \- GNU project C and C++ compiler
+gcc \- GNU project "C" and C++ compiler
.SH "\*(C+ NOTES"
.IX Header " NOTES"
Other mentions of \*(C+.
--
1.5.6.5