[PATCH] v5.8.8 pod2html -- Add --[no]fragmentuniq to support more readable <a name=..> refs #8819
Comments
From @jaaltoCreated by jaalto@cante.cante.netDESCRIPTION THe pod2html converter constructs obfusticated <a name=...> frament THE SOLUTION Offer alternate method to construct the frament identifiers in a more The patch implements new option: --[no]fragmentuniq The old, obfusticated id operation, is the deault. User can change the --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> [with option --nofragmentuniq] <dt><strong><a name="item__progress_bar"><strong>-#/--progress-bar</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: === modified file 'Html.pm' Inline Patch--- 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();
}Perl Info |
From @eserteJari Aalto (via RT) <perlbug-followup@perl.org> writes:
Instead of creating a obfuscated id, why not just use an integer Regards, -- tkrevdiff - graphical display of diffs between revisions (RCS, CVS or SVN) |
|
The RT System itself - Status changed from 'new' to 'open' |
From @jaaltoslaven@rezic.de (Slaven Rezic) writes:
Yes, this would be better default for the pod2html
There still is. Consider =pod =item --Verbose =cut Where the link with integer would be http://localhost/index.html#1 Whereas the "human readable", the proposed --fragmentuniq will produce http://localhost/index.html#item_verbose Sharing that link is much more friendly than just number. Jari |
From @tamiasOn Sun, Mar 04, 2007 at 08:52:31PM +0200, Jari Aalto wrote:
Note Slaven suggested *appending the integer to the human readable id*. Ronald |
From @jaaltorjk-perl-p5p@tamias.net (Ronald J Kimball) writes:
Ah, misread that, thanks. Still, it's different to have fragment: #item_verbose [1] Than random number: #item_verbose30 [2] When you post a link to the page, you can just make it directly if you remember Anyway, the patch offers both choices: Globally unique tags or sign Jari |
From @eserteJari Aalto <jari.aalto@cante.net> writes:
Don't append a random number, but start from 1, and do not append #item_verbose and if there was ever another fragment with the same name, then it #item_verbose_1 (or maybe start from 2, as it's really the 2nd fragment with the same Regards, -- tknotes - A knotes clone, written in Perl/Tk. |
From @jaaltoslaven@rezic.de (Slaven Rezic) writes:
Good idea. I've reworked the patch as follows: - No more special option --fragmentuniq Jari USE CASE [v5.8.8. original pod2html] <dt><strong><a name="item__2d_23_2f_2d_2dprogress_2dbar"><strong>-#/--progress-bar</strong></a></strong> USE CASE [after the patch] <dt><strong><a name="progress_bar" class="item"><strong>-#/--progress-bar</strong></a></strong> NEW PATCH [ /usr/share/perl/5.8.8/Pod/Html.pm ] === modified file 'Html.pm' Inline Patch--- Html.pm 2007-03-05 08:02:39 +0000
+++ Html.pm 2007-03-07 07:31:02 +0000
@@ -216,7 +216,6 @@
=cut
-
my($Cachedir);
my($Dircache, $Itemcache);
my @Begin_Stack;
@@ -1107,7 +1106,7 @@
sub emit_item_tag($$$){
my( $otext, $text, $compact ) = @_;
- my $item = fragment_id( $text );
+ my $item = fragment_id( $text , -generate);
$EmittedItem = $item;
### print STDERR "emit_item_tag=$item ($text)\n";
@@ -1116,9 +1115,9 @@
if ($Items_Named{$item}++) {
print HTML process_text( \$otext );
} else {
- my $name = 'item_' . $item;
+ my $name = $item;
$name = anchorify($name);
- print HTML qq{<a name="$name">}, process_text( \$otext ), '</a>';
+ print HTML qq{<a name="$name" class="item">}, process_text( \$otext ), '</a>';
}
print HTML "</strong>\n";
undef( $EmittedItem );
@@ -1981,7 +1980,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;
}
@@ -2057,14 +2057,70 @@
return $res;
}
+{
+ my %seen; # static fragment record hash
+
+sub fragment_id_readable {
+ my $text = shift;
+ my $generate = shift; # optional flag
+
+ my $orig = $text;
+
+ # just clean the punctuation and leave the words for the
+ # fragment identifier.
+ $text =~ s/([[:punct:]\s])+/$1/g;
+ $text =~ s/[[:punct:]\s]+\Z//g;
+
+ # "=item --version", remove leading punctuation.
+ $text =~ s/^[-[:punct:]]//;
+
+ unless ($text)
+ {
+ # Nothing left after removing punctuation, so leave it as is
+ # E.g. if option is named: "=item -#"
+
+ $text = $orig;
+ }
+
+ if ($generate) {
+ if ( exists $seen{$text} ) {
+ # This already exists, make it unique
+ $seen{$text}++;
+ $text = $text . $seen{$text};
+ } else {
+ $seen{$text} = 1; # first time seen this fragment
+ }
+ }
+
+ $text;
+}}
+
+my @HC;
+sub fragment_id_obfusticated { # This was the old "_2d_2d__"
+ my $text = shift;
+ my $generate = shift; # optional flag
+
+ # 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();
+ my $text = shift;
+ my $generate = shift; # optional flag
+
$text =~ s/\s+\Z//s;
if( $text ){
# a method or function?
@@ -2085,12 +2141,8 @@
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 );
+ fragment_id_readable($text, $generate);
+
} else {
return undef();
} |
|
@rgs - Status changed from 'open' to 'resolved' |
From @jaaltorgarciasuarez@gmail.com ("Rafael Garcia-Suarez") writes:
That's good, thank you, |
From @rgarciaOn 07/03/07, Jari Aalto <jari.aalto@cante.net> wrote:
Thanks, applied as change #30584 (with test adjustments). |
Migrated from rt.perl.org#41687 (status was 'resolved')
Searchable as RT41687$
The text was updated successfully, but these errors were encountered: