From owner-freebsd-ports Sat Aug 15 20:14:15 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id UAA22782 for freebsd-ports-outgoing; Sat, 15 Aug 1998 20:14:15 -0700 (PDT) (envelope-from owner-freebsd-ports@FreeBSD.ORG) Received: from localhost.my.domain (ppp1718.on.bellglobal.com [206.172.249.182]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id UAA22759 for ; Sat, 15 Aug 1998 20:14:11 -0700 (PDT) (envelope-from hoek@FreeBSD.ORG) Received: from localhost (tim@localhost) by localhost.my.domain (8.8.8/8.8.8) with SMTP id XAA05634; Sat, 15 Aug 1998 23:13:06 -0400 (EDT) (envelope-from ac199@hwcn.org) X-Authentication-Warning: localhost.my.domain: tim owned process doing -bs Date: Sat, 15 Aug 1998 23:13:06 -0400 (EDT) From: Tim Vanderhoek X-Sender: tim@localhost Reply-To: ac199@hwcn.org To: Bill Fumerola cc: ports@FreeBSD.ORG Subject: Re: bsd.port.mk updates (was: Re: ports/7617:) In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-ports@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Sat, 15 Aug 1998, Bill Fumerola wrote: > > If you're volunteering to write a page (even a text, non-html > > page) that lists the latest changes to bsd.port.mk, _AND_ to keep > > that page up-to-date, I'll happily find a place for it. > > I'd volunteer to work on that and/or a NICE AND COMPLETE explanation of > all the (many, poorly documented) Makefile options for ports, given that One of the frequent ports committers could probably comment on what would be most useful (steve, mph, vanilla?). You have no idea how much I would like to take porting.sgml, rip it up, rewrite, and put it back together into a nice, much sexier, document... I'm not entirely sure how porting.sgml should be rewritten (if I was sure, doing the rewriting would be easy! :), but I am sure that a reference document such as you suggest would be useful. Some of the variables that ports _can_ use are undocumented intentionally. If you do write such a document, be careful to avoid documenting these variables. There is, of course, no agreement on what these variables are, so use your judgement. :) One slight aggravation is that ports documentation is getting increasingly spread-out. See the BUGS section of ports(7) for list... I prefer spreading it out further to smacking it ontop of porting.sgml. A reference might be better written in the form of - Ports that require uids [stuff ripped from porting.sgml inserted here, after rewriting, etc. :-] - Ports that need PATCHFILES from different PATCH_SITES [more writing] - Ports that need to use /var/run [...] - Ports that need different PLISTs depending on their configuartion [...] - Ports that can't fetch their distfile automatically [...] - Ports that supply "info" documentation [rip and rewrite from porting.sgml] - Ports that add a module to Apache [...] - Use your imagination here... :-) With the items being ordered from least arcane to most arcane. I hesitate to use the term FAQ since that implies a question and answer format which I fund ugly and cumbersome. The assorted bsd.port.mk variables are somewhat documented in bsd.port.mk. Something that documents by name each more carefully (or more verbosely, at least ;-) would be useful. Perhaps a similar reference for each element or file found in a port. Eg. - pkg/PLIST [lengthy description of the ideal PLIST] - pkg/DESCR [lengthy description of the ideal DESCR] - pkg/COMMENT [...] - files/md5 [...] Hmm... Use your imagination. :-) > they were cvsup'able so multiple people could work on it. I'd be willing > to head up or at least start something like that. Well, obviously I can't promise that any other people would work on it. Putting it under the main FreeBSD cvs tree is no problem. In fact, we generally prefer that. In case you haven't noticed, we have enough trouble keeping our existing documentation up-to-date, so at least a good-faith agreement to try and save if from becoming just more misleading and wrong documentation would be nice... An ideal submission would be in DocBook. :) LinuxDoc would probably be converted to DocBook by the ever-energetic nik. :) A plain-text document is probably not a problem, either, but couldn't be added to the handbook. -- This .sig is not innovative, witty, or profund. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-ports" in the body of the message