confused about POD

[ccc31807]

This might be just a mental glitch, but I seem to be having a problem
wrapping my mind around POD. My mental image is javadoc, which allows
me to produce HTML documentation of Java classes from internal
documation (in Javadoc format) by running a command.

If I document my Perl code (either an executable or a PM) using POD
formatted text, what command do I run to produce a series of HTML
pages?

What I want to do is pass a source listing (such as some_script.plx,
or SOMEPM.pm or <some_perl_dir>) to a utility and have it output HTML
files.

Thanks, CC.

[bugbear]

http://lmgtfy.com/?q=POD+html

BugBear

[ccc31807]

On May 25, 11:17 am, bugbear <bugbear@trim_papermule.co.uk_trim>
wrote:
> http://lmgtfy.com/?q=POD+html

Yeah. I tried that. This isn't the same as the javadoc command.

I can write a (small) perl script that takes a file or a list of files
as input, and produces an html file for each input, plus an index.html
that hyper links all of them. However, I'd have to spend several days
to get it right. It seems to me that this is something that someone
else might have written, but I can't seem to find it.

Maybe I'm unique in that this is the first time that someone has
thought of this. I think not ... which is why I'm confused.

Thanks, CC.

[Jim Gibson]

In article
<9e847891-17d3-4223...@i19g2000yqn.googlegroups.com>,

Have you looked on CPAN for POD-processing modules? You will get lots
of hits. (I haven't tried any of them). So, no, you are not the first
person who has tried this.

perldoc is not the same as javadoc. javadoc will scan the Java source
and extract information from Java methods and annotations. perldoc
scans the Perl code and extracts information from between POD tags that
is independent of the code.

--
Jim Gibson

[Brian Helterline]

On 5/25/2012 7:47 AM, ccc31807 wrote:
> If I document my Perl code (either an executable or a PM) using POD
> formatted text, what command do I run to produce a series of HTML
> pages?
>
> What I want to do is pass a source listing (such as some_script.plx,
> or SOMEPM.pm or<some_perl_dir>) to a utility and have it output HTML
> files.

For ActivePerl on Windows, when you use their PPM tool to install
modules, it grabs the module, installs it and generates HTML on the fly
to add into index.html. You could take a peak into that code to see how
they do it. I am pretty sure it is all perl.

-brian

[ccc31807]

On May 25, 1:19 pm, Brian Helterline <brian.helterl...@hp.com> wrote:
> For ActivePerl on Windows, when you use their PPM tool to install
> modules, it grabs the module, installs it and generates HTML on the fly
> to add into index.html.  You could take a peak into that code to see how
> they do it. I am pretty sure it is all perl.

Yeah, same idea but with the code I write. We lost a programmer who
left eight years of code and ZERO documentation (not Perl code).

Guess what the latest initiative of management is right about now!

I never minded writing javadoc comments, and I don't mind writing perl
comments in POD format. I /do/ mind jumping through hoops to generate
HTML pages.

I use Strawberry (on M$), but looking at ActvePerl is a good idea.
Thanks.

CC.

[Peter J. Holzer]

On 2012-05-25 15:26, ccc31807 <cart...@gmail.com> wrote:
> On May 25, 11:17 am, bugbear <bugbear@trim_papermule.co.uk_trim>
> wrote:
>> http://lmgtfy.com/?q=POD+html
>
> Yeah. I tried that. This isn't the same as the javadoc command.
>
> I can write a (small) perl script that takes a file or a list of files
> as input, and produces an html file for each input, plus an index.html
> that hyper links all of them. However, I'd have to spend several days
> to get it right. It seems to me that this is something that someone
> else might have written, but I can't seem to find it.

Well, the obvious script "that someone else might have written" is of
course pod2html. Maybe you should start by explaining why that isn't
adequate for your needs (I can think of a couple of reasons, but my
reasons are probably not the same as your reasons).

hp


--
_ | Peter J. Holzer | Deprecating human carelessness and
|_|_) | Sysadmin WSR | ignorance has no successful track record.
| | | h...@hjp.at |
__/ | http://www.hjp.at/ | -- Bill Code on as...@irtf.org

[jl_...@hotmail.com]

On May 25, 8:47 am, ccc31807 <carte...@gmail.com> wrote:
>
> If I document my Perl code (either an executable or a PM) using POD
> formatted text, what command do I run to produce a series of HTML
> pages?

You can use "pd2html" to accomplish that. For example, let's say
you want to read the perldocs for the Math::BigInt module. You can
read them straight up with the command:

perldoc Math::BigInt

but if you'd rather read them with a web browser, you can use
"pod2html" like this:

pod2html Math::BigInt > math_bigint_documentation.html

then open the file "math_bigint_documentation.html" in your favorite
web browser, and enjoy!

There are more formats you can read the perldocs in. For example,
if you prefer to read a LaTeX-formatted documentation, you can create
one with the command:

pod2latex Math::BigInt > latex_file

Incidentally, I can't always remember the proper formatting codes
to use, and instead of looking them up with "perldoc perlpod",
sometimes I prefer to pick apart an already written POD and learn by
example. (If you haven't figured it out by now, I often use the
Math::BigInt module to see how some POD formatting was done.)

If I want to see how some formatting was done in the Math::BigInt
module, I type:

perldoc -l Math::BigInt
(that's the letter "ell", not the number 1)

That shows me where the module's file is literally located, then I can
read it with any text viewer/editor I have available.

I can also skip a step just by typing:

perldoc -m Math::BigInt

and then I'll be immediately shown the module file's exact contents
(code, POD, and all).

I hope this helps!

-- Jean-Luc

[ccc31807]

On May 25, 4:03 pm, "Peter J. Holzer" <hjp-usen...@hjp.at> wrote:
> Well, the obvious script "that someone else might have written" is of
> course pod2html. Maybe you should start by explaining why that isn't
> adequate for your needs (I can think of a couple of reasons, but my
> reasons are probably not the same as your reasons).

The simple answer is that it doesn't do what I want it to.

For example, suppose I have the directory listing shown below because
it's rather lengthy.

Further suppose I run the following command at the command prompt,

> generate_html_from_embedded_pod_in_perl_source_files *.pm *.plx *.cgi

expecting it to generate a sub-directory (perhaps called
'documentation') with the following files:
- index.html
- CCC_LOCATIONS.html
- console.html
- SQL.html
- etc.

I want a separate html file for every perl source file. I want the
index.html to list and link to each html file and each html file to
extract all the POD embedded in each plx, pm, or cgi file. pod2html
doesn't do this.

If nothing does this, it's okay. With a little effort I can write a
clunky something that does a minimal job. Obviously, I'd rather use
something the has been written and tested by someone who knows what
they are doing better than I do.

Thanks, CC.

04/25/2012 03:41 PM 152,319 ACAD_PROGS.pm
04/25/2012 10:01 AM 19,985 CAS.csv
04/26/2012 02:09 PM 14,618 cas_courses.csv
04/30/2012 01:49 PM 31,020 cas_courses.sql
04/25/2012 01:04 PM 3,656 CCC_LOCATIONS.plx
04/25/2012 10:00 AM 17,685 COE.csv
05/07/2012 12:06 PM 1,761 console.cgi
05/07/2012 01:16 PM 14,195 courses.cgi
05/07/2012 01:17 PM 329 courses_20120507.csv
04/26/2012 03:09 PM 3,369 coursetest.sql
05/07/2012 01:42 PM 1,635 database_schedules.plx
04/25/2012 03:25 PM 342 database_schema.txt
04/26/2012 09:07 AM 25,491 fac.csv
04/30/2012 05:07 PM 5,174 faculty.cgi
04/30/2012 04:13 PM 70,568 faculty.sql
04/30/2012 04:04 PM 10,916 get_resource.cgi
05/07/2012 11:58 AM 3,234 HTML.pm
05/07/2012 12:07 PM 2,498 locations.cgi
04/25/2012 02:08 PM 3,554 locations.sql
05/04/2012 05:11 PM 660 print_csv.cgi
05/07/2012 12:05 PM 3,161 programs.cgi
04/25/2012 04:03 PM 198,723 programs.sql
05/04/2012 05:42 PM 1,532 question.plx
04/27/2012 11:12 AM 1,606 schedules.css
05/07/2012 12:08 PM 192,512 schedules.db
04/03/2012 09:55 AM 74,955 SER_FINAL_FAC.pm
05/01/2012 12:52 PM 3,069 SER_programs.plx
05/04/2012 10:25 AM 4,857 SER_programs.sql
05/07/2012 12:05 PM 4,245 SQL.pm
04/30/2012 10:49 AM 424 term.sql
05/07/2012 11:16 AM 2,345 terms.cgi
05/04/2012 10:36 AM 2,197 todo.plx

[Peter J. Holzer]

On 2012-05-25 21:41, ccc31807 <cart...@gmail.com> wrote:
> On May 25, 4:03 pm, "Peter J. Holzer" <hjp-usen...@hjp.at> wrote:
>> Well, the obvious script "that someone else might have written" is of
>> course pod2html. Maybe you should start by explaining why that isn't
>> adequate for your needs (I can think of a couple of reasons, but my
>> reasons are probably not the same as your reasons).
>
> The simple answer is that it doesn't do what I want it to.
>
> For example, suppose I have the directory listing shown below because
> it's rather lengthy.
>
> Further suppose I run the following command at the command prompt,
>
>> generate_html_from_embedded_pod_in_perl_source_files *.pm *.plx *.cgi
>
> expecting it to generate a sub-directory (perhaps called
> 'documentation') with the following files:
> - index.html
> - CCC_LOCATIONS.html
> - console.html
> - SQL.html
> - etc.
>
> I want a separate html file for every perl source file.

Since pod2html works on a single file anyway, you get that naturally.
You just have to invoke pod2html on every file, for example like this:

for i in scripts/* lib/**/*.pm
do
mkdir -p ${i%/*}
pod2html --htmlroot=http://example.org/doc/
--infile=$i
--outfile=echo ${i%%.pm}.html
--podroot=lib
done

(zsh syntax, untested)

> I want the index.html to list and link to each html file

pod2html doesn't do this - you'd have to build the index in the loop
shown above.

It does, however, create links between the pages.

> and each html file to extract all the POD embedded in each plx, pm, or
> cgi file.

It does do this (one file at a time).

> pod2html doesn't do this.

Well, AFAICS it does everything except for a trivial loop and and index.

Now for the reasons why I don't like pod2html:

* It adds annoying verbage to links, for example a sentence like
"This method returns a list of L<Foo::Bar> objects." becomes "this
method returns a list of <a href=".../Foo/Bar.html">the Foo::Bar
manpage</a> objects". This is hard-coded and not configurable.
* Sometimes it's hard to get your links to point where you want them
(sorry, no current example, but I've wrestled with that in the past).
(This may in fact be a problem with the POD format)
* The HTML output is really inflexible, there isn't even support for
including a style sheet.

> If nothing does this, it's okay.

There are at least two website which automatically convert large amounts
of POD into (rather pretty) HTML:

http://search.cpan.org
http://perldoc.perl.org

I think the source code for both is available.

[Ben Morrow]

Quoth "Peter J. Holzer" <hjp-u...@hjp.at>:

> On 2012-05-25 21:41, ccc31807 <cart...@gmail.com> wrote:
> >
> > I want the index.html to list and link to each html file
>
> pod2html doesn't do this - you'd have to build the index in the loop
> shown above.
>

<snip>

>
> Now for the reasons why I don't like pod2html:
>
> * It adds annoying verbage to links, for example a sentence like
> "This method returns a list of L<Foo::Bar> objects." becomes "this
> method returns a list of <a href=".../Foo/Bar.html">the Foo::Bar
> manpage</a> objects". This is hard-coded and not configurable.

So does Pod::Man, used by default by command-line perldoc; the practice
originated there, since man doesn't support hyperlinks. (IMHO a simple
'...returns a list of Foo::Bar(3pm) objects' as is usual with manpage
cross-refernces would have been better, but there we go.) This is
documented in the perlpod manpage, and POD authors are supposed to
either make their sentences make sense with the additions or use the
L<...|...> syntax to suppress them. (I do the latter, and yes, it's
extremely annoying.)

Modern POD formatters don't add them, since it has been deemed Not
Helpful, but until perldoc's default format changes to something
Pod::Simple-based PODpages still need to be written on the assumption
they may be added.

> * Sometimes it's hard to get your links to point where you want them
> (sorry, no current example, but I've wrestled with that in the past).
> (This may in fact be a problem with the POD format)
> * The HTML output is really inflexible, there isn't even support for
> including a style sheet.

Pod::Simple::HTML generates much better, and much more customisable,
HTML; and Pod::Simple::HTMLBatch will convert a whole tree and make you
an index.

Ben