diff --git a/handbook/Makefile b/handbook/Makefile index c020756881..f189e6c73b 100644 --- a/handbook/Makefile +++ b/handbook/Makefile @@ -1,16 +1,16 @@ -# $Id: Makefile,v 1.13 1996-06-07 15:56:34 alex Exp $ +# $Id: Makefile,v 1.14 1996-06-30 18:01:23 phk Exp $ SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml SRCS+= cyclades.sgml dialup.sgml SRCS+= diskless.sgml dma.sgml eresources.sgml esdi.sgml SRCS+= firewalls.sgml glossary.sgml goals.sgml SRCS+= handbook.sgml history.sgml hw.sgml install.sgml kerberos.sgml SRCS+= kernelconfig.sgml kerneldebug.sgml memoryuse.sgml -SRCS+= mirrors.sgml nfs.sgml nutshell.sgml pgpkeys.sgml +SRCS+= mirrors.sgml nfs.sgml nutshell.sgml pgpkeys.sgml policies.sgml SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml quotas.sgml relnotes.sgml SRCS+= routing.sgml scsi.sgml sections.sgml sio.sgml SRCS+= skey.sgml slipc.sgml slips.sgml stable.sgml submitters.sgml sup.sgml SRCS+= synching.sgml troubleshooting.sgml userppp.sgml uart.sgml linuxemu.sgml .include diff --git a/handbook/handbook.sgml b/handbook/handbook.sgml index e6ab8f4c7e..b79266b919 100644 --- a/handbook/handbook.sgml +++ b/handbook/handbook.sgml @@ -1,167 +1,168 @@ - + %authors; %lists; %sections; ]> FreeBSD Handbook <author> <name>The FreeBSD Documentation Project</name> </author> <date>May 15, 1996</date> <abstract>Welcome to FreeBSD! This handbook covers the installation and day to day use of <bf>FreeBSD Release 2.1.0</bf>. This manual is a <bf>work in progress</bf> and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the &a.doc The latest version of this document is always available from the <url url="http://www.FreeBSD.ORG/" name="FreeBSD World Wide Web server">. It may also be downloaded in ascii, LaTeX, postscript or HTML from the <url url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/docs" name="FreeBSD FTP server"> or one of the numerous <ref id="mirrors" name="mirror sites">. </abstract> <toc> <!-- ************************************************************ --> <part><heading>Basics</heading> <chapt><heading>Introduction</heading> <p>FreeBSD is a 4.4 BSD Lite based operating system for Intel architecture (x86) based PCs. For an overview of FreeBSD, see <ref id="nutshell" name="FreeBSD in a nutshell">. For a history of the project, read <ref id="history" name="a brief history of FreeBSD">. To see a description of the latest release, read <ref id="relnotes" name="about the current release">. If you're interested in contributing something to the FreeBSD project (code, equipment, sacks of unmarked bills), please see about <ref id="submitters" name="contributing to FreeBSD">. &nutshell; &history; &goals; &relnotes; &install; &basics; <chapt><heading>Installing applications</heading> <sect><heading>* Installing packages</heading> &ports; <!-- ************************************************************ --> <part><heading>System Administration</heading> &kernelconfig; <chapt><heading>Users, groups and security</heading> &crypt; &skey; &kerberos; &firewalls; &printing; "as; <chapt><heading>The X-Window System</heading> <p>Pending the completion of this section, please refer to documentation supplied by the <url url="http://www.xfree86.org/" name="The XFree86 Project, Inc">. &hw; <!-- ************************************************************ --> <part><heading>Network Communications</heading> <chapt><heading>Basic Networking</heading> <sect><heading>* Ethernet basics</heading> <sect><heading>* Serial basics</heading> <sect><heading>* Hardwired Terminals</heading> &dialup; <chapt><heading>PPP and SLIP</heading> <p>If your connection to the Internet is through a modem, or you wish to provide other people with dialup connections to the Internet using FreeBSD, you have the option of using PPP or SLIP. Furthermore, two varieties of PPP are provided: <em>user</em> (sometimes referred to as iijppp) and <em>kernel</em>. The procedures for configuring both types of PPP, and for setting up SLIP are described in this chapter. &userppp; &ppp; &slipc; &slips; <chapt><heading>Advanced networking</heading> &routing; &nfs; &diskless; <sect><heading>* Yellow Pages/NIS</heading> <sect><heading>* ISDN</heading> <chapt><heading>* Mail</heading> <!-- ************************************************************ --> <part><heading>Advanced topics</heading> ¤t; &stable; &synching; &submitters; &troubleshooting; &kerneldebug; &linuxemu; <chapt><heading>FreeBSD internals</heading> &booting; &memoryuse; &dma; <!-- ************************************************************ --> <part><heading>Appendices</heading> &mirrors; &bibliography; &eresources; &contrib; + &policies; &pgpkeys; <!-- &glossary; --> </book> </linuxdoc> diff --git a/handbook/policies.sgml b/handbook/policies.sgml new file mode 100644 index 0000000000..f77ae49a96 --- /dev/null +++ b/handbook/policies.sgml @@ -0,0 +1,147 @@ +<!-- $Id: policies.sgml,v 1.1 1996-06-30 18:01:25 phk Exp $ --> +<!-- The FreeBSD Documentation Project --> + +<chapt><heading>Source Tree Guidelines and Policies +<label id="policies"> +</heading> + +<p><em>Contributed by &a.phk;.</em> + +This chapter documents various guidelines and policies in force +for the FreeBSD sourcetree. + +<sect><heading>MAINTAINER on Makefiles</heading> + +<p>June 1996. + +<p>If a particular subpart of the FreeBSD is being maintained by a +person or group of persons, they can communicate this fact to the +world by adding a + +<verb> + MAINTAINER= email-addresses +</verb> + +<p>line to the makefiles covering this piece of subpart of the tree. + +<p>The semantics of this is as follows: + +<p>The maintainer owns and is responsible for that code. This means +that he is responsible for fixing bugs and answer PRs pertaining +to that piece of the code, and in the case of contrib software, +for tracking new versions, as appropriate. + +<p>Commits to the directories covered by this shall be sent to the +maintainer for review. Only if the maintainer does not respond +for un unacceptable period of time, to several emails, will it be +acceptable to commit changes without review by the maintainer. + +<p>It is of course not acceptable to add a person or group as maintainer +unless they agree to assume this duty, on the other hand it doesn't +have to be a committer and it can easily to be a group of people. + +<p> Some software distributions have attacked this problem by +providing configuration scripts. Some of these are very clever, but +they have an unfortunate tendency to triumphantly announce that your +system is something you've never heard of and then ask you lots of +questions that sound like a final exam in system-level Unix +programming (``Does your system's gethitlist function return a const +pointer to a fromboz or a pointer to a const fromboz? Do you have +Foonix style unacceptable exception handling? And if not, why not?''). + +<p> Fortunately, with the Ports collection, all the hard work involved +has already been done, and you can just type 'make install' and get a +working program. + +<sect><heading>contributed software</heading> + +<p>June 1996. + +<p>Some parts of the FreeBSD distribution consists of software that +is actively being maintained outside the FreeBSD project. For +historical reasons, we call this "contributed" software. Some +examples are perl, gcc and patch. + +<p>Over the last couple of years, various methods have been used in +dealing with this type of software and all have some number of +advantages and drawbacks. No clear winner has emerged. + +<p>Since this is the case, after some debate one of these methods has +been selected as the "official" method and will be required for +future imports of software of this kind. Furthermore, it is strongly +suggested that existing contrib software converge on this model +over time as it has significant advantages over the old method, +including the ability to easily obtain diffs relative to the +"official" versions of the source by everyone (even without cvs +access). This will make it significantly easier to return changes +to the primary developers of the contributed software. + +<p>Ultimately, however, it comes down to the people actually doing +the work. If using this model is particularly unsuited to the +package being dealt with, exceptions to these rules may be granted +only with the approval of the core team and with the general +consensus of the other developers. The ability to maintain the +package in the future will be a key issue in the decisions. + +<p>The "Tcl" embeddable programming language will be used as example +of how this model works: + +<p><verb>src/contrib/tcl</verb> contains the source as distributed by the maintainers +of this package. Parts that are entirely not applicable for FreeBSD +can be removed. In the case of Tcl, the "mac", "win" and "compat" +subdirectories were eliminated before the import + +<p><verb>src/lib/libtcl</verb> contains only a "bmake style" Makefile that uses +the standard bsd.lib.mk makefile rules to produce the library and +install the documentation. + +<p><verb>src/usr.bin/tclsh</verb> contains only a bmake style Makefile which will +produce and install the "tclsh" program and its associated man-pages +using the standard bsd.prog.mk rules. + +<p><verb>src/tools/tools/tcl_bmake</verb> contains a couple of shell-scrips that can be of help +when the tcl software needs updated, these are not part of the +build or installed software. + +<p>The important thing here is that the "src/contrib/tcl" directory +is created according to the rules: It is supposed to contain the +sources as distributed (on a proper CVS vendor-branch) with as few +FreeBSD-specific changes as possible. The 'easy-import' tool on +freefall will assist in doing the import but, if there are any +doubts on how to go about it, it is imperative that you ask first +and not blunder ahead and hope it "works out". CVS is not forgiving +of import accidents and a fair amount of effort is required to back +out major mistakes. + +<p>Because of some unfortunate design limitations with CVS's vendor +branches, it is required that "official" patches from the vendor +be applied to the original distributed sources and the result +re-imported onto the vendor branch again. Official patches should +never be patched into the the FreeBSD checked out version and +"committed", as this destroys the vendor branch coherency and makes +imports future versions rather difficult as there will be conflicts. + +<p>Since many packages contain files that are meant for compatibility +with other architectures and environments that FreeBSD, it is +permissible to remove parts of the dist tree that are of no interest +to FreeBSD in order to save space. Files containing copyright +notices and release-note kind of information applicable to the +remaining files shall >not< be removed. + +<p>If it seems easier, the "bmake" makefiles can be produced from the +dist tree automatically by some utility, something which would +hopefully make it even easier to upgrade to a new version. If this +is done, be sure to check in such utilities (as necessary) in the +src/tools directory along with the port itself so that it's available +to future maintainers. + +<p>In the src/contrib/tcl level directory, a file called README.FreeBSD +should be added and it should states things like: + +<itemize> + <item> Which files have been left out + <item> Where the original distribution was obtained from and/or the official + master site. + <item> Where to send patches back to the original authors + <item> Perhaps an overview of the FreeBSD-specific changes that have been made. +</itemize> diff --git a/handbook/sections.sgml b/handbook/sections.sgml index 57dfee3d2b..1fc0319e63 100644 --- a/handbook/sections.sgml +++ b/handbook/sections.sgml @@ -1,53 +1,54 @@ -<!-- $Id: sections.sgml,v 1.13 1996-06-07 15:56:40 alex Exp $ --> +<!-- $Id: sections.sgml,v 1.14 1996-06-30 18:01:25 phk Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- Entities containing all the pieces of the handbook are --> <!-- defined here --> <!ENTITY bibliography SYSTEM "bibliography.sgml"> <!ENTITY basics SYSTEM "basics.sgml"> <!ENTITY booting SYSTEM "booting.sgml"> <!ENTITY contrib SYSTEM "contrib.sgml"> <!ENTITY ctm SYSTEM "ctm.sgml"> <!ENTITY current SYSTEM "current.sgml"> <!ENTITY stable SYSTEM "stable.sgml"> <!ENTITY crypt SYSTEM "crypt.sgml"> <!ENTITY dialup SYSTEM "dialup.sgml"> <!ENTITY diskless SYSTEM "diskless.sgml"> <!ENTITY dma SYSTEM "dma.sgml"> <!ENTITY eresources SYSTEM "eresources.sgml"> <!ENTITY esdi SYSTEM "esdi.sgml"> <!ENTITY firewalls SYSTEM "firewalls.sgml"> <!ENTITY goals SYSTEM "goals.sgml"> <!ENTITY glossary SYSTEM "glossary.sgml"> <!ENTITY history SYSTEM "history.sgml"> <!ENTITY hw SYSTEM "hw.sgml"> <!ENTITY install SYSTEM "install.sgml"> <!ENTITY kerberos SYSTEM "kerberos.sgml"> <!ENTITY kernelconfig SYSTEM "kernelconfig.sgml"> <!ENTITY kerneldebug SYSTEM "kerneldebug.sgml"> <!ENTITY linuxemu SYSTEM "linuxemu.sgml"> <!ENTITY memoryuse SYSTEM "memoryuse.sgml"> <!ENTITY mirrors SYSTEM "mirrors.sgml"> <!ENTITY nfs SYSTEM "nfs.sgml"> <!ENTITY nutshell SYSTEM "nutshell.sgml"> <!ENTITY pgpkeys SYSTEM "pgpkeys.sgml"> +<!ENTITY policies SYSTEM "policies.sgml"> <!ENTITY porting SYSTEM "porting.sgml"> <!ENTITY ports SYSTEM "ports.sgml"> <!ENTITY ppp SYSTEM "ppp.sgml"> <!ENTITY printing SYSTEM "printing.sgml"> <!ENTITY quotas SYSTEM "quotas.sgml"> <!ENTITY relnotes SYSTEM "relnotes.sgml"> <!ENTITY routing SYSTEM "routing.sgml"> <!ENTITY scsi SYSTEM "scsi.sgml"> <!ENTITY sio SYSTEM "sio.sgml"> <!ENTITY cy SYSTEM "cyclades.sgml"> <!ENTITY skey SYSTEM "skey.sgml"> <!ENTITY slipc SYSTEM "slipc.sgml"> <!ENTITY slips SYSTEM "slips.sgml"> <!ENTITY submitters SYSTEM "submitters.sgml"> <!ENTITY sup SYSTEM "sup.sgml"> <!ENTITY synching SYSTEM "synching.sgml"> <!ENTITY troubleshooting SYSTEM "troubleshooting.sgml"> <!ENTITY uart SYSTEM "uart.sgml"> <!ENTITY userppp SYSTEM "userppp.sgml">