[Module::Build] [PATCH] Re: [Module-build-general] documenting ./Build docs

[Steve P. <sp...@qu...>]

On Wednesday, October 1, 2003, at 11:10  pm, Mark Stosberg wrote:

> Hello,
>
> Today I looked into seeing what the "docs" action does. When I ran it,
> the output looks identical to just running "./Build".
>
> So I looked at the code. It looks like they are in fact doing the exact
> same thing. If you don't specify an action, "build" is the default.
> "build" calls the "code" action, and then "docs" action.
>
> If you call the "docs" action directly, it depends on the "code" 
> action,
> so again the "code" ation gets called, followed by the "docs" action.
>
> So it doesn't seem an incredibly useful action at the moment.
> :). It would seem more useful if you could build the docs without
> depending on the code being built, but I'm not sure if that will make
> sense from a technical perspective.

That's not really possible, seeing as building your codebase might 
involve generating some documentation specific to that build (or 
platform).

And the split is not entirely useless as it may seem... :)  The 'code' 
action doesn't depend on the 'docs' action, which is good because 
'test' depends on 'code', which means you don't have to build the docs 
to test your code.  (whereas, if there were only one 'build' action, 
'test' would have to rely on it.)


> At any rate, the docs could say something like:
>
> docs
>
> Builds all the man pages for the binary and library POD.
> This action depends on the code being built, and will call the
> 'code' action if it hasn't already run. By default this action
> gives the exact seems results as simply running "./Build".

Good idea, though I'd say it slightly differently by referring to 
'docs' from the 'build' action.  I've attached a patch against current 
CVS updates the pod for 'build' and introduces 'code', and 'docs'.

hth,
-Steve