Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical

avoiding writing readme for scripts

by Anonymous Monk
on Oct 16, 2000 at 18:40 UTC ( #36913=perlquestion: print w/replies, xml ) Need Help??

Anonymous Monk has asked for the wisdom of the Perl Monks concerning the following question:

Just out simple curiosity. Is there a module that writes the readme.txt file for a script. I just wrote a script for school,a dn now they want me to write something about it, so the non-Perl users can set it up. Ahhhh... must avoid non-programming work.

Replies are listed 'Best First'.
Re: avoiding writing readme for scripts
by KM (Priest) on Oct 16, 2000 at 18:45 UTC
    When Larry says a virtue is to be Lazy, he didn't mean to be a Lazy SoB. Part of programming is to write the README files so users know how to use the stuff you write. Not everyone can read Perl, or read everyones style of Perl and the README helps to remedy this. If you used POD within your script, you could extract it.. otherwise, it would be good practice, especially for a student, to write a decent README for your script. Sometimes when writing how to use a script you can see things that don't make sense, aren't obvious, and things that in general would be good to fix. So, do everyone a favor, and write your README.. it is not programming, but still the work of any respectable programmer (IMO).


      In fact Larry wants you to turn all of those normally bad things into virtues by doing them in an enlightened manner.

      Have hubris but maintain it intact by being good enough to justify it.

      Be lazy, but think ahead to anticipate demands on your time and head them off in advance. For instance it is less work to write good documentation then call RTFM than it is to answer questions.

      Be impatient but take it out by getting to good answers fast rather than complaining.

      In other words let each deadly sin redeem itself by motivating you to act in a virtuous manner. :-)

      its not that i'm lazy... its just i'm patiently challenged. Boy you guys answer these questions really fast. That's amzing.
Re: avoiding writing readme for scripts
by neophyte (Curate) on Oct 16, 2000 at 18:44 UTC
    I think you want to read perlpod. You can use pod2txt or pod2html to produce separate files from the documentation included in your script.


Re: avoiding writing readme for scripts
by arturo (Vicar) on Oct 16, 2000 at 18:47 UTC

    I don't think you're going to get self-documenting code (how would you expect the code to know what it's doing, and be able to state that in a manner that the average user can understand?). You're going to have to write the documentation yourself. But there are tools to help you with that task.

    One thing you can do is embed the documentation in the script itself, using POD (plain ol' documentation). That way, they can read up themselves by typing perldoc

    Read up on POD with man perlpod

    Philosophy can be made out of anything -- or less

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://36913]
Approved by root
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (5)
As of 2020-09-29 21:08 GMT
Find Nodes?
    Voting Booth?
    If at first I donít succeed, I Ö

    Results (153 votes). Check out past polls.