Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw

Re: Pod::Master

by mojotoad (Monsignor)
on Nov 07, 2002 at 14:54 UTC ( #211085=note: print w/replies, xml ) Need Help??

in reply to Pod::Master

Nice work!

I have a minor layout issue; perhaps it's just how my brain works. In the one-shot module description, I'd consider putting the NAME/description up at the top, above the TOC. It shouldn't add so much space that the TOC is pushed off the bottom of the page; with the unnamed TOC on top I had to scramble around with my eyes a bit to find the name of the module. Perhaps just an extra blurb at the top of the TOC would suffice, in addition to a NAME section.

Also, in your example POD for Pod::Master, I see no DEPENDENCIES section. Will this be handled in a generic POD way, or will it take advantage of that nifty INSTALLED MODULES format?

Again, nice work.

Replies are listed 'Best First'.
Re: Re: Pod::Master
by PodMaster (Abbot) on Nov 07, 2002 at 17:45 UTC

    Oh yeah, I switched SYNOPSIS/DESCRIPTION, d'oh ;)

    And the 2nd d'oh, I generated that page by hand , without the --header option, here's what it really looks like by default (d'oh).

    Now, I am not subclassing Pod::Html, so whatever Pod::Html does, it does on its own (i myself like the toc)

    What does Will this be handled in a generic POD way, or will it take advantage of that nifty INSTALLED MODULES format? mean?

    What is a "generic POD way"? And how would I take advantage of "that nifty INSTALLED MODULES format?"

    I kind of think DEPENDENCIES belong in the README/Makefile.PL, so that's why I didn't put it in the pod.

    I'm pretty satisfied with Pod::Html and I don't plan on re-inventing it any time soon (i'm satisfied in writing patches ;)

    ** The Third rule of perl club is a statement of fact: pod is sexy.

      Don't get me wrong, I like the TOC as well -- it was just an issue of visually locating the name of the module immediately.

      By generic POD I just meant normal =head1 plus either items or a comma-separated list of dependencies. It wasn't really a clearly thought-out question, but it seemed you had more going on with the code that generated the INSTALLED MODULES than merely POD parsing. I guess I'm secretly desiring some tool, other than perl -c, that will recursively trace dependencies and present them in an outline format.

      You are right that lots of modules do indeed put the dependencies in README/Makefile.PL (as well as perhaps POD). A dependency-sniffer would no doubt get tripped up on optional dynamic dependencies as well. :(


Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://211085]
[choroba]: I mean, the slides are, but not the makefile with scripts to create them
[Corion]: haukex: I've only now arrived at that revelation ;)
[Corion]: choroba: I use spod5, which also has that support, and also implements its own kinda-make stuff
[haukex]: But that module I just linked to assumes that most verbatim blocks are runnable code, I have other modules where that's not the case, so there I just copy-and-paste the synopsis into the author tests...
[haukex]: not the most efficient, but then again, I don't have that many modules on CPAN :-)
[Corion]: haukex: Yes, but if it's only supposed to run on my machine, I can be far more liberal with how I extract the code etc.
[Corion]: haukex: Yes - I see the benefit of using Dist::Zilla for people with 150+ modules on CPAN, but I don't see it for myself, and I'm always put off from contributing to such modules because they require a lot of toolchain setup that I don't want to ...
[Corion]: ... spend time on if I only want to provide a short patch
[haukex]: Corion: Yes exactly, in the author tests I don't worry about portability as much, I also don't list the author tests' dependencies in Makefile.PL
[haukex]: I figure someone who wants to contribute will know how to install the missing modules ;-) Not the nicest way to go but I don't think many people are using my modules yet

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (13)
As of 2017-02-27 12:34 GMT
Find Nodes?
    Voting Booth?
    Before electricity was invented, what was the Electric Eel called?

    Results (385 votes). Check out past polls.