Date: Sat, 25 Nov 2000 11:50:52 -0700 From: Mike Porter <mupi@mknet.org> To: Steve Kargl <sgk@troutmask.apl.washington.edu>, Sheldon Hearn <sheldonh@uunet.co.za> Cc: Mike Meyer <mwm@mired.org>, cvs-all@freebsd.org Subject: Re: cvs commit: src/share/man/man5 make.conf.5 src/share/man/man7 build.7 Message-ID: <00112511505203.00436@mukappa.home.com> In-Reply-To: <200011251739.eAPHdke20159@troutmask.apl.washington.edu> References: <200011251739.eAPHdke20159@troutmask.apl.washington.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Sat, 25 Nov 2000, Steve Kargl wrote: > Sheldon Hearn wrote: > > > On a larger scale, is there a rational for having these things be two > > > document repositories at all? > > > > I think that manual pages are designed to document utilities, interfaces, > > formats and drivers. I think that the handbook is designed to document > > more general processes that may or may not include the use of more than > > one utility, interface, driver or format. > > This sounds reasonable, except the handbook isn't built and > installed on your system after "make world" while man pages > are. AFAIK, the tools required to buld and read the handbook > are not part of the base system. > > "man rc.conf" brings up a page that can be read. "man handbook" > does not work, "handbook handbook" doesn't work, "info handbook" > does not work. This all also disregards the historical context: "man" has been around a lot longer than the handbook, indeed "man man" doesn't even have a "history" section, which tends to indicate that man predates BSD. (this may not be a valid assumption, but man has most definitely been a fixture of both AT&T and Berkley since before there was an appriciable difference. Having said all that, I think that there is a definite need for both; on the one hand, man is quick, part of the "standard distribution" and all that, but on the other hand, the handbook allows space for much greater detail and explanations, and in general is easier to use and navigate. This makes it easier for people less familiar with BSD specifically and "Unix-like" or "Unix-based" OSes in general (read: "newbies") to have an easier time getting stuff set up and running. I know for my part, coming from the Linux world, the BSD-ish way of doing things seems a little strange at first, and so I have found myslef referring to both sets of documenation at various times for various things. For example, because it tends to be quicker (not to mention local), man is great for things like (as previously mentioned) figuring out what I need to put in various config files. But it isn't great for telling me what the various options actually DO (ie, why do I want to enable/disable a specific feature, and what are the implications of doing so). The handbook is much better in that regard. Having said all that, check out the FreeBSD Documentation project at http://www.freebsd.org/docproj/docproj.html. According to them (as found at www.freebsd.org/docproj/doc-set.html): re: man pages: - ----- "The Project does not really concern itself with these, since they are a part of the base system. The exception to this is the Japanese team, who are translating them. There is no reason other volunteers could not step in to translate the manual pages to other languages as well. That is not to say that the manual pages are unimportant, far from it. It is just that they are intimately tied to specific systems of FreeBSD, and most of the time the best person to write the manual page is the person that wrote that part of FreeBSD." - ----- and re: the handbook: - -------- " This is maintained by the project. Topics that need a more in depth discussion are addressed in the Handbook." - -------- For context, I believe the comment about "more in depth" is relative to the FAQs rather than the man pages, but I think it is applicable to that as well. mike -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.3 (FreeBSD) Comment: For info see http://www.gnupg.org iEYEARECAAYFAjogCgwACgkQZ7GovTQbIm53BQCeP7y5gnbNd9+wDIXb1UeTp7sm w58AnAi9RI+EolIdVhfKnMil6c604028 =dxVQ -----END PGP SIGNATURE----- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?00112511505203.00436>