Front page | perl.perl5.porters |
Postings from March 2007
[perl #41687] [PATCH] v5.8.8 pod2html -- Add --[no]fragmentuniq to support more readable <a name=..> refs
Thread Next
From:
Jari Aalto
Date:
March 4, 2007 01:38
Subject:
[perl #41687] [PATCH] v5.8.8 pod2html -- Add --[no]fragmentuniq to support more readable <a name=..> refs
Message ID:
rt-3.6.HEAD-2051-1172969986-86.41687-75-0@perl.org
# New Ticket Created by Jari Aalto
# Please include the string: [perl #41687]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=41687 >
This is a bug report for perl from jaalto@cante.cante.net,
generated with the help of perlbug 1.35 running under perl v5.8.8.
-----------------------------------------------------------------
[Please enter your report here]
DESCRIPTION
THe pod2html converter constructs obfusticated <a name=...> frament
ids. Those are not suitable for posting in email and other social
context where URL links are exchanged.
THE SOLUTION
Offer alternate method to construct the frament identifiers in a more
human readable manner. By taking the words from the current line to
construct the ID are "readable choice". This of course does not
guarantee the uniqueness, but as this option is not enabled by
default, the user has the responsibility to make sure that all =item
and =head tags can be considered unique.
The patch implements new option:
--[no]fragmentuniq
The old, obfusticated id operation, is the deault. User can change the
method to use "human readble" fragments with:
--nofragmentuniq
USE CASES
[the default; notice "2d_23_2f_2d_2d" etc.]
<dt><strong><a name="item__2d_23_2f_2d_2dprogress_2dbar"><strong>-#/--progress-bar</strong></a></strong>
<dt><strong><a name="item__2da_7c_2d_2dappend"><strong>-a|--append</strong></a></strong>
<dt><strong><a name="item__2da_7c_2d_2duser_2dagent__22agent_string_22"><strong>-A|--user-agent "agent string"</strong></a></strong>
<dt><strong><a name="item__2d_2danyauth"><strong>--anyauth</strong></a></strong>
[with option --nofragmentuniq]
<dt><strong><a name="item__progress_bar"><strong>-#/--progress-bar</strong></a></strong>
<dt><strong><a name="item__a_append"><strong>-a|--append</strong></a></strong>
<dt><strong><a name="item__a_user_agentagent_string"><strong>-A|--user-agent "agent string"</strong></a></strong>
<dt><strong><a name="item__anyauth"><strong>--anyauth</strong></a></strong>
The PATCH for /usr/share/perl/5.8.8/Pod/Html.pm
........................................................................
Notice, that this patch builds on top of my previous bug report titled:
"[perl #41686] perlbug AutoReply: [PATCH] v5.8.8 pod2html -- option
--quota-style us for "q" => ``q'' conversion"
=== modified file 'Html.pm'
--- Html.pm 2007-03-03 18:42:19 +0000
+++ Html.pm 2007-03-04 00:37:33 +0000
@@ -64,6 +64,16 @@
Flushes the item and directory caches.
+=item fragmentuniq
+
+ --fragmentuniq
+
+Make the <a name=...> references fully unique by adding random text.
+In large text this is probably the only choice to make the hyperlink
+references unique. With --noframentuniq the reference is constructed
+from the words in the current line thus making it more human readable
+(suitable for posting links to the text).
+
=item header
--header
@@ -235,6 +245,7 @@
my @Begin_Stack;
my @Libpods;
my($Htmlroot, $Htmldir, $Htmlfile, $Htmlfileurl, $Prelink, $QuoteStyleUS);
+my($FragmentUniq);
my($Podfile, @Podpath, $Podroot);
my $Css;
@@ -302,6 +313,7 @@
$Doindex = 1; # non-zero if we should generate an index
$Prelink = 0; # Treat <pre>..</pre> for URLsx
$QuoteStyleUS = 0; # Treat "quote" as ``quote'' in HTML
+ $FragmentUniq = 1; # <a name=...> frament names
$Backlink = ''; # text for "back to top" links
$Listlevel = 0; # current list depth
@Listend = (); # the text to use to end the list.
@@ -632,6 +644,8 @@
--cachedir - directory for the item and directory cache files.
--css - stylesheet URL
--flush - flushes the item and directory caches.
+ --[no]fragmentuniq
+x - Use words from line with random text to make <a name> links.
--[no]header - produce block header/footer (default is no headers).
--help - prints this message.
--hiddendirs - search hidden directories in podpath
@@ -667,7 +681,8 @@
}
sub parse_command_line {
- my ($opt_backlink,$opt_cachedir,$opt_css,$opt_flush,$opt_header,$opt_help,
+ my ($opt_backlink,$opt_cachedir,$opt_css,$opt_flush,$opt_fragment_uniq,
+ $opt_header,$opt_help,
$opt_htmldir,$opt_htmlroot,$opt_index,$opt_infile,$opt_libpods,
$opt_netscape,$opt_outfile,$opt_prelink,
$opt_podpath,$opt_podroot,$opt_quote_style_us,$opt_quiet,
@@ -679,6 +694,7 @@
'cachedir=s' => \$opt_cachedir,
'css=s' => \$opt_css,
'flush' => \$opt_flush,
+ 'fragmentuniq!' => \$opt_fragment_uniq,
'header!' => \$opt_header,
'help' => \$opt_help,
'hiddendirs!'=> \$opt_hiddendirs,
@@ -710,6 +726,7 @@
$Cachedir = $opt_cachedir if defined $opt_cachedir;
$Css = $opt_css if defined $opt_css;
$Header = $opt_header if defined $opt_header;
+ $FragmentUniq = $opt_fragment_uniq if defined $opt_fragment_uniq;
$Htmldir = $opt_htmldir if defined $opt_htmldir;
$Htmlroot = $opt_htmlroot if defined $opt_htmlroot;
$Doindex = $opt_index if defined $opt_index;
@@ -2017,7 +2034,8 @@
$heading =~ s/\s+\Z//;
$heading =~ s/\A\s+//;
# The hyphen is a disgrace to the English language.
- $heading =~ s/[-"?]//g;
+ # $heading =~ s/[-"?]//g;
+ $heading =~ s/["?]//g;
$heading = lc( $heading );
return $heading;
}
@@ -2093,12 +2111,38 @@
return $res;
}
+sub fragment_id_readable {
+ my $text = shift;
+
+ # just clean the punctuation and leave the words for the
+ # fragment identifier.
+ $text =~ s/([[:punct:]\s])+/$1/g;
+ $text =~ s/[[:punct:]\s]+\Z//g;
+
+ $text;
+}
+
+my @HC;
+sub fragment_id_unique {
+ my $text = shift;
+
+ # text? Normalize by obfusticating the fragment id to make it unique
+ $text =~ s/\s+/_/sg;
+
+ $text =~ s{(\W)}{
+ defined( $HC[ord($1)] ) ? $HC[ord($1)]
+ : ( $HC[ord($1)] = sprintf( "%%%02X", ord($1) ) ) }gxe;
+ $text = substr( $text, 0, 50 );
+
+ $text;
+}
+
#
# fragment_id - construct a fragment identifier from:
# a) =item text
# b) contents of C<...>
#
-my @HC;
+
sub fragment_id {
my $text = shift();
$text =~ s/\s+\Z//s;
@@ -2121,12 +2165,16 @@
return $1 if $text =~ m{^([a-z\d_]+)(\s+[A-Z\d,/& ]+)?$};
return $1 if $text =~ m{^([a-z\d]+)\s+Module(\s+[A-Z\d,/& ]+)?$};
- # text? normalize!
- $text =~ s/\s+/_/sg;
- $text =~ s{(\W)}{
- defined( $HC[ord($1)] ) ? $HC[ord($1)]
- : ( $HC[ord($1)] = sprintf( "%%%02X", ord($1) ) ) }gxe;
- $text = substr( $text, 0, 50 );
+ my $frag;
+
+ if ( $FragmentUniq ) {
+ $frag = fragment_id_unique($text);
+ } else {
+ $frag = fragment_id_readable($text);
+ }
+
+ $frag;
+
} else {
return undef();
}
[Please do not change anything below this line]
-----------------------------------------------------------------
---
Flags:
category=core
severity=low
---
Site configuration information for perl v5.8.8:
Configured by Debian Project at Wed Dec 6 23:17:41 UTC 2006.
Summary of my perl5 (revision 5 version 8 subversion 8) configuration:
Platform:
osname=linux, osvers=2.6.18.3, archname=i486-linux-gnu-thread-multi
uname='linux saens 2.6.18.3 #1 smp sat nov 25 13:39:52 est 2006 i686 gnulinux '
config_args='-Dusethreads -Duselargefiles -Dccflags=-DDEBIAN -Dcccdlflags=-fPIC -Darchname=i486-linux-gnu -Dprefix=/usr -Dprivlib=/usr/share/perl/5.8 -Darchlib=/usr/lib/perl/5.8 -Dvendorprefix=/usr -Dvendorlib=/usr/share/perl5 -Dvendorarch=/usr/lib/perl5 -Dsiteprefix=/usr/local -Dsitelib=/usr/local/share/perl/5.8.8 -Dsitearch=/usr/local/lib/perl/5.8.8 -Dman1dir=/usr/share/man/man1 -Dman3dir=/usr/share/man/man3 -Dsiteman1dir=/usr/local/man/man1 -Dsiteman3dir=/usr/local/man/man3 -Dman1ext=1 -Dman3ext=3perl -Dpager=/usr/bin/sensible-pager -Uafs -Ud_csh -Uusesfio -Uusenm -Duseshrplib -Dlibperl=libperl.so.5.8.8 -Dd_dosuid -des'
hint=recommended, useposix=true, d_sigaction=define
usethreads=define use5005threads=undef useithreads=define usemultiplicity=define
useperlio=define d_sfio=undef uselargefiles=define usesocks=undef
use64bitint=undef use64bitall=undef uselongdouble=undef
usemymalloc=n, bincompat5005=undef
Compiler:
cc='cc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -DTHREADS_HAVE_PIDS -DDEBIAN -fno-strict-aliasing -pipe -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
optimize='-O2',
cppflags='-D_REENTRANT -D_GNU_SOURCE -DTHREADS_HAVE_PIDS -DDEBIAN -fno-strict-aliasing -pipe -I/usr/local/include'
ccversion='', gccversion='4.1.2 20061115 (prerelease) (Debian 4.1.1-20)', gccosandvers=''
intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234
d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12
ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
alignbytes=4, prototype=define
Linker and Libraries:
ld='cc', ldflags =' -L/usr/local/lib'
libpth=/usr/local/lib /lib /usr/lib
libs=-lgdbm -lgdbm_compat -ldb -ldl -lm -lpthread -lc -lcrypt
perllibs=-ldl -lm -lpthread -lc -lcrypt
libc=/lib/libc-2.3.6.so, so=so, useshrplib=true, libperl=libperl.so.5.8.8
gnulibc_version='2.3.6'
Dynamic Linking:
dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
cccdlflags='-fPIC', lddlflags='-shared -L/usr/local/lib'
Locally applied patches:
---
@INC for perl v5.8.8:
/home/jaalto/var/lib/code/perl
/etc/perl
/usr/local/lib/perl/5.8.8
/usr/local/share/perl/5.8.8
/usr/lib/perl5
/usr/share/perl5
/usr/lib/perl/5.8
/usr/share/perl/5.8
/usr/local/lib/site_perl
/usr/local/lib/perl/5.8.7
/usr/local/share/perl/5.8.7
/usr/local/lib/perl/5.8.4
/usr/local/share/perl/5.8.4
.
---
Environment for perl v5.8.8:
HOME=/home/jaalto
LANG (unset)
LANGUAGE (unset)
LC_ALL=en_US
LD_LIBRARY_PATH (unset)
LOGDIR (unset)
PATH=/usr/local/bin:/home/jaalto/var/link/bin:/sbin:/bin:/usr/bin:/usr/sbin:/usr/share/bin:/usr/bin/X11:/usr/games
PERL5LIB=/home/jaalto/var/lib/code/perl
PERL_BADLANG (unset)
SHELL=/bin/bash
Thread Next
-
[perl #41687] [PATCH] v5.8.8 pod2html -- Add --[no]fragmentuniq to support more readable <a name=..> refs
by Jari Aalto