From owner-freebsd-doc Thu May 23 10:33:33 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.3/8.7.3) id KAA04099 for doc-outgoing; Thu, 23 May 1996 10:33:33 -0700 (PDT) Received: from fslg8.fsl.noaa.gov (fslg8.fsl.noaa.gov [137.75.131.171]) by freefall.freebsd.org (8.7.3/8.7.3) with SMTP id KAA04083 for ; Thu, 23 May 1996 10:33:29 -0700 (PDT) Received: by fslg8.fsl.noaa.gov (5.57/Ultrix3.0-C) id AA26497; Thu, 23 May 96 17:33:23 GMT Message-Id: <9605231733.AA26497@fslg8.fsl.noaa.gov> Received: by emu.fsl.noaa.gov (1.40.112.3/16.2) id AA215982801; Thu, 23 May 1996 11:33:21 -0600 Date: Thu, 23 May 1996 11:33:21 -0600 From: Sean Kelly To: jrclark@felix.iupui.edu Cc: doc@freebsd.org In-Reply-To: <2.2.32.19960523130853.006972e4@felix.iupui.edu> (message from John Clark on Thu, 23 May 1996 09:08:53 -0400) Subject: Re: FAQ Contribution Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "John" == John Clark writes: John> Documentation Maintainers: Yes? John> Recently I switched from Linux to FreeBSD. Congratulations, and thanks. John> Doing this allowed me to see some serious holes in your John> documentation. Probably among the worst is the total lack John> of coherent directions for using the "ports" collection. I'm afraid I have to be critical as well here. With utmost resepect to Misters Palmer and Hubbard, the ports section could certainly use some work to make it more tutorial and less meandering. It reads like a FAQ and not at all like the tone I think we need in a handbook. Perhaps someone could rewrite that section into a more tutorial-like form? John> You have a great deal of the documentation in place for this John> topic in the handbook, however, key details are missing. John> Most prominently, there is NO mention, anywhere, that one John> has to type "get portname.tar.gz" to fetch the port John> subdirectory from cdrom.com. To be thorough though, that step isn't actually necessary in all cases. For example, if you've got an Internet connection and installed the ports collection from your CD-ROM or made a symbolic link tree to the CD-ROM, a simple `make' will automatically fetch the port sources for the port in question. John> One sentence in the handbook could rectify this. True. John> There are other problems as far as conveying the concept of John> how the port is used and its relationship to the generic John> internet distribution of the "port" in question. I don't understand. Huh? John> Anyway, I have written a FAQ to be added on this subject. Great! I'd be willing to convert your FAQ into the SGML format needed for the FreeBSD documentation project. However, if you'd like to to do this yourself, it'd be an excellent opportunity to learn the DTD that we're using for the FAQ and the handbook ... which would be useful information for future contributions ... hint, hint :-) I've skimmed through your FAQ and will have complete comments available by Saturday. Thanks for the contribution! -- Sean Kelly NOAA Forecast Systems Laboratory kelly@fsl.noaa.gov Boulder Colorado USA http://www-sdd.fsl.noaa.gov/~kelly/