confused about POD

Discussion in 'Perl Misc' started by ccc31807, May 25, 2012.

  1. ccc31807

    ccc31807 Guest

    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.
    ccc31807, May 25, 2012
    #1
    1. Advertising

  2. ccc31807

    ccc31807 Guest

    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.
    ccc31807, May 25, 2012
    #2
    1. Advertising

  3. ccc31807

    Jim Gibson Guest

    In article
    <>,
    ccc31807 <> 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.
    >
    > 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.


    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
    Jim Gibson, May 25, 2012
    #3
  4. 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
    Brian Helterline, May 25, 2012
    #4
  5. ccc31807

    ccc31807 Guest

    On May 25, 1:19 pm, Brian Helterline <> 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.
    ccc31807, May 25, 2012
    #5
  6. On 2012-05-25 15:26, ccc31807 <> 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.
    | | | |
    __/ | http://www.hjp.at/ | -- Bill Code on
    Peter J. Holzer, May 25, 2012
    #6
  7. ccc31807

    Guest

    On May 25, 8: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?



    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
    , May 25, 2012
    #7
  8. ccc31807

    ccc31807 Guest

    On May 25, 4:03 pm, "Peter J. Holzer" <> 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
    ccc31807, May 25, 2012
    #8
  9. On 2012-05-25 21:41, ccc31807 <> wrote:
    > On May 25, 4:03 pm, "Peter J. Holzer" <> 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.

    hp


    --
    _ | Peter J. Holzer | Deprecating human carelessness and
    |_|_) | Sysadmin WSR | ignorance has no successful track record.
    | | | |
    __/ | http://www.hjp.at/ | -- Bill Code on
    Peter J. Holzer, May 26, 2012
    #9
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Amontec Team, Laurent Gauch

    interfacing Chameleon POD

    Amontec Team, Laurent Gauch, Feb 5, 2004, in forum: VHDL
    Replies:
    0
    Views:
    585
    Amontec Team, Laurent Gauch
    Feb 5, 2004
  2. dede
    Replies:
    0
    Views:
    392
  3. John Dibling

    Definition of POD types

    John Dibling, Aug 11, 2003, in forum: C++
    Replies:
    3
    Views:
    994
    John Dibling
    Aug 11, 2003
  4. Ajax Chelsea

    Is array of POD still a POD type?

    Ajax Chelsea, Dec 1, 2003, in forum: C++
    Replies:
    1
    Views:
    335
    Ron Natalie
    Dec 1, 2003
  5. Himanshu Garg
    Replies:
    1
    Views:
    148
    Himanshu Garg
    Sep 21, 2003
Loading...

Share This Page