diff --git a/en/handbook/README b/en/handbook/README index 01305e15f4..ed609185f9 100644 --- a/en/handbook/README +++ b/en/handbook/README @@ -132,5 +132,16 @@ FreeBSD-doc mailing list) if they have specific questions. and knocked together a quick Perl script to do it. It's ~nik/bin/para.pl on freefall. + 5. Got halfway through looking for filenames, and marking them up as such. + + There are a lot ( :-( ) of filenames in the Handbook. The conversion + process did a pretty good job of marking them as ... + but it wasn't perfect. + + I'm halfway through (line 16704) going through the Handbook, eyeballing + each line and changing things like ... + to ... where appropriate. + + The remainder will follow tomorrow evening. \ No newline at end of file diff --git a/en/handbook/handbook.sgml b/en/handbook/handbook.sgml index 23c25b4f5a..4d243dd44c 100644 --- a/en/handbook/handbook.sgml +++ b/en/handbook/handbook.sgml @@ -1505,8 +1505,8 @@ Before installing from a MS-DOS partition To prepare for installation from an MS-DOS partition, copy the - files from the distribution into a directory called C:\FREEBSD. The directory tree structure of + files from the distribution into a directory called + C:\FREEBSD. The directory tree structure of the CDROM must be partially reproduced within this directory so we suggest using the DOS xcopy command. For example, to prepare for a minimal installation of FreeBSD: @@ -1514,13 +1514,13 @@ C> MD C:\FREEBSD C> XCOPY /S E:\BIN C:\FREEBSD\BIN\ C> XCOPY /S E:\MANPAGES C:\FREEBSD\MANPAGES\ - assuming that C: - is where you have free space and E: + assuming that C: + is where you have free space and E: is where your CDROM is mounted. For as many `DISTS' you wish to install from MS-DOS (and you - have free space for), install each one under C:\FREEBSD - the BIN dist + have free space for), install each one under + C:\FREEBSD - the BIN dist is only the minimal requirement. @@ -2248,10 +2248,11 @@ Install the program executable and other supporting - files, man pages, etc. under the /usr/local hierarchy, where - they will not get mixed up with system programs. This also - makes sure that all the ports you install will go in the same - place, instead of being flung all over your system. + files, man pages, etc. under the + /usr/local hierarchy, where they will not + get mixed up with system programs. This also makes sure that + all the ports you install will go in the same place, instead + of being flung all over your system. @@ -2291,7 +2292,8 @@ the initial setting up will already have been done for you. If not, make sure the FreeBSD CDROM is in - the drive and mounted on, say, /cdrom. Then do + the drive and mounted on, say, /cdrom. Then + do # mkdir /usr/ports # cd /usr/ports # ln -s @@ -2299,8 +2301,8 @@ to enable the ports make mechanism to find the tarballs (it - expects to find them in /usr/ports/distfiles, which is why we - sym-linked the CDROM's tarball directory to that + expects to find them in /usr/ports/distfiles, + which is why we sym-linked the CDROM's tarball directory to that directory). Now, suppose you want to install the gnats program from the @@ -2434,7 +2436,7 @@ - Makefile + <filename>Makefile</filename> The most important component of a skeleton is the Makefile. This contains various statements that specify how the port should @@ -2480,9 +2482,10 @@ Skipping over the next few lines for a minute, the line .include <bsd.port.mk> says that the other statements and commands needed for this port are - in a standard file called `bsd.port.mk". As these are the - same for all ports, there is no point in duplicating them all over - the place, so they are kept in a single standard file. + in a standard file called bsd.port.mk. As + these are the same for all ports, there is no point in duplicating + them all over the place, so they are kept in a single standard + file. This is probably not the place to go into a detailed examination of how Makefiles work; suffice it to say that the line @@ -2496,13 +2499,13 @@ - The files directory + The <filename>files</filename> directory The file containing the for the port is called "md5", after - the MD5 algorithm used for ports checksums. It lives in a - directory with the slightly confusing name of - "files". + remap="checksum"> for the port is called + md5, after the MD5 algorithm used for ports + checksums. It lives in a directory with the slightly confusing + name of files. This directory can also contain other miscellaneous files that are required by the port and do not belong anywhere else. @@ -2510,7 +2513,7 @@ - The patches directory + The <filename>patches</filename> directory This directory contains the needed to make everything work properly under @@ -2519,7 +2522,7 @@ - The pkg directory + The <filename>pkg</filename> directory This program contains three quite useful files:- @@ -2527,18 +2530,19 @@ - COMMENT - a one-line description of the program. + COMMENT - a one-line description of + the program. - DESCR - a more detailed description. + DESCR - a more detailed description. - PLIST - a list of all the files that will be created - when the program is installed. + PLIST - a list of all the files + that will be created when the program is installed. @@ -2703,16 +2707,19 @@ tarballs? - A. It is a file ending in .tar or .tar.gz (with variations - like .tar.Z, or even .tgz if you are trying to squeeze the - names into a DOS filesystem). + A. It is a file ending in .tar or + .tar.gz (with variations like + .tar.Z, or even .tgz + if you are trying to squeeze the names into a DOS + filesystem). Basically, it is a directory tree that has been archived - into a single file (.tar) and optionally compressed (.gz). - This technique was originally used for - Tape ARchives (hence - the name `tar'), but it is a widely used way of distributing - program source code around the Internet. + into a single file (.tar) and optionally + compressed (.gz). This technique was + originally used for Tape + ARchives (hence the name `tar'), but it is + a widely used way of distributing program source code around + the Internet. You can see what files are in them, or even extract them yourself, by using the standard Unix tar program, which comes @@ -2763,15 +2770,15 @@ Q. I did that, but when I tried to put it into - /usr/ports/distfiles I got some error about not having - permission. + /usr/ports/distfiles I got some error + about not having permission. A. The ports mechanism looks for the tarball in - /usr/ports/distfiles, but you will not be able to copy - anything there because it is sym-linked to the CDROM, which is - read-only. You can tell it to look somewhere else by - doing + /usr/ports/distfiles, but you will not be + able to copy anything there because it is sym-linked to the + CDROM, which is read-only. You can tell it to look somewhere + else by doing DISTDIR=/where/you/put/it make @@ -2781,9 +2788,10 @@ Q. Does the ports scheme only work if you have everything - in /usr/ports? My system administrator says I must put - everything under /u/people/guests/wurzburger, but it does not - seem to work. + in /usr/ports? My system administrator + says I must put everything under + /u/people/guests/wurzburger, but it does + not seem to work. A. You can use the PORTSDIR and PREFIX variables to tell @@ -2796,16 +2804,20 @@ install - will compile the port in /u/people/guests/wurzburger/ports - and install everything under /usr/local. + will compile the port in + /u/people/guests/wurzburger/ports and + install everything under /usr/local. + make PREFIX=/u/people/guests/wurzburger/local install - will compile it in /usr/ports and install it in - /u/people/guests/wurzburger/local. + will compile it in /usr/ports and + install it in + /u/people/guests/wurzburger/local. + And of course @@ -2912,11 +2924,12 @@ install - or by editing /etc/make.conf, but unfortunately not all - ports respect this. The surest way is to do 'make configure', - then go into the source directory and inspect the Makefiles by - hand, but this can get tedious if the source has lots of - sub-directories, each with their own Makefiles. + or by editing /etc/make.conf, but + unfortunately not all ports respect this. The surest way is to + do 'make configure', then go into the source directory and + inspect the Makefiles by hand, but this can get tedious if the + source has lots of sub-directories, each with their own + Makefiles. @@ -2997,8 +3010,8 @@ Q. I tried that and it still left all those tarballs or - whatever you called them in the distfiles directory. Can I - delete those as well? + whatever you called them in the distfiles + directory. Can I delete those as well? A. Yes, if you are sure you have finished with them, those @@ -3078,7 +3091,8 @@ A. Nothing secret about it at all, just look at the - bsd.ports.mk and bsd.ports.subdir.mk files in your bsd.ports.mk and + bsd.ports.subdir.mk files in your makefiles directory. (Note: readers with an aversion to intricate shell-scripts are advised not to follow this @@ -3171,10 +3185,10 @@ which is the staging area where your kernel will be built. Notice the logical organization of the directory tree, with each supported device, filesystem, and option in its own subdirectory. Also, - anything inside the i386 directory - deals with PC hardware only, while everything outside the i386 directory is common to all platforms - which FreeBSD could potentially be ported to. + anything inside the i386 directory deals with + PC hardware only, while everything outside the + i386 directory is common to all platforms which + FreeBSD could potentially be ported to.
@@ -3187,15 +3201,15 @@ Next, move to the i386/conf directory and - copy the GENERIC configuration file to the name you want to give - your kernel. For example: + copy the GENERIC configuration file to the name + you want to give your kernel. For example: # cd /usr/src/sys/i386/conf # cp GENERIC MYKERNEL Traditionally, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with different hardware, it is a good idea to name it after your - machine's hostname. We will call it MYKERNEL for the purpose of - this example. + machine's hostname. We will call it MYKERNEL + for the purpose of this example.
@@ -3205,19 +3219,22 @@
- Now, edit MYKERNEL with your favorite text editor. If you are - just starting out, the only editor available will probably be - vi, which is too complex to explain - here, but is covered well in many books in the Now, edit MYKERNEL with your favorite text + editor. If you are just starting out, the only editor available + will probably be vi, which is too + complex to explain here, but is covered well in many books in the + . Feel free to change the comment lines at the top to reflect your configuration or the - changes you have made to differentiate it from GENERIC. + changes you have made to differentiate it from + GENERIC. If you have build a kernel under SunOS or some other BSD - operating system, much of this file will be very familiar to you. - If you are coming from some other operating system such as DOS, on - the other hand, the GENERIC configuration file might seem - overwhelming to you, so follow the descriptions in the GENERIC configuration file + might seem overwhelming to you, so follow the descriptions in the + section slowly and carefully. @@ -3269,14 +3286,16 @@ most lines only contain one argument. Anything following a # is considered a comment and ignored. The following sections describe each keyword, generally in the order - they are listed in GENERIC, although some related keywords have been - grouped together in a single section (such as Networking) even - though they are actually scattered throughout the GENERIC file. - An - exhaustive list of options and more detailed explanations of the - device lines is present in the LINT configuration file, located in - the same directory as GENERIC. If you are in doubt as to the - purpose or necessity of a line, check first in LINT. + they are listed in GENERIC, although some + related keywords have been grouped together in a single section + (such as Networking) even though they are actually scattered + throughout the GENERIC file. + An exhaustive list of options and + more detailed explanations of the device lines is present in the + LINT configuration file, located in the same + directory as GENERIC. If you are in doubt as to + the purpose or necessity of a line, check first in + LINT. The kernel is currently being moved to a better organization of the option handling. Traditionally, each option in the config file @@ -3352,9 +3371,9 @@ remap=tt>cpu line may be present with different values of cpu_type - as are present in the GENERIC kernel. For a custom - kernel, it is best to specify only the cpu you have. If, - for example, you have an Intel Pentium, use + as are present in the GENERIC kernel. + For a custom kernel, it is best to specify only the cpu + you have. If, for example, you have an Intel Pentium, use I586_CPU for cpu_type. @@ -3365,8 +3384,9 @@ Next, we have ident, which is the identification of the kernel. You should - change this from GENERIC to whatever you named your - kernel, in this example, MYKERNEL. The value you put in + change this from GENERIC to whatever + you named your kernel, in this example, + MYKERNEL. The value you put in ident will print when you boot up the kernel, so it is useful to give a kernel a different name if you want to keep it separate from your @@ -3439,10 +3459,10 @@ This line specifies the location and name of the - kernel. Traditionally the kernel is called vmunix but in FreeBSD, it is aptly - named kernel. You should - always use kernel for + kernel. Traditionally the kernel is called + vmunix but in FreeBSD, it is aptly + named kernel. You should always use + kernel for kernel_name because changing it will render numerous system utilities inoperative. The second part of the line specifies the disk and partition where @@ -3623,9 +3643,9 @@ Process filesystem. This is a pretend filesystem - mounted on /proc which allows programs like - ps(1) to give you more information on - what processes are running. + mounted on /proc which allows + programs like ps(1) to give you more + information on what processes are running. @@ -5354,8 +5374,8 @@ - If any additional files (such as principal.* or master_key) + If any additional files (such as + principal.* or master_key) exist, then use the kdb_destroy command to destroy the old Kerberos database, of if Kerberos is not running, simply delete the extra files with dvilj2p makes the filter hpdf quite complex since dvilj2p cannot read from standard input. It wants to work with a filename. What is worse, the filename has to end in .dvi so using /dev/fd/0 for standard input is problematic. We can get around that problem by linking (symbolically) a temporary file name (one that ends in .dvi) to /dev/fd/0, thereby forcing dvilj2p to read from standard input. The only other fly in the ointment is the fact that we - cannot use /tmp for the temporary link. Symbolic links are - owned by user and group bin. - The filter runs as user daemon. - And the /tmp directory has the sticky bit - set. The filter can create the link, but it will not be able - clean up when done and remove it since the link will belong to - a different user. + cannot use /tmp for the temporary link. + Symbolic links are owned by user and group bin. The filter runs as user daemon. And the + /tmp directory has the sticky bit set. + The filter can create the link, but it will not be able clean + up when done and remove it since the link will belong to a + different user. Instead, the filter will make the symbolic link in the current working directory, which is the spooling directory @@ -10755,8 +10776,8 @@ You can control how much free space there needs to remain on the filesystem where a spooling directory - resides. Make a file called minfree in the spooling directory + resides. Make a file called + minfree in the spooling directory for the local printer. Insert in that file a number representing how many disk blocks (512 bytes) of free space there has to be for a remote job to be @@ -10766,11 +10787,11 @@ your filesystem. You can also use it to give a certain priority to local users: they will be able to queue jobs long after the free disk space has fallen below the - amount specified in the minfree file. + amount specified in the minfree + file. - For example, let us add a minfree file for the printer + For example, let us add a + minfree file for the printer bamboo. We examine /etc/printcap to find the spooling directory for this printer; here is options QUOTA The - stock GENERIC kernel does not have this enabled by default, so you - will have to configure, build and install a custom kernel in order - to use disk quotas. Please refer to the + stock GENERIC kernel does not have this enabled + by default, so you will have to configure, build and install a + custom kernel in order to use disk quotas. Please refer to the section for more information on kernel configuration. @@ -13294,7 +13315,7 @@ cuag If you do not want or need callout devices for some reason, you can dispense with making - the cua* devices. + the cua* devices. @@ -14498,10 +14519,12 @@ must contain one or more lines describing your host adapter(s). This includes I/O addresses, interrupts etc. Consult the man page for your adapter driver to get more info. - Apart from that, check out /sys/i386/conf/LINT for an overview - of a kernel config file. LINT contains every possible option - you can dream of. It does not imply LINT - will actually get you to a working kernel at all. + Apart from that, check out + /sys/i386/conf/LINT for an overview of a + kernel config file. LINT contains every + possible option you can dream of. It does + not imply LINT will + actually get you to a working kernel at all. Although it is probably stating the obvious: the kernel config file should reflect your actual hardware setup. So, @@ -14677,8 +14700,9 @@ probed. Because the INQUIRY response also includes the version number of the device firmware, it is even possible that for different firmware versions different workarounds are used. - See e.g. /sys/scsi/st.c and /sys/scsi/scsiconf.c for more info - on how this is done. + See e.g. /sys/scsi/st.c and + /sys/scsi/scsiconf.c for more info on how + this is done. This scheme works fine, but keep in mind that it of course only works for devices that are KNOWN to be weird. If you are @@ -15353,8 +15377,8 @@ rewoffl. If you are using the NCR SCSI controllers, patch the file - /usr/src/sys/pci/ncr.c (as shown below). Build and install a - new kernel. + /usr/src/sys/pci/ncr.c (as shown below). + Build and install a new kernel. diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml index 23c25b4f5a..4d243dd44c 100644 --- a/en_US.ISO8859-1/books/handbook/book.sgml +++ b/en_US.ISO8859-1/books/handbook/book.sgml @@ -1505,8 +1505,8 @@ Before installing from a MS-DOS partition To prepare for installation from an MS-DOS partition, copy the - files from the distribution into a directory called C:\FREEBSD. The directory tree structure of + files from the distribution into a directory called + C:\FREEBSD. The directory tree structure of the CDROM must be partially reproduced within this directory so we suggest using the DOS xcopy command. For example, to prepare for a minimal installation of FreeBSD: @@ -1514,13 +1514,13 @@ C> MD C:\FREEBSD C> XCOPY /S E:\BIN C:\FREEBSD\BIN\ C> XCOPY /S E:\MANPAGES C:\FREEBSD\MANPAGES\ - assuming that C: - is where you have free space and E: + assuming that C: + is where you have free space and E: is where your CDROM is mounted. For as many `DISTS' you wish to install from MS-DOS (and you - have free space for), install each one under C:\FREEBSD - the BIN dist + have free space for), install each one under + C:\FREEBSD - the BIN dist is only the minimal requirement. @@ -2248,10 +2248,11 @@ Install the program executable and other supporting - files, man pages, etc. under the /usr/local hierarchy, where - they will not get mixed up with system programs. This also - makes sure that all the ports you install will go in the same - place, instead of being flung all over your system. + files, man pages, etc. under the + /usr/local hierarchy, where they will not + get mixed up with system programs. This also makes sure that + all the ports you install will go in the same place, instead + of being flung all over your system. @@ -2291,7 +2292,8 @@ the initial setting up will already have been done for you. If not, make sure the FreeBSD CDROM is in - the drive and mounted on, say, /cdrom. Then do + the drive and mounted on, say, /cdrom. Then + do # mkdir /usr/ports # cd /usr/ports # ln -s @@ -2299,8 +2301,8 @@ to enable the ports make mechanism to find the tarballs (it - expects to find them in /usr/ports/distfiles, which is why we - sym-linked the CDROM's tarball directory to that + expects to find them in /usr/ports/distfiles, + which is why we sym-linked the CDROM's tarball directory to that directory). Now, suppose you want to install the gnats program from the @@ -2434,7 +2436,7 @@ - Makefile + <filename>Makefile</filename> The most important component of a skeleton is the Makefile. This contains various statements that specify how the port should @@ -2480,9 +2482,10 @@ Skipping over the next few lines for a minute, the line .include <bsd.port.mk> says that the other statements and commands needed for this port are - in a standard file called `bsd.port.mk". As these are the - same for all ports, there is no point in duplicating them all over - the place, so they are kept in a single standard file. + in a standard file called bsd.port.mk. As + these are the same for all ports, there is no point in duplicating + them all over the place, so they are kept in a single standard + file. This is probably not the place to go into a detailed examination of how Makefiles work; suffice it to say that the line @@ -2496,13 +2499,13 @@ - The files directory + The <filename>files</filename> directory The file containing the for the port is called "md5", after - the MD5 algorithm used for ports checksums. It lives in a - directory with the slightly confusing name of - "files". + remap="checksum"> for the port is called + md5, after the MD5 algorithm used for ports + checksums. It lives in a directory with the slightly confusing + name of files. This directory can also contain other miscellaneous files that are required by the port and do not belong anywhere else. @@ -2510,7 +2513,7 @@ - The patches directory + The <filename>patches</filename> directory This directory contains the needed to make everything work properly under @@ -2519,7 +2522,7 @@ - The pkg directory + The <filename>pkg</filename> directory This program contains three quite useful files:- @@ -2527,18 +2530,19 @@ - COMMENT - a one-line description of the program. + COMMENT - a one-line description of + the program. - DESCR - a more detailed description. + DESCR - a more detailed description. - PLIST - a list of all the files that will be created - when the program is installed. + PLIST - a list of all the files + that will be created when the program is installed. @@ -2703,16 +2707,19 @@ tarballs? - A. It is a file ending in .tar or .tar.gz (with variations - like .tar.Z, or even .tgz if you are trying to squeeze the - names into a DOS filesystem). + A. It is a file ending in .tar or + .tar.gz (with variations like + .tar.Z, or even .tgz + if you are trying to squeeze the names into a DOS + filesystem). Basically, it is a directory tree that has been archived - into a single file (.tar) and optionally compressed (.gz). - This technique was originally used for - Tape ARchives (hence - the name `tar'), but it is a widely used way of distributing - program source code around the Internet. + into a single file (.tar) and optionally + compressed (.gz). This technique was + originally used for Tape + ARchives (hence the name `tar'), but it is + a widely used way of distributing program source code around + the Internet. You can see what files are in them, or even extract them yourself, by using the standard Unix tar program, which comes @@ -2763,15 +2770,15 @@ Q. I did that, but when I tried to put it into - /usr/ports/distfiles I got some error about not having - permission. + /usr/ports/distfiles I got some error + about not having permission. A. The ports mechanism looks for the tarball in - /usr/ports/distfiles, but you will not be able to copy - anything there because it is sym-linked to the CDROM, which is - read-only. You can tell it to look somewhere else by - doing + /usr/ports/distfiles, but you will not be + able to copy anything there because it is sym-linked to the + CDROM, which is read-only. You can tell it to look somewhere + else by doing DISTDIR=/where/you/put/it make @@ -2781,9 +2788,10 @@ Q. Does the ports scheme only work if you have everything - in /usr/ports? My system administrator says I must put - everything under /u/people/guests/wurzburger, but it does not - seem to work. + in /usr/ports? My system administrator + says I must put everything under + /u/people/guests/wurzburger, but it does + not seem to work. A. You can use the PORTSDIR and PREFIX variables to tell @@ -2796,16 +2804,20 @@ install - will compile the port in /u/people/guests/wurzburger/ports - and install everything under /usr/local. + will compile the port in + /u/people/guests/wurzburger/ports and + install everything under /usr/local. + make PREFIX=/u/people/guests/wurzburger/local install - will compile it in /usr/ports and install it in - /u/people/guests/wurzburger/local. + will compile it in /usr/ports and + install it in + /u/people/guests/wurzburger/local. + And of course @@ -2912,11 +2924,12 @@ install - or by editing /etc/make.conf, but unfortunately not all - ports respect this. The surest way is to do 'make configure', - then go into the source directory and inspect the Makefiles by - hand, but this can get tedious if the source has lots of - sub-directories, each with their own Makefiles. + or by editing /etc/make.conf, but + unfortunately not all ports respect this. The surest way is to + do 'make configure', then go into the source directory and + inspect the Makefiles by hand, but this can get tedious if the + source has lots of sub-directories, each with their own + Makefiles. @@ -2997,8 +3010,8 @@ Q. I tried that and it still left all those tarballs or - whatever you called them in the distfiles directory. Can I - delete those as well? + whatever you called them in the distfiles + directory. Can I delete those as well? A. Yes, if you are sure you have finished with them, those @@ -3078,7 +3091,8 @@ A. Nothing secret about it at all, just look at the - bsd.ports.mk and bsd.ports.subdir.mk files in your bsd.ports.mk and + bsd.ports.subdir.mk files in your makefiles directory. (Note: readers with an aversion to intricate shell-scripts are advised not to follow this @@ -3171,10 +3185,10 @@ which is the staging area where your kernel will be built. Notice the logical organization of the directory tree, with each supported device, filesystem, and option in its own subdirectory. Also, - anything inside the i386 directory - deals with PC hardware only, while everything outside the i386 directory is common to all platforms - which FreeBSD could potentially be ported to. + anything inside the i386 directory deals with + PC hardware only, while everything outside the + i386 directory is common to all platforms which + FreeBSD could potentially be ported to.
@@ -3187,15 +3201,15 @@ Next, move to the i386/conf directory and - copy the GENERIC configuration file to the name you want to give - your kernel. For example: + copy the GENERIC configuration file to the name + you want to give your kernel. For example: # cd /usr/src/sys/i386/conf # cp GENERIC MYKERNEL Traditionally, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with different hardware, it is a good idea to name it after your - machine's hostname. We will call it MYKERNEL for the purpose of - this example. + machine's hostname. We will call it MYKERNEL + for the purpose of this example.
@@ -3205,19 +3219,22 @@
- Now, edit MYKERNEL with your favorite text editor. If you are - just starting out, the only editor available will probably be - vi, which is too complex to explain - here, but is covered well in many books in the Now, edit MYKERNEL with your favorite text + editor. If you are just starting out, the only editor available + will probably be vi, which is too + complex to explain here, but is covered well in many books in the + . Feel free to change the comment lines at the top to reflect your configuration or the - changes you have made to differentiate it from GENERIC. + changes you have made to differentiate it from + GENERIC. If you have build a kernel under SunOS or some other BSD - operating system, much of this file will be very familiar to you. - If you are coming from some other operating system such as DOS, on - the other hand, the GENERIC configuration file might seem - overwhelming to you, so follow the descriptions in the GENERIC configuration file + might seem overwhelming to you, so follow the descriptions in the + section slowly and carefully. @@ -3269,14 +3286,16 @@ most lines only contain one argument. Anything following a # is considered a comment and ignored. The following sections describe each keyword, generally in the order - they are listed in GENERIC, although some related keywords have been - grouped together in a single section (such as Networking) even - though they are actually scattered throughout the GENERIC file. - An - exhaustive list of options and more detailed explanations of the - device lines is present in the LINT configuration file, located in - the same directory as GENERIC. If you are in doubt as to the - purpose or necessity of a line, check first in LINT. + they are listed in GENERIC, although some + related keywords have been grouped together in a single section + (such as Networking) even though they are actually scattered + throughout the GENERIC file. + An exhaustive list of options and + more detailed explanations of the device lines is present in the + LINT configuration file, located in the same + directory as GENERIC. If you are in doubt as to + the purpose or necessity of a line, check first in + LINT. The kernel is currently being moved to a better organization of the option handling. Traditionally, each option in the config file @@ -3352,9 +3371,9 @@ remap=tt>cpu line may be present with different values of cpu_type - as are present in the GENERIC kernel. For a custom - kernel, it is best to specify only the cpu you have. If, - for example, you have an Intel Pentium, use + as are present in the GENERIC kernel. + For a custom kernel, it is best to specify only the cpu + you have. If, for example, you have an Intel Pentium, use I586_CPU for cpu_type. @@ -3365,8 +3384,9 @@ Next, we have ident, which is the identification of the kernel. You should - change this from GENERIC to whatever you named your - kernel, in this example, MYKERNEL. The value you put in + change this from GENERIC to whatever + you named your kernel, in this example, + MYKERNEL. The value you put in ident will print when you boot up the kernel, so it is useful to give a kernel a different name if you want to keep it separate from your @@ -3439,10 +3459,10 @@ This line specifies the location and name of the - kernel. Traditionally the kernel is called vmunix but in FreeBSD, it is aptly - named kernel. You should - always use kernel for + kernel. Traditionally the kernel is called + vmunix but in FreeBSD, it is aptly + named kernel. You should always use + kernel for kernel_name because changing it will render numerous system utilities inoperative. The second part of the line specifies the disk and partition where @@ -3623,9 +3643,9 @@ Process filesystem. This is a pretend filesystem - mounted on /proc which allows programs like - ps(1) to give you more information on - what processes are running. + mounted on /proc which allows + programs like ps(1) to give you more + information on what processes are running. @@ -5354,8 +5374,8 @@ - If any additional files (such as principal.* or master_key) + If any additional files (such as + principal.* or master_key) exist, then use the kdb_destroy command to destroy the old Kerberos database, of if Kerberos is not running, simply delete the extra files with dvilj2p makes the filter hpdf quite complex since dvilj2p cannot read from standard input. It wants to work with a filename. What is worse, the filename has to end in .dvi so using /dev/fd/0 for standard input is problematic. We can get around that problem by linking (symbolically) a temporary file name (one that ends in .dvi) to /dev/fd/0, thereby forcing dvilj2p to read from standard input. The only other fly in the ointment is the fact that we - cannot use /tmp for the temporary link. Symbolic links are - owned by user and group bin. - The filter runs as user daemon. - And the /tmp directory has the sticky bit - set. The filter can create the link, but it will not be able - clean up when done and remove it since the link will belong to - a different user. + cannot use /tmp for the temporary link. + Symbolic links are owned by user and group bin. The filter runs as user daemon. And the + /tmp directory has the sticky bit set. + The filter can create the link, but it will not be able clean + up when done and remove it since the link will belong to a + different user. Instead, the filter will make the symbolic link in the current working directory, which is the spooling directory @@ -10755,8 +10776,8 @@ You can control how much free space there needs to remain on the filesystem where a spooling directory - resides. Make a file called minfree in the spooling directory + resides. Make a file called + minfree in the spooling directory for the local printer. Insert in that file a number representing how many disk blocks (512 bytes) of free space there has to be for a remote job to be @@ -10766,11 +10787,11 @@ your filesystem. You can also use it to give a certain priority to local users: they will be able to queue jobs long after the free disk space has fallen below the - amount specified in the minfree file. + amount specified in the minfree + file. - For example, let us add a minfree file for the printer + For example, let us add a + minfree file for the printer bamboo. We examine /etc/printcap to find the spooling directory for this printer; here is options QUOTA The - stock GENERIC kernel does not have this enabled by default, so you - will have to configure, build and install a custom kernel in order - to use disk quotas. Please refer to the + stock GENERIC kernel does not have this enabled + by default, so you will have to configure, build and install a + custom kernel in order to use disk quotas. Please refer to the section for more information on kernel configuration. @@ -13294,7 +13315,7 @@ cuag If you do not want or need callout devices for some reason, you can dispense with making - the cua* devices. + the cua* devices. @@ -14498,10 +14519,12 @@ must contain one or more lines describing your host adapter(s). This includes I/O addresses, interrupts etc. Consult the man page for your adapter driver to get more info. - Apart from that, check out /sys/i386/conf/LINT for an overview - of a kernel config file. LINT contains every possible option - you can dream of. It does not imply LINT - will actually get you to a working kernel at all. + Apart from that, check out + /sys/i386/conf/LINT for an overview of a + kernel config file. LINT contains every + possible option you can dream of. It does + not imply LINT will + actually get you to a working kernel at all. Although it is probably stating the obvious: the kernel config file should reflect your actual hardware setup. So, @@ -14677,8 +14700,9 @@ probed. Because the INQUIRY response also includes the version number of the device firmware, it is even possible that for different firmware versions different workarounds are used. - See e.g. /sys/scsi/st.c and /sys/scsi/scsiconf.c for more info - on how this is done. + See e.g. /sys/scsi/st.c and + /sys/scsi/scsiconf.c for more info on how + this is done. This scheme works fine, but keep in mind that it of course only works for devices that are KNOWN to be weird. If you are @@ -15353,8 +15377,8 @@ rewoffl. If you are using the NCR SCSI controllers, patch the file - /usr/src/sys/pci/ncr.c (as shown below). Build and install a - new kernel. + /usr/src/sys/pci/ncr.c (as shown below). + Build and install a new kernel. diff --git a/en_US.ISO_8859-1/books/handbook/book.sgml b/en_US.ISO_8859-1/books/handbook/book.sgml index 23c25b4f5a..4d243dd44c 100644 --- a/en_US.ISO_8859-1/books/handbook/book.sgml +++ b/en_US.ISO_8859-1/books/handbook/book.sgml @@ -1505,8 +1505,8 @@ Before installing from a MS-DOS partition To prepare for installation from an MS-DOS partition, copy the - files from the distribution into a directory called C:\FREEBSD. The directory tree structure of + files from the distribution into a directory called + C:\FREEBSD. The directory tree structure of the CDROM must be partially reproduced within this directory so we suggest using the DOS xcopy command. For example, to prepare for a minimal installation of FreeBSD: @@ -1514,13 +1514,13 @@ C> MD C:\FREEBSD C> XCOPY /S E:\BIN C:\FREEBSD\BIN\ C> XCOPY /S E:\MANPAGES C:\FREEBSD\MANPAGES\ - assuming that C: - is where you have free space and E: + assuming that C: + is where you have free space and E: is where your CDROM is mounted. For as many `DISTS' you wish to install from MS-DOS (and you - have free space for), install each one under C:\FREEBSD - the BIN dist + have free space for), install each one under + C:\FREEBSD - the BIN dist is only the minimal requirement. @@ -2248,10 +2248,11 @@ Install the program executable and other supporting - files, man pages, etc. under the /usr/local hierarchy, where - they will not get mixed up with system programs. This also - makes sure that all the ports you install will go in the same - place, instead of being flung all over your system. + files, man pages, etc. under the + /usr/local hierarchy, where they will not + get mixed up with system programs. This also makes sure that + all the ports you install will go in the same place, instead + of being flung all over your system. @@ -2291,7 +2292,8 @@ the initial setting up will already have been done for you. If not, make sure the FreeBSD CDROM is in - the drive and mounted on, say, /cdrom. Then do + the drive and mounted on, say, /cdrom. Then + do # mkdir /usr/ports # cd /usr/ports # ln -s @@ -2299,8 +2301,8 @@ to enable the ports make mechanism to find the tarballs (it - expects to find them in /usr/ports/distfiles, which is why we - sym-linked the CDROM's tarball directory to that + expects to find them in /usr/ports/distfiles, + which is why we sym-linked the CDROM's tarball directory to that directory). Now, suppose you want to install the gnats program from the @@ -2434,7 +2436,7 @@ - Makefile + <filename>Makefile</filename> The most important component of a skeleton is the Makefile. This contains various statements that specify how the port should @@ -2480,9 +2482,10 @@ Skipping over the next few lines for a minute, the line .include <bsd.port.mk> says that the other statements and commands needed for this port are - in a standard file called `bsd.port.mk". As these are the - same for all ports, there is no point in duplicating them all over - the place, so they are kept in a single standard file. + in a standard file called bsd.port.mk. As + these are the same for all ports, there is no point in duplicating + them all over the place, so they are kept in a single standard + file. This is probably not the place to go into a detailed examination of how Makefiles work; suffice it to say that the line @@ -2496,13 +2499,13 @@ - The files directory + The <filename>files</filename> directory The file containing the for the port is called "md5", after - the MD5 algorithm used for ports checksums. It lives in a - directory with the slightly confusing name of - "files". + remap="checksum"> for the port is called + md5, after the MD5 algorithm used for ports + checksums. It lives in a directory with the slightly confusing + name of files. This directory can also contain other miscellaneous files that are required by the port and do not belong anywhere else. @@ -2510,7 +2513,7 @@ - The patches directory + The <filename>patches</filename> directory This directory contains the needed to make everything work properly under @@ -2519,7 +2522,7 @@ - The pkg directory + The <filename>pkg</filename> directory This program contains three quite useful files:- @@ -2527,18 +2530,19 @@ - COMMENT - a one-line description of the program. + COMMENT - a one-line description of + the program. - DESCR - a more detailed description. + DESCR - a more detailed description. - PLIST - a list of all the files that will be created - when the program is installed. + PLIST - a list of all the files + that will be created when the program is installed. @@ -2703,16 +2707,19 @@ tarballs? - A. It is a file ending in .tar or .tar.gz (with variations - like .tar.Z, or even .tgz if you are trying to squeeze the - names into a DOS filesystem). + A. It is a file ending in .tar or + .tar.gz (with variations like + .tar.Z, or even .tgz + if you are trying to squeeze the names into a DOS + filesystem). Basically, it is a directory tree that has been archived - into a single file (.tar) and optionally compressed (.gz). - This technique was originally used for - Tape ARchives (hence - the name `tar'), but it is a widely used way of distributing - program source code around the Internet. + into a single file (.tar) and optionally + compressed (.gz). This technique was + originally used for Tape + ARchives (hence the name `tar'), but it is + a widely used way of distributing program source code around + the Internet. You can see what files are in them, or even extract them yourself, by using the standard Unix tar program, which comes @@ -2763,15 +2770,15 @@ Q. I did that, but when I tried to put it into - /usr/ports/distfiles I got some error about not having - permission. + /usr/ports/distfiles I got some error + about not having permission. A. The ports mechanism looks for the tarball in - /usr/ports/distfiles, but you will not be able to copy - anything there because it is sym-linked to the CDROM, which is - read-only. You can tell it to look somewhere else by - doing + /usr/ports/distfiles, but you will not be + able to copy anything there because it is sym-linked to the + CDROM, which is read-only. You can tell it to look somewhere + else by doing DISTDIR=/where/you/put/it make @@ -2781,9 +2788,10 @@ Q. Does the ports scheme only work if you have everything - in /usr/ports? My system administrator says I must put - everything under /u/people/guests/wurzburger, but it does not - seem to work. + in /usr/ports? My system administrator + says I must put everything under + /u/people/guests/wurzburger, but it does + not seem to work. A. You can use the PORTSDIR and PREFIX variables to tell @@ -2796,16 +2804,20 @@ install - will compile the port in /u/people/guests/wurzburger/ports - and install everything under /usr/local. + will compile the port in + /u/people/guests/wurzburger/ports and + install everything under /usr/local. + make PREFIX=/u/people/guests/wurzburger/local install - will compile it in /usr/ports and install it in - /u/people/guests/wurzburger/local. + will compile it in /usr/ports and + install it in + /u/people/guests/wurzburger/local. + And of course @@ -2912,11 +2924,12 @@ install - or by editing /etc/make.conf, but unfortunately not all - ports respect this. The surest way is to do 'make configure', - then go into the source directory and inspect the Makefiles by - hand, but this can get tedious if the source has lots of - sub-directories, each with their own Makefiles. + or by editing /etc/make.conf, but + unfortunately not all ports respect this. The surest way is to + do 'make configure', then go into the source directory and + inspect the Makefiles by hand, but this can get tedious if the + source has lots of sub-directories, each with their own + Makefiles. @@ -2997,8 +3010,8 @@ Q. I tried that and it still left all those tarballs or - whatever you called them in the distfiles directory. Can I - delete those as well? + whatever you called them in the distfiles + directory. Can I delete those as well? A. Yes, if you are sure you have finished with them, those @@ -3078,7 +3091,8 @@ A. Nothing secret about it at all, just look at the - bsd.ports.mk and bsd.ports.subdir.mk files in your bsd.ports.mk and + bsd.ports.subdir.mk files in your makefiles directory. (Note: readers with an aversion to intricate shell-scripts are advised not to follow this @@ -3171,10 +3185,10 @@ which is the staging area where your kernel will be built. Notice the logical organization of the directory tree, with each supported device, filesystem, and option in its own subdirectory. Also, - anything inside the i386 directory - deals with PC hardware only, while everything outside the i386 directory is common to all platforms - which FreeBSD could potentially be ported to. + anything inside the i386 directory deals with + PC hardware only, while everything outside the + i386 directory is common to all platforms which + FreeBSD could potentially be ported to.
@@ -3187,15 +3201,15 @@ Next, move to the i386/conf directory and - copy the GENERIC configuration file to the name you want to give - your kernel. For example: + copy the GENERIC configuration file to the name + you want to give your kernel. For example: # cd /usr/src/sys/i386/conf # cp GENERIC MYKERNEL Traditionally, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with different hardware, it is a good idea to name it after your - machine's hostname. We will call it MYKERNEL for the purpose of - this example. + machine's hostname. We will call it MYKERNEL + for the purpose of this example.
@@ -3205,19 +3219,22 @@
- Now, edit MYKERNEL with your favorite text editor. If you are - just starting out, the only editor available will probably be - vi, which is too complex to explain - here, but is covered well in many books in the Now, edit MYKERNEL with your favorite text + editor. If you are just starting out, the only editor available + will probably be vi, which is too + complex to explain here, but is covered well in many books in the + . Feel free to change the comment lines at the top to reflect your configuration or the - changes you have made to differentiate it from GENERIC. + changes you have made to differentiate it from + GENERIC. If you have build a kernel under SunOS or some other BSD - operating system, much of this file will be very familiar to you. - If you are coming from some other operating system such as DOS, on - the other hand, the GENERIC configuration file might seem - overwhelming to you, so follow the descriptions in the GENERIC configuration file + might seem overwhelming to you, so follow the descriptions in the + section slowly and carefully. @@ -3269,14 +3286,16 @@ most lines only contain one argument. Anything following a # is considered a comment and ignored. The following sections describe each keyword, generally in the order - they are listed in GENERIC, although some related keywords have been - grouped together in a single section (such as Networking) even - though they are actually scattered throughout the GENERIC file. - An - exhaustive list of options and more detailed explanations of the - device lines is present in the LINT configuration file, located in - the same directory as GENERIC. If you are in doubt as to the - purpose or necessity of a line, check first in LINT. + they are listed in GENERIC, although some + related keywords have been grouped together in a single section + (such as Networking) even though they are actually scattered + throughout the GENERIC file. + An exhaustive list of options and + more detailed explanations of the device lines is present in the + LINT configuration file, located in the same + directory as GENERIC. If you are in doubt as to + the purpose or necessity of a line, check first in + LINT. The kernel is currently being moved to a better organization of the option handling. Traditionally, each option in the config file @@ -3352,9 +3371,9 @@ remap=tt>cpu line may be present with different values of cpu_type - as are present in the GENERIC kernel. For a custom - kernel, it is best to specify only the cpu you have. If, - for example, you have an Intel Pentium, use + as are present in the GENERIC kernel. + For a custom kernel, it is best to specify only the cpu + you have. If, for example, you have an Intel Pentium, use I586_CPU for cpu_type. @@ -3365,8 +3384,9 @@ Next, we have ident, which is the identification of the kernel. You should - change this from GENERIC to whatever you named your - kernel, in this example, MYKERNEL. The value you put in + change this from GENERIC to whatever + you named your kernel, in this example, + MYKERNEL. The value you put in ident will print when you boot up the kernel, so it is useful to give a kernel a different name if you want to keep it separate from your @@ -3439,10 +3459,10 @@ This line specifies the location and name of the - kernel. Traditionally the kernel is called vmunix but in FreeBSD, it is aptly - named kernel. You should - always use kernel for + kernel. Traditionally the kernel is called + vmunix but in FreeBSD, it is aptly + named kernel. You should always use + kernel for kernel_name because changing it will render numerous system utilities inoperative. The second part of the line specifies the disk and partition where @@ -3623,9 +3643,9 @@ Process filesystem. This is a pretend filesystem - mounted on /proc which allows programs like - ps(1) to give you more information on - what processes are running. + mounted on /proc which allows + programs like ps(1) to give you more + information on what processes are running. @@ -5354,8 +5374,8 @@ - If any additional files (such as principal.* or master_key) + If any additional files (such as + principal.* or master_key) exist, then use the kdb_destroy command to destroy the old Kerberos database, of if Kerberos is not running, simply delete the extra files with dvilj2p makes the filter hpdf quite complex since dvilj2p cannot read from standard input. It wants to work with a filename. What is worse, the filename has to end in .dvi so using /dev/fd/0 for standard input is problematic. We can get around that problem by linking (symbolically) a temporary file name (one that ends in .dvi) to /dev/fd/0, thereby forcing dvilj2p to read from standard input. The only other fly in the ointment is the fact that we - cannot use /tmp for the temporary link. Symbolic links are - owned by user and group bin. - The filter runs as user daemon. - And the /tmp directory has the sticky bit - set. The filter can create the link, but it will not be able - clean up when done and remove it since the link will belong to - a different user. + cannot use /tmp for the temporary link. + Symbolic links are owned by user and group bin. The filter runs as user daemon. And the + /tmp directory has the sticky bit set. + The filter can create the link, but it will not be able clean + up when done and remove it since the link will belong to a + different user. Instead, the filter will make the symbolic link in the current working directory, which is the spooling directory @@ -10755,8 +10776,8 @@ You can control how much free space there needs to remain on the filesystem where a spooling directory - resides. Make a file called minfree in the spooling directory + resides. Make a file called + minfree in the spooling directory for the local printer. Insert in that file a number representing how many disk blocks (512 bytes) of free space there has to be for a remote job to be @@ -10766,11 +10787,11 @@ your filesystem. You can also use it to give a certain priority to local users: they will be able to queue jobs long after the free disk space has fallen below the - amount specified in the minfree file. + amount specified in the minfree + file. - For example, let us add a minfree file for the printer + For example, let us add a + minfree file for the printer bamboo. We examine /etc/printcap to find the spooling directory for this printer; here is options QUOTA The - stock GENERIC kernel does not have this enabled by default, so you - will have to configure, build and install a custom kernel in order - to use disk quotas. Please refer to the + stock GENERIC kernel does not have this enabled + by default, so you will have to configure, build and install a + custom kernel in order to use disk quotas. Please refer to the section for more information on kernel configuration. @@ -13294,7 +13315,7 @@ cuag If you do not want or need callout devices for some reason, you can dispense with making - the cua* devices. + the cua* devices. @@ -14498,10 +14519,12 @@ must contain one or more lines describing your host adapter(s). This includes I/O addresses, interrupts etc. Consult the man page for your adapter driver to get more info. - Apart from that, check out /sys/i386/conf/LINT for an overview - of a kernel config file. LINT contains every possible option - you can dream of. It does not imply LINT - will actually get you to a working kernel at all. + Apart from that, check out + /sys/i386/conf/LINT for an overview of a + kernel config file. LINT contains every + possible option you can dream of. It does + not imply LINT will + actually get you to a working kernel at all. Although it is probably stating the obvious: the kernel config file should reflect your actual hardware setup. So, @@ -14677,8 +14700,9 @@ probed. Because the INQUIRY response also includes the version number of the device firmware, it is even possible that for different firmware versions different workarounds are used. - See e.g. /sys/scsi/st.c and /sys/scsi/scsiconf.c for more info - on how this is done. + See e.g. /sys/scsi/st.c and + /sys/scsi/scsiconf.c for more info on how + this is done. This scheme works fine, but keep in mind that it of course only works for devices that are KNOWN to be weird. If you are @@ -15353,8 +15377,8 @@ rewoffl. If you are using the NCR SCSI controllers, patch the file - /usr/src/sys/pci/ncr.c (as shown below). Build and install a - new kernel. + /usr/src/sys/pci/ncr.c (as shown below). + Build and install a new kernel.