develooper Front page | perl.module.build | Postings from April 2007

more questions about the help action

Thread Next
From:
Eric Wilhelm
Date:
April 14, 2007 14:17
Subject:
more questions about the help action
Message ID:
200704141417.14083.ewilhelm@cpan.org
Three behavioral questions:
1. doc-only overrides
2. accumulation is a bug?
3. formatting

-----------
1.  Should subclasses be able to override *just* docs?

e.g. =item help in the subclass documentation gets picked-up even if the 
method hasn't been overridden.  This seems like it could cause trouble 
if you override the action and docs, but then delete your ACTION_help 
sub and forget to kill the docs.

Of course, Module::Build itself does this (the docs are in Build.pm and 
the code is in Base.pm), so we would basically have to special-case 
that.  If anything, I guess the rule would be "$self->can($action) ne 
Module::Build->can($action)" or so.

Yeah, maybe not worth it.  At least, wherever it is that we're 
documenting `./Build help` wrt subclassing (I can't seem to find it), 
we should mention how this all works.


-----------
2.  If documentation is found in a subclass and superclass, should we be 
concatenating them together?  It really seems like we should just stop 
when we find some doc.  What we do now makes this:

  =item help

  Does the help thing.

  You should probably not be seeing this.  That is, we haven't
  overridden the help action, but we're able to override just the
  docs?  That seems reasonable, but might be wrong.

  =item help

  [version 0.03]

  This action will simply print out a message that is meant to help you
  use the build process.  It will show you a list of available build
  actions too.

  With an optional argument specifying an action name (e.g. C<Build help
  test>), the 'help' action will show you any POD documentation it can
  find for that action.


-----------
3.  Formatting?

The [version foo] stuff in the core docs doesn't seem too useful on the 
command-line.  Similarly, the =item should probably be stripped and 
maybe convert the pod markup to plaintext (and maybe Term::ANSIScreen 
highlighting?)


Thanks,
Eric
-- 
So malloc calls a timeout and starts rummaging around the free chain,
sorting things out, and merging adjacent small free blocks into larger
blocks. This takes 3 1/2 days.
--Joel Spolsky
---------------------------------------------------
    http://scratchcomputing.com
---------------------------------------------------

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About