Re: How to get help with pkgsrc / pkgsrc documentation

["James K. Lowden" <jklowden%schemamania.org@localhost>]

Roland Illig wrote:
> 
> in the last months, the documentation of the pkgsrc infrastructure has 
> improved quite a lot. It's just that many people don't know that this 
> has happended. Therefore I'm writing this informational mail.
...
> $ make help
> usage: /usr/bin/make help topic=<topic>
> 
>          <topic> may be a variable name or a make target,

Hi Roland, 

Thanks for working on this.  You wouldn't mind a few suggestions, would
you?  

"make help" isn't terribly useful as it is.  It would be nice to easily
find what topics are available.  

For instance, I tried a few things on my 2006Q3 tree, in lang/perl5:

$ cd lang/perl5
$ make help
usage: /usr/bin/make help TOPIC=<VARNAME>
$ man pkgsrc
man: no entry for pkgsrc in the manual.
$ make help topic=CHECK_WRKREF
No help found for CHECK_WRKREF.
$ make help topic=check_wrkref
No help found for check_wrkref.
$ make help topic=extract # one I know is a valid target
=========================================================================
==
# $NetBSD: bsd.extract.mk,v 1.1 2006/06/06 03:05:48 jlam Exp $
#
# This Makefile fragment is included to bsd.pkg.mk and defines the
# relevant variables and targets for the "extract" phase.
#
# The following are the "public" targets provided by this module:
#
#    extract
#
# The following targets may be overridden in a package Makefile:
#
#    pre-extract, do-extract, post-extract
#
=========================================================================
==
$ make help topic=pre-extract
No help found for pre-extract.
$ make help topic=wrkobjdir
No help found for wrkobjdir.
$ make help topic=objdir
No help found for objdir.

As you can see, I'm not very good at this.

If I don't remember the name correctly, it would be nice to do something
like:

        $ make help topic=help | grep OBJ

(or topic=topics) and offer that suggestion if all I type is "make help",
along the lines of what you see if you type "perldoc" by itself (when Perl
is installed, that is). 

pkgsrc has a bewildering set of knobs.  Thanks for putting a lever by the
stone blocking the entrance to the cave.  

Regards, 

--jkl