Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

README 20 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • Man, why should there be a logical structure? That's just crazy talk, man!  ;-)

    • Right! There's More Than One Way to Do It! Fight the power!

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
  • I think Licenses is unnecessary - RMS can bite my shiny metal ass. As can your lawyer. As long as you have a LICENSE section in your POD (I violate this in several modules though).

    Telling me that Makefile.PL shouldn't prompt though is just wrong. There's a lot of cases where it should. What about optional modules (via ExtUtils::AutoInstall - the recommended way by CPAN testers)? What about locations of things like the httpd when you need to test mod_perl modules (and no, finding it in the usual paths isn't

    • Prompting: well, like I said, it's not always possible. But if you can get those things into command line arguments it means I can decide them all up front and come back to that window after lunch. (It also makes it easier to put modules into core. The main perl source has recently eliminated one of the last interactive prompts (at install time). Of course, you may never want your mod_perl modules in core.  :) ) If someone's installing something as complicated as a mod_perl module, I'd say there's

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
      • I *think* ExtUtils::AutoInstall allows some command line flags to either install everything or install nothing. Not sure though.

        As for CD makers, they should take some more time and effort over it - contact the authors of things you want to put on there, and offer them a free copy ferchristsake. The CPAN is a free resource and everyone can get it, so don't try and con people into thinking that it's a massive bonus to be able to get a version of this software without downloading it.

    • Sorry, Matt, you're completely wrong. Any questions that your Makefile.PL needs should be supplied on the command line or in environment variables. If it can't autodetect what it needs then it should die and say so.

      Non-Interactivity is an absolute necessity when you're building packages from modules and expecting them to work.

      If you want to do clever stuff, let the advanced user that needs to do it read the damn docs and figure out how to do so. Optimise for the common case by not asking questions.

      • I'm not WRONG. I just have a different opinion to you.

        Writing installers is probably the hardest part of every single software project I've ever worked on. Period. This is not something Open Source developers need to be wasting their time on when they can ask questions and have an easier life.

        Feel free to supply patches.

        • Feel free to supply patches.

          That's the real answer. "Right" and "wrong" are really defined by the module author. If someone else wants it another way, is willing to do the work, and the module author doesn't mind, great!

          But I think you'll find most of us increasingly prefer non-interactive installations.

          --
          J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
  • One thing that screwed me up in some of my first releases to CPAN was this note from the PAUSE site [cpan.org]

    Do not upload the READMEs that are integrated in your distribution files. PAUSE is designed to take care of unwrappig your file with tar or zip, registering all the modules it finds in there, and placing the readme file (i.e. a file with the name README in the top level directory of your package) into your directory. PAUSE will change the name of the file to package-name.readme. It should do so within a few

  • I don't like having information spread over all the different files, so I am tending more and more to put all documentation in well-named and well-placed sections in the Pod. I just generate the README that.

    Since I say the Pod must always start with why you should use the module, that makes for a relevent README.

    This approach also simplifies things for makepmdist and its users.

    • That makes sense, too. The main thing is, I hate looking at a module, thinking, "What does that do?" and then reading installation instructions or licensing info in the README.  :) Secondarily, I hate looking for something in the place where I expect it (Changes, for example) and not finding it, and having to search through three other files to find out where s/he put it.

      So a relaxed generalization of my preferences is, "Put what I want in the place where I expect it. Other stuff is cool, if it's

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
  • It's all too complicated. I would simplify it down completely and make it easier on the author.

    I don't think README files are necessary any more, now that we have search.cpan.org. It's always out of sync with the main module documentation anyway, so move everything there instead.

    Likewise, INSTALL is silly. Everyone knows how to install a simple Perl module thesedays, and if it's tricky, then put more magic code in your Makefile.PL  ;-)

    My recent crusade is against interactive Makefile.PLs. They shoul

    • My recent crusade is against interactive Makefile.PLs.

      Woohoo! Somebody agrees!  :)

      Everyone knows how to install a simple Perl module thesedays

      Exactly my point. I know, and I'm tired of reading it where a description of the module should be. I personally wouldn't be affected at all if there were no installation instructions with the module.

      Been thinking about trying out Gentoo. It seems to provide all the benefits of LFS and Debian, and I hear it will work on my iBook!

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers

    • I'm totally with you on non interactivity. It's exactly the same reason that I hate perl's default Configure script. I just want to come back and find it built, or find an error telling me why not.

      If you want some hints about getting CPAN integrated with a packaging system, you might want to look at the BSDPAN stuff that's included in FreeBSD-CURRENT. I haven't used it, but it's meant to auto-package CPAN modules into FreeBSD packages when they're installed via CPAN.pm.

  • The README should not include your module's documentation. That's what the embedded POD is for. The README should not include installation instructions. That's what the INSTALL file is for.

    Your README should definitely not consist solely of module installation instructions.

    Man, you're just going to love this particular example then.

    There's this module that just got uploaded on CPAN. The README with it contains... well: nothing. Nothing at all, except what h2xs put there as an example, I think. Christ. I

    • I know. What do you think prompted my rant? :) [This is by no means the first module to do this.]

      I think h2xs shouldn't say that the README should include installation instructions, because I don't think that's where those instructions should go. Or, at least, they should be shoved down at the bottom under the "Why do I want to use this module?" part.

      Petal is sort of a bad name for a module, too. Great name for a program. Maybe it's a huge configuration management system. Maybe it's an automatic d

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
    • Well whatdayaknow... 3 days later, and there is a new upload for Petal (uploaded yesterday), and this one does have a proper readme file...
      Readme for Petal 0.3 [cpan.org]

      Not only that, but by the looks of it, the module does indeed look very interesting. And now, we can know about it.

Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.