[PATCH] v5.8.8 pod2html -- Add <div>..</div> around the outputted INDEX section #8821

p5pRT · 2007-03-04T21:33:14Z

Migrated from rt.perl.org#41698 (status was 'resolved')

Searchable as RT41698$

p5pRT · 2007-03-04T21:33:19Z

From @jaalto

Created by jaalto@cante.cante.net

Applying a style sheet (CSS) to a pod2html generated index entry is
quite difficult. The following patch wraps the index inside
<div>...</div> structure for more easier management.

USE CASE [before]

<ul>

<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>

<li><a href="#progress_meter">PROGRESS METER</a></li>
</ul>

<li><a href="#options">OPTIONS</a></li>
<li><a href="#files">FILES</a></li>
<li><a href="#environment">ENVIRONMENT</a></li>
<li><a href="#exit_codes">EXIT CODES</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#authors">AUTHORS</a></li>
</ul>

<hr />

USE CASE [after the patch]

<div name="index">
<p><a name="__index__"></a></p>

<ul>

<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>

<li><a href="#progress_meter">PROGRESS METER</a></li>
</ul>

<li><a href="#options">OPTIONS</a></li>
<li><a href="#files">FILES</a></li>
<li><a href="#environment">ENVIRONMENT</a></li>
<li><a href="#exit_codes">EXIT CODES</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#authors">AUTHORS</a></li>
</ul>

[ /usr/share/perl/5.8.8/Pod/Html.pm ]

=== modified file 'Html.pm'

Inline Patch

--- Html.pm     2007-03-04 19:08:25 +0000
+++ Html.pm     2007-03-04 21:31:00 +0000
@@ -512,13 +512,25 @@
     # still generate an index, but surround it with an html comment.
     # that way some other program can extract it if desired.
     $index =~ s/--+/-/g;
-    print HTML "<p><a name=\"__index__\"></a></p>\n";
-    print HTML "<!-- INDEX BEGIN -->\n";
-    print HTML "<!--\n" unless $Doindex;
-    print HTML $index;
-    print HTML "-->\n" unless $Doindex;
-    print HTML "<!-- INDEX END -->\n\n";
-    print HTML "<hr />\n" if $Doindex and $index;
+
+    my $hr = ($Doindex and $index) ? qq(<hr name="index" />) : "";
+
+    unless ($Doindex)
+    {
+        $index = qq(<!--\n$index\n-->\n);
+    }
+
+    print HTML << "END_OF_INDEX";
+
+<!-- INDEX BEGIN -->
+<div name="index">
+<p><a name=\"__index__\"></a></p>
+$index
+$hr
+</div>
+<!-- INDEX END -->
+
+END_OF_INDEX

     # now convert this file
     my $after_item;             # set to true after an =item

Perl Info


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

p5pRT · 2007-03-05T17:53:13Z

From nospam-abuse@bloodgate.com

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Moin Jari,

On Sunday 04 March 2007 21:33:20 Jari Aalto wrote:

# New Ticket Created by Jari Aalto
# Please include the string: [perl #41698]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=41698 >

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]

Applying a style sheet (CSS) to a pod2html generated index entry is
quite difficult. The following patch wraps the index inside
<div>...</div> structure for more easier management.
[snip]

Jari, I do think that your bugreports are sensible, and thorough and backed
up with patches. However, I would also like to note that pod2html is
outdated, and big, giant hack.

We now have that nide, shiny thing called Pod::Simple, which is a nice,
extensible POD parser.

And it has a part called Pod::Simple::HTML. This module currently has some
problems (like not being easily subclassable, and not handing the
output/input stream in a manner actually nec. for HTML generation, but I
disgres).

So instead of hacking further on pod2html, and thus prolong the life of a
broken tool, I would suggest that we instead hack on Pod::Simple::HTML (or
XHTML) and finally get if of the ground.

Many of your problems could be really easily solved with a clean POD parser
(we have that) and a clean HTML generator (we lack this).

Do you think that would be something you could do?

All the best,

Tels

- --
Signed on Mon Mar 5 18:41:55 2007 with key 0x93B84C15.
View my photo gallery: http://bloodgate.com/photos
PGP key on http://bloodgate.com/tels.asc or per email.

"helft den armen vögeln"

-- gegen kleinschreibung
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)

iQEVAwUBRexlL3cLPEOTuEwVAQIIwAf9Esy2/qiAVsSrC2vppwaueQyGZdh9+KK2
353aDgp8XpXgUQpi5ipQnhpK/3k4W2xr8gLX02a9mdvXcuKwerdhrErBUDjIn7/I
MPKm7fMdTKGHeqUOWi25IAYxOOSuVHs0RISEJdn+zNtRMIf4xs8gwcUUguLoLw/N
PN/SAkdceWTqN97Uq1C/AgRMBjERMY/3ts3ZD/lYxHSggQHSLYAjizREb1M+LVaT
YZ/Y2aZp7dzyOO/kVZDjGdw7IBWyz/Svr9r7sSB1OeMrl32iz7AQ0bgRb+Yl4Hmd
s7Ud7K2+bfo3kQJEGjKeGkfNZMY5o5Pny5DdKSw2s0cPhDGncWrA9w==
=0mPK
-----END PGP SIGNATURE-----

p5pRT · 2007-03-05T17:53:14Z

The RT System itself - Status changed from 'new' to 'open'

p5pRT · 2007-03-05T23:38:57Z

From @jaalto

nospam-abuse@bloodgate.com (Tels) writes:

# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=41698 >
Applying a style sheet (CSS) to a pod2html generated index entry is
quite difficult. The following patch wraps the index inside
<div>...</div> structure for more easier management.

Jari, I do think that your bugreports are sensible, and thorough and backed
up with patches. However, I would also like to note that pod2html is
outdated, and big, giant hack.

I agree that pod2html seems like after thought but I have neem using
it very long time. It has resisted time comparable well.

It's only now when I ran into project where I really needed CSS to
format POD pages and found pod2html no up to the task. Even the Perl
documentation is much more beatiful:

http://perldoc.perl.org/perlpod.html

So these must be be some CSS thingies going at Perl Head Quartes. I
wonder why nobody has touched pod2html in years, years.

We now have that nide, shiny thing called Pod::Simple, which is a nice,
extensible POD parser.

And it has a part called Pod::Simple::HTML. This module currently has some
problems (like not being easily subclassable, and not handing the
output/input stream in a manner actually nec. for HTML generation, but I
disgres).

So instead of hacking further on pod2html, and thus prolong the life of a
broken tool, I would suggest that we instead hack on Pod::Simple::HTML (or
XHTML) and finally get if of the ground.

I agree that replacement and proper support for POD is welcomed. Thank
you for that.

I do believe that it is worth improving the pod2html. Especially if
the changes could be made to 5.10. All the patches are relatively
small, very local and fix simple, but irrating issues.

I don't expect pod2html to be end of it's life - not yet.

It can be phased out when the features are complete; then the change
won't be noticed by the uses if switch at some point to
Pod::Simple::HTML happens.

So, if you ask me -- please put in the patches and great many are
happy in the field.

Many of your problems could be really easily solved with a clean POD parser
(we have that) and a clean HTML generator (we lack this).

Do you think that would be something you could do?

I'd be happy to lend sime time if possible. As you know we usually
want to fix things at hand that need immediate actions. It should be
that way: to respond to problems in timely manner

Whether I can put more effort there is question, depends how occupied
I am in other projests at hand, but I do promise to take a serious
look.

Jari

p5pRT · 2007-03-14T15:51:25Z

@rgs - Status changed from 'open' to 'resolved'

p5pRT · 2007-03-14T17:23:09Z

From @rgarcia

On 04/03/07, via RT Jari Aalto <perlbug-followup@perl.org> wrote:

Applying a style sheet (CSS) to a pod2html generated index entry is
quite difficult. The following patch wraps the index inside
<div>...</div> structure for more easier management.

Thanks, applied as #30583.

p5pRT closed this as completed Mar 14, 2007

p5pRT added Severity Low distro-Linux type-core labels Oct 18, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[PATCH] v5.8.8 pod2html -- Add <div>..</div> around the outputted INDEX section #8821

[PATCH] v5.8.8 pod2html -- Add <div>..</div> around the outputted INDEX section #8821

p5pRT commented Mar 4, 2007

p5pRT commented Mar 4, 2007

p5pRT commented Mar 5, 2007

p5pRT commented Mar 5, 2007

p5pRT commented Mar 5, 2007

p5pRT commented Mar 14, 2007

p5pRT commented Mar 14, 2007

[PATCH] v5.8.8 pod2html -- Add <div>..</div> around the outputted INDEX section #8821

[PATCH] v5.8.8 pod2html -- Add <div>..</div> around the outputted INDEX section #8821

Comments

p5pRT commented Mar 4, 2007

p5pRT commented Mar 4, 2007

From @jaalto

Created by jaalto@cante.cante.net

p5pRT commented Mar 5, 2007

From nospam-abuse@bloodgate.com

p5pRT commented Mar 5, 2007

p5pRT commented Mar 5, 2007

From @jaalto

p5pRT commented Mar 14, 2007

p5pRT commented Mar 14, 2007

From @rgarcia