Subject: Re: How to get help with pkgsrc / pkgsrc documentation
To: None <firstname.lastname@example.org>
From: Roland Illig <rillig@NetBSD.org>
Date: 11/20/2006 01:05:56
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.
> $ 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
> $ 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. :)