# The following was supposedly scribed by
# Darren Chamberlain
# on Friday 29 April 2005 04:48 am:
>> I'm rather tired of manually editing README files before each
>> release, and do not like using a straight pod2text either, since it
>> contains a lot of superfluous information.
>
>I always do perldoc -t Module.pod > README, and it works out pretty
>good
It looks like what Rob is trying to do is create a README which contains
only the "README-like" info, while also causing these sections to be
ignored by the standard perldoc. IMO, this is a good idea, and maybe
could be builtin to Module::Build. I don't like having INSTALLATION
sections in the docs for things that are already installed, and I would
prefer not to read about function prototypes when I'm just trying to
install a module.
The important thing is that you don't have to use a special perldoc on
the module file and don't have to change the pod text. I'm guessing
that's why everything has a '=for readme foo' syntax to it?
How do you make a section that both goes in the readme and works with
perldoc? Is that what the commands are for?
Rob: have you considered something like '=for hacking foo' as a way to
create the HACKING file (such as programmer documentation embedded in a
script?)
Not sure how useful the includes are in making a README, but if you can
make something like HACKING work, includes might become more useful.
BTW, I like to have changes in my perldoc, and in the CHANGES file (and
in the README.) Right now I use a little script for that, but it would
be good to have a system that did it automagically.
--Eric
--
Peer's Law: The solution to the problem changes the problem.
---------------------------------------------
http://scratchcomputing.com
---------------------------------------------
