Eric Wilhelm wrote:
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.
I'm glad somebody understands what I was talking about!
I want a middle way between 'perl2text Module.pm > README' and manually updating a README every time.
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?
If you had no '=for readme' formatting codes, it would include the entire POD as if you used 'pod2text Module.pm > README'. You add the
codes to specify what you want skipped, or included only in the readme.
Some sections like REQUIREMENTS and INSTALLATION could be generated
automatically. For requirements, parsing the META.yml should be good enough. For installation, check if there is a Makefile.PL and/or Build.PL.
I think this should cover most cases.
Eric: I don't understand the '=for hacking foo' stuff.
In my modules I sometimes add '=begin internal/=end internal' sections to document internal methods, but I leave those for anyone hacking a module to find: I don't export them to anything.
Rob
