Re: How to get help with pkgsrc / pkgsrc documentation

[Roland Illig <rillig%NetBSD.org@localhost>]

James K. Lowden wrote:
> "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>

That line already differs from pkgsrc-current. I've said "in the last 
months", and that usually means "after the last branch". :)

> $ man pkgsrc
> man: no entry for pkgsrc in the manual.

Maybe a short man page would be useful that just points to the pkgsrc 
guide and some other sources of help.

> $ make help topic=CHECK_WRKREF
> No help found for CHECK_WRKREF.

CHECK_WRKREF has not been documented in 2006Q3.

> $ make help topic=check_wrkref
> No help found for check_wrkref.

Same here.

> $ make help topic=pre-extract
> No help found for pre-extract.

It's because the extract.mk file does not follow the (strict) formatting 
conventions that the pkgsrc help system expects. I've fixed this.

> $ make help topic=wrkobjdir
> No help found for wrkobjdir.

This works in pkgsrc-current, but the help text is not very useful. :(

> $ make help topic=objdir
> No help found for objdir.
>
> As you can see, I'm not very good at this.

It's by no way your fault, it's the one of the pkgsrc developers who 
thought that no one would need commented code.

> 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).

Yes, that would be very helpful. At the moment I'm not sure what the 
best way would be to implement this index. I'd really like to have a 
one-line description for every variable, together with lots of 
information about the variable's use, best practice, situations in which 
to avoid that variable, and so on. I already thought about having a man 
page for each of them. That would be much work, but obviously helpful.

I'm hoping that complaints such as yours will make pkgsrc a better 
documented place. And I'm sure they will. :)

Roland