cvs commit: doc/en_US.ISO8859-1/books/handbook/ports/chapter.sgml

[Doug Barton]

Marc Fonvieille wrote:
> On Thu, Jul 19, 2007 at 01:21:23AM +0000, Chin-San Huang wrote:
>> chinsan     2007-07-19 01:21:23 UTC
>>
>>   FreeBSD doc repository
>>
>>   Modified files:
>>     en_US.ISO8859-1/books/handbook/ports chapter.sgml 
>>   Log:
>>   - Introduce another way for upgrading packages and ports using bpkg(8).
>>
> [...]
> 
> I'm not sure the Handbook has the vocation to talk about all available
> tools to manage ports and packages.  What is bpkg?  Is it a reliable
> tool that has been extensively tested and recommended by the ports
> developers?  This port has been added on 24 June 2007...
> Now, the Handbook talk about: portupgrade, portmanager and bpkg, and I'm
> sure some will object we should talk about portmaster.
> According to what I see in /usr/ports/UPDATING we should only document
> both portupgrade and portmaster, then point people to ports/ports-mgmt/
> if they want to experiment other tools.

FWIW, I (with portmaster author hat on) am sort of ambivalent about
this issue. I've avoided adding anything to that chapter about
portmaster because my personal feeling is that a laundry list of tools
isn't useful to the user, especially if all the descriptions are the
same size as the ones that are there now.

What I think would be more useful (and again, I'm speaking only for
myself) would be a list of tools available with a brief description of
each, and links to outside sources (web pages, pkg-descr files, etc.)
where an interested user can get more information. I do think that
letting our users know that there are tools available is a good thing,
I don't think mini-manuals for each tool is appropriate in that context.

If anyone else thinks that this is a good idea, I'd be happy to
contribute a paragraph on portmaster, and help with rewriting that
section if desired.

Doug

PS, I set reply-to the -doc list since this is more of a
meta-discussion about the idea rather than a discussion about the commit.

-- 

    This .signature sanitized for your protection