Date: Sat, 15 Aug 1998 23:13:06 -0400 (EDT) From: Tim Vanderhoek <ac199@hwcn.org> To: Bill Fumerola <billf@chc-chimes.com> Cc: ports@FreeBSD.ORG Subject: Re: bsd.port.mk updates (was: Re: ports/7617:) Message-ID: <Pine.BSF.3.96.980815221021.1275H-100000@localhost> In-Reply-To: <Pine.HPP.3.96.980815202422.22712C-100000@hp9000.chc-chimes.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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... <shrug> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.3.96.980815221021.1275H-100000>