diff options
Diffstat (limited to 'en_US.ISO_8859-1')
142 files changed, 0 insertions, 174257 deletions
diff --git a/en_US.ISO_8859-1/Makefile b/en_US.ISO_8859-1/Makefile deleted file mode 100644 index 0b2210c098..0000000000 --- a/en_US.ISO_8859-1/Makefile +++ /dev/null @@ -1,9 +0,0 @@ -# $FreeBSD$ - -SUBDIR = articles -SUBDIR+= books - -COMPAT_SYMLINK = en - -DOC_PREFIX?= ${.CURDIR}/.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/Makefile b/en_US.ISO_8859-1/articles/Makefile deleted file mode 100644 index b9f0648b93..0000000000 --- a/en_US.ISO_8859-1/articles/Makefile +++ /dev/null @@ -1,21 +0,0 @@ -# $FreeBSD: doc/en_US.ISO_8859-1/articles/Makefile,v 1.10 2001/03/14 18:11:19 nik Exp $ - -SUBDIR = committers-guide -SUBDIR+= dialup-firewall -SUBDIR+= diskless-x -SUBDIR+= explaining-bsd -SUBDIR+= freebsd-questions -SUBDIR+= fonts -SUBDIR+= formatting-media -SUBDIR+= ipsec-must -SUBDIR+= mh -SUBDIR+= multi-os -SUBDIR+= new-users -SUBDIR+= programming-tools -SUBDIR+= vm-design -SUBDIR+= zip-drive - -# ROOT_SYMLINKS+= new-users - -DOC_PREFIX?= ${.CURDIR}/../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/Makefile.inc b/en_US.ISO_8859-1/articles/Makefile.inc deleted file mode 100644 index 68161e6d79..0000000000 --- a/en_US.ISO_8859-1/articles/Makefile.inc +++ /dev/null @@ -1,5 +0,0 @@ -# -# $FreeBSD$ -# - -DESTDIR?= ${DOCDIR}/en_US.ISO_8859-1/articles/${.CURDIR:T} diff --git a/en_US.ISO_8859-1/articles/committers-guide/Makefile b/en_US.ISO_8859-1/articles/committers-guide/Makefile deleted file mode 100644 index 51fe6d2820..0000000000 --- a/en_US.ISO_8859-1/articles/committers-guide/Makefile +++ /dev/null @@ -1,27 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/Makefile,v 1.3 1999/09/06 06:52:35 peter Exp $ -# -# Build the FreeBSD New Committers Guide -# - -MAINTAINER=jhb@FreeBSD.org - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -JADEFLAGS+= -V %generate-article-toc% - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/committers-guide/article.sgml b/en_US.ISO_8859-1/articles/committers-guide/article.sgml deleted file mode 100644 index d815e9ef34..0000000000 --- a/en_US.ISO_8859-1/articles/committers-guide/article.sgml +++ /dev/null @@ -1,2260 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"> -%authors; - -<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"> -%mailing-lists; -]> - -<article> - <artheader> - <title>Committer Guide</title> - - <authorgroup> - <author> - <surname>The FreeBSD Documentation Project</surname> - </author> - </authorgroup> - - <pubdate>$FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.70 2001/06/03 21:39:50 dd Exp $</pubdate> - - <copyright> - <year>1999</year> - <year>2000</year> - <year>2001</year> - <holder>The FreeBSD Documentation Project</holder> - </copyright> - - <abstract> - <para>This document provides information for the FreeBSD committer - community. All new committers should read this document before they - start, and existing committers are strongly encouraged to review it - from time to time.</para> - </abstract> - </artheader> - - <sect1 id="admin"> - <title>Administrative Details</title> - - <informaltable frame="none" orient="port"> - <tgroup cols="2"> - <tbody> - <row> - <entry><emphasis>Main Repository Host</emphasis></entry> - <entry><hostid>freefall.FreeBSD.org</hostid></entry> - </row> - - <row> - <entry><emphasis>Login Methods</emphasis></entry> - <entry>&man.ssh.1;</entry> - </row> - - <row> - <entry><emphasis>Main CVSROOT</emphasis></entry> - <entry>/home/ncvs</entry> - </row> - - <row> - <entry><emphasis>Main CVS Repository Meisters</emphasis></entry> - <entry>&a.jdp; and &a.peter; as well as &a.asami; for - <filename>ports/</filename></entry> - </row> - - <row> - <entry><emphasis>Mailing List</emphasis></entry> - <entry><email>developers@FreeBSD.org</email>, - <email>cvs-committers@FreeBSD.org</email></entry> - </row> - - <row> - <entry><emphasis>Noteworthy CVS Tags</emphasis></entry> - <entry>RELENG_3 (3.x-STABLE), RELENG_4 (4.x-STABLE), HEAD (-CURRENT)</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>It is required that you use &man.ssh.1; or &man.telnet.1; - with Kerberos 5 to connect to the repository hosts. These are - generally more secure than plain &man.telnet.1; or - &man.rlogin.1; since credential negotiation will always be - encrypted. All traffic is encrypted by default with &man.ssh.1;. - With utilities like &man.ssh-agent.1; and &man.scp.1; also - available, &man.ssh.1; is also far more convenient. If you do - not know anything about &man.ssh.1;, please see - <xref linkend="ssh.guide">.</para> - </sect1> - - <sect1 id="cvs.operations"> - <title>CVS Operations</title> - - <para>It is assumed that you are already familiar with the basic operation - of CVS.</para> - - <para>The CVS Repository Meisters (Peter Wemm and John Polstra) - are the <quote>owners</quote> of the CVS repository and are - responsible for any and <emphasis>all</emphasis> direct - modification of it for the purposes of cleanup or fixing some - grievous abuse of CVS by a committer. No one else should - attempt to touch the repository directly. Should you cause some - repository accident, say a bad cvs import or tag operation, do - <emphasis role="bold">not</emphasis> attempt to fix it yourself! - Mail or call John or Peter immediately and report the problem to - one of them instead. The only ones allowed to directly fiddle - the repository bits are the repomeisters. Satoshi Asami is also a - repomeister for the <filename>ports/</filename> portion of the - tree.</para> - - <para>CVS operations are usually done by logging into - <hostid>freefall</hostid>, making sure the - <envar>CVSROOT</envar> environment variable is set to - <filename>/home/ncvs</filename>, and then doing the appropriate - check-out/check-in operations. If you wish to add - something which is wholly new (like contrib-ified - sources, etc), a script called <quote>easy-import</quote> is - also provided for making the process easier. It automatically - adds the new module entry, does the appropriate thing with - <command>cvs import</command>, etc. – just run it without - arguments and it will prompt you for everything it needs to - know.</para> - - <para>Note that when you use CVS on <hostid>freefall</hostid>, you - should set your <literal>umask</literal> to <literal>2</literal>, - as well as setting the <literal>CVSUMASK</literal> environment - variable to <literal>2</literal>. This ensures that any new - files created by <command>cvs add</command> will have the correct - permissions. If you add a file or directory and discover that the - file in the repository has incorrect permissions (specifically, - all files in the repository should be group writable by group - <literal>ncvs</literal>), contact one of the repository meisters - as described below.</para> - - <para>If you are familiar with remote CVS and consider yourself - pretty studly with CVS in general, you can also do CVS - operations directly from your own machine and local working - sources. Just remember to set <envar>CVS_RSH</envar> to - <wordasword>ssh</wordasword> so that you are using a relatively - secure and reliable transport. If you have no idea what any of - the above even means, on the other hand, then please stick with - logging into <hostid>freefall</hostid> and applying your diffs - with &man.patch.1;.</para> - - <para>If you need to use CVS <command>add</command> and - <command>delete</command> operations in a manner that is - effectively a <quote>mv</quote> operation, then a repository - copy is in order rather than your CVS <command>add</command> and - <command>delete</command>. In a repository copy, a <link - linkend="conventions">CVS Meister</link> will copy the file(s) - to their new name and/or location and let you know when it is - done. The purpose of a repository copy is to preserve file - change history, or logs. We in the FreeBSD Project greatly - value the change history CVS gives to the project.</para> - - <para>CVS reference information, tutorials, and FAQs can also be found at: - <ulink - url="http://www.cvshome.org/docs/index.html">http://www.cvshome.org/docs/index.html</ulink>, - and the information in <ulink url="http://cvsbook.red-bean.com/cvsbook.html">Karl Fogel's - chapters from <quote>Open Source Development with CVS</quote></ulink> are also very - useful.</para> - - <para>&a.des; also supplied the following <quote>mini primer</quote> for - CVS.</para> - - <orderedlist> - <listitem> - <para>Check out a module with the <literal>co</literal> or - <literal>checkout</literal> command.</para> - - <screen>&prompt.user; <userinput>cvs checkout shazam</userinput></screen> - - <para>This checks out a copy of the <filename>shazam</filename> module. If - there is no <filename>shazam</filename> module in the modules file, it looks for a - top-level directory named <filename>shazam</filename> instead.</para> - - <table frame="none"> - <title>Useful <command>cvs checkout</command> options</title> - - <tgroup cols=2> - <tbody> - <row> - <entry><option>-P</option></entry> - <entry>Don't create empty directories</entry> - </row> - - <row> - <entry><option>-l</option></entry> - <entry>Check out a single level, no subdirectories</entry> - </row> - - <row> - <entry><option>-r<replaceable>rev</replaceable></option></entry> - <entry>Check out revision, branch or tag - <replaceable>rev</replaceable></entry> - </row> - - <row> - <entry><option>-D<replaceable>date</replaceable></option></entry> - <entry>Check out the sources as they were on date - <replaceable>date</replaceable></entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Practical FreeBSD examples:</para> - - <itemizedlist> - <listitem> - <para>Check out the <filename>miscfs</filename> module, - which corresponds to <filename>src/sys/miscfs</filename>:</para> - - <screen>&prompt.user; <userinput>cvs co miscfs</userinput></screen> - - <para>You now have a directory named <filename>miscfs</filename> - with subdirectories <filename>CVS</filename>, - <filename>deadfs</filename>, <filename>devfs</filename>, and so - on. One of these (<filename>linprocfs</filename>) is - empty.</para> - </listitem> - - <listitem> - <para>Check out the same files, but with full path:</para> - - <screen>&prompt.user; <userinput>cvs co src/sys/miscfs</userinput></screen> - - <para>You now have a directory named <filename>src</filename>, - with subdirectories <filename>CVS</filename> and - <filename>sys</filename>. <filename>src/sys</filename> has - subdirectories <filename>CVS</filename> and - <filename>miscfs</filename>, etc.</para> - </listitem> - - <listitem> - <para>Check out the same files, but prunes empty - directories:</para> - - <screen>&prompt.user; <userinput>cvs co -P miscfs</userinput></screen> - - <para>You now have a directory named - <filename>miscfs</filename> with subdirectories - <filename>CVS</filename>, <filename>deadfs</filename>, - <filename>devfs</filename>... but note that there is no - <filename>linprocfs</filename> subdirectory, because there - are no files in it.</para> - </listitem> - - <listitem> - <para>Check out the directory <filename>miscfs</filename>, but - none of the subdirectories:</para> - - <screen>&prompt.root; <userinput>cvs co -l miscfs</userinput></screen> - - <para>You now have a directory named <filename>miscfs</filename> - with just one subdirectory named - <filename>CVS</filename>.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as - it is in the 4.x branch:</para> - - <screen>&prompt.user; <userinput>cvs co -rRELENG_4 miscfs</userinput></screen> - - <para>You can modify the sources and commit along this - branch.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as - it was in 3.4-RELEASE.</para> - - <screen>&prompt.user; <userinput>cvs co -rRELENG_3_4_0_RELEASE miscfs</userinput></screen> - - <para>You will not be able to commit modifications, since - RELENG_3_4_0_RELEASE is a point in time, not a branch.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as it was - on Jan 15 2000.</para> - - <screen>&prompt.user; <userinput>cvs co -D'01/15/2000' miscfs</userinput></screen> - - <para>You will not be able to commit modifications.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as it was - one week agao.</para> - - <screen>&prompt.user; <userinput>cvs co -D'last week' miscfs</userinput></screen> - - <para>You will not be able to commit modifications.</para> - </listitem> - </itemizedlist> - - <para>Note that cvs stores metadata in subdirectories named - <filename>CVS</filename>.</para> - - <para>Arguments to <option>-D</option> and <option>-r</option> - are sticky, which means cvs will remember them later, e.g. - when you do a <command>cvs update</command>.</para> - </listitem> - - <listitem> - <para>Check the status of checked-out files with the - <literal>status</literal> command.</para> - - <screen>&prompt.user; <userinput>cvs status shazam</userinput></screen> - - <para>This displays the status of the - <filename>shazam</filename> file or of every file in the - <filename>shazam</filename> directory. For every file, the - status is given as one of:</para> - - <informaltable frame="none"> - <tgroup cols=2> - <tbody> - <row> - <entry>Up-to-date</entry> - <entry>File is up-to-date and unmodified.</entry> - </row> - - <row> - <entry>Needs Patch</entry> - <entry>File is unmodified, but there's a newer revision in - the repository.</entry> - </row> - - <row> - <entry>Locally Modified</entry> - <entry>File is up-to-date, but modified.</entry> - </row> - - <row> - <entry>Needs Merge</entry> - <entry>File is modified, and there's a newer revision in the - repository.</entry> - </row> - - <row> - <entry>File had conflicts on merge</entry> - <entry>There were conflicts the last time this file was - updated, and they haven't been resolved yet.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>You'll also see the local revision and date, - the revision number of the newest applicable version - (<quote>newest applicable</quote> because if you have a - sticky date, tag or branch, it may not be the actual newest - revision), and any sticky tags, dates or options.</para> - </listitem> - - <listitem> - <para>Once you've checked something out, update it with the - <literal>update</literal> command.</para> - - <screen>&prompt.user; <userinput>cvs update shazam</userinput></screen> - - <para>This updates the <filename>shazam</filename> file or the - contents of the <filename>shazam</filename> directory to the - latest version along the branch you checked out. If you - checked out a <quote>point in time</quote>, does nothing - unless the tags have moved in the repository or some other weird - stuff is going on.</para> - - <para>Useful options, in addition to those listed above for - <literal>checkout</literal>:</para> - - <informaltable frame="none"> - <tgroup cols=2> - <tbody> - <row> - <entry><option>-d</option></entry> - <entry>Check out any additional missing directories.</entry> - </row> - - <row> - <entry><option>-A</option></entry> - <entry>Update to head of main branch.</entry> - </row> - - <row> - <entry><option>-j<replaceable>rev</replaceable></option></entry> - <entry>More magic (see below).</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>If you checked out a module with <option>-r</option> or - <option>-D</option>, running <command>cvs update</command> - with a different <option>-r</option> or <option>-D</option> - argument or with <option>-A</option> will select a new branch, - revision or date. The <option>-A</option> option clears all - sticky tags, dates or revisions whereas <option>-r</option> - and <option>-D</option> set new ones.</para> - - <para>Theoretically, specifying <literal>HEAD</literal> as - argument to <option>-r</option> will give you the same result - as <option>-A</option>, but that's just theory.</para> - - <para>The <option>-d</option> option is useful if:</para> - - <itemizedlist> - <listitem> - <para>somebody has added subdirectories to the module - you've checked out after you checked it out.</para> - </listitem> - - <listitem> - <para>you checked out with <option>-l</option>, and later - change your mind and want to check out the subdirectories - as well.</para> - </listitem> - - <listitem> - <para>you deleted some subdirectories and want to check - them all back out.</para> - </listitem> - </itemizedlist> - - <para><emphasis>Watch the output of the <command>cvs - update</command> with care.</emphasis> The letter in front of - each file name indicates what was done with it:</para> - - <informaltable frame="none"> - <tgroup cols=2> - <tbody> - <row> - <entry><literal>U</literal></entry> - <entry>The file was updated with no trouble.</entry> - </row> - - <row> - <entry><literal>P</literal></entry> - <entry>The file was updated with no trouble (you'll only see - this when working against a remote repo).</entry> - </row> - - <row> - <entry><literal>M</literal></entry> - <entry>The file had been modified, and was merged with no - conflicts.</entry> - </row> - - <row> - <entry><literal>C</literal></entry> - <entry>The file had been modified, and was merged with - conflicts.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Merging is what happens if you check out a copy of - some source code, modify it, then someone else commits a - change, and you run <command>cvs update</command>. CVS notices - that you've made local changes, and tries to merge your - changes with the changes between the version you originally - checked out and the one you updated to. If the changed are to - separate portions of the file, it'll almost always work fine - (though the result might not be syntactically or semantically - correct).</para> - - <para>CVS will print an 'M' in front of every locally modified - file even if there is no newer version in the repository, so - <command>cvs update</command> is handy for getting a summary - of what you've changed locally.</para> - - <para>If you get a <literal>C</literal>, then your changes - conflicted with the changes in the repository (the changes - were to the same lines, or neighboring lines, or you changed - the local file so much that <command>cvs</command> can't - figure out how to apply the repository's changes). You'll have - to go through the file manually and resolve the conflicts; - they'll be marked with rows of <literal><</literal>, - <literal>=</literal> and <literal>></literal> signs. For - every conflict, there'll be a marker line with seven - <literal><</literal> signs and the name of the file, - followed by a chunk of what your local file contained, - followed by a separator line with seven <literal>=</literal> - signs, followed by the corresponding chunk in the - repository version, followed by a marker line with seven - <literal>></literal> signs and the revision number you - updated to.</para> - - <para>The <option>-j</option> option is slightly voodoo. It - updates the local file to the specified revision as if you - used <option>-r</option>, but it does not change the recorded - revision number or branch of the local file. It's not really - useful except when used twice, in which case it will merge the - changes between the two specified versions into the working - copy.</para> - - <para>For instance, say you commit a change to - <filename>shazam/shazam.c</filename> in -CURRENT and later - want to MFC it. The change you want to MFC was revision - 1.15:</para> - - <itemizedlist> - <listitem> - <para>Check out the -STABLE version of the - <filename>shazam</filename> module:</para> - - <screen>&prompt.user; <userinput>cvs co -rRELENG_4 shazam</userinput></screen> - </listitem> - - <listitem> - <para>Apply the changes between rev 1.14 and 1.15:</para> - - <screen>&prompt.user; <userinput>cvs update -j1.14 -j1.15 shazam/shazam.c</userinput></screen> - </listitem> - </itemizedlist> - - <para>You'll almost certainly get a conflict because - of the <literal>$Id: article.sgml,v 1.71 2001-06-09 14:01:06 nik Exp $</literal> (or in FreeBSD's case, - <literal>$FreeBSD<!-- stop expansion -->$</literal>) lines, so you'll have to edit - the file to resolve the conflict (remove the marker lines and - the second <literal>$Id: article.sgml,v 1.71 2001-06-09 14:01:06 nik Exp $</literal> line, leaving the original - <literal>$Id: article.sgml,v 1.71 2001-06-09 14:01:06 nik Exp $</literal> line intact).</para> - </listitem> - - <listitem> - <para>View differences between the local version and the - repository version with the <literal>diff</literal> - command.</para> - - <screen>&prompt.user; <userinput>cvs diff shazam</userinput></screen> - - <para>shows you every modification you've made to the - <filename>shazam</filename> file or module.</para> - - <table frame="none"> - <title>Useful <command>cvs diff</command> options</title> - - <tgroup cols=2> - <tbody> - <row> - <entry><option>-u</option></entry> - <entry>Uses the unified diff format.</entry> - </row> - - <row> - <entry><option>-N</option></entry> - <entry>Shows missing or added files.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>You always want to use <option>-u</option>, since - unified diffs are much easier to read than almost any other - diff format (in some circumstances, context diffs may be - better, but they're much bulkier). A unified diff consists of - a series of hunks. Each hunk begins with a line that starts - with two <literal>@</literal> signs and specifies where in the - file the differences are and how many lines they span. This - is followed by a number of lines; some (preceded by a blank) - are context; some (preceded by a <literal>-</literal> sign) - are outtakes and some (preceded by a <literal>+</literal>) are - additions.</para> - - <para>You can also diff against a different version - than the one you checked out by specifying a version - with <option>-r</option> or <option>-D</option> as in - <literal>checkout</literal> or <literal>update</literal>, - or even view the diffs between two arbitrary versions - (with no regard for what you have locally) by specifying - <emphasis>two</emphasis> versions with <option>-r</option> or - <option>-D</option>.</para> - </listitem> - - <listitem> - <para>View log entries with the <literal>log</literal> - command.</para> - - <!-- XXX needs more details --> - <screen>&prompt.user; <userinput>cvs log shazam</userinput></screen> - </listitem> - - <listitem> - <para>See who did what with the <literal>annotate</literal> command. - This command shows you each line of the specified file or - files, along with which user most recently changed that - line.</para> - - <screen>&prompt.user; <userinput>cvs annotate shazam</userinput></screen> - </listitem> - - <listitem> - <para>Add new files with the <literal>add</literal> command.</para> - - <para>Create the file, <command>cvs add</command> it, then - <command>cvs commit</command> it.</para> - - <para>Similarly, you can add new directories by creating them - and then <command>cvs add</command>ing them. Note that you - don't need to commit directories.</para> - </listitem> - - <listitem> - <para>Remove obsolete files with the <literal>remove</literal> command.</para> - - <para>Remove the file, then <command>cvs rm</command> it, then - <command>cvs commit</command> it.</para> - </listitem> - - <listitem> - <para>Commit with the <literal>commit</literal> or - <literal>checkin</literal> command.</para> - - <table frame="none"> - <title>Useful <command>cvs commit</command> options</title> - - <tgroup cols=2> - <tbody> - <row> - <entry><option>-f</option></entry> - <entry>Force a commit of an unmodified file.</entry> - </row> - - <row> - <entry><option>-m<replaceable>msg</replaceable></option></entry> - <entry>Specify a commit message on the command line rather - than invoking an editor.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Use the <option>-f</option> option if you realize that - you left out important information from the commit message.</para> - - <para>Good commit messages are important. They tell others - why you did the changes you did, not just right here and now, - but months or years from now when someone wonders why some - seemingly illogical or inefficient piece of code snuck into - your source file. It's also an invaluable aid to deciding - which changes to MFC and which not to MFC.</para> - - <para>Don't waste space in the commit messages explaining - <emphasis>what</emphasis> you did. That's what - <command>cvs diff</command> is for. Instead, tell us - <emphasis>why</emphasis> you did it.</para> - - <para>Avoid committing several unrelated changes in one go. It - makes merging difficult, and also makes it harder to determine - which change is the culprit if a bug crops up.</para> - - <para>Avoid committing style or whitespace fixes and - functionality fixes in one go. It makes merging difficult, - and also makes it harder to understand just what functional - changes were made.</para> - - <para>Avoid committing changes to multiple files in one go - with a generic, vague message. Instead, commit each file (or - small groups of files) with tailored commit messages.</para> - - <para>Before committing, <emphasis>always</emphasis>:</para> - - <itemizedlist> - <listitem> - <para>verify which branch you're committing to, using - <command>cvs status</command>.</para> - </listitem> - - <listitem> - <para>review your diffs, using - <command>cvs diff</command></para> - </listitem> - </itemizedlist> - - <para>Also, ALWAYS specify which files to commit explicitly on - the command line, so you don't accidentally commit other files - than the ones you intended - <command>cvs commit</command> - with no arguments will commit every modification in your - current working directory and every subdirectory.</para> - </listitem> - </orderedlist> - - <para>Additional tips and tricks:</para> - - <orderedlist> - <listitem> - - <para>You can place commonly used options in your - <filename>~/.cvsrc</filename>, like this:</para> - - <programlisting>cvs -z3 -diff -Nu -update -Pd -checkout -P</programlisting> - - <para>This example says:</para> - - <itemizedlist> - <listitem> - <para>always use compression level 3 when talking to a - remote server. This is a life-saver when working over a - slow connection.</para> - </listitem> - - <listitem> - <para>always use the <option>-N</option> (show added or - removed files) and <option>-u</option> (unified diff - format) options to &man.diff.1;.</para> - </listitem> - - <listitem> - <para>always use the <option>-P</option> (prune empty - directories) and <option>-d</option> (check out new - directories) options when updating.</para> - </listitem> - - <listitem> - <para>always use the <option>-P</option> (prune empty - directories) option when checking out.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Use Eivind Eklund's <command>cdiff</command> script to - view unidiffs. It's a wrapper for &man.less.1; that adds ANSI - color codes to make hunk headers, outtakes and additions stand - out; context and garbage are unmodified. It also expands tabs - properly (tabs often look wrong in diffs because of the extra - character in front of each line).</para> - -<para><ulink url="http://people.FreeBSD.org/~eivind/cdiff">http://people.FreeBSD.org/~eivind/cdiff</ulink></para> - - <para>Simply use it instead of &man.more.1; or &man.less.1;:</para> - - <screen>&prompt.user; <userinput>cvs diff -Nu shazam | cdiff</userinput></screen> - - <para>Alternatively some editors like &man.vim.1; - (ports/editors/vim5) have color support and when used as - a pager with color syntax highlighting switched on will - highlight many types of file, including diffs, patches, - and cvs/rcs logs. </para> - - <screen>&prompt.user; <userinput> echo "syn on" >> ~/.vimrc </userinput> -&prompt.user; <userinput> cvs diff -Nu shazam | vim -</userinput> -&prompt.user; <userinput> cvs log shazam | vim -</userinput> </screen> - </listitem> - - <listitem> - <para>CVS is old, arcane, crufty and buggy, and sometimes - exhibits non-deterministic behavior which some claim as proof - that it's actually merely the Newtonian manifestation of a - sentient transdimensional entity. It's not humanly possible - to know its every quirk inside out, so don't be afraid to ask - the resident AI (<email>cvs@FreeBSD.org</email>) for help when - you screw up.</para> - </listitem> - - <listitem> - <para>Don't leave the <command>cvs commit</command> command in commit - message editing mode for too long (more than 2-3 minutes). It - locks the directory you are working with and will prevent other - developers from committing into the same directory. If you have - to type a long commit message, type it before executing - <command>cvs commit</command>, and insert it into the commit - message.</para> - </listitem> - </orderedlist> - - </sect1> - - <sect1 id="conventions"> - <title>Conventions and Traditions</title> - - <para>As a new committer there are a number of things you should do - first.</para> - - <itemizedlist> - <listitem> - <para>Add yourself to the <quote>Developers</quote> section of the - Handbook and remove yourself from the <quote>Additional - Contributors</quote> section.</para> - - <para>This is a relatively easy task, but remains a good first test of - your CVS skills.</para> - </listitem> - - <listitem> - <para>Add an entry for yourself to - <filename>www/en/news/newsflash.sgml</filename>. Look for the other - entries that look like <quote>A new committer</quote> and follow the - format.</para> - </listitem> - - <listitem> - <para>If you have a PGP or GnuPG key, you may want to add it to - <filename>doc/en_US.ISO_8859-1/books/handbook/pgpkeys</filename>. - </para> - </listitem> - - <listitem> - <para>Some people also add an entry for themselves to - <filename>ports/astro/xearth/files/freebsd.committers.markers</filename>.</para> - </listitem> - - <listitem> - <para>Introduce yourself to the other committers, otherwise no one - will have any idea who you are or what you are working on. You do - not have to write a comprehensive biography, just write a paragraph - or two about who you are and what you plan to be working on as a - committer in FreeBSD. Email this to - <email>developers@FreeBSD.org</email> and you will be on your - way!</para> - </listitem> - - <listitem> - <para>Log into <hostid>hub.FreeBSD.org</hostid> and create a - <filename>/var/forward/<replaceable>user</replaceable></filename> - (where <replaceable>user</replaceable> is your username) file - containing the e-mail address where you want mail addressed to - <replaceable>yourusername</replaceable>@FreeBSD.org to be forwarded. - This includes all of the commit messages as well as any other mail - addressed to <email>cvs-committers@FreeBSD.org</email> and - <email>developers@FreeBSD.org</email>. Really - large mailboxes which have taken up permanent residence on - <hostid>hub</hostid> often get <quote>accidently</quote> truncated - without warning, so forward it or read it and you will not lose - it.</para> - </listitem> - </itemizedlist> - - <para>All new committers also have a mentor assigned to them for - the first few months. Your mentor is more or less responsible for - explaining anything which is confusing to you and is also - responsible for your actions during this initial period. If you - make a bogus commit, it is only going to embarrass your mentor - and you should probably make it a policy to pass at least your - first few commits by your mentor before committing it to the - repository.</para> - - <para>All commits should go to <literal>-CURRENT</literal> first - before being merged to <literal>-STABLE</literal>. No major new - features or high-risk modifications should be made to the - <literal>-STABLE</literal> branch.</para> - </sect1> - - <sect1 id="developer.relations"> - <title>Developer Relations</title> - - <para>If you are working directly on your own code or on code - which is already well established as your responsibility, then - there is probably little need to check with other committers - before jumping in with a commit. If you see a bug in an area of - the system which is clearly orphaned (and there are a few such - areas, to our shame), the same applies. If, however, you are - about to modify something which is clearly being actively - maintained by someone else (and it is only by watching the - <literal>cvs-committers</literal> mailing list that you can - really get a feel for just what is and is not) then consider - sending the change to them instead, just as you would have - before becoming a committer. For ports, you should contact the - listed <makevar>MAINTAINER</makevar> in the - <filename>Makefile</filename>. For other parts of the - repository, if you are unsure who the active maintainer might - be, it may help to scan the output of <command>cvs log</command> - to see who has committed changes in the past. &a.fenner; has - written a nice shell script that can help determine who the - active maintainer might be. It lists each person who has - committed to a given file along with the number of commits each - person has made. It can be found on <hostid>freefall</hostid> - at <filename>~fenner/bin/whodid</filename>. If your queries go - unanswered or the committer otherwise indicates a lack of - proprietary interest in the area affected, go ahead and commit - it.</para> - - <para>If you are unsure about a commit for any reason at - all, have it reviewed by <literal>-hackers</literal> - before committing. Better to have it flamed then and there - rather than when it is part of the CVS repository. If you do - happen to commit something which results in controversy - erupting, you may also wish to consider backing the change out - again until the matter is settled. Remember – with CVS we - can always change it back.</para> - </sect1> - - <sect1 id="gnats"> - <title>GNATS</title> - - <para>The FreeBSD Project utilizes - <application>GNATS</application> for tracking bugs and change - requests. Be sure that if you commit a fix or suggestion found - in a <application>GNATS</application> PR, you use - <command>edit-pr <replaceable>pr-number</replaceable></command> - on <hostid>freefall</hostid> to close it. It is also considered - nice if you take time to close any PRs associated with your - commits, if appropriate. You can also make use of - &man.send-pr.1; yourself for proposing any change which you feel - should probably be made, pending a more extensive peer-review - first.</para> - - <para>You can find out more about <application>GNATS</application> - at:</para> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html">http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.FreeBSD.org/support.html">http://www.FreeBSD.org/support.html</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.FreeBSD.org/send-pr.html">http://www.FreeBSD.org/send-pr.html</ulink></para> - </listitem> - - <listitem> - <para>&man.send-pr.1;</para> - </listitem> - </itemizedlist> - - <para>You can run a local copy of GNATS, and then integrate the FreeBSD - GNATS tree in to it using CVSup. Then you can run GNATS commands - locally, or use other interfaces, such as <command>tkgnats</command>. - This lets you query the PR database without needing to be connected to - the Internet.</para> - - <procedure> - <title>Using a local GNATS tree</title> - - <step> - <para>If you are not already downloading the GNATS tree, add this line - to your <filename>supfile</filename>, and re-sup. Note that since - GNATS is not under CVS control it has no tag, so if you are adding - it to your existing <filename>supfile</filename> it should appear - before any <quote>tag=</quote> entry as these remain active once set. - </para> - - <programlisting>gnats release=current prefix=/usr</programlisting> - - <para>This will place the FreeBSD GNATS tree in - <filename>/usr/gnats</filename>. You can use a - <emphasis>refuse</emphasis> file to control which categories to - receive. For example, to only receive <literal>docs</literal> PRs, - put this line in - <filename>/usr/local/etc/cvsup/sup/refuse</filename><footnote> - <para>The precise path depends on the <literal>*default - base</literal> setting in your - <filename>supfile</filename>.</para> - </footnote>.</para> - - <programlisting>gnats/[a-ce-z]*</programlisting> - - <para>The rest of these examples assume you have only supped the - <literal>docs</literal> category. Adjust them as necessary, - depending on the categories you are synching.</para> - </step> - - <step> - <para>Install the GNATS port from - <filename>ports/databases/gnats</filename>. This will place the - various GNATS directories under - <filename>$PREFIX/share/gnats</filename>.</para> - </step> - - <step> - <para>Symlink the GNATS directories you are supping under the version - of GNATS you have installed.</para> - - <screen>&prompt.root; <userinput>cd /usr/local/share/gnats/gnats-db</userinput> -&prompt.root; <userinput>ln -s /usr/gnats/docs</userinput></screen> - - <para>Repeat as necessary, depending on how many GNATS categories you - are synching.</para> - </step> - - <step> - <para>Update the GNATS <filename>categories</filename> file with these - categories. The file is - <filename>$PREFIX/share/gnats/gnats-db/gnats-adm/categories</filename>.</para> - - <programlisting># This category is mandatory -pending:Category for faulty PRs:gnats-admin: -# -# FreeBSD categories -# -docs:Documentation Bug:nik:</programlisting> - </step> - - <step> - <para>Run <filename>$PREFIX/libexec/gnats/gen-index</filename> to - recreate the GNATS index. The output has to be redirected to - <filename>$PREFIX/share/gnats/gnats-db/gnats-adm/index</filename>. - You can do this periodically from &man.cron.8;, or run &man.cvsup.1; - from a shell script that does this as well.</para> - - <screen>&prompt.root; <userinput>/usr/local/libexec/gnats/gen-index \ - > /usr/local/share/gnats/gnats-db/gnats-adm/index</userinput></screen> - </step> - - <step> - <para>Test the configuration by querying the PR database. This - command shows open <literal>docs</literal> PRs.</para> - - <screen>&prompt.root; <userinput>query-pr -c docs -s open</userinput></screen> - - <para>Other interfaces, like - <filename>ports/databases/tkgnats</filename> should also work - nicely.</para> - </step> - - <step> - <para>Pick a PR and close it.</para> - </step> - </procedure> - - <note> - <para>This procedure only works to allow you to view and query the PRs - locally. To edit or close them you will still have to log in to - <hostid>freefall</hostid> and do it from there.</para> - </note> - </sect1> - - <sect1 id="people"> - <title>Who's Who</title> - - <para>Besides Peter Wemm and John Polstra, the repository - meisters, there are other FreeBSD project members whom you will - probably get to know in your role as a committer. Briefly, - and by no means all-inclusively, these are:</para> - - <variablelist> - <varlistentry> - <term>&a.asami;</term> - - <listitem> - <para>Satoshi is the Ports Wraith, meaning that he has - ultimate authority over any modifications to the ports - collection or the ports skeleton makefiles. He is also - the one responsible for administering ports freezes before - the releases.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.ru;</term> - - <listitem> - <para>Ruslan is Mister &man.mdoc.7;. If you are writing a - man page and need - some advice on the structure, or the markup, ask Ruslan.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.bde;</term> - - <listitem> - <para>Bruce is the Style Police-Meister. - When you do a commit that could have been done better, - Bruce will be there to tell you. Be thankful that someone - is. Bruce is also very knowledgeable on the various - standards applicable to FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.gallatin;</term> - <term>&a.mjacob;</term> - <term>&a.dfr;</term> - <term>&a.obrien;</term> - - <listitem> - <para>These are the primary developers and overseers of the - DEC Alpha AXP platform.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.dg;</term> - - <listitem> - <para>David is the overseer of the - VM system. If you have a VM system change in mind, - coordinate it with David.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.jkh;</term> - - <listitem> - <para>Jordan is the release engineer. He is responsible for - setting release deadlines and controlling the release - process. During code freezes, he also has final authority - on all changes to the system for whichever branch is - pending release status. If there is something you want - merged from <literal>-CURRENT</literal> to - <literal>-STABLE</literal> (whatever values those may have - at any given time), he is also the one to talk to about - it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.bmah;</term> - - <listitem> - <para>Bruce is keeper of the release notes - (<filename>src/release/texts/*</filename> or - <filename>src/release/doc/*</filename>, - as appropriate). If you commit a - change that you think is worthy of mention in the release notes, - please make sure Bruce knows about it. Better still, send him - a patch with your suggested commentary for the release - notes.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.obrien;</term> - - <listitem> - <para>David is the unofficial <filename>src/contrib</filename>-Meister. - If you have something - significant you'd like to do there, you should probably - coordinate it with David first. Please consult him before - importing into <filename>src/contrib</filename> if you have - never done this before in the FreeBSD CVS repository. Also - if you need to commit to something you do not maintain in - <filename>src/contrib</filename> and it is unclear who the - maintainer / point of contact is. (It is also not a bad idea - to consult David if you need to make a non-import commit to - something you maintain in <filename>src/contrib</filename> and - you are new to how FreeBSD does things.)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.brian;</term> - - <listitem> - <para>Official maintainer of - <filename>/usr/sbin/ppp</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.wollman;</term> - - <listitem> - <para>If you need advice on obscure network internals or - aren't sure of some potential change to the networking - subsystem you have in mind, Garrett is someone to talk - to. Garrett is also very knowledgeable on the various - standards applicable to FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.committers;</term> - - <listitem> - <para>cvs-committers is the entity that CVS uses to send you all your - commit messages. You should <emphasis>never</emphasis> send email - directly to this list. You should only send replies to this list - when they are short and are directly related to a commit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.developers;</term> - - <listitem> - <para>developers is all committers. This list was created to be a - forum for the committers "community" issues. Examples are Core - voting, announcements, etc... developers@FreeBSD.org is - <emphasis>not</emphasis> intended as a place for code reviews or a - replacement for arch@FreeBSD.org or audit@FreeBSD.org. In fact - using it as such hurts the FreeBSD Project as it gives a sense of a - closed list where general decisions affecting all of the FreeBSD - using community are made with out being "open".</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="ssh.guide"> - <title>SSH Quick-Start Guide</title> - - <procedure> - <step> - <para>If you are using FreeBSD 4.0 or later, - OpenSSH is included in the base system. - If you are using an earlier release, - update and install one of the SSH ports. In general, - you will probably want to get OpenSSH from the port in - <filename>/usr/ports/security/openssh</filename>. You - may also wish to check out the original ssh1 in - <filename>/usr/ports/security/ssh</filename>, but make - certain you pay attention to its license. Note that both - of these ports cannot be installed at the same time.</para> - </step> - - <step> - <para>If you do not wish to type your password in every - time you use &man.ssh.1;, and you use RSA keys to - authenticate, &man.ssh-agent.1; is there for your - convenience. If you want to use &man.ssh-agent.1;, make - sure that you run it before running other applications. X - users, for example, usually do this from their - <filename>.xsession</filename> or - <filename>.xinitrc</filename> file. See &man.ssh-agent.1; - for details.</para> - </step> - - <step> - <para>Generate a key pair using &man.ssh-keygen.1;. The key - pair will wind up in the - <filename><envar>$HOME</envar>/.ssh</filename> - directory.</para> - </step> - - <step> - <para>Send your public key - (<filename><envar>$HOME</envar>/.ssh/identity.pub</filename>) - to the person setting you up as a committer so it can be put - into your <filename>authorized_keys</filename> file in your - home directory on <hostid>freefall</hostid> - (i.e. - <filename><envar>$HOME</envar>/.ssh/authorized_keys</filename>). - </para> - </step> - </procedure> - - <para>Now you should be able to use &man.ssh-add.1; for - authentication once per session. This will prompt you for - your private key's pass phrase, and then store it in your - authentication agent (&man.ssh-agent.1;). If you no longer - wish to have your key stored in the agent, issuing - <command>ssh-add -d</command> will remove it.</para> - - <para>Test by doing something such as <command>ssh - freefall.FreeBSD.org ls /usr</command>.</para> - - <para>For more information, see - <filename>/usr/ports/security/openssh</filename>, &man.ssh.1;, - &man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and - &man.scp.1;.</para> - </sect1> - - <sect1> - <title>The FreeBSD Committers' Big List of Rules</title> - - <orderedlist> - <listitem> - <para>Respect other committers.</para> - </listitem> - - <listitem> - <para>Respect other contributors.</para> - </listitem> - - <listitem> - <para>Discuss any significant change - <emphasis>before</emphasis> committing.</para> - </listitem> - - <listitem> - <para>Respect existing maintainers (if listed in the - <makevar>MAINTAINER</makevar> field in - <filename>Makefile</filename> or in the - <filename>MAINTAINER</filename> file in the top-level - directory).</para> - </listitem> - - <listitem> - <para>Never touch the repository directly. Ask a - Repomeister.</para> - </listitem> - - <listitem> - <para>Any disputed change must be backed out pending - resolution of the dispute if requested by a maintainer. - Security related changes may - override a maintainer's wishes at the Security Officer's - discretion.</para> - </listitem> - - <listitem> - <para>Changes go to <literal>-CURRENT</literal> before - <literal>-STABLE</literal> unless specifically permitted by - the release engineer or unless they're not applicable to - <literal>-CURRENT</literal>. Any non-trivial or non-urgent - change which is applicable should also be allowed to sit in - <literal>-CURRENT</literal> for at least 3 days before - merging so that it can be given sufficient testing. The - release engineer has the same authority over the - <literal>-STABLE</literal> branch as outlined for the - maintainer in rule #5.</para> - </listitem> - - <listitem> - <para>Don't fight in public with other committers; it looks - bad. If you must <quote>strongly disagree</quote> about - something, do so only in private.</para> - </listitem> - - <listitem> - <para>Respect all code freezes and read the - <literal>committers</literal> mailing list in a timely manner - so you know when a code freeze is in effect.</para> - </listitem> - - <listitem> - <para>When in doubt on any procedure, ask first!</para> - </listitem> - - <listitem> - <para>Test your changes before committing them.</para> - </listitem> - - <listitem> - <para>Don't commit to anything under the - <filename>src/contrib</filename>, - <filename>src/crypto</filename>, and - <filename>src/sys/contrib</filename> trees without - <emphasis>explicit</emphasis> approval from the respective - maintainer(s).</para> - </listitem> - </orderedlist> - - <para>As noted, breaking some of these rules can be grounds for - suspension or, upon repeated offense, permanent removal of - commit privileges. Three or more members of core - acting in unison, - have the power to temporarily suspend commit privileges until - <literal>-core</literal> as a whole has the chance to review the - issue. In case of an <quote>emergency</quote> (a committer - doing damage to the repository), a temporary suspension may also - be done by the repository meisters or any other member of core - who may happen to be awake at the time. Only core as a whole - has the authority to suspend commit privileges for any - significant length of time or to remove them permanently, the - latter generally only being done after consultation with - committers. This rule does not exist to set core up as a bunch - of cruel dictators who can dispose of committers as casually as - empty soda cans, but to give the project a kind of safety fuse. - If someone is seriously out of control, it's important to be - able to deal with this immediately rather than be paralyzed by - debate. In all cases, a committer whose privileges are - suspended or revoked is entitled to a <quote>hearing</quote>, - the total duration of the suspension being determined at that - time. A committer whose privileges are suspended may also - request a review of the decision after 30 days and every 30 days - thereafter (unless the total suspension period is less than 30 - days). A committer whose privileges have been revoked entirely - may request a review after a period of 6 months have elapsed. - This review policy is <emphasis>strictly informal</emphasis> - and, in all cases, core reserves the right to either act on or - disregard requests for review if they feel their original - decision to be the right one.</para> - - <para>In all other aspects of project operation, core is a subset - of committers and is bound by the <emphasis>same - rules</emphasis>. Just because someone is in core doesn't mean - that they have special dispensation to step outside of any of - the lines painted here; core's <quote>special powers</quote> - only kick in when it acts as a group, not on an individual - basis. As individuals, we are all committers first and core - second.</para> - - <sect2> - <title>Details</title> - - <orderedlist> - <listitem> - <para>Respect other committers.</para> - - <para>This means that you need to treat other committers as - the peer-group developers that they are. Despite our - occasional attempts to prove the contrary, one doesn't get - into committers by being stupid and nothing rankles more - than being treated that way by one of your peers. Whether - we always feel respect for one another or not (and - everyone has off days), we still have to - <emphasis>treat</emphasis> other committers with respect - at all times or the whole team structure rapidly breaks - down.</para> - - <para>Being able to work together long term is this project's - greatest asset, one far more important than any set of - changes to the code, and turning arguments about code into - issues that affect our long-term ability to work - harmoniously together is just not worth the trade-off by - any conceivable stretch of the imagination.</para> - - <para>To comply with this rule, don't send email when you're - angry or otherwise behave in a manner which is likely to - strike others as needlessly confrontational. First calm - down, then think about how to communicate in the most - effective fashion for convincing the other person(s) that - your side of the argument is correct, don't just blow off - some steam so you can feel better in the short term at the - cost of a long-term flame war. Not only is this very bad - <quote>energy economics</quote>, but repeated displays of - public aggression which impair our ability to work well - together will be dealt with severely by the project - leadership and may result in suspension or termination of - your commit privileges. That's never an option which the - project's leadership enjoys in the slightest, but unity - comes first. No amount of code or good advice is worth - trading that away.</para> - </listitem> - - <listitem> - <para>Respect other contributors.</para> - - <para>You weren't always a committer. At one time you were - a contributor. Remember that at all times. Remember what - it was like trying to get help and attention. Don't forget - that your work as a contributor time was very important to - you. Remember what it was like. Don't discourage, belittle, - or demean contributors. Treat them with respect. They are - our committers in waiting. They are every bit as important - to the project as committers. Their contributions are as - valid and as important as your own. After all, you made - many contributions before you became a committer. Always - remember that. </para> - - <para>Consider the points raised under 'Respect other committers' - and apply them also to contributors.</para> - </listitem> - - <listitem> - <para>Discuss any significant change - <emphasis>before</emphasis> committing.</para> - - <para>The CVS repository is not where changes should be - initially submitted for correctness or argued over, that - should happen first in the mailing lists and then - committed only once something resembling consensus has - been reached. This doesn't mean that you have to ask - permission before correcting every obvious syntax error or - man page misspelling, simply that you should try to - develop a feel for when a proposed change isn't quite such - a no-brainer and requires some feedback first. People - really don't mind sweeping changes if the result is - something clearly better than what they had before, they - just don't like being <emphasis>surprised</emphasis> by - those changes. The very best way of making sure that - you're on the right track is to have your code reviewed by - one or more other committers.</para> - - <para>When in doubt, ask for review!</para> - </listitem> - - <listitem> - <para>Respect existing maintainers if listed.</para> - - <para>Many parts of FreeBSD aren't <quote>owned</quote> in - the sense that any specific individual will jump up and - yell if you commit a change to <quote>their</quote> area, - but it still pays to check first. One convention we use - is to put a maintainer line in the - <filename>Makefile</filename> for any package or subtree - which is being actively maintained by one or more people; - see <ulink - url="http://www.FreeBSD.org/handbook/policies.html">http://www.FreeBSD.org/handbook/policies.html</ulink> - for documentation on this. Where sections of code have - several maintainers, commits to affected areas by one - maintainer need to be reviewed by at least one other - maintainer. In cases where the - <quote>maintainer-ship</quote> of something isn't clear, - you can also look at the CVS logs for the file(s) in - question and see if someone has been working recently or - predominantly in that area.</para> - - <para>Other areas of FreeBSD fall under the control of - someone who manages an overall category of FreeBSD - evolution, such as internationalization or networking. - See <ulink url="http://www.FreeBSD.org/handbook/staff-who.html">http://www.FreeBSD.org/handbook/staff-who.html</ulink> - for more information on this.</para> - </listitem> - - <listitem> - <para>Never touch the repository directly. Ask a - Repomeister.</para> - - <para>This is pretty clear - you're not allowed to make - direct modifications to the CVS repository, period. In - case of difficulty, ask one of the repository meisters by - sending mail to <email>cvs@FreeBSD.org</email> and simply - wait for them to fix the problem and get back to you. Do - not attempt to fix the problem yourself!</para> - - <para>If you're thinking about putting down a tag or doing a - new import of code on a vendor branch, you might also find - it useful to ask for advice first. A lot of people get - this wrong the first few times and the consequences are - expensive in terms of files touched and angry CVSup/CTM - folks who are suddenly getting a lot of changes sent over - unnecessarily.</para> - </listitem> - - <listitem> - <para>Any disputed change must be backed out pending - resolution of the dispute if requested by a maintainer - Security related changes may - override a maintainer's wishes at the Security Officer's - discretion.</para> - - <para>This may be hard to swallow in times of conflict (when - each side is convinced that they're in the right, of - course) but CVS makes it unnecessary to have an ongoing - dispute raging when it's far easier to simply reverse the - disputed change, get everyone calmed down again and then - try and figure out how best to proceed. If the change - turns out to be the best thing after all, it can be easily - brought back. If it turns out not to be, then the users - didn't have to live with the bogus change in the tree - while everyone was busily debating its merits. People - very very rarely call for back-outs in the repository - since discussion generally exposes bad or controversial - changes before the commit even happens, but on such rare - occasions the back-out should be done without argument so - that we can get immediately on to the topic of figuring - out whether it was bogus or not.</para> - </listitem> - - <listitem> - <para>Changes go to <literal>-CURRENT</literal> before - <literal>-STABLE</literal> unless specifically permitted - by the release engineer or unless they're not applicable - to <literal>-CURRENT</literal>. Any non-trivial or - non-urgent change which is applicable should also be - allowed to sit in <literal>-CURRENT</literal> for at least - 3 days before merging so that it can be given sufficient - testing. The release engineer has the same authority over - the <literal>-STABLE</literal> branch as outlined in rule - #5.</para> - - <para>This is another <quote>don't argue about it</quote> - issue since it's the release engineer who is ultimately - responsible (and gets beaten up) if a change turns out to - be bad. Please respect this and give the release engineer - your full cooperation when it comes to the - <literal>-STABLE</literal> branch. The management of - <literal>-STABLE</literal> may frequently seem to be - overly conservative to the casual observer, but also bear - in mind the fact that conservatism is supposed to be the - hallmark of <literal>-STABLE</literal> and different rules - apply there than in <literal>-CURRENT</literal>. There's - also really no point in having <literal>-CURRENT</literal> - be a testing ground if changes are merged over to - <literal>-STABLE</literal> immediately. Changes need a - chance to be tested by the <literal>-CURRENT</literal> - developers, so allow some time to elapse before merging - unless the <literal>-STABLE</literal> fix is critical, - time sensitive or so obvious as to make further testing - unnecessary (spelling fixes to manpages, obvious bug/typo - fixes, etc.) In other words, apply common sense.</para> - </listitem> - - <listitem> - <para>Don't fight in public with other committers; it looks - bad. If you must <quote>strongly disagree</quote> about - something, do so only in private.</para> - - <para>This project has a public image to uphold and that - image is very important to all of us, especially if we are - to continue to attract new members. There will be - occasions when, despite everyone's very best attempts at - self-control, tempers are lost and angry words are - exchanged, and the best we can do is try and minimize the - effects of this until everyone has cooled back down. That - means that you should not air your angry words in public - and you should not forward private correspondence to - public mailing lists or aliases. What people say - one-to-one is often much less sugar-coated than what they - would say in public, and such communications therefore - have no place there - they only serve to inflame an - already bad situation. If the person sending you a - flame-o-gram at least had the grace to send it privately, - then have the grace to keep it private yourself. If you - feel you are being unfairly treated by another developer, - and it is causing you anguish, bring the matter up with - core rather than taking it public. We will do our best to - play peace makers and get things back to sanity. In cases - where the dispute involves a change to the codebase and - the participants do not appear to be reaching an amicable - agreement, core may appoint a mutually-agreeable 3rd party - to resolve the dispute. All parties involved must then - agree to be bound by the decision reached by this 3rd - party.</para> - </listitem> - - <listitem> - <para>Respect all code freezes and read the - <literal>committers</literal> mailing list on a timely - basis so you know when they are.</para> - - <para>Committing changes during a code freeze is a really - big mistake and committers are expected to keep up-to-date - on what's going on before jumping in after a long absence - and committing 10 megabytes worth of accumulated stuff. - People who abuse this on a regular basis will have their - commit privileges suspended until they get back from the - FreeBSD Happy Reeducation Camp we run in Greenland.</para> - </listitem> - - <listitem> - <para>When in doubt on any procedure, ask first!</para> - - <para>Many mistakes are made because someone is in a hurry - and just assumes they know the right way of doing - something. If you have not done it before, chances are - good that you do not actually know the way we do things - and really need to ask first or you are going to - completely embarrass yourself in public. There's no shame - in asking <quote>how in the heck do I do this?</quote> We - already know you are an intelligent person; otherwise, you - would not be a committer.</para> - </listitem> - - <listitem> - <para>Test your changes before committing them.</para> - - <para>This may sound obvious, but if it really were so - obvious then we probably wouldn't see so many cases of - people clearly not doing this. If your changes are to the - kernel, make sure you can still compile both GENERIC and - LINT. If your changes are anywhere else, make sure you - can still make world. If your changes are to a branch, - make sure your testing occurs with a machine which is - running that code. If you have a change which also may - break another architecture, be sure and test on all - supported architectures. Currently, this is only the x86 - and the Alpha so it's pretty easy to do. If you need to - test on the AXP, your account on <hostid - role="fqdn">beast.FreeBSD.org</hostid> will let you - compile and test Alpha binaries/kernels/etc. As other - architectures are added to the FreeBSD supported platforms - list, the appropriate shared testing resources will be - made available.</para> - </listitem> - - <listitem> - <para>Don't commit to anything under the - <filename>src/contrib</filename>, - <filename>src/crypto</filename>, and - <filename>src/sys/contrib</filename> trees without - <emphasis>explicit</emphasis> approval from the respective - maintainer(s).</para> - - <para>The trees mentioned above are for contributed software - usually imported onto a vendor branch. Committing something - there, even if it doesn't take the file off the vendor branch, - may cause unnecessary headaches for those responsible for - maintaining that particular piece of software. Thus, unless - you have <emphasis>explicit</emphasis> approval from the - maintainer (or you are the maintainer), do - <emphasis>not</emphasis> commit there!</para> - - <para>Please note that this doesn't mean you shouldn't try to - improve the software in question; you are still more than - welcome to do so. Ideally, you should submit your patches to - the vendor. If your changes are FreeBSD-specific, talk to the - maintainer; they may be willing to apply them locally. But - whatever you do, do <emphasis>not</emphasis> commit there by - yourself!</para> - - <para>Contact the &a.core; if you wish to take up maintainership - of an unmaintained part of the tree.</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Other Suggestions</title> - - <para>When committing documentation changes, use a spell checker - before committing. :) For all SGML docs, you should also - verify that your formatting directives are correct by running - <command>make lint</command>.</para> - - <para>For all on-line manual pages, run <command>manck</command> - (from ports) over the man page to verify all of the cross - references and file references are correct and that the man - page has all of the appropriate <makevar>MLINK</makevar>s - installed.</para> - - <para>Do not mix style fixes with new functionality. A style - fix is any change which does not modify the functionality of - the code. Mixing the changes obfuscates the functionality - change when using <command>cvs diff</command>, which can hide - any new bugs. Do not include whitespace changes with content - changes in commits to <filename>doc/</filename> or - <filename>www/</filename>. The extra clutter in the diffs - makes the translators' job much more difficult. Instead, make - any style or whitespace changes in separate commits that are - clearly labeled as such in the commit message.</para> - </sect2> - </sect1> - - <sect1> - <title>Ports Specific FAQ</title> - - <qandaset> - <qandadiv> - <title>Adding a New Port</title> - - <qandaentry> - <question> - <para>How do I add a new port?</para> - </question> - - <answer> - <para>First, please read the section about repository - copy.</para> - - <para>The easiest way to add a new port is to use the - <command>addport</command> script on - <hostid>freefall</hostid>. It will add a port from the - directory you specify, determining the category automatically - from the port <filename>Makefile</filename>. - It will also add an entry to the - <filename>CVSROOT/modules</filename> file and the port's - category <filename>Makefile</filename>. It was - written by &a.mharo; and &a.will;, but Will is the current - maintainer so please send questions/patches about - <command>addport</command> to him.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Any other things I need to know when I add a new - port?</para> - </question> - - <answer> - <para>Check the port, preferably to make sure it compiles - and packages correctly. This is the recommended - sequence:</para> - - <screen>&prompt.root; <userinput>make install</userinput> -&prompt.root; <userinput>make package</userinput> -&prompt.root; <userinput>make deinstall</userinput> -&prompt.root; <userinput>pkg_add <replaceable>package you built above</replaceable></userinput> -&prompt.root; <userinput>make deinstall</userinput> -&prompt.root; <userinput>make reinstall</userinput> -&prompt.root; <userinput>make package</userinput> - </screen> - - <para>The - <ulink url="http://www.FreeBSD.org/porters-handbook/index.html">Porters - Handbook</ulink> contains more detailed - instructions.</para> - - <para>Use &man.portlint.1; to check the syntax of the port. - You don't necessarily have to eliminate all warnings but - make sure you have fixed the simple ones.</para> - - <para>If the port came from a submitter who has not - contributed to the project before, add that person's - name to the Handbook's <citetitle - pubwork="section">Additional Contributors</citetitle> - section.</para> - - <para>Close the PR if the port came in as a PR. To close - a PR, just do - <userinput>edit-pr <replaceable>PR#</replaceable></userinput> - on <hostid>freefall</hostid> and change the - <varname>state</varname> from <constant>open</constant> - to <constant>closed</constant>. You will be asked to - enter a log message and then you are done.</para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Repository Copies</title> - - <qandaentry> - <question> - <para>When do we need a repository copy?</para> - </question> - - <answer> - <para>When you want to add a port that is related to - any port that is already in the tree in a separate - directory, please send mail to the ports manager asking - about it. Here <wordasword>related</wordasword> means - it is a different version or a slightly modified - version. Examples are - <filename>print/ghostscript*</filename> (different - versions) and <filename>x11-wm/windowmaker*</filename> - (English-only and internationalized version).</para> - - <para>Another example is when a port is moved from one - subdirectory to another, or when you want to change the - name of a directory because the author(s) renamed their - software even though it is a - descendant of a port already in a tree.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>When do we <emphasis>not</emphasis> need a - repository copy?</para> - </question> - - <answer> - <para>When there is no history to preserve. If a port is - added into a wrong category and is moved immediately, - it suffices to simply <command>cvs remove</command> the - old one and <command>addport</command> the new - one.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What do I need to do?</para> - </question> - - <answer> - <para>Send mail to the ports manager, who will do a copy - from the old location/name to the new location/name. - You will then get a notice, at which point you are - expected to perform the following:</para> - - <procedure> - <step> - <para><command>cvs remove</command> the old port (if - necessary)</para> - </step> - - <step> - <para>Adjust the parent (category) - <filename>Makefile</filename></para> - </step> - - <step> - <para>Update <filename>CVSROOT/modules</filename></para> - </step> - - <step> - <para>If other ports depend on the updated port, - change their <filename>Makefile</filename>s' - dependency lines</para> - </step> - - <step> - <para>If the port changed categories, modify the - <makevar>CATEGORIES</makevar> line of the port's - <filename>Makefile</filename> accordingly</para> - </step> - </procedure> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Ports Freeze</title> - - <qandaentry> - <question> - <para>What is a <quote>ports freeze</quote>?</para> - </question> - - <answer> - <para>Before a release, it is necessary to restrict - commits to the ports tree for a short period of time - while the packages and the release itself are being - built. This is to ensure consistency among the various - parts of the release, and is called the <quote>ports - freeze</quote>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How long is a ports freeze?</para> - </question> - - <answer> - <para>Usually an hour or two.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What does it mean to me?</para> - </question> - - <answer> - <para>During the ports freeze, you are not allowed to - commit anything to the tree without explicit approval - from the ports manager. <quote>Explicit - approval</quote> here means either of the - following:</para> - - <itemizedlist> - <listitem> - <para>You asked the ports manager and got a reply - saying, <quote>Go ahead and commit - it.</quote></para> - </listitem> - - <listitem> - <para>The ports manager sent a mail to you or the - mailing lists during the ports freeze pointing out - that the port is broken and has to be fixed.</para> - </listitem> - </itemizedlist> - - <para>Note that you do not have implicit permission to fix - a port during the freeze just because it is - broken.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I know when the ports freeze starts?</para> - </question> - - <answer> - <para>The ports manager will send out warning messages to - the <email>freebsd-ports@FreeBSD.org</email> and - <email>cvs-committers@FreeBSD.org</email> mailing lists - announcing the start of the impending release, usually - two or three weeks in advance. The exact starting time - will not be determined until a few days before the - actual release. This is because the ports freeze has to - be synchronized with the release, and it is usually not - known until then when exactly the release will be - rolled.</para> - - <para>When the freeze starts, there will be another - announcement to the - <email>cvs-committers@FreeBSD.org</email> list, of - course.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I know when the ports freeze ends?</para> - </question> - - <answer> - <para>A few hours after the release, the ports manager - will send out a mail to the - <email>freebsd-ports@FreeBSD.org</email> and - <email>cvs-committers@FreeBSD.org</email> mailing lists - announcing the end of the ports freeze. Note that the - release being cut does not automatically end the freeze. - We have to make sure there will not be any last minute - snafus that result in an immediate re-rolling of the - release.</para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Miscellaneous Questions</title> - - <qandaentry> - <question> - <para>How do I know if my port is building correctly or - not?</para> - </question> - - <answer> - <para>First, go check - <ulink url="http://bento.FreeBSD.org/~asami/errorlogs/">http://bento.FreeBSD.org/~asami/errorlogs/</ulink>. - - There you will find error logs from the latest package - building runs on 3-stable, 4-stable and 5-current.</para> - - <para>However, just because the port doesn't show up there - doesn't mean it's building correctly. (One of the - dependencies may have failed, for instance.) Here are - the relevant directories on bento, so feel free to dig - around.</para> - - <programlisting> /a/asami/portbuild/3/errors error logs from latest 3-stable run - /logs all logs from latest 3-stable run - /packages packages from latest 3-stable run - /bak/errors error logs from last complete 3-stable run - /bak/logs all logs from last complete 3-stable run - /bak/packages packages from last complete 3-stable run - /4/errors error logs from latest 4-stable run - /logs all logs from latest 4-stable run - /packages packages from latest 4-stable run - /bak/errors error logs from last complete 4-stable run - /bak/logs all logs from last complete 4-stable run - /bak/packages packages from last complete 4-stable run - /5/errors error logs from latest 5-current run - /logs all logs from latest 5-current run - /packages packages from latest 5-current run - /bak/errors error logs from last complete 5-current run - /bak/logs all logs from last complete 5-current run - /bak/packages packages from last complete 5-current run - </programlisting> - - <para>Basically, if the port shows up in - <filename>packages</filename>, or it is in - <filename>logs</filename> but not in - <filename>errors</filename>, it built fine. (The - <filename>errors</filename> directories are what you get - from the web page.)</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I added a new port. Do I need to add it to the - <filename>INDEX</filename>?</para> - </question> - - <answer> - <para>No. The ports manager will regenerate the - <filename>INDEX</filename> and commit it every few - days.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Are there any other files I'm not allowed to - touch?</para> - </question> - - <answer> - <para>Any file directly under <filename>ports/</filename>, or - any file under a subdirectory that starts with an - uppercase letter (<filename>Mk/</filename>, - <filename>Tools/</filename>, etc.). In particular, the - ports manager is very protective of - <filename>ports/Mk/bsd.port*.mk</filename> so don't - commit changes to those files unless you want to face his - wra(i)th.</para> - </answer> - </qandaentry> - </qandadiv> - </qandaset> - </sect1> - - <sect1> - <title>Miscellaneous Questions</title> - - <qandaset> - <qandaentry> - <question> - <para>Why are trivial or cosmetic changes to files on a vendor - branch a bad idea?</para> - </question> - - <answer> - <itemizedlist> - <listitem> - <para>From now on, every new vendor release of that file will - need to have patches merged in by hand.</para> - </listitem> - - <listitem> - <para>From now on, every new vendor release of that file will - need to have patches <emphasis>verified</emphasis> by hand.</para> - </listitem> - - <listitem> - <para>The <option>-j</option> option doesn't work very well. - Ask &a.obrien; for horror stories.</para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I add a new file to a CVS branch?</para> - </question> - - <answer> - <para>To add a file onto a branch, simply checkout or update - to the branch you want to add to and then add the file using - <command>cvs add</command> as you normally would. For - example, if you wanted to MFC the file - <filename>src/sys/alpha/include/smp.h</filename> from HEAD - to RELENG_4 and it does not exist in RELENG_4 yet, you would - use the following steps:</para> - - <example> - <title>MFC'ing a New File</title> - - <screen>&prompt.user; <userinput>cd sys/alpha/include</userinput> -&prompt.user; <userinput>cvs update -rRELENG_4</userinput> -cvs update: Updating . -U clockvar.h -U console.h -... -&prompt.user; <userinput>cvs update -kk -Ap smp.h > smp.h</userinput> -=================================================================== -Checking out smp.h -RCS: /usr/cvs/src/sys/alpha/include/smp.h,v -VERS: 1.1 -*************** -&prompt.user; <userinput>cvs add smp.h</userinput> -cvs add: scheduling file `smp.h' for addition on branch `RELENG_4' -cvs add: use 'cvs commit' to add this file permanently -&prompt.user; <userinput>cvs commit</userinput> - </screen> - </example> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What <quote>meta</quote> information should I include in a - commit message?</para> - </question> - - <answer> - <para>As well as including an informative message with each commit - you may need to include some additional information as - well.</para> - - <para>This information consists of one or more lines containing the - the key word or phrase, a colon, tabs for formatting, and then the - additional information.</para> - - <para>The key words or phrases are:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>PR:</literal></entry> - <entry>The problem report (if any) which is affected - (typically, by being closed) by this commit.</entry> - </row> - - <row> - <entry><literal>Submitted by:</literal></entry> - <entry>The name and e-mail address of the person that - submitted the fix.</entry> - </row> - - <row> - <entry><literal>Reviewed by:</literal></entry> - <entry>The name and e-mail address of the person or people - that reviewed the change. If a patch was submitted to a - mailing list for review, and the review was favourable, - then just include the list name.</entry> - </row> - - <row> - <entry><literal>Approved by:</literal></entry> - <entry>The name and e-mail address of the person or people - that approved the change. It is customary to get prior - approval for a commit if it is to an area of the tree to - which you do not usually commit. In addition, during the - run up to a new release all commits - <emphasis>must</emphasis> be approved by the release - engineer. If these are your first commits then you should - have passed them past your mentor first for approval, and - you should list your mentor.</entry> - </row> - - <row> - <entry><literal>Obtained from:</literal></entry> - <entry>The name of the project (if any) from which the code - was obtained.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <example> - <title>Commit log for a commit based on a PR</title> - - <para>You want to commit a change based on a PR submitted by John - Smith containing a patch. The end of the commit message should - look something like this.</para> - - <programlisting>... - -PR: foo/12345 -Submitted by: John Smith <John.Smith@example.com></programlisting> - </example> - - <example> - <title>Commit log for a commit needing review</title> - - <para>You want to change the virtual memory system. You have - posted patches to the appropriate mailing list (in this case, - <literal>freebsd-arch</literal>) and the changes have been - approved.</para> - - <programlisting>... - -Reviewed by: -arch</programlisting> - </example> - - <example> - <title>Commit log for a commit needing approval</title> - - <para>You want to commit a change to a section of the tree with a - MAINTAINER assigned. You have collaborated with the listed - MAINTAINER, who has told you to go ahead and commit.</para> - - <programlisting>... - -Approved by: <replaceable>abc</replaceable></programlisting> - - <para>Where <replaceable>abc</replaceable> is the account name of - the person who approved.</para> - </example> - - <example> - <title>Commit log for a commit bringing in code from - OpenBSD</title> - - <para>You want to commit some code based on work done in the - OpenBSD project.</para> - - <programlisting>... - -Obtained from: OpenBSD</programlisting> - </example> - - <para>In some cases you may need to combine some of these.</para> - - <para>Consider the situation where a user has submitted a PR - containing code from the NetBSD project. You are looking at the - PR, but it's not an area of the tree you normally work in, so - you've decided to get the change reviewed by the - <literal>arch</literal> mailing list.</para> - - <para>The extra information to include in the commit would look - something like</para> - - <programlisting>PR: foo/54321 -Submitted by: John Smith <John.Smith@example.com> -Reviewed by: -arch -Obtained from: NetBSD</programlisting> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/articles/dialup-firewall/Makefile b/en_US.ISO_8859-1/articles/dialup-firewall/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO_8859-1/articles/dialup-firewall/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/dialup-firewall/article.sgml b/en_US.ISO_8859-1/articles/dialup-firewall/article.sgml deleted file mode 100644 index c76119415a..0000000000 --- a/en_US.ISO_8859-1/articles/dialup-firewall/article.sgml +++ /dev/null @@ -1,361 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/articles/dialup-firewall/article.sgml,v 1.6 2001/02/27 12:45:43 jesusr Exp $ ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <articleinfo> - <title>Dialup firewalling with FreeBSD</title> - - <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Silver</surname> - - <affiliation> - <address><email>marcs@draenor.org</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$Date: 2001-04-17 15:53:37 $</pubdate> - - <abstract> - <para>This article documents how to setup a firewall using a PPP - dialup with FreeBSD and IPFW, and specifically with firewalling over - a dialup with a dynamically assigned IP address. This document does - not cover setting up your PPP connection in the first place.</para> - </abstract> - </articleinfo> - - <sect1 id="preface"> - <title>Preface</title> - - <para>Dialup Firewalling with FreeBSD</para> - - <para>This document aims to cover the process that is required in - order to setup firewalling with FreeBSD when are dynamically - assigned an IP address by your ISP. While every effort has been - made to make this document as informative and correct as possible, - you are welcome to mail your comments/suggestions to the - <ulink URL="mailto:marcs@draenor.org">maintainer</ulink>.</para> - </sect1> - - <sect1 id="kernel"> - <title>Kernel Options</title> - - <para>The first thing you'll need to do is recompile your kernel in - FreeBSD. If you need more information on how to recompile the kernel, - then the best place to start is the <ulink - URL="http://www.freebsd.org/handbook/kernelconfig.html">kernel - configuration section in the Handbook</ulink>. You need to compile the - following options into the kernel: </para> - - <variablelist> - <varlistentry> - <term><literal>options IPFIREWALL</literal></term> - - <listitem> - <para>Enables the kernel's firewall code.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options IPFIREWALL_VERBOSE</literal></term> - - <listitem> - <para>Sends logged packets to the system logger.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options - IPFIREWALL_VERBOSE_LIMIT=<replaceable>100</replaceable></literal></term> - - <listitem> - <para>Limits the number of times a matching entry is logged. This - stops your log files filling up with lots of repetitive entries. - <replaceable>100</replaceable> is a reasonable number to use, but - you can adjust it based on your requirements.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options IPDIVERT</literal></term> - - <listitem> - <para>Enables <emphasis>divert</emphasis> sockets, which will be - shown later.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>There are also some other OPTIONAL items that you can compile - into the kernel for some added security. These are not required in - order to get firewalling to work, but some more paranoid users may - want to use them.</para> - - <variablelist> - <varlistentry> - <term><literal>options TCP_RESTRICT_RST</literal></term> - - <listitem> - <para>This option blocks all TCP RST packets. This is - best used for systems that might be exposed to SYN - flooding (IRC Servers are a good example) or for those who - do not want to be easily portscannable.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options TCP_DROP_SYNFIN</literal></term> - - <listitem> - <para>This option ignores TCP packets with SYN and FIN. This - prevents tools such as nmap etc from identifying the TCP/IP - stack of the machine, but breaks support for RFC1644 - extensions. This is NOT recommended if the machine will be - running a web server.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Don't reboot once you have recompiled the kernel. Hopefully, we will - need to reboot just once in order to complete the installing of the - firewall.</para> - </sect1> - - <sect1 id="rcconf"> - <title>Changing <filename>/etc/rc.conf</filename> to load the - firewall</title> - - <para>We now need to make some changes to - <filename>/etc/rc.conf</filename> in order to tell it about the - firewall. Simply add the following lines:</para> - - <programlisting>firewall_enable="YES" -firewall_script="/etc/firewall/fwrules" -natd_enable="YES" -natd_interface="tun0" -natd_flags="-dynamic"</programlisting> - - <para>For more information on what the above do take a look at - <filename>/etc/defaults/rc.conf</filename> and read - &man.rc.conf.5;</para> - </sect1> - - <sect1> - <title>Disable PPP's network address translation</title> - - <para>You may already be using PPP's built in network address - translation (NAT). If that is the case you will have to disable it, - as these examples use &man.natd.8; to do the same.</para> - - <para>If you already have a block of entries to - automatically start PPP it probably looks like this:</para> - - <programlisting>ppp_enable="YES" -ppp_mode="auto" -ppp_nat="YES" -ppp_profile="<replaceable>profile</replaceable>"</programlisting> - - <para>If so, remove the <literal>ppp_nat="YES"</literal> line. You will - also need to remove any <literal>nat enable yes</literal> or - <literal>alias enable yes</literal> in - <filename>/etc/ppp/ppp.conf</filename>.</para> - </sect1> - - <sect1 id="rules"> - <title>The ruleset for the firewall</title> - - <para>We're nearly done now. All that remains now is to define the - firewall rules and then we can reboot and the firewall should be up and - running. I realise that everyone will want something slightly different - when it comes to their rulebase. What I've tried to do is write a - rulebase that suits most dialup users. You can obviously modify it to - your needs by simply using the following rules as the foundation for - your own rulebase. First, let's start with the basics of closed - firewalling. What you want to do is deny everything by default and then - only open up for the things you really need. Rules should be in the - order of allow first and then deny. The premise is that you add the - rules for your allows, and then everything else is denied. :)</para> - - <para>Now, let's make the dir /etc/firewall. Change into the directory and - edit the file fwrules as we specified in rc.conf. Please note that you - can change this filename to be anything you wish. This guide just gives - an example of a filename. </para> - - <para>Now, let's look at a sample firewall file, and we'll detail - everything in it. </para> - - <programlisting># Firewall rules -# Written by Marc Silver (marcs@draenor.org) -# http://draenor.org/ipfw -# Freely distributable - - -# Define the firewall command (as in /etc/rc.firewall) for easy -# reference. Helps to make it easier to read. -fwcmd="/sbin/ipfw" - -# Force a flushing of the current rules before we reload. -$fwcmd -f flush - -# Divert all packets through the tunnel interface. -$fwcmd add divert natd all from any to any via tun0 - -# Allow all data from my network card and localhost. Make sure you -# change your network card (mine was fxp0) before you reboot. :) -$fwcmd add allow ip from any to any via lo0 -$fwcmd add allow ip from any to any via fxp0 - -# Allow all connections that I initiate. -$fwcmd add allow tcp from any to any out xmit tun0 setup - -# Once connections are made, allow them to stay open. -$fwcmd add allow tcp from any to any via tun0 established - -# Everyone on the internet is allowed to connect to the following -# services on the machine. This example shows that people may connect -# to ssh and apache. -$fwcmd add allow tcp from any to any 80 setup -$fwcmd add allow tcp from any to any 22 setup - -# This sends a RESET to all ident packets. -$fwcmd add reset log tcp from any to any 113 in recv tun0 - -# Allow outgoing DNS queries ONLY to the specified servers. -$fwcmd add allow udp from any to <replaceable>x.x.x.x</replaceable> 53 out xmit tun0 - -# Allow them back in with the answers... :) -$fwcmd add allow udp from <replaceable>x.x.x.x</replaceable> 53 to any in recv tun0 - -# Allow ICMP (for ping and traceroute to work). You may wish to -# disallow this, but I feel it suits my needs to keep them in. -$fwcmd add 65435 allow icmp from any to any - -# Deny all the rest. -$fwcmd add 65435 deny log ip from any to any</programlisting> - - <para>You now have a fully functional firewall that will allow on - connections to ports 80 and 22 and will log any other connection - attempts. Now, you should be able to safely reboot and your firewall - should come up fine. If you find this incorrect in anyway or experience - any problems, or have any suggestions to improve this page, please - email me.</para> - </sect1> - - <sect1> - <title>Questions</title> - - <qandaset> - <qandaentry> - <question> - <para>Why are you using natd and ipfw when you could be using - the built in ppp-filters?</para> - </question> - - <answer> - <para>I'll have to be honest and say there's no definitive reason - why I use ipfw and natd instead of the built in ppp filters. From - the discussions I've had with people the consensus seems to be - that while ipfw is certainly more powerful and more configurable - than the ppp filters, what it makes up for in functionality it - loses in being easy to customise. One of the reasons I use it is - because I prefer firewalling to be done at a kernel level rather - than by a userland program.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>If I'm using private addresses internally, such as in the - 192.168.0.0 range, Could I add a command like <literal>$fwcmd add - deny all from any to 192.168.0.0:255.255.0.0 via tun0</literal> - to the firewall rules to prevent outside attempts to connect to - internal machines?</para> - </question> - - <answer> - <para>The simple answer is no. The reason for this is that natd is - doing address translation for <emphasis>anything</emphasis> being - diverted through the tun0 device. As far as it's concerned - incoming packets will speak only to the dynamically assigned IP - address and NOT to the internal network. Note though that you can - add a rule like <literal>$fwcmd add deny all from - 192.168.0.4:255.255.0.0 to any via tun0</literal> which would - limit a host on your internal network from going out via the - firewall.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>There must be something wrong. I followed your instructions - to the letter and now I am locked out.</para> - </question> - - <answer> - <para>This tutorial assumes that you are running - <emphasis>userland-ppp</emphasis>, therefore the supplied ruleset - operates on the <devicename>tun0</devicename> interface, which - corresponds to the first connection made with &man.ppp.8; (a.k.a. - <emphasis>user-ppp</emphasis>). Additional connections would use - <devicename>tun1</devicename>, <devicename>tun2</devicename> and so - on.</para> - - <para>You should also note that &man.pppd.8; uses the - <devicename>ppp0</devicename> interface instead, so if you start the - connection with &man.pppd.8; you must substitute - <devicename>tun0</devicename> for <devicename>ppp0</devicename>. A - quick way to edit the firewall rules to reflect this change is shown - below. The original ruleset is backed up as - <filename>fwrules_tun0</filename>.</para> - - <screen> - &prompt.user; <userinput>cd /etc/firewall</userinput> - /etc/firewall&prompt.user; <userinput>su</userinput> - <prompt>Password:</prompt> - /etc/firewall&prompt.root; <userinput>mv fwrules fwrules_tun0</userinput> - /etc/firewall&prompt.root; <userinput>cat fwrules_tun0 | sed s/tun0/ppp0/g > fwrules</userinput> - </screen> - - <para>To know whether you are currently using &man.ppp.8; or - &man.pppd.8; you can examine the output of &man.ifconfig.8; once the - connection is up. E.g., for a connection made with &man.pppd.8; you - would see something like this (showing only the relevant lines):</para> - - <screen> - &prompt.user; <userinput>ifconfig</userinput> - <emphasis>(skipped...)</emphasis> - ppp0: flags=<replaceable>8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524</replaceable> - inet <replaceable>xxx.xxx.xxx.xxx</replaceable> --> <replaceable>xxx.xxx.xxx.xxx</replaceable> netmask <replaceable>0xff000000</replaceable> - <emphasis>(skipped...)</emphasis> - </screen> - - <para>On the other hand, for a connection made with &man.ppp.8; - (<emphasis>user-ppp</emphasis>) you should see something similar to - this:</para> - - <screen> - &prompt.user; <userinput>ifconfig</userinput> - <emphasis>(skipped...)</emphasis> - ppp0: flags=<replaceable>8010<POINTOPOINT,MULTICAST> mtu 1500</replaceable> - <emphasis>(skipped...)</emphasis> - tun0: flags=<replaceable>8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524</replaceable> - <emphasis>(IPv6 stuff skipped...)</emphasis> - inet <replaceable>xxx.xxx.xxx.xxx</replaceable> --> <replaceable>xxx.xxx.xxx.xxx</replaceable> netmask <replaceable>0xffffff00</replaceable> - Opened by PID <replaceable>xxxxx</replaceable> - <emphasis>(skipped...)</emphasis> - </screen> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/articles/diskless-x/Makefile b/en_US.ISO_8859-1/articles/diskless-x/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO_8859-1/articles/diskless-x/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/diskless-x/article.sgml b/en_US.ISO_8859-1/articles/diskless-x/article.sgml deleted file mode 100644 index 692ea3367f..0000000000 --- a/en_US.ISO_8859-1/articles/diskless-x/article.sgml +++ /dev/null @@ -1,349 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD: doc/en_US.ISO_8859-1/articles/diskless-x/article.sgml,v 1.3 1999/11/15 22:55:44 phantom Exp $ ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <articleinfo> - <title>Diskless X Server: a how to guide</title> - - <authorgroup> - <author> - <firstname> Jerry</firstname> - <surname>Kendall</surname> - <affiliation> - <address> - <email>jerry@kcis.com</email> - </address> - </affiliation> - </author></authorgroup> - - <pubdate>28-December-1996</pubdate> - - <copyright> - <year>1996</year> - <holder>Jerry Kendall</holder> - </copyright> - - <abstract> - <para>With the help of some friends on the FreeBSD-hackers list, I have - been able to create a diskless X terminal. The creation of the X - terminal required first creating a diskless system with minimal - utilities mounted via NFS. These same steps were used to create 2 - separate diskless systems. The first is <hostid - role="fqdn">altair.kcis.com</hostid>. A diskless X terminal that I - run on my old 386DX-40. It has a 340Meg hard disk but, I did not want - to change it. So, it boots from <hostid - role="fqdn">antares.kcis.com</hostid> across a Ethernet. The second - system is a 486DX2-66. I setup a diskless FreeBSD (complete) that - uses no local disk. The server in that case is a Sun 670MP running - SunOS 4.1.3. The same setup configuration was needed for both.</para> - - <para>I am sure that there is stuff that needs to be added - to this. Please send me any comments.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Creating the boot floppy (On the diskless system)</title> - - <para>Since the network boot loaders will not work with some of the TSR's - and such that MS-DOS uses, it is best to create a dedicated boot floppy - or, if you can, create an MS-DOS menu that will (via the - <filename>config.sys</filename>/<filename>autoexec.bat</filename> files) - ask what configuration to load when the system starts. The later is the - method that I use and it works great. My MS-DOS (6.x) menu is - below.</para> - - <example> - <title><filename>config.sys</filename></title> - - <programlisting>[menu] -menuitem=normal, normal -menuitem=unix, unix -[normal] -.... -normal config.sys stuff -... -[unix]</programlisting> - </example> - - <example> - <title><filename>autoexec.bat</filename></title> - - <programlisting>@ECHO OFF -goto %config% - -:normal -... -normal autoexec.bat stuff -... -goto end - -:unix -cd \netboot -nb8390.com - -:end</programlisting> - </example> - </sect1> - - <sect1> - <title>Getting the network boot programs (On the server)</title> - - <para>Compile the 'net-boot' programs that are located in - <filename>/usr/src/sys/i386/boot/netboot</filename>. You should read - the comments at the top of the <filename>Makefile</filename>. Adjust as - required. Make a backup of the original in case it gets foobar'd. When - the build is done, there should be 2 MS-DOS executables, - <filename>nb8390.com</filename> and <filename>nb3c509.com</filename>. - One of these two programs will be what you need to run on the diskless - server. It will load the kernel from the boot server. At this point, - put both programs on the MS-DOS boot floppy created earlier.</para> - </sect1> - - <sect1> - <title>Determine which program to run (On the diskless system)</title> - - <para>If you know the chipset that your Ethernet adapter uses, this is - easy. If you have the NS8390 chipset, or a NS8390 based chipset, use - <filename>nb8390.com</filename>. If you have a 3Com 509 based chipset, - use the <filename>nb3C509.com</filename> boot program. If you are not - sure which you have, try using one, if it says <errorname>No adapter - found</errorname>, try the other. Beyond that, you are pretty much on - your own.</para> - </sect1> - - <sect1> - <title>Booting across the network</title> - - <para>Boot the diskless system with out any config.sys/autoexec.bat - files. try running the boot program for your Ethernet adapter.</para> - - <para>My Ethernet adapter is running in WD8013 16bit mode so I run - <filename>nb8390.com</filename></para> - - <screen><prompt>C:></prompt> <userinput>cd \netboot</userinput> -<prompt>C:></prompt> <userinput>nb8390</userinput> - -<prompt>Boot from Network (Y/N) ?</prompt> <userinput>Y</userinput> - -BOOTP/TFTP/NFS bootstrap loader ESC for menu - -Searching for adapter.. -WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66 - -Searching for server...</screen> - - <para>At this point, my diskless system is trying to find a machine to act - as a boot server. Make note of the <literal>addr</literal> line above, - you will need this number later. Reset the diskless system and modify - your <filename>config.sys</filename> and - <filename>autoexec.bat</filename> files to do these steps automatically - for you. Perhaps in a menu. If you had to run - <command>nb3c509.com</command> instead of <command>nb8390.com</command> - the output is the same as above. If you got <errorname>No adapter - found</errorname> at the <literal>Searching for adapter...</literal> - message, verify that you did indeed set the compile time defines in the - <filename>Makefile</filename> correctly.</para> - </sect1> - - <sect1> - <title>Allowing systems to boot across the network (On the server)</title> - - <para>Make sure the <filename>/etc/inetd.conf</filename> file has entries - for tftp and bootps. Mine are listed below:</para> - - <programlisting>tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /tftpboot -# -# Additions by who ever you are -bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab</programlisting> - - <para>If you have to change the <filename>/etc/inetd.conf</filename> file, - send a <literal>HUP</literal> signal to inetd. To do this, get the - process ID of inetd with <command>ps -ax | grep inetd | grep -v - grep</command>. Once you have it, send it a HUP signal. Do this by - <command>kill -HUP <pid></command>. This will force inetd to - re-read its config file.</para> - - <para>Did you remember to note the <literal>addr</literal> line from the - output of the boot loader on the diskless system? Guess what, here is - where you need it.</para> - - <para>Add an entry to <literal>/etc/bootptab</literal> (maybe creating the - file). It should be laid out identical to this:</para> - - <programlisting>altair:\ - :ht=ether:\ - :ha=004001432666:\ - :sm=255.255.255.0:\ - :hn:\ - :ds=199.246.76.1:\ - :ip=199.246.76.2:\ - :gw=199.246.76.1:\ - :vm=rfc1048:</programlisting> - - <para>The lines are as follows:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>altair</literal></entry> - <entry>the diskless systems name without the domain name.</entry> - </row> - - <row> - <entry><literal>ht=ether</literal></entry> - <entry>the hardware type of 'ethernet'.</entry> - </row> - - <row> - <entry><literal>ha=004001432666</literal></entry> - <entry>the hardware address (the number noted above).</entry> - </row> - - <row> - <entry><literal>sm=255.255.255.0</literal></entry> - <entry>the subnet mask.</entry> - </row> - - <row> - <entry><literal>hn</literal></entry> - <entry>tells server to send client's hostname to the - client.</entry> - </row> - - <row> - <entry><literal>ds=199.246.76.1</literal></entry> - <entry>tells the client who the domain server is.</entry> - </row> - - <row> - <entry><literal>ip=199.246.76.2</literal></entry> - <entry>tells the client what it's IP address is.</entry> - </row> - - <row> - <entry><literal>gw=199.246.76.1</literal></entry> - <entry>tells the client what the default gateway is.</entry> - </row> - - <row> - <entry><literal>vm=...</literal></entry> - <entry>just leave it there.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>Be sure to setup the IP addresses correctly, the addresses above - are my own.</para> - </note> - - <para>Create the directory '/tftpboot' on the server it will contain the - configuration files for the diskless systems that the server will serve. - These files will be named 'cfg.<ip>' where <ip> is the IP - address of the diskless system. The config file for 'altair' is - /tftpboot/cfg.199.246.76.2. The contents is:</para> - - <programlisting>rootfs 199.246.76.1:/DiskLess/rootfs/altair -hostname altair.kcis.com</programlisting> - - <para>The line <literal>hostname altair.kcis.com</literal> simply tells - the diskless system what its fully qualified domain name is.</para> - - <para>The line <literal>rootfs - 199.246.76.1:/DiskLess/rootfs/altair</literal> tells the diskless - system where its NFS mountable root filesystem is located.</para> - - <note> - <para>The NFS mounted root filesystem will be mounted <emphasis>read - only</emphasis>.</para> - </note> - - <para>The hierarchy for the diskless system can be re-mounted allowing - read-write operations if required.</para> - - <para>I use my spare 386DX-40 as a dedicated X terminal.</para> - - <para>The hierarchy for 'altair' is:</para> - - <literallayout>/ -/bin -/etc -/tmp -/sbin -/dev -/dev/fd -/usr -/var -/var/run</literallayout> - - <para>The actual list of files is:</para> - - <screen>-r-xr-xr-x 1 root wheel 779984 Dec 11 23:44 ./kernel --r-xr-xr-x 1 root bin 299008 Dec 12 00:22 ./bin/sh --rw-r--r-- 1 root wheel 499 Dec 15 15:54 ./etc/rc --rw-r--r-- 1 root wheel 1411 Dec 11 23:19 ./etc/ttys --rw-r--r-- 1 root wheel 157 Dec 15 15:42 ./etc/hosts --rw-r--r-- 1 root bin 1569 Dec 15 15:26 ./etc/XF86Config.altair --r-x------ 1 bin bin 151552 Jun 10 1995 ./sbin/init --r-xr-xr-x 1 bin bin 176128 Jun 10 1995 ./sbin/ifconfig --r-xr-xr-x 1 bin bin 110592 Jun 10 1995 ./sbin/mount_nfs --r-xr-xr-x 1 bin bin 135168 Jun 10 1995 ./sbin/reboot --r-xr-xr-x 1 root bin 73728 Dec 13 22:38 ./sbin/mount --r-xr-xr-x 1 root wheel 1992 Jun 10 1995 ./dev/MAKEDEV.local --r-xr-xr-x 1 root wheel 24419 Jun 10 1995 ./dev/MAKEDEV</screen> - - <para>Don't forget to run <command>MAKEDEV all</command> in the - <filename>dev</filename> directory.</para> - - <para>My <filename>/etc/rc</filename> for <hostid>altair</hostid> - is:</para> - -<programlisting>#!/bin/sh -# -PATH=/bin:/ -export PATH -# -# configure the localhost -/sbin/ifconfig lo0 127.0.0.1 -# -# configure the ethernet card -/sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00 -# -# mount the root filesystem via NFS -/sbin/mount antares:/DiskLess/rootfs/altair / -# -# mount the /usr filesystem via NFS -/sbin/mount antares:/DiskLess/usr /usr -# -/usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1 -# -# Reboot after X exits -/sbin/reboot -# -# We blew up.... -exit 1</programlisting> - - <para>Any comments and all questions welcome.</para> - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO_8859-1/articles/explaining-bsd/Makefile b/en_US.ISO_8859-1/articles/explaining-bsd/Makefile deleted file mode 100644 index 3893643f3e..0000000000 --- a/en_US.ISO_8859-1/articles/explaining-bsd/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO_8859-1/articles/freebsd-questions/Makefile,v 1.1 2001/02/16 00:22:33 nik Exp $ -# - -MAINTAINER=grog@FreeBSD.org - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/explaining-bsd/article.sgml b/en_US.ISO_8859-1/articles/explaining-bsd/article.sgml deleted file mode 100644 index ad1ba6cec5..0000000000 --- a/en_US.ISO_8859-1/articles/explaining-bsd/article.sgml +++ /dev/null @@ -1,542 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <articleinfo> - <title>Explaining BSD</title> - - <author> - <firstname>Greg</firstname> - <surname>Lehey</surname> - - <affiliation> - <address><email>grog@FreeBSD.org</email></address> - </affiliation> - </author> - - <abstract> - <para>In the open source world, the word <quote>Linux</quote> is almost - synonymous with <quote>Operating System</quote>, but it's not the only - open source <trademark>UNIX</trademark> operating system. According - to the <ulink - url="http://www.leb.net/hzo/ioscount/data/r.9904.txt">Internet - Operating System Counter</ulink>, as of April 1999 31.3% of the - world's network connected machines run Linux. 14.6% run BSD UNIX. - Some of the world's largest web operations, such as <ulink - url="http://www.yahoo.com">Yahoo!</ulink>, run BSD. The world's - busiest ftp server, <ulink - url="ftp://ftp.cdrom.com">ftp.cdrom.com</ulink>, uses BSD to - transfer 1.4 TB of data a day. Clearly this is not a niche - market: BSD is a well-kept secret.</para> - - <para>So what's the secret? Why isn't BSD better known? This white - paper addresses these and other questions.</para> - - <para>Throughout this paper, differences between BSD and Linux will be - noted <emphasis>like this</emphasis>.</para> - </abstract> - </articleinfo> - - <sect1> - <title>What is BSD?</title> - - <para>BSD stands for <quote>Berkeley Software Distribution</quote>. It is - the name of distributions of source code from the University of - California, Berkeley, which were originally extensions to AT&T's - Research UNIX operating system. Several open source operating system - projects are based on a release of this source code known as - 4.4BSD-Lite. In addition, they comprise a number of packages from other - Open Source projects, including notably the GNU project. The overall - operating system comprises:</para> - - <itemizedlist> - <listitem> - <para>The BSD kernel, which handles process scheduling, memory - management, symmetric multi-processing (SMP), device drivers, - etc.</para> - - <para><emphasis>Unlike the Linux kernel, there are several different - BSD kernels with differing capabilities.</emphasis></para> - </listitem> - - <listitem> - <para>The C library, the base API for the system.</para> - - <para><emphasis>The BSD C library is based on code from Berkeley, not - the GNU project.</emphasis></para> - </listitem> - - <listitem> - <para>Utilities such as shells, file utilities, compilers and - linkers.</para> - - <para><emphasis>Some of the utilities are derived from the GNU - project, others are not.</emphasis></para> - </listitem> - - <listitem> - <para>The X Window system, which handles graphical display.</para> - - <para>The X Window system used in most versions of BSD is maintained - by a separate project, the - <ulink url="http://www.XFree86.org/">XFree86 project</ulink>. - This is the same code as Linux uses. BSD does not normally - specify a <quote>graphical desktop</quote> such as GNOME or KDE, - though these are available.</para> - </listitem> - - <listitem> - <para>Many other programs and utilities.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>What, a real UNIX?</title> - - <para>The BSD operating systems are not clones, but open source - derivatives of AT&T's Research UNIX operating system, which is also - the ancestor of the modern UNIX System V. This may surprise you. How - could that happen when AT&T has never released its code as open - source?</para> - - <para>It's true that AT&T UNIX is not open source, and in a copyright - sense BSD is very definitely <emphasis>not</emphasis> UNIX, but on the - other hand, AT&T has imported sources from other projects, - noticeably the Computer Sciences Research Group of the University of - California in Berkeley, CA. Starting in 1976, the CSRG started - releasing tapes of their software, calling them <emphasis>Berkeley - Software Distribution</emphasis> or <emphasis>BSD</emphasis>.</para> - - <para>Initial BSD releases consisted mainly of user programs, but that - changed dramatically when the CSRG landed a contract with the Defense - Advanced Projects Research Agency (DARPA) to upgrade the communications - protocols on their network, ARPANET. The new protocols were known as - the <emphasis>Internet Protocols</emphasis>, later - <emphasis>TCP/IP</emphasis> after the most important protocols. The - first widely distributed implementation was part of 4.2BSD, in - 1982.</para> - - <para>In the course of the 1980s, a number of new workstation companies - sprang up. Many preferred to license UNIX rather than developing - operating systems for themselves. In particular, Sun Microsystems - licensed UNIX and implemented a version of 4.2BSD, which they called - SunOS. When AT&T themselves were allowed to sell UNIX commercially, - they started with a somewhat bare-bones implementation called System - III, to be quickly followed by System V. The System V code base did not - include networking, so all implementions included additional software - from the BSD, including the TCP/IP software, but also utilities such as - the <emphasis>csh</emphasis> shell and the <emphasis>vi</emphasis> - editor. Collectively, these enhancements were known as the - <emphasis>Berkeley Extensions</emphasis>.</para> - - <para>The BSD tapes contained AT&T source code and thus required a - UNIX source license. By 1990, the CSRG's funding was running out, and - it faced closure. Some members of the group decided to release the BSD - code, which was Open Source, without the AT&T proprietary code. - This finally happened with the <emphasis>Networking Tape 2</emphasis>, - usually known as <emphasis>Net/2</emphasis>. Net/2 was not a complete - operating system: about 20% of the kernel code was missing. One of the - CSRG members, William F. Jolitz, wrote the remaining code and released - it in early 1992 as <emphasis>386BSD</emphasis>. At the same time, - another group of ex-CSRG members formed a commercial company called - <ulink url="http://www.bsdi.com">Berkeley Software Design Inc.</ulink> - and released a beta version of an operating system called - <ulink url="http://www.bsdi.com">BSD/386</ulink>, which was based on - the same sources. The name of the operating system has since changed - to BSD/OS.</para> - - <para>386BSD never became a stable operating system. Instead, two other - projects split off from it in 1993: - <ulink url="http://www.NetBSD.org">NetBSD</ulink> and - <ulink url="http://www.FreeBSD.org">FreeBSD</ulink>. The two projects - originally diverged due to differences in patience waiting for - improvements to 386BSD: the NetBSD people started early in the year, - and the first version of FreeBSD wasn't ready until the end of the - year. In the meantime, the code base had diverged sufficiently to - make it difficult to merge. In addition, the projects had different - aims, as we'll see below. In 1996, a further project, - <ulink url="http://www.OpenBSD.org">OpenBSD</ulink>, split off from - NetBSD.</para> - </sect1> - - <sect1> - <title>Why isn't BSD better known?</title> - - <para>For a number of reasons, BSD is relatively unknown:</para> - - <orderedlist> - <listitem> - <para>The BSD developers are often more interested in polishing their - code than marketing it.</para> - </listitem> - - <listitem> - <para>Much of Linux's popularity is due to factors external to the - Linux projects, such as the press, and to companies formed to - provide Linux services. Until recently, the open source BSDs had no - such proponents.</para> - </listitem> - - <listitem> - <para>BSD developers tend to be more experienced than Linux - developers, and have less interest in making the system easy to use. - Newcomers tend to feel more comfortable with Linux.</para> - </listitem> - - <listitem> - <para>In 1992, AT&T sued - <ulink url="http://www.bsdi.com">BSDI</ulink>, - the vendor of BSD/386, alleging that the product contained - AT&T-copyrighted code. The case was settled out of court in - 1994, but the spectre of the litigation continues to haunt people. - As recently as March 2000 an article published on the web claimed - that the court case had been <quote>recently settled</quote>.</para> - - <para>One detail that the lawsuit did clarify is the naming: in the - 1980s, BSD was known as <quote>BSD UNIX</quote>. With the - elimination of the last vestige of AT&T code from BSD, it - also lost the right to the name UNIX. Thus you will see - references in book titles to <quote>the 4.3BSD UNIX operating - system</quote> and <quote>the 4.4BSD operating - system</quote>.</para> - </listitem> - - <listitem> - <para>There is a perception that the BSD projects are fragmented and - belligerent. The - <ulink url="http://interactive.wsj.com/bin/login?Tag=/&URI=/archive/retrieve.cgi%253Fid%253DSB952470579348918651.djm&">Wall Street - Journal</ulink> spoke of <quote>balkanization</quote> of the - BSD projects. Like the law suit, this perception bases mainly - on ancient history.</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>Comparing BSD and Linux</title> - - <para>So what's really the difference between, say, Debian Linux and - FreeBSD? For the average user, the difference is surprisingly small: - Both are UNIX-like operating systems. Both are developed by - non-commercial projects (this doesn't apply to many other Linux - distributions, of course). In the following section, we'll look at BSD - and compare it to Linux. The description applies most closely to - FreeBSD, which accounts for an estimated 80% of the BSD installations, - but the differences from NetBSD and OpenBSD are small.</para> - - <sect2> - <title>Who owns BSD?</title> - - <para>No one person or corporation owns BSD. It is created and - distributed by a community of highly technical and committed - contributors all over the world. Some of the components of BSD are - Open Source projects managed by a different project maintainer.</para> - </sect2> - - <sect2> - <title>How is BSD developed and updated?</title> - - <para>The BSD kernels are developed and updated following the Open - Source development model. Each project maintains a publicly - accessible <emphasis>source tree</emphasis> under the - <ulink url="http://www.sourcegear.com/CVS">Concurrent Versions - System</ulink> (CVS), which contains all source files for the - project, including documentation and other incidental files. CVS - allows users to <quote>check out</quote> (in other words, to - extract a copy of) any desired version of the system.</para> - - <para>A large number of developers worldwide contribute to improvements - to BSD. They are divided into three kinds:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Contributors</emphasis> write code or documentation. - They are not permitted to commit (add code) directly to the source - tree. In order for their code to be included in the system, it - must be reviewed and checked in by a registered developer, known - as a <emphasis>committer</emphasis>.</para> - </listitem> - - <listitem> - <para><emphasis>Committers</emphasis> are developers with write - access to the source tree. In order to become a committer, an - individual must show ability in the area in which he is - active.</para> - - <para> - It is at the individual committer's discretion whether he should - obtain authority before committing changes to the source tree. In - general, an experienced committer may make changes which are - obviously correct without obtaining consensus. For example, a - documentation project committer may correct typographical or - grammatical errors without review. On the other hand, developers - making far-reaching or complicated changes are expected to submit - their changes for review before committing them. In extreme - cases, a core team member with a function such as Principal - Architect may order that changes be removed from the tree, a - process known as <emphasis>backing out</emphasis>. All committers - receive mail describing each individual commit, so it is not - possible to commit secretly.</para> - </listitem> - - <listitem> - <para><emphasis>Core team</emphasis> In addition, FreeBSD - and NetBSD each have a core team which manages the project. The - core teams developed in the course of the projects, and their role - is not always well-defined. It is not necessary to be a developer - in order to be a core team member, though it is normal. The rules - for the core team vary from one project to the other, but in - general they have more say in the direction of the project than - non-core team members have.</para> - </listitem> - </itemizedlist> - - <para>This arrangement differs from Linux in a number of ways:</para> - - <orderedlist> - <listitem> - <para>No one person controls the content of the system. In - practice, this difference is overrated, since the Chief Architect - can require that code be backed out, and even in the Linux project - several people are permitted to make changes.</para> - </listitem> - - <listitem> - <para>On the other hand, there <emphasis>is</emphasis> a central - repository, a single place where you can find the entire operating - system sources, including all older versions.</para> - </listitem> - - <listitem> - <para>BSD projects maintain the entire <quote>Operating - System</quote>, not only the kernel. This distinction is only - marginally useful: neither BSD nor Linux is useful without - applications. The applications used under BSD are frequently the - same as the applications used under Linux.</para> - </listitem> - - <listitem> - <para>As a result of the formalized maintenance of a single CVS - source tree, BSD development is clear, and it is possible to - access any version of the system by release number or by date. - CVS also allows incremental updates to the system: for example, - the FreeBSD repository is updated about 100 times a day. Most of - these changes are small.</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>BSD releases</title> - - <para>Each BSD project provides the system in three different - <quote>releases</quote>. As with Linux, releases are assigned a - number such as 1.4.1 or 3.5. In addition, the version number has a - suffix indicating its purpose:</para> - - <orderedlist> - <listitem> - <para>The development version of the system is called - <emphasis>CURRENT</emphasis>. FreeBSD assigns a number to - CURRENT, for example FreeBSD 5.0-CURRENT. NetBSD uses a slightly - different naming scheme and appends a single-letter suffix which - indicates changes in the internal interfaces, for example NetBSD - 1.4.3G. OpenBSD does not assign a number ("OpenBSD-current"). - All new development on the system goes into this branch.</para> - </listitem> - - <listitem> - <para>At regular intervals, between two and four times a year, the - projects bring out a <emphasis>RELEASE</emphasis> version of the - system, which is available on CD-ROM and for free download from - ftp sites, for example OpenBSD 2.6-RELEASE or NetBSD 1.4-RELEASE. - The RELEASE version is intended for end users and is the normal - version of the system. NetBSD also provides <emphasis>patch - releases</emphasis> with a third digit, for example NetBSD - 1.4.2.</para> - </listitem> - - <listitem> - <para>As bugs are found in a RELEASE version, they are fixed, and - the fixes are added to the CVS tree. In FreeBSD, the resultant - version is called the STABLE version, while in NetBSD and OpenBSD - it continues to be called the RELEASE version. Smaller new - features can also be added to this branch after a period of test - in the CURRENT branch.</para> - </listitem> - </orderedlist> - - <para><emphasis>By contrast, Linux maintains two separate code trees: - the stable version and the development version. Stable versions - have an even minor version number, such as 2.0, 2.2 or 2.4. - Development versions have an odd minor version number, such as 2.1, - 2.3 or 2.5. In each case, the number is followed by a further - number designating the exact release. In addition, each vendor adds - their own userland programs and utilities, so the name of the - distribution is also important. Each distribution vendor also - assigns version numbers to the distribution, so a complete - description might be something like <quote>TurboLinux 6.0 with kernel - 2.2.14</quote></emphasis></para> - </sect2> - - <sect2> - <title>What versions of BSD are available?</title> - - <para>In contrast to the numerous Linux distributions, there are only - three open source BSDs. Each BSD project maintains its own source - tree and its own kernel. In practice, though, there appear to be - fewer divergences between the userland code of the projects than there - is in Linux.</para> - - <para>It's difficult to categorize the goals of each project: the - differences are very subjective. Basically,</para> - - <itemizedlist> - <listitem> - <para>FreeBSD aims for high performance and ease of use by - end users, and is a favourite of web content providers. It runs - on PCs and Compaq's Alpha processors. The FreeBSD project has - significantly more users than the other projects.</para> - </listitem> - - <listitem> - <para>NetBSD aims for maximum portability: <quote>of course it runs - NetBSD</quote>. It runs on machines from palmtops to large - servers, and has even been used on NASA space missions. It is a - particularly good choice for running on old non-Intel - hardware.</para> - </listitem> - - <listitem> - <para>OpenBSD aims for security and code purity: it uses a - combination of the open source concept and rigorous code reviews - to create a system which is demonstrably correct, making it the - choice of security-conscious organizations such as banks, stock - exchanges and US Government departments. Like NetBSD, it runs on - a number of platforms.</para> - </listitem> - </itemizedlist> - - <para>There are also two additional BSD operating systems which are not - open source, BSD/OS and Apple's Mac OS X:</para> - - <itemizedlist> - <listitem> - <para>BSD/OS is the oldest of the 4.4BSD derivatives. It - is not open source, though source code licenses are available at - relatively low cost. It resembles FreeBSD in many ways.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.apple.com/macosx/server/">Mac OS - X</ulink> is the latest version of the operating system for - <ulink url="http://www.apple.com">Apple Computer Inc.'s</ulink> - Macintosh line. Unlike the rest of the operating system, the - kernel is open source. As part of this development, key Apple - developers have commit access to the FreeBSD source tree.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>How does the BSD license differ from the GNU Public - license?</title> - - <para>Linux is available under the - <ulink url="http://www.fsf.org/copyleft/gpl.html">GNU General Public - License</ulink> (GPL), which is designed to eliminate closed - source software. In particular, any derivative work of a product - released under the GPL must also be supplied with source code if - requested. By contrast, the - <ulink url="http://www.opensource.org/licenses/bsd-license.html">BSD - license</ulink> is less restrictive: binary-only distributions are - allowed. This is particularly attractive for embedded - applications.</para> - </sect2> - - <sect2> - <title>What else should I know?</title> - - <para>Since fewer applications are available for BSD than Linux, the BSD - developers created a Linux compatibility package, which allows Linux - programs to run under BSD. The package includes both kernel - modifications, in order to correctly perform Linux system calls, and - Linux compatibility files such as the C library. There is no - noticeable difference in execution speed between a Linux application - running on a Linux machine and a Linux application running on a BSD - machine of the same speed.</para> - - <para>The <quote>all from one supplier</quote> nature of BSD means that - upgrades are much easier to handle than is frequently the case with - Linux. BSD handles library version upgrades by providing - compatibility modules for earlier library versions, so it is possible - to run binaries which are several years old with no problems.</para> - </sect2> - - <sect2> - <title>Which should I use, BSD or Linux?</title> - - <para>What does this all mean in practice? Who should use BSD, who - should use Linux?</para> - - <para>This is a very difficult question to answer. Here are some - guidelines:</para> - - <itemizedlist> - <listitem> - <para><quote>If it ain't broke, don't fix it</quote>: If you already - use an open source operating system, and you are happy with it, - there's probably no good reason to change.</para> - </listitem> - - <listitem> - <para>BSD systems, in particular FreeBSD, can have notably higher - performance than Linux. But this isn't across the board. In many - cases, there is little or no difference in performance. In some - cases, Linux may perform better than FreeBSD.</para> - </listitem> - - <listitem> - <para>In general, BSD systems have a better reputation for - reliability, mainly as a result of the more mature code - base.</para> - </listitem> - - <listitem> - <para>The BSD license may be more attractive than the GPL.</para> - </listitem> - - <listitem> - <para>BSD can execute Linux code, while Linux can't execute BSD - code. As a result, more software is available for BSD than for - Linux.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Who provides support, service, and training for BSD?</title> - - <para>BSDi have always supported BSD/OS, and they have recently - announced support contracts for FreeBSD.</para> - - <para>In addition, each of the projects has a list of consultants for - hire: - <ulink url="http://www.freebsd.org/commercial/consulting_bycat.html">FreeBSD</ulink>, - <ulink url="http://www.netbsd.org/gallery/consultants.html">NetBSD</ulink>, - and <ulink url="http://www.openbsd.org/support.html">OpenBSD</ulink>.</para> - </sect2> - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO_8859-1/articles/fonts/Makefile b/en_US.ISO_8859-1/articles/fonts/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO_8859-1/articles/fonts/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/fonts/article.sgml b/en_US.ISO_8859-1/articles/fonts/article.sgml deleted file mode 100644 index 8d8291fdae..0000000000 --- a/en_US.ISO_8859-1/articles/fonts/article.sgml +++ /dev/null @@ -1,988 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/fonts/article.sgml,v 1.14 2001/04/17 15:53:37 nik Exp $ --> -<!-- The FreeBSD Documentation Project --> -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<!-- Recently, I wanted to figure out how to use some additional fonts that - I had accumulated. I finally figured out *how to do it* from the various - man pages and documentation. Since it might be of use to other users, - and I didn't see any reference to this topic in the FAQ or handbook, I - thought I'd try my hand at a simple cookbook tutorial addressing the - use of fonts. I have included my unanswered questions at the end of - the document. - - Anyway, here's what I put together. This is my present understanding of - fonts and how to use them with FreeBSD. I am sure that there are errors or - misunderstandings, but it contains enough valid information to allow the - use of additional fonts with Ghostscript, X11 and Groff. This is my first - attempt to write anything along the lines of a tutorial/FAQ, so I am sure - it is pretty raw. There are probably better ways to do some of this stuff, - and I would welcome being corrected. - --> - -<!-- The section "Setting a virtual console to 80x60 line mode" was - updated to reflect changes in FreeBSD system configuration - files by Mark Ovens <mark@ukug.uk.freebsd.org> 27/5/00 - --> - -<article> - <articleinfo> - <title>Fonts and FreeBSD</title> - - <subtitle>A Tutorial</subtitle> - - <authorgroup> - <author> - <firstname>Dave</firstname> - - <surname>Bodenstab</surname> - - <affiliation> - <address> - <email>imdave@synet.net</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>Wed Aug 7, 1996</pubdate> - - <abstract> - <para>This document contains a description of the various font - files that may be used with FreeBSD and the syscons driver, - X11, Ghostscript and Groff. Cookbook examples are provided - for switching the syscons display to 80x60 mode, and for using - type 1 fonts with the above application programs.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Introduction</title> - - <para>There are many sources of fonts available, and one might ask - how they might be used with FreeBSD. The answer can be found by - carefully searching the documentation for the component that one - would like to use. This is very time consuming, so this - tutorial is an attempt to provide a shortcut for others who - might be interested.</para> - </sect1> - - <sect1> - <title>Basic terminology</title> - - <para>There are many different font formats and associated font - file suffixes. A few that will be addressed here are:</para> - - <variablelist> - <varlistentry> - <term><filename>.pfa</filename>, <filename>.pfb</filename></term> - - <listitem> - <para>Postscript type 1 fonts. The - <filename>.pfa</filename> is the - <emphasis>A</emphasis>scii form and - <filename>.pfb</filename> the <emphasis>B</emphasis>inary - form.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.afm</filename></term> - - <listitem> - <para>The font metrics associated with a type 1 font.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.pfm</filename></term> - - <listitem> - <para>The printer font metrics associated with a type 1 - font.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.ttf</filename></term> - - <listitem> - <para>A TrueType font</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.fot</filename></term> - - <listitem> - <para>An indirect reference to a TrueType font (not an - actual font)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.fon</filename>, <filename>.fnt</filename></term> - - <listitem> - <para>Bitmapped screen fonts</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The <filename>.fot</filename> file is used by Windows as - sort of a symbolic link to the actual TrueType font - (<filename>.ttf</filename>) file. The <filename>.fon</filename> - font files are also used by Windows. I know of no way to use - this font format with FreeBSD.</para> - </sect1> - - <sect1> - <title>What font formats can I use?</title> - - <para>Which font file format is useful depends on the application - being used. FreeBSD by itself uses no fonts. Application - programs and/or drivers may make use of the font files. Here is - a small cross reference of application/driver to the font type - suffixes:</para> - - <variablelist> - <varlistentry> - <term>Driver</term> - - <listitem> - <variablelist> - <varlistentry> - <term>syscons</term> - - <listitem> - <para><filename>.fnt</filename></para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Application</term> - - <listitem> - <variablelist> - <varlistentry> - <term>Ghostscript</term> - - <listitem> - <para><filename>.pfa</filename>, - <filename>.pfb</filename>, - <filename>.ttf</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>X11</term> - - <listitem> - <para><filename>.pfa</filename>, - <filename>.pfb</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Groff</term> - - <listitem> - <para><filename>.pfa</filename>, - <filename>.afm</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Povray</term> - - <listitem> - <para><filename>.ttf</filename></para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - - <para>The <filename>.fnt</filename> suffix is used quite - frequently. I suspect that whenever someone wanted to create a - specialized font file for their application, more often than not - they chose this suffix. Therefore, it is likely that files with - this suffix are not all the same format; specifically, the - <filename>.fnt</filename> files used by syscons under FreeBSD - may not be the same format as a <filename>.fnt</filename> file - one encounters in the MSDOS/Windows environment. I have not - made any attempt at using other <filename>.fnt</filename> files - other than those provided with FreeBSD.</para> - </sect1> - - <sect1> - <title>Setting a virtual console to 80x60 line mode</title> - - <para>First, an 8x8 font must be loaded. To do this, - <filename>/etc/rc.conf</filename> should contain the - line (change the font name to an appropriate one for - your locale):</para> - - <informalexample> - <programlisting>font8x8="iso-8x8" # font 8x8 from /usr/share/syscons/fonts/* (or NO).</programlisting> - </informalexample> - - <para>The command to actually switch the mode is - &man.vidcontrol.1;:</para> - - <informalexample> - <screen>&prompt.user; <userinput>vidcontrol VGA_80x60</userinput> - </screen> - </informalexample> - - <para>Various screen orientated programs, such as &man.vi.1;, must - be able to determine the current screen dimensions. As this is - achieved this through <command>ioctl</command> calls to the console - driver (such as &man.syscons.4;) they will correctly determine the new - screen dimensions.</para> - - <para>To make this more seamless, one can embed these commands in - the startup scripts so it takes place when the system boots. - To do this is add this line to <filename>/etc/rc.conf</filename> - </para> - - <informalexample> - <programlisting>allscreens_flags="VGA_80x60" # Set this vidcontrol mode for all virtual screens - </programlisting> - </informalexample> - - <para>References: &man.rc.conf.5;, &man.vidcontrol.1;.</para> - </sect1> - - <sect1> - <title>Using type 1 fonts with X11</title> - - <para>X11 can use either the <filename>.pfa</filename> or the - <filename>.pfb</filename> format fonts. The X11 fonts are - located in various subdirectories under - <filename>/usr/X11R6/lib/X11/fonts</filename>. Each font file - is cross referenced to its X11 name by the contents of the - <filename>fonts.dir</filename> file in each directory.</para> - - <para>There is already a directory named <filename>Type1</filename>. The - most straight forward way to add a new font is to put it into - this directory. A better way is to keep all new fonts in a - separate directory and use a symbolic link to the additional - font. This allows one to more easily keep track of ones fonts - without confusing them with the fonts that were originally - provided. For example:</para> - - <informalexample> - <screen><lineannotation>Create a directory to contain the font files</lineannotation> -&prompt.user; <userinput>mkdir -p /usr/local/share/fonts/type1</userinput> -&prompt.user; <userinput>cd /usr/local/share/fonts/type1</userinput> - -<lineannotation>Place the .pfa, .pfb and .afm files here</lineannotation> -<lineannotation>One might want to keep readme files, and other documentation</lineannotation> -<lineannotation>for the fonts here also</lineannotation> -&prompt.user; <userinput>cp /cdrom/fonts/atm/showboat/showboat.pfb .</userinput> -&prompt.user; <userinput>cp /cdrom/fonts/atm/showboat/showboat.afm .</userinput> - -<lineannotation>Maintain an index to cross reference the fonts</lineannotation> -&prompt.user; <userinput>echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX</userinput> - </screen> - </informalexample> - - <para>Now, to use a new font with X11, one must make the font file - available and update the font name files. The X11 font names - look like:</para> - - <informalexample> - <screen>-bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 - | | | | | | | | | | | | \ \ - | | | | | \ \ \ \ \ \ \ +----+- character set - | | | | \ \ \ \ \ \ \ +- average width - | | | | \ \ \ \ \ \ +- spacing - | | | \ \ \ \ \ \ +- vertical res. - | | | \ \ \ \ \ +- horizontal res. - | | | \ \ \ \ +- points - | | | \ \ \ +- pixels - | | | \ \ \ - foundry family weight slant width additional style - </screen> - </informalexample> - - <para>A new name needs to be created for each new font. If you - have some information from the documentation that accompanied - the font, then it could serve as the basis for creating the - name. If there is no information, then you can get some idea by - using &man.strings.1; on the font file. For example:</para> - - <informalexample> - <screen>&prompt.user; <userinput>strings showboat.pfb | more</userinput> -%!FontType1-1.0: Showboat 001.001 -%%CreationDate: 1/15/91 5:16:03 PM -%%VMusage: 1024 45747 -% Generated by Fontographer 3.1 -% Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten. -FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup -/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse -{save true}{false}ifelse}{false}ifelse -12 dict begin -/FontInfo 9 dict dup begin - /version (001.001) readonly def - /FullName (Showboat) readonly def - /FamilyName (Showboat) readonly def - /Weight (Medium) readonly def - /ItalicAngle 0 def - /isFixedPitch false def - /UnderlinePosition -106 def - /UnderlineThickness 16 def - /Notice (Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def -end readonly def -/FontName /Showboat def ---stdin-- - </screen> - </informalexample> - - <para>Using this information, a possible name might be:</para> - - <informalexample> - <screen>-type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 - </screen> - </informalexample> - - <para>The components of our name are:</para> - - <variablelist> - <varlistentry> - <term>Foundry</term> - - <listitem> - <para>Lets just name all the new fonts - <literal>type1</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Family</term> - - <listitem> - <para>The name of the font.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Weight</term> - - <listitem> - <para>Normal, bold, medium, semibold, etc. From the - &man.strings.1; - output above, it appears that this font has a weight of - <emphasis>medium</emphasis>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Slant</term> - - <listitem> - <para><emphasis remap=bf>r</emphasis>oman, <emphasis - remap=bf>i</emphasis>talic, <emphasis - remap=bf>o</emphasis>blique, etc. Since the - <emphasis>ItalicAngle</emphasis> is zero, - <emphasis>roman</emphasis> will be used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Width</term> - - <listitem> - <para>Normal, wide, condensed, extended, etc. Until it can - be examined, the assumption will be - <emphasis>normal</emphasis>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Additional style</term> - - <listitem> - <para>Usually omitted, but this will indicate that the font - contains decorative capital letters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Spacing</term> - - <listitem> - <para>proportional or monospaced. - <emphasis>Proportional</emphasis> is used since - <emphasis>isFixedPitch</emphasis> is false.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>All of these names are arbitrary, but one should strive to - be compatible with the existing conventions. A font is - referenced by name with possible wild cards by an X11 program, - so the name chosen should make some sense. One might begin by - simply using - - <informalexample> - <screen>…-normal-r-normal-…-p-… - </screen> - </informalexample> - - as the name, and then use - &man.xfontsel.1; - to examine it and adjust the name based on the appearance of the - font.</para> - - <para>So, to complete our example:</para> - - <informalexample> - <screen><lineannotation>Make the font accessible to X11</lineannotation> -&prompt.user; <userinput>cd /usr/X11R6/lib/X11/fonts/Type1</userinput> -&prompt.user; <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</userinput> - -<lineannotation>Edit fonts.dir and fonts.scale, adding the line describing the font -and incrementing the number of fonts which is found on the first line.</lineannotation> -&prompt.user; <userinput>ex fonts.dir -:1p -25 -:1c -26 -. -:$a -showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 -. -:wq</userinput> - -<lineannotation><filename>fonts.scale</filename> seems to be identical to <filename>fonts.dir</filename>…</lineannotation> -&prompt.user; <userinput>cp fonts.dir fonts.scale</userinput> - -<lineannotation>Tell X11 that things have changed</lineannotation> -&prompt.user; <userinput>xset fp rehash</userinput> - -<lineannotation>Examine the new font</lineannotation> -&prompt.user; <userinput>xfontsel -pattern -type1-*</userinput> - </screen> - </informalexample> - - <para>References: &man.xfontsel.1;, &man.xset.1;, <citetitle>The X - Windows System in a Nutshell</citetitle>, <ulink - URL="http://www.ora.com/">O'Reilly & - Associates</ulink>.</para> - </sect1> - - <sect1> - <title>Using type 1 fonts with Ghostscript</title> - - <para>Ghostscript references a font via its <filename>Fontmap</filename> - file. This must be modified in a similar way to the X11 - <filename>fonts.dir</filename> file. Ghostscript can use either - the <filename>.pfa</filename> or the <filename>.pfb</filename> - format fonts. Using the font from the previous example, here is - how to use it with Ghostscript:</para> - - <informalexample> - <screen><lineannotation>Put the font in Ghostscript's font directory</lineannotation> -&prompt.user; <userinput>cd /usr/local/share/ghostscript/fonts</userinput> -&prompt.user; <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</userinput> - -<lineannotation>Edit Fontmap so Ghostscript knows about the font</lineannotation> -&prompt.user; <userinput>cd /usr/local/share/ghostscript/4.01</userinput> -&prompt.user; <userinput>ex Fontmap -:$a -/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat -. -:wq</userinput> - -<lineannotation>Use Ghostscript to examine the font</lineannotation> -&prompt.user; <userinput>gs prfont.ps</userinput> -Aladdin Ghostscript 4.01 (1996-7-10) -Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights -reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... - /1899520 581354 1300084 13826 0 done. -GS><userinput>Showboat DoFont</userinput> -Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... - 1939688 565415 1300084 16901 0 done. ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< -GS><userinput>quit</userinput> - </screen> - </informalexample> - - <para>References: <filename>fonts.txt</filename> in the - Ghostscript 4.01 distribution</para> - </sect1> - - <sect1> - <title>Using type 1 fonts with Groff</title> - - <para>Now that the new font can be used by both X11 and - Ghostscript, how can one use the new font with groff? First of - all, since we are dealing with type 1 postscript fonts, the - groff device that is applicable is the <emphasis>ps</emphasis> - device. A font file must be created for each font that groff - can use. A groff font name is just a file in - <filename>/usr/share/groff_font/devps</filename>. With our - example, the font file could be - <filename>/usr/share/groff_font/devps/SHOWBOAT</filename>. The - file must be created using tools provided by groff.</para> - - <para>The first tool is <command>afmtodit</command>. This is not - normally installed, so it must be retrieved from the source - distribution. I found I had to change the first line of the - file, so I did:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp</userinput> -&prompt.user; <userinput>ex /tmp/afmtodit.pl -:1c -#!/usr/bin/perl -P- -. -:wq</userinput> - </screen> - </informalexample> - - <para>This tool will create the groff font file from the metrics - file (<filename>.afm</filename> suffix.) Continuing with our - example:</para> - - <informalexample> - <screen><lineannotation>Many <filename>.afm</filename> files are in Mac format… ^M delimited lines -We need to convert them to unix style ^J delimited lines</lineannotation> -&prompt.user; <userinput>cd /tmp</userinput> -&prompt.user; <userinput>cat /usr/local/share/fonts/type1/showboat.afm | - tr '\015' '\012' >showboat.afm</userinput> - -<lineannotation>Now create the groff font file</lineannotation> -&prompt.user; <userinput>cd /usr/share/groff_font/devps</userinput> -&prompt.user; <userinput>/tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT</userinput> - </screen> - </informalexample> - - <para>The font can now be referenced with the name - SHOWBOAT.</para> - - <para>If ghostscript is used to drive the printers on the system, - then nothing more needs to be done. However, if true postscript - printers are used, then the font must be down loaded to the - printer in order for the font to be used (unless the printer - happens to have the showboat font built in or on an accessible - font disk.) The final step is to create a down loadable font. - The <command>pfbtops</command> tool is used to create the - <filename>.pfa</filename> format of the font, and the - <filename>download</filename> file is modified to reference the new - font. The <filename>download</filename> file must reference the - internal name of the font. This can easily be determined from - the groff font file as illustrated:</para> - - <informalexample> - <screen><lineannotation>Create the <filename>.pfa</filename> font file</lineannotation> -&prompt.user; <userinput>pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa</userinput> - </screen> - </informalexample> - - <para>Of course, if the <filename>.pfa</filename> file is already - available, just use a symbolic link to reference it.</para> - - <informalexample> - <screen><lineannotation>Get the internal font name</lineannotation> -&prompt.user; <userinput>fgrep internalname SHOWBOAT</userinput> -internalname Showboat - -<lineannotation>Tell groff that the font must be down loaded</lineannotation> -&prompt.user; <userinput>ex download -:$a -Showboat showboat.pfa -. -:wq</userinput> - </screen> - </informalexample> - - <para>To test the font:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cd /tmp</userinput> -&prompt.user; <userinput>cat >example.t <<EOF -.sp 5 -.ps 16 -This is an example of the Showboat font: -.br -.ps 48 -.vs (\n(.s+2)p -.sp -.ft SHOWBOAT -ABCDEFGHI -.br -JKLMNOPQR -.br -STUVWXYZ -.sp -.ps 16 -.vs (\n(.s+2)p -.fp 5 SHOWBOAT -.ft R -To use it for the first letter of a paragraph, it will look like: -.sp 50p -\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the -showboat font as its first letter. -Additional vertical space must be used to allow room for the larger -letter. -EOF</userinput> -&prompt.user; <userinput>groff -Tps example.t >example.ps</userinput> - -<lineannotation>To use ghostscript/ghostview</lineannotation> -&prompt.user; <userinput>ghostview example.ps</userinput> - -<lineannotation>To print it</lineannotation> -&prompt.user; <userinput>lpr -Ppostscript example.ps</userinput> - </screen> - </informalexample> - - <para>References: - <filename>/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man</filename>, - &man.groff.font.5;, &man.groff.char.7;, &man.pfbtops.1;.</para> - </sect1> - - <sect1> - <title>Converting TrueType fonts to a groff/postscript format for - groff</title> - - <para>This potentially requires a bit of work, simply because it - depends on some utilities that are not installed as part of the - base system. They are:</para> - - <variablelist> - <varlistentry> - <term><command>ttf2pf</command></term> - - <listitem> - <para>TrueType to postscript convertsion utilities. This - allows conversion of a TrueType font to an ascii font - metric (<filename>.afm</filename>) file.</para> - - <para>Currently available at <ulink - url="http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/">http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf</ulink>. - Note: These files are postscript programs and must be - downloaded to disk by holding down the - <keycap>Shift</keycap> key when clicking on the link. - Otherwise, your browser may try to launch - <application>ghostview</application> to view them.</para> - - <para>The files of interest are:</para> - - <itemizedlist> - <listitem> - <para><filename>GS_TTF.PS</filename></para> - </listitem> - - <listitem> - <para><filename>PF2AFM.PS</filename></para> - </listitem> - - <listitem> - <para><filename>ttf2pf.ps</filename></para> - </listitem> - </itemizedlist> - - <para>The funny upper/lower case is due to their being - intended also for DOS shells. - <filename>ttf2pf.ps</filename> makes use of the others as - upper case, so any renaming must be consistent with this. - (Actually, <filename>GS_TTF.PS</filename> and - <filename>PFS2AFM.PS</filename> are supposedly part of the - ghostscript distribution, but it's just as easy to use - these as an isolated utility. FreeBSD doesn't seem to - include the latter.) You also may want to have these - installed to - <filename>/usr/local/share/groff_font/devps</filename>(?).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>afmtodit</command></term> - - <listitem> - <para>Creates font files for use with groff from ascii font - metrics file. This usually resides in the directory, - <filename>/usr/src/contrib/groff/afmtodit</filename>, and - requires some work to get going.</para> - - <note> - <para> If you're paranoid about working in the - <filename>/usr/src</filename> tree, simply copy the - contents of the above directory to a work - location.</para> - </note> - - <para>In the work area, you'll need to make the utility. - Just type:</para> - - <screen><prompt>#</prompt> <userinput>make -f Makefile.sub afmtodit</userinput> - </screen> - - <para>You may also need to copy - <filename>/usr/contrib/groff/devps/generate/textmap</filename> - to - <filename>/usr/share/groff_font/devps/generate</filename> - if it doesn't already exist.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Once all these utilities are in place, you're ready to - commence:</para> - - <orderedlist> - <listitem> - <para>Create the <filename>.afm</filename> file by - typing:</para> - - <screen><prompt>%</prompt> <userinput>gs <optional>-dNODISPLAY</optional> <optional>-q</optional> -- ttf2pf.ps <replaceable>TTF_name</replaceable> <optional><replaceable>PS_font_name</replaceable> <optional><replaceable>AFM_name</replaceable></optional></optional></userinput> - </screen> - - <para>Where, <replaceable>TTF_name</replaceable> is your - TrueType font file, <replaceable>PS_font_name</replaceable> - is the file name for the <filename>.pfa</filename> file, - <replaceable>AFM_name</replaceable> is the name you wish for - the <filename>.afm</filename> file. If you do not specify - output file names for the <filename>.pfa</filename> or - <filename>.afm</filename> files, then default names will be - generated from the TrueType font file name.</para> - - <para>This also produces a <filename>.pfa</filename> file, the - ascii postscript font metrics file - (<filename>.pfb</filename> is for the binrary form). This - won't be needed, but could (I think) be useful for a - fontserver.</para> - - <para>For example, to convert the 30f9 Barcode font using the - default file names, use the following command:</para> - - <screen><prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf</userinput> -Aladdin Ghostscript 5.10 (1997-11-23) -Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Converting 3of9.ttf to 3of9.pfa and 3of9.afm. - </screen> - - <para>If you want the converted fonts to be stored in - <filename>A.pfa</filename> and <filename>B.afm</filename>, - then use this command:</para> - - <screen><prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B</userinput> -Aladdin Ghostscript 5.10 (1997-11-23) -Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Converting 3of9.ttf to A.pfa and B.afm. - </screen> - </listitem> - - <listitem> - <para>Create the groff postscript file:</para> - - <para>Change directories to - <filename>/usr/share/groff_font/devps</filename> so as to - make the following command easier to execute. You'll - probably need root priviledges for this. (Or, if you're - paranoid about working there, make sure you reference the - files <filename>DESC</filename>, - <filename>text.enc</filename> and - <filename>generate/textmap</filename> as being in this - directory.)</para> - - <screen><prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc file.afm \ - generate/textmap <replaceable>PS_font_name</replaceable></userinput> - </screen> - - <para>Where, <filename>file.afm</filename> is the - <replaceable>AFM_name</replaceable> created by - <command>ttf2pf.ps</command> above, and - <replaceable>PS_font_name</replaceable> is the font name - used from that command, as well as the name that - &man.groff.1; will use for references to this font. For - example, assuming you used the first - <command>tiff2pf.ps</command> command above, then the 3of9 - Barcode font can be created using the command:</para> - - <screen><prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc 3of9.afm \ - generate/textmap 3of9</userinput> - </screen> - - <para>Ensure that the resulting - <replaceable>PS_font_name</replaceable> file (e.g., - <filename>3of9</filename> in the example above) is located - in the directory - <filename>/usr/share/groff_font/devps</filename> by copying - or moving it there.</para> - - <para>Note that if <filename>ttf2pf.ps</filename> assigns a - font name using the one it finds in the TrueType font file - and you want to use a different name, you must edit the - <filename>.afm</filename> file prior to running - <command>afmtodit</command>. This name must also match the - one used in the Fontmap file if you wish to pipe - &man.groff.1; into &man.gs.1;.</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>Can TrueType fonts be used with other programs?</title> - - <para>The TrueType font format is used by Windows, Windows 95, and - Mac's. It is quite popular and there are a great number of - fonts available in this format.</para> - - <para>Unfortunately, there are few applications that I am aware of - that can use this format: Ghostscript and Povray come to mind. - Ghostscript's support, according to the documentation, is - rudimentary and the results are likely to be inferior to type 1 - fonts. Povray version 3 also has the ability to use TrueType - fonts, but I rather doubt many people will be creating documents - as a series of raytraced pages :-).</para> - - <para>This rather dismal situation may soon change. The <ulink - url="http://www.freetype.org/">FreeType Project</ulink> is - currently developing a useful set of FreeType tools:</para> - - <itemizedlist> - <listitem> - <para>The freetype module is included with XFree86 4.x. For - more information please see the <ulink - url="http://www.freebsd.org/handbook/x-fonts.html">FreeBSD - Handbook</ulink> or the <ulink - url="http://www.xfree86.org/4.0.2/fonts.html">XFree86 4.0.2 - Fonts</ulink> page.</para> - </listitem> - - <listitem> - <para>The <command>xfsft</command> font server for X11 can - serve TrueType fonts in addition to regular fonts. Though - currently in beta, it is said to be quite useable. See - <ulink - url="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz - Chroboczek's page</ulink> for further information. - Porting instructions for FreeBSD can be found at <ulink - url="http://math.missouri.edu/~stephen/software/">Stephen - Montgomery's software page</ulink>.</para> - </listitem> - - <listitem> - <para><command>xfstt</command> is another font server for X11, - available under <ulink url=" - ftp://sunsite.unc.edu/pub/Linux/X11/fonts"> - ftp://sunsite.unc.edu/pub/Linux/X11/fonts</ulink>.</para> - </listitem> - - <listitem> - <para>A program called <command>ttf2bdf</command> can produce - BDF files suitable for use in an X environment from TrueType - files. Linux binaries are said to be available from <ulink - url="ftp://crl.nmsu.edu/CLR/multiling/General">ftp://crl.nmsu.edu/CLR/multiling/General/</ulink>.</para> - </listitem> - - <listitem> - <para>For people requiring the use of Asian TrueType fonts, - the <command>XTT</command> font server may be worth a look. - Information about <command>XTT</command> can be found at - URL: <ulink - url="http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html">http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html</ulink>.</para> - </listitem> - - <listitem> - <para>and others …</para> - </listitem> - </itemizedlist> - - <para>The <ulink - url="http://freetype.sourceforge.net/projects.html">FreeType Projects - page </ulink> is a good starting point for information on - these and other free TrueType projects.</para> - </sect1> - - <sect1> - <title>Where can additional fonts be obtained?</title> - - <para>Many fonts are available on the Internet. They are either - entirely free, or are share-ware. In addition, there are many - inexpensive CDROMs available that contain many fonts. Some - Internet locations (as of August 1996) are:</para> - - <itemizedlist> - <listitem> - <para><ulink - url="ftp://ftp.winsite.com">ftp://ftp.winsite.com</ulink> - (Formerly CICA)</para> - </listitem> - - <listitem> - <para><ulink - url="http://www.simtel.net/">http://www.simtel.net/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="ftp://ftp.coast.net/">ftp://ftp.coast.net/</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html">http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="http://www.esselte.com/letraset/index.html">http://www.esselte.com/letraset/index.html</ulink></para> - </listitem> - - <listitem> - <para><ulink - url="http://www.inil.com/users/elfring/esf.htm">http://www.inil.com/users/elfring/esf.htm</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Additional questions</title> - - <itemizedlist> - <listitem> - <para>What use are the <filename>.pfm</filename> files?</para> - </listitem> - - <listitem> - <para>Can one generate the <filename>.afm</filename> file from - a <filename>.pfa</filename> or - <filename>.pfb</filename>?</para> - </listitem> - - <listitem> - <para>How to generate the groff character mapping files for - postscript fonts with non-standard character names?</para> - </listitem> - - <listitem> - <para>Can xditview and devX?? devices be setup to access all - the new fonts?</para> - </listitem> - - <listitem> - <para>It would be good to have examples of using TrueType - fonts with povray and ghostscript.</para> - </listitem> - </itemizedlist> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/articles/formatting-media/Makefile b/en_US.ISO_8859-1/articles/formatting-media/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO_8859-1/articles/formatting-media/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/formatting-media/article.sgml b/en_US.ISO_8859-1/articles/formatting-media/article.sgml deleted file mode 100644 index 9e2da98466..0000000000 --- a/en_US.ISO_8859-1/articles/formatting-media/article.sgml +++ /dev/null @@ -1,636 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/formatting-media/article.sgml,v 1.15 2001/04/17 15:53:38 nik Exp $ --> -<article> - <articleinfo> - <title>Formatting Media For Use With FreeBSD</title> - - <subtitle>A Tutorial</subtitle> - - <authorgroup> - <author> - <firstname>Doug</firstname> - - <surname>White</surname> - - <affiliation> - <address> - <email>dwhite@resnet.uoregon.edu</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>March 1997</pubdate> - - <abstract> - <para>This document describes how to slice, partition, and - format hard disk drives and similar media for use with - FreeBSD. The examples given have been tested under FreeBSD - 2.2 and should work for other releases. The text has been updated - for FreeBSD version 4.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Introduction & Definitions</title> - - <sect2> - <title>Overview</title> - - <para>Successfully adding disks to an existing system is the - mark of an experienced system administrator. Slicing, - partitioning, and adding disks requires a careful dance of - proper command and name syntax. One slipped finger and an - entire disk could disappear in seconds. This document is - written in an attempt to simplify this process and avoid - accidents. Thankfully, enhancements to existing tools - (notably sysinstall) have greatly improved this process in - recent releases of FreeBSD.</para> - - <para>There are two possible modes of disk formatting:</para> - - <itemizedlist> - <listitem> - <para><firstterm>compatibility mode</firstterm>: Arranging a - disk so that it has a slice table for use with other - operating systems.</para> - </listitem> - - <listitem> - <para><firstterm>dedicated mode</firstterm>, sometimes called - <firstterm>dangerously dedicated mode</firstterm>: Formatting a disk - with no slice table. This makes the process of adding disks easier, - however non-FreeBSD operating systems may not accept the disk. The - term <emphasis>dangerously</emphasis> refers to the danger that the - system may not recognize a disk formatted in this manner.</para> - </listitem> </itemizedlist> - - <para>For most cases, dedicated mode is the easiest to set up - and use in existing systems, as a new disk is usually - dedicated entirely to FreeBSD. However, compatibility mode - insures optimum interoperability with future installations at - a cost of increased complexity.</para> - - <para>In addition to selecting the mode, two methods of slicing - the disk are available. One is using the system installation - tool <command>/stand/sysinstall</command>. 2.1.7-RELEASE and - later versions of <command>sysinstall</command> contain code - to ease setup of disks during normal system operation, mainly - allowing access to the Label and Partition editors and a Write - feature which will update just the selected disk and slice - without affecting other disks. The other method is running - the tools manually from a root command line. For - dedicated mode, only three or four commands are involved while - <command>sysinstall</command> requires some - manipulation.</para> - </sect2> - - <sect2> - <title>Definitions</title> - - <para>UNIX disk management over the centuries has invented many - new definitions for old words. The following glossary covers - the definitions used in this document and (hopefully) for - FreeBSD in general.</para> - -<!-- I'm tempted to use GLOSSARY here but will resort to a list for -now. --> - - <itemizedlist> - <listitem> - <para>compatibility mode: Arranging a disk so that it has a - slice table for use with other operating systems. Oppose - dedicated mode.</para> - </listitem> - - <listitem> - <para>(dangerously) dedicated mode: Formatting a disk with no - slice table. This makes the process of adding disks - easier, however non-FreeBSD operating systems may not - accept the disk. Oppose compatibility mode.</para> - </listitem> - - <listitem> - <para>disk: A circular disc, covered with magnetic or - similarly manipulable material, spun by a motor under a - head. Data is stored on the disk by changing the pattern - of magnetism on the disc, which can be later read. Hard - disks, CD-ROMs, Magneto-optical,and Zip/Jaz removables are - examples of disks.</para> - </listitem> - - <listitem> - <para>slice: A division of a disk. Up to four slices are - permitted on one disk in the PC standard. Slices are - composed of contiguous sectors. Slices are recorded in a - <quote>slice table</quote> used by the system BIOS to - locate bootable partitions. The slice table is usually - called the Partition Table in DOS parlance. Maintained by - the fdisk utility.</para> - </listitem> - - <listitem> - <para>partition: A division of a slice. Usually used in - reference to divisions of the FreeBSD slice of a disk. - Each filesystem and swap area on a disk resides in a - partition. Maintained using the disklabel utility.</para> - </listitem> - - <listitem> - <para>sector: Smallest subdivision of a disk. One sector - usually represents 512 bytes of data.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Warnings & Pitfalls</title> - - <para>Building disks is not something to take lightly. It is - quite possible to destroy the contents of other disks in your - system if the proper precautions are not taken.</para> - - <para><emphasis>Check your work carefully.</emphasis> It is very simple - to destroy the incorrect disk when working with these - commands. When in doubt consult the kernel boot output for - the proper device.</para> - - <para>Needless to say, we are not responsible for any damage to - any data or hardware that you may experience. You work at - your own risk!</para> - </sect2> - - <sect2> - <title>Zip, Jaz, and Other Removables</title> - - <para>Removable disks can be formatted in the same way as normal - hard disks. It is essential to have the disk drive connected - to the system and a disk placed in the drive during startup, - so the kernel can determine the drive's geometry. Check the - <command>dmesg</command> output and make sure your device and - the disk's size is listed. If the kernel reports - - <informalexample> - <screen>Can't get the size - </screen> - </informalexample> - - then the disk was not in the drive. In this case, you will - need to restart the machine before attempting to format - disks.</para> - </sect2> - </sect1> - - <sect1> - <title>Formatting Disks in Dedicated Mode</title> - - <sect2> - <title>Introduction</title> - - <para>This section details how to make disks that are totally - dedicated to FreeBSD. Remember, dedicated mode disks sometimes - cannot be booted by the PC architecture.</para> - </sect2> - - <sect2> - <title>Making Dedicated Mode Disks using Sysinstall</title> - - <para><command>/stand/sysinstall</command>, the system - installation utility, has been expanded in recent versions to - make the process of dividing disks properly a less tiring - affair. The fdisk and disklabel editors built into sysinstall - are GUI tools that remove much of the confusion from slicing - disks. For FreeBSD versions 2.1.7 and later, this is perhaps - the simplest way to slice disks.</para> - - <procedure> - <step> - <para>Start sysinstall as root by typing - - <informalexample> - <screen>&prompt.root; <userinput>/stand/sysinstall</userinput> - </screen> - </informalexample> - - from the command prompt.</para> - </step> - - <step> - <para>Select <command>Index</command>.</para> - </step> - - <step> - <para>Select <command>Partition</command>.</para> - </step> - - <step> - <para>Select the disk to edit with arrow keys and - <keycap>SPACE</keycap>.</para> - </step> - - <step> - <para>If you are using this entire disk for FreeBSD, select - <command>A</command>.</para> - </step> - - <step> - <para>When asked: - - <informalexample> - <screen>Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - </screen> - </informalexample> - - answer <command>No</command>.</para> - </step> - - <step> - <para>When asked if you still want to do this, answer - <command>Yes</command>.</para> - </step> - - <step> - <para>Select <command>Write</command>.</para> - </step> - - <step> - <para>When warned about Writing on installed systems, answer - <command>Yes</command>.</para> - </step> - - <step> - <para><command>Quit</command>the FDISK Editor and - <keycap>ESCAPE</keycap> back to the Index menu.</para> - </step> - - <step> - <para>Select <command>Label</command> from the Index - menu.</para> - </step> - - <step> - <para>Label as desired. For a single partition, enter - <command>C</command> to Create a partition, accept the - default size, partition type Filesystem, and a mountpoint - (which isn't used).</para> - </step> - - <step> - <para>Enter <command>W</command> when done and confirm to - continue. The filesystem will be newfs'd for you, unless - you select otherwise (for news partitions you'll want to - do this!). You'll get the error: - - <informalexample> - <screen>Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory - </screen> - </informalexample> - - Ignore.</para> - </step> - - <step> - <para>Exit out by repeatedly pressing - <keycap>ESCAPE</keycap>.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Making Dedicated Mode Disks Using the Command Line</title> - - <para>Execute the following commands, replacing ad2 with the - disk name.</para> - - <informalexample> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad2 count=2</userinput> -&prompt.root; <userinput>disklabel /dev/ad2 | disklabel -B -R -r ad2 /dev/stdin</userinput> -<lineannotation>We only want one partition, so using slice 'c' should be fine:</lineannotation> -&prompt.root; <userinput>newfs /dev/ad2c</userinput> - </screen> - </informalexample> - - <para>If you need to edit the disklabel to create multiple - partitions (such as swap), use the following: </para> - - <informalexample> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad2 count=2</userinput> -&prompt.root; <userinput>disklabel /dev/$d > /tmp/label</userinput> -<lineannotation>Edit disklabel to add partitions:</lineannotation> -&prompt.root; <userinput>vi /tmp/label</userinput> -&prompt.root; <userinput>disklabel -B -R -r ad2 /tmp/label</userinput> -<lineannotation>newfs partitions appropriately</lineannotation> - </screen> - </informalexample> - - <para>Your disk is now ready for use.</para> - </sect2> - </sect1> - - <sect1> - <title>Making Compatibility Mode Disks</title> - - <sect2> - <title>Introduction</title> - - <para>The command line is the easiest way to make dedicated - disks, and the worst way to make compatibility disks. The - command-line fdisk utility requires higher math skills and an - in-depth understanding of the slice table, which is more than - most people want to deal with. Use sysinstall for - compatibility disks, as described below.</para> - </sect2> - - <sect2> - <title>Making Compatibility Mode Disks Using Sysinstall</title> - - <procedure> - <step> - <para>Start sysinstall as root by typing - - <informalexample> - <screen>&prompt.root; <userinput>/stand/sysinstall</> - </screen> - </informalexample> - - from the command prompt.</para> - </step> - - <step> - <para>Select <command>Index</command>.</para> - </step> - - <step> - <para>Select <command>Partition</command>.</para> - </step> - - <step> - <para>Select the disk to edit with arrow keys and - <keycap>SPACE</keycap>.</para> - </step> - - <step> - <para>If you are using this entire disk for FreeBSD, select - <command>A</command>.</para> - </step> - - <step> - <para>When asked: - - <informalexample> - <screen>Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)? - </screen> - </informalexample> - - answer <command>yes</command>.</para> - </step> - - <step> - <para>Select <command>Write</command>.</para> - </step> - - <step> - <para>When asked to install the boot manager, select None - with <keycap>SPACE</keycap> then hit - <keycap>ENTER</keycap> for OK.</para> - </step> - - <step> - <para><command>Quit</command> the FDISK Editor.</para> - </step> - - <step> - <para>You'll be asked about the boot manager, select - <command>None</command> again. </para> - </step> - - <step> - <para>Select <command>Label</command> from the Index - menu.</para> - </step> - - <step> - <para>Label as desired. For a single partition, accept the - default size, type filesystem, and a mountpoint (which - isn't used).</para> - </step> - - <step> - <para>The filesystem will be newfs'd for you, unless you - select otherwise (for news partitions you'll want to do - this!). You'll get the error: - - <informalexample> - <screen>Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory - </screen> - </informalexample> - - Ignore.</para> - </step> - - <step> - <para>Exit out by repeatedly pressing - <keycap>ESCAPE</keycap>.</para> - </step> - </procedure> - - <para>Your new disk is now ready for use.</para> - </sect2> - </sect1> - - <sect1> - <title>Other Disk Operations</title> - - <sect2> - <title>Adding Swap Space</title> - - <para>As a system grows, it's need for swap space can also grow. - Although adding swap space to existing disks is very - difficult, a new disk can be partitioned with additional swap - space.</para> - - <para>To add swap space when adding a disk to a system:</para> - - <procedure> - <step> - <para>When partitioning the disk, edit the disklabel and - allocate the amount of swap space to add in partition `b' - and the remainder in another partition, such as `a' or - `e'. The size is given in 512 byte blocks.</para> - </step> - - <step> - <para>When newfsing the drive, do NOT newfs the `c' - partition. Instead, newfs the partition where the - non-swap space lies.</para> - </step> - - <step> - <para>Add an entry to <filename>/etc/fstab</filename> as - follows:</para> - - <informalexample> - <programlisting>/dev/ad0b none swap sw 0 0 - </programlisting> - </informalexample> - - <para>Change /dev/ad0b to the device of the newly added - space.</para> - </step> - - <step> - <para>To make the new space immediately available, use the - <command>swapon</command> command. - - <informalexample> - <screen>&prompt.root; <userinput>swapon /dev/da0b</userinput> -swapon: added /dev/da0b as swap space - </screen> - </informalexample> - </para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Copying the Contents of Disks</title> -<!-- Should have specific tag --> - - <para>Submitted By: Renaud Waldura - (<email>renaud@softway.com</email>) </para> - - <para>To move file from your original base disk to the fresh new - one, do: - - <informalexample> - <screen>&prompt.root; <userinput>mount /dev/ad2 /mnt</userinput> -&prompt.root; <userinput>pax -r -w -p e /usr/home /mnt</userinput> -&prompt.root; <userinput>umount /mnt</userinput> -&prompt.root; <userinput>rm -rf /usr/home/*</userinput> -&prompt.root; <userinput>mount /dev/ad2 /usr/home</userinput> - </screen> - </informalexample> - </para> - </sect2> - - <sect2> - <title>Creating Striped Disks using CCD</title> - - <para>Commands Submitted By: Stan Brown - (<email>stanb@awod.com</email>) </para> - - <para>The Concatenated Disk Driver, or CCD, allows you to treat - several identical disks as a single disk. Striping can result - in increased disk performance by distributing reads and writes - across the disks. See the &man.ccd.4; and &man.ccdconfig.8; - man pages or the <ulink - URL="http://stampede.cs.berkeley.edu/ccd/">CCD - Homepage</ulink> for further details.</para> - - <para>You no longer need to build a special kernel to run ccd. When you - run <command>ccdconfig</command>, it will load the KLD for you if the - kernel does not contain CCD support.</para> - - <para>You build CCDs on disk partitions of type - <emphasis>4.2BSD</emphasis>. If you want to use the entire disk, you - still need to create a new partition. For example, <userinput>disklabel - -e</userinput> might show: - - <informalexample> - <screen># size offset fstype [fsize bsize bps/cpg] - c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) - </screen> - </informalexample> - - <para>You shouldn't use partition <emphasis>c</emphasis> for the CCD, - since it is of type <emphasis>unused</emphasis>. Instead, create a new - partition of exactly the same size, but with type - <emphasis>4.2BSD</emphasis>:</para> - - <informalexample> - <screen># size offset fstype [fsize bsize bps/cpg] - c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) -<userinput> e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597)</userinput> - </screen> - </informalexample> - - <para>To create a new CCD, execute the following commands. This - describes how to add three disks together; simply add or remove devices - as necessary. Remember that the disks to be striped must be - <emphasis>identical.</emphasis></para> - - <informalexample> - <screen>&prompt.root; <userinput>cd /dev ; sh MAKDEV ccd0</userinput> - -&prompt.root; <userinput>disklabel -r -w da0 auto</userinput> -&prompt.root; <userinput>disklabel -r -w da1 auto</userinput> -&prompt.root; <userinput>disklabel -r -w da2 auto</userinput> - -&prompt.root; <userinput>disklabel -e da0</userinput> -<lineannotation>Add partition e with type 4.2BSD</lineannotation> -&prompt.root; <userinput>disklabel -e da1</userinput> -<lineannotation>Add partition e with type 4.2BSD</lineannotation> -&prompt.root; <userinput>disklabel -e da2</userinput> -<lineannotation>Add partition e with type 4.2BSD</lineannotation> - -&prompt.root; <userinput>ccdconfig ccd0 273 0 /dev/da0e /dev/da1e /dev/da2e</userinput> - -&prompt.root; <userinput>newfs /dev/ccd0c</userinput> - </screen> - </informalexample> - - <para>The value 273 is the stripe size. This is the number of disk - sectors (of 512 bytes each) in each block of data on the CCD. It should - be at least 128 kB, and it should not be not be a power of 2.</para> - - <para>Now you can mount and use your CCD by referencing device - /dev/ccd0c.</para> -<para> -A more powerful and flexible alternative to CCD is Vinum. See the <ulink -URL="http://www.vinumvm.org/">Vinum Project home page</ulink> for further -details -</para> - - </sect2> - </sect1> - - <sect1> - <title>Credits</title> - - <para>The author would like to thank the following individuals for - their contributions to this project:</para> - - <itemizedlist> - <listitem> - <para>Darryl Okahata - (<email>darrylo@hpnmhjw.sr.hp.com</email>) for his simple - dedicated mode setup documentation which I have used - repeatedly on FreeBSD-questions.</para> - </listitem> - - <listitem> - <para>Jordan Hubbard (<email>jkh@FreeBSD.org</email>) for - making sysinstall useful for this type of task.</para> - </listitem> - - <listitem> - <para>John Fieber (<email>jfieber@indiana.edu</email>) for - making information and examples of the DocBook DTD on which - this document is based.</para> - </listitem> - - <listitem> - <para>Greg Lehey (<email>grog@FreeBSD.org</email>) for - checking my work and pointing out inaccuracies, as well as - miscellaneous support.</para> - </listitem> - </itemizedlist> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/articles/freebsd-questions/Makefile b/en_US.ISO_8859-1/articles/freebsd-questions/Makefile deleted file mode 100644 index 16296d21ff..0000000000 --- a/en_US.ISO_8859-1/articles/freebsd-questions/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/Makefile,v 1.3 1999/09/06 06:52:35 peter Exp $ -# - -MAINTAINER=grog@FreeBSD.org - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/freebsd-questions/article.sgml b/en_US.ISO_8859-1/articles/freebsd-questions/article.sgml deleted file mode 100644 index a3bf0ff5ea..0000000000 --- a/en_US.ISO_8859-1/articles/freebsd-questions/article.sgml +++ /dev/null @@ -1,563 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <artheader> - <title>How to get best results from the FreeBSD-questions mailing - list</title> - - <author> - <firstname>Greg</firstname> - <surname>Lehey</surname> - - <affiliation> - <address><email>grog@FreeBSD.org</email></address> - </affiliation> - </author> - - <pubdate>$FreeBSD$</pubdate> - - <abstract> - <para>This document provides useful information for people looking to - prepare an e-mail to the FreeBSD-questions mailing list. Advice and - hints are given that will maximise the chance that the reader will - receive useful replies.</para> - - <para>This document is regularly posted to the FreeBSD-questions mailing - list.</para> - </abstract> - </artheader> - - <sect1> - <title id="Introduction">Introduction</title> - - <para><literal>FreeBSD-questions</literal> is a mailing list maintained by - the FreeBSD project to help people who have questions about the normal - use of FreeBSD. Another group, <literal>FreeBSD-hackers</literal>, - discusses more advanced questions such as future development - work.</para> - - <note> - <para>The term <quote>hacker</quote> has nothing to do with breaking - into other people's computers. The correct term for the latter - activity is <quote>cracker</quote>, but the popular press hasn't found - out yet. The FreeBSD hackers disapprove strongly of cracking - security, and have nothing to do with it. For a longer description of - hackers, see Eric Raymond's <ulink - url="http://www.tuxedo.org/~esr/faqs/hacker-howto.html">How To Become A Hacker</ulink></para> - </note> - - <para>This is a regular posting aimed to help both those seeking advice - from FreeBSD-questions (the <quote>newcomers</quote>), and also those - who answer the questions (the <quote>hackers</quote>).</para> - - <para>Inevitably there is some friction, which stems from the different - viewpoints of the two groups. The newcomers accuse the hackers of being - arrogant, stuck-up, and unhelpful, while the hackers accuse the - newcomers of being stupid, unable to read plain English, and expecting - everything to be handed to them on a silver platter. Of course, there's - an element of truth in both these claims, but for the most part these - viewpoints come from a sense of frustration.</para> - - <para>In this document, I'd like to do something to relieve this - frustration and help everybody get better results from - FreeBSD-questions. In the following section, I recommend how to submit - a question; after that, we'll look at how to answer one.</para> - </sect1> - - <sect1> - <title id="subscribe">How to subscribe to FreeBSD-questions</title> - - <para>FreeBSD-questions is a mailing list, so you need mail access. Send - a mail message to <email>majordomo@FreeBSD.org</email> with the single - line:</para> - - <literallayout class="monospaced">subscribe FreeBSD-questions</literallayout> - - <para><application>majordomo</application> is an automatic program which - maintains the mailing list, so you don't need a subject line. If your - mailer complains, however, you can put anything you like in the subject - line.</para> - - <para>When you get the reply from <application>majordomo</application> - telling you the details of the list, <emphasis>please save - it</emphasis>. If you ever should want to leave the list, you'll need - the information there. See the next section for more details.</para> - </sect1> - - <sect1> - <title id="unsubscribe">How to unsubscribe from FreeBSD-questions</title> - - <para>When you subscribed to FreeBSD-questions, you got a welcome message - from <email>Majordomo@FreeBSD.ORG</email>. In this message, amongst - other things, it told you how to unsubscribe. Here's a typical - message:</para> - - <literallayout class="monospaced">Welcome to the freebsd-questions mailing list! - -If you ever want to remove yourself from this mailing list, you can send -mail to "Majordomo@FreeBSD.ORG" with the following command in the body -of your email message: - -unsubscribe freebsd-questions Greg Lehey <grog@lemis.de> - -Here's the general information for the list you've subscribed to, -in case you don't already have it: - -FREEBSD-QUESTIONS User questions -This is the mailing list for questions about FreeBSD. -You should not send "how to" questions to the technical lists unless -you consider the question to be pretty technical.</literallayout> - - <para>Normally, unsubscribing is even simpler than the message suggests: - you don't need to specify your mail ID unless it is different from the - one which you specified when you subscribed.</para> - - <para>If Majordomo replies and tells you (incorrectly) that you're not on - the list, this may mean one of two things:</para> - - <orderedlist> - <listitem> - <para>You have changed your mail ID since you subscribed. That's - where keeping the original message from <literal>majordomo</literal> - comes in handy. For example, the sample message above shows my mail - ID as <literal>grog@lemis.de</literal>. Since then, I have changed - it to <literal>grog@lemis.com</literal>. If I were to try to remove - <literal>grog@lemis.com</literal> from the list, it would fail: I - would have to specify the name with which I joined.</para> - </listitem> - - <listitem> - <para>You're subscribed to a mailing list which is subscribed to - <literal>FreeBSD-questions</literal>. If that's the case, you'll - have to figure out which one it is and get your name taken off that - one. If you're not sure which one it might be, check the headers of - the messages you receive from freebsd-questions: maybe there's a - clue there.</para> - </listitem> - </orderedlist> - - <para>If you've done all this, and you still can't figure out what's going - on, send a message to <email>Postmaster@FreeBSD.org</email>, and he will - sort things out for you. <emphasis>Don't</emphasis> send a message to - FreeBSD-questions: they can't help you.</para> - </sect1> - - <sect1> - <title id="askwho">Should I ask <literal>-questions</literal> or - <literal>-hackers</literal>?</title> - - <para>Two mailing lists handle general questions about FreeBSD, - <literal>FreeBSD-questions</literal> and - <literal>FreeBSD-hackers</literal>. In some cases, it's not really - clear which group you should ask. The following criteria should help - for 99% of all questions, however:</para> - - <orderedlist> - <listitem> - <para>If the question is of a general nature, ask - <literal>FreeBSD-questions</literal>. Examples might be questions - about intstalling FreeBSD or the use of a particular UNIX - utility.</para> - </listitem> - - <listitem> - <para>If you think the question relates to a bug, but you're not sure, - or you don't know how to look for it, send the message to - <literal>FreeBSD-questions</literal>.</para> - </listitem> - - <listitem> - <para>If the question relates to a bug, and you're - <emphasis>sure</emphasis> that it's a bug (for example, you can - pinpoint the place in the code where it happens, and you maybe have - a fix), then send the message to - <literal>FreeBSD-hackers</literal>.</para> - </listitem> - - <listitem> - <para>If the question relates to enhancements to FreeBSD, and you - can make suggestions about how to implement them, then send the - message to <literal>FreeBSD-hackers</literal>.</para> - </listitem> - </orderedlist> - - <para>There are also a number of other specialized mailing lists, for - example <literal>FreeBSD-isp</literal>, which caters to the interests of - ISPs (Internet Service Providers) who run FreeBSD. If you happen to be - an ISP, this doesn't mean you should automatically send your questions - to <literal>FreeBSD-isp</literal>. The criteria above still apply, and - it's in your interest to stick to them, since you're more likely to get - good results that way.</para> - </sect1> - - <sect1> - <title id="submit">How to submit a question</title> - - <para>When submitting a question to FreeBSD-questions, consider the - following points:</para> - - <itemizedlist> - <listitem> - <para> Remember that nobody gets paid for answering a FreeBSD - question. They do it of their own free will. You can influence this - free will positively by submitting a well-formulated question - supplying as much relevant information as possible. You can - influence this free will negatively by submitting an incomplete, - illegible, or rude question. It's perfectly possible to send a - message to FreeBSD-questions and not get an answer even if you - follow these rules. It's much more possible to not get an answer if - you don't. In the rest of this document, we'll look at how to get - the most out of your question to FreeBSD-questions.</para> - </listitem> - - <listitem> - <para>Not everybody who answers FreeBSD questions reads every message: - they look at the subject line and decide whether it interests them. - Clearly, it's in your interest to specify a subject. ``FreeBSD - problem'' or ``Help'' aren't enough. If you provide no subject at - all, many people won't bother reading it. If your subject isn't - specific enough, the people who can answer it may not read - it.</para> - </listitem> - - <listitem> - <para>Format your message so that it is legible, and - PLEASE DON'T SHOUT!!!!!. We appreciate that a lot of people don't - speak English as their first language, and we try to make - allowances for that, but it's really painful to try to read a - message written full of typos or without any line breaks.</para> - - <para>Don't underestimate the effect that a poorly formatted mail - message has, not just on the FreeBSD-questions mailing list. - Your mail message is all people see of you, and if it's poorly - formatted, one line per paragraph, badly spelt, or full of - errors, it will give people a poor impression of you.</para> - - <para>A lot of badly formatted messages come from - <ulink url="http://www.lemis.com/email.html">bad mailers or badly - configured mailers</ulink>. The following mailers are known to - send out badly formatted messages without you finding out about - them:</para> - - <itemizedlist> - <listitem> - <para>cc:Mail</para> - </listitem> - - <listitem> - <para>Eudora</para> - </listitem> - - <listitem> - <para>exmh</para> - </listitem> - - <listitem> - <para>Microsoft Exchange</para> - </listitem> - - <listitem> - <para>Microsoft Internet Mail</para> - </listitem> - - <listitem> - <para>Microsoft Outlook</para> - </listitem> - - <listitem> - <para>Netscape</para> - </listitem> - </itemizedlist> - - <para>As you can see, the mailers in the Microsoft world are frequent - offenders. If at all possible, use a UNIX mailer. If you must use a - mailer under Microsoft environments, make sure it is set up - correctly. Try not to use <acronym>MIME</acronym>: a lot of people - use mailers which don't get on very well with - <acronym>MIME</acronym>.</para> - </listitem> - - <listitem> - <para>Make sure your time and time zone are set correctly. This may - seem a little silly, since your message still gets there, but many - of the people you are trying to reach get several hundred messages a - day. They frequently sort the incoming messages by subject and by - date, and if your message doesn't come before the first answer, they - may assume they missed it and not bother to look.</para> - </listitem> - - <listitem> - <para>Don't include unrelated questions in the same message. Firstly, - a long message tends to scare people off, and secondly, it's more - difficult to get all the people who can answer all the questions to - read the message.</para> - </listitem> - - <listitem> - <para>Specify as much information as possible. This is a difficult - area, and we need to expand on what information you need to submit, - but here's a start:</para> - - <itemizedlist> - <listitem> - <para>In nearly every case, it's important to know the version of - FreeBSD you're running. This is particularly the case for - FreeBSD-CURRENT, where you should also specify the date of the - sources, though of course you shouldn't be sending questions - about -CURRENT to FreeBSD-questions.</para> - </listitem> - - <listitem><para>With any problem which <emphasis>could</emphasis> be - hardware related, tell us about your hardware. In case of - doubt, assume it's possible that it's hardware. What kind of - CPU are you using? How fast? What motherboard? How much - memory? What peripherals?</para> - - <para>There's a judgement call here, of course, but the output of - the &man.dmesg.8; command can frequently be very useful, since it - tells not just what hardware you're running, but what version of - FreeBSD as well.</para> - </listitem> - - <listitem> - <para>If you get error messages, don't say <quote>I get error - messages</quote>, say (for example) <quote>I get the error - message 'No route to host'</quote>.</para> - </listitem> - - <listitem> - <para>If your system panics, don't say <quote>My system - panicked</quote>, say (for example) <quote>my system panicked - with the message 'free vnode isn't'</quote>.</para> - </listitem> - - <listitem> - <para>If you have difficulty installing FreeBSD, please tell us - what hardware you have. In particular, it's important to know - the IRQs and I/O addresses of the boards installed in your - machine.</para> - </listitem> - - <listitem> - <para>If you have difficulty getting PPP to run, describe the - configuration. Which version of PPP do you use? What kind of - authentication do you have? Do you have a static or dynamic IP - address? What kind of messages do you get in the log - file?</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>A lot of the information you need to supply is the output of - programs, such as &man.dmesg.8;, or console messages, which usually - appear in <filename>/var/log/messages</filename>. Don't try to copy - this information by typing it in again; it's a real pain, and you're - bound to make a mistake. To send log file contents, either make a - copy of the file and use an editor to trim the information to what - is relevant, or cut and paste into your message. For the output of - programs like &man.dmesg.8;, redirect the output to a file and - include that. For example,</para> - - <screen>&prompt.user; <userinput>dmesg > /tmp/dmesg.out</userinput></screen> - - <para>This redirects the information to the file - <filename>/tmp/dmesg.out</filename>.</para> - </listitem> - - <listitem> - <para>If you do all this, and you still don't get an answer, there - could be other reasons. For example, the problem is so complicated - that nobody knows the answer, or the person who does know the answer - was offline. If you don't get an answer after, say, a week, it - might help to re-send the message. If you don't get an answer to - your second message, though, you're probably not going to get one - from this forum. Resending the same message again and again will - only make you unpopular.</para> - </listitem> - </itemizedlist> - - <para>To summarize, let's assume you know the answer to the following - question (yes, it's the same one in each case <literal>:-)</literal>. - You choose which of these two questions you would be more prepared to - answer:</para> - - <example> - <title>Message 1</title> - - <literallayout class="monospaced">Subject: HELP!!?!?? -I just can't get hits damn silly FereBSD system to -workd, and Im really good at this tsuff, but I have never seen -anythign sho difficult to install, it jst wont work whatever I try -so why don't y9ou guys tell me what I doing wrong.</literallayout> - </example> - - <example> - <title>Message 2</title> - - <literallayout class="monospaced">Subject: Problems installing FreeBSD - -I've just got the FreeBSD 2.1.5 CD-ROM from Walnut Creek, and I'm having a lot -of difficulty installing it. I have a 66 MHz 486 with 16 MB of -memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball -disk and a Toshiba 3501XA CD-ROM drive. The installation works just -fine, but when I try to reboot the system, I get the message -``Missing Operating System''.</literallayout> - </example> - </sect1> - - <sect1> - <title id="followup">How to follow up to a question</title> - - <para>Often you will want to send in additional information to a question - you have already sent. The best way to do this is to reply to your - original message. This has three advantages:</para> - - <orderedlist> - <listitem> - <para>You include the original message text, so people will know what - you're talking about. Don't forget to trim unnecessary text out, - though.</para> - </listitem> - - <listitem> - <para>The text in the subject line stays the same (you did remember to - put one in, didn't you?). Many mailers will sort messages by - subject. This helps group messages together.</para> - </listitem> - - <listitem> - <para>The message reference numbers in the header will refer to the - previous message. Some mailers, such as - <ulink url="http://www.mutt.org/">mutt</ulink>, can - <emphasis>thread</emphasis> messages, showing the exact - relationships between the messages.</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title id="answer">How to answer a question</title> - - - <para>Before you answer a question to FreeBSD-questions, consider:</para> - - <orderedlist> - <listitem> - <para>A lot of the points on submitting questions also apply to - answering questions. Read them.</para> - </listitem> - - <listitem> - <para>Has somebody already answered the question? The easiest way to - check this is to sort your incoming mail by subject: then - (hopefully) you'll see the question followed by any answers, all - together.</para> - - <para>If somebody has already answered it, it doesn't automatically - mean that you shouldn't send another answer. But it makes sense to - read all the other answers first.</para> - </listitem> - - <listitem> - <para>Do you have something to contribute beyond what has already been - said? In general, <quote>Yeah, me too</quote> answers don't help - much, although there are exceptions, like when somebody is - describing a problem he's having, and he doesn't know whether it's - his fault or whether there's something wrong with the hardware or - software. If you do send a <quote>me too</quote> answer, you should - also include any further relevant information.</para> - </listitem> - - <listitem> - <para>Are you sure you understand the question? Very frequently, the - person who asks the question is confused or doesn't express himself - very well. Even with the best understanding of the system, it's - easy to send a reply which doesn't answer the question. This - doesn't help: you'll leave the person who submitted the question - more frustrated or confused than ever. If nobody else answers, and - you're not too sure either, you can always ask for more - information.</para> - </listitem> - - <listitem> - <para>Are you sure your answer is correct? - If not, wait a day or so. If nobody else comes up with a - better answer, you can still reply and say, for example, <quote>I - don't know if this is correct, but since nobody else has - replied, why don't you try replacing your ATAPI CD-ROM with - a frog?</quote>.</para> - </listitem> - - <listitem> - <para>Unless there's a good reason to do otherwise, reply to the - sender and to FreeBSD-questions. Many people on the - FreeBSD-questions are <quote>lurkers</quote>: they learn by reading - messages sent and replied to by others. If you take a message which - is of general interest off the list, you're depriving these people - of their information. Be careful with group replies; lots of people - send messages with hundreds of CCs. If this is the case, be sure to - trim the Cc: lines appropriately.</para> - </listitem> - - <listitem> - <para>Include relevant text from the original message. Trim it to the - minimum, but don't overdo it. It should still be possible for - somebody who didn't read the original message to understand what - you're talking about.</para> - </listitem> - - <listitem> - <para>Use some technique to identify which text came from the original - message, and which text you add. I personally find that prepending - <quote><literal>> </literal></quote> to the original message - works best. Leaving white space after the - <quote><literal>> </literal></quote> and leave empty lines - between your text and the original text both make the result more - readable.</para> - </listitem> - - <listitem> - <para>Put your response in the correct place (after the text to which - it replies). It's very difficult to read a thread of responses - where each reply comes before the text to which it replies.</para> - </listitem> - - <listitem> - <para>Most mailers change the subject line on a reply by prepending a - text such as <quote>Re: </quote>. If your mailer doesn't do it - automatically, you should do it manually.</para> - </listitem> - - <listitem> - <para>If the submitter didn't abide by format conventions (lines too - long, inappropriate subject line), <emphasis>please</emphasis> fix - it. In the case of an incorrect subject line (such as - <quote>HELP!!??</quote>), change the subject line to (say) - <quote>Re: Difficulties with sync PPP (was: HELP!!??)</quote>. That - way other people trying to follow the thread will have less - difficulty following it.</para> - - <para>In such cases, it's appropriate to say what you did and why you - did it, but try not to be rude. If you find you can't answer - without being rude, don't answer.</para> - - <para>If you just want to reply to a message because of its bad - format, just reply to the submitter, not to the list. You can just - send him this message in reply, if you like.</para> - </listitem> - </orderedlist> - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO_8859-1/articles/ipsec-must/Makefile b/en_US.ISO_8859-1/articles/ipsec-must/Makefile deleted file mode 100644 index 0647dfada3..0000000000 --- a/en_US.ISO_8859-1/articles/ipsec-must/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -DOCFORMAT= html - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/ipsec-must/article.sgml b/en_US.ISO_8859-1/articles/ipsec-must/article.sgml deleted file mode 100644 index 34edb9c5c5..0000000000 --- a/en_US.ISO_8859-1/articles/ipsec-must/article.sgml +++ /dev/null @@ -1,297 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> - -<html> - <head> - <title>Independent Verification of IPSec Functionality in FreeBSD</title> - </head> - - <body text="#000000" bgcolor="#FFFFFF"> - - <h1>Independent Verification of IPsec Functionality Under FreeBSD 3.0</h1> - - <p align="center"><i>You installed IPsec and it seems to be working. - How do you know? I describe a method for experimentally verifying - that IPsec is working</i></p> - - <h2>The Problem</h2> - - <p>First, let's assume you have <a href="#Installing IPsec">installed - <i>IPsec</i></a>. How do you know its <a href="#Caveat">working</a>? - Sure, your connection won't work if its misconfigured, and it will work - when you finally get it right. <i>Netstat</i> will list it. But can you - independently confirm it?</p> - - <h2>The Solution</h2> - - <p>First, some crypto-relevent info theory:</p> - - <ol> - <li> - <p>Encrypted data is uniformly distributed, ie, has maximal entropy - per symbol.</p> - </li> - - <li> - <p>Raw, uncompressed data is typically redundant, i.e., has - sub-maximal entropy.</p> - </li> - </ol> - - <p>Suppose you could measure the entropy of the data to- and from- your - network interface. Then you could see the difference between unencrypted - data and encrypted data. This would be true even if some of the data - in "encrypted mode" was not encrypted ---as the outermost IP header must - be, if the packet is to be routable.</p> - - <h4><a name="MUST"></a>MUST</h4> - - <p>Ueli Maurer's "Universal Statistical Test for Random Bit Generators" - ("MUST") quickly measures the entropy of a sample. It uses a - compression-like algorithm. <a href="#Maurer's Universal Statistical - Test">The code is given below for a variant which measures successive - (~quarter megabyte) chunks of a file</a>.</p> - - <h4><a NAME="Tcpdump"></a>Tcpdump</h4> - - <p>We also need a way to capture the raw network data. A program called - "<i>tcpdump</i>" lets you do this, if you have enabled the <i>Berkeley - Packet Filter</i> interface in your <a - href="#KERNELNAME">kernel's config file</a>.</p> - - <p>The command</p> - - <blockquote><b>tcpdump</b> <b>-c</b> 4000 <b>-s</b> 10000 <b>-w</b> - <i>dumpfile.bin</i></blockquote> - - <p>will capture 4000 raw packets to <i>dumpfile.bin</i>. Up to 10,000 - bytes per packet will be captured in this example.</p> - - <h2>The Experiment</h2> - - <p>Here's the experiment. Open a window to an IPsec host and another - window to an insecure host.</p> - - <p>Now start <a href="#Tcpdump">capturing packets</a>.</p> - - <p>In the "secure" window, run the unix command "yes", which will stream - the "y" character. After a while, stop this. Switch to the insecure - window, and repeat. After a while, stop.</p> - - <p>Now run <a href="#Maurer's Universal Statistical Test">MUST</a> on the - captured packets. You should see something like the the following. - The important thing to note is that the secure connection has 93% (6.7) - of the expected value (7.18), and the "normal" connection has 29% (2.1) - of the expected value.</p> - - - <pre>% tcpdump -c 4000 -s 10000 -w ipsecdemo.bin -% uliscan ipsecdemo.bin - -Uliscan 21 Dec 98 -L=8 256 258560 -Measuring file ipsecdemo.bin -Init done -Expected value for L=8 is 7.1836656 -6.9396 -------------------------------------------------------- -6.6177 ----------------------------------------------------- -6.4100 --------------------------------------------------- -2.1101 ----------------- -2.0838 ----------------- -2.0983 -----------------</pre> - - <h2><a NAME="Caveat"></a>Caveat</h2> - - <p>This experiment shows that IPsec <i>does</i> seem to be distributing the - payload data <i>uniformly</i>, as encryption should. However, the - experiment described here <i>can not </i>detect many possible flaws in a - system (none of which do I have any evidence for). These include poor - key generation or exchange, data or keys being visible to others, use of - weak algorithms, kernel subversion, etc. Study the source; know the - code.</p> - - <h2><a NAME="IPsec"></a>IPsec -Definition</h2> - - <p>Internet Protocol security extensions to IP v 4; required for IP v6. A - protocol for negotiating encryption and authentication at the IP - (host-to-host) level. SSL secures only one application socket; SSH - secures only a login; PGP secures only a specified file or - message. IPsec encrypts everything between two hosts.</p> - - <h2><a NAME="Installing IPsec"></a>Installing IPsec</h2> - - <p>Starting from the BSD 3.0 stable release,</p> - - <ol> - <li> - <p>install IPsec v0.04, rebuild, reinstall</p> - </li> - - <li> - <p>run the administration tools (e.g, <i>ipsecadm</i>) and distribute - keys (or use <i>Photuris</i> for key exchange)</p> - </li> - - <li> - <p>set the routes (<i>rt</i>) up appropriately</p> - </li> - </ol> - - <p>You may want to make an "ipsec_setup" script containing the - <i>ipsecadm</i> and <i>rt</i> commands which establish your IPsec - tunnel. You can run this script automatically at boottime from your - <i>/etc/rc.local</i> The ipsec_setup script will have to contain at - least two <i>ipsecadm</i> commands and one <i>rt</i> command to be - useful.</p> - - <h2><a NAME="KERNELNAME"></a>usr/src/sys/i386/conf/KERNELNAME</h2> - - <p>This needs to be present in the kernel config file in order to run - IPsec. After adding it, run <i>config</i>, etc. and rebuild and - reinstall.</p> - - <pre># The `bpfilter' pseudo-device enables the Berkeley Packet Filter. Be -# aware of the legal and administrative consequences of enabling this -# option. Heh heh. The number of devices determines the maximum number of -# simultaneous BPF clients programs runnable. -pseudo-device bpfilter 2 #Berkeley packet filter - -# IPSEC -options IPSEC -options "MD5" -pseudo-device enc 1</pre> - - <h2><a name="Maurer's Universal Statistical Test"></a>Maurer's Universal Statistical Test (for block - size=8 bits)</h2> - - <pre><![ CDATA [/* - ULISCAN.c ---blocksize of 8 - - 1 Oct 98 - 1 Dec 98 - 21 Dec 98 uliscan.c derived from ueli8.c - - This version has // comments removed for Sun cc - - This implements Ueli M Maurer's "Universal Statistical Test for Random - Bit Generators" using L=8 - - Accepts a filename on the command line; writes its results, with other - info, to stdout. - - Handles input file exhaustion gracefully. - - Ref: J. Cryptology v 5 no 2, 1992 pp 89-105 - also on the web somewhere, which is where I found it. - - -David Honig - honig@sprynet.com - - Usage: - ULISCAN filename - outputs to stdout -*/ - -#define L 8 -#define V (1<<L) -#define Q (10*V) -#define K (100 *Q) -#define MAXSAMP (Q + K) - -#include <stdio.h> -#include <math.h> - -int main(argc, argv) -int argc; -char **argv; -{ - FILE *fptr; - int i,j; - int b, c; - int table[V]; - double sum = 0.0; - int iproduct = 1; - int run; - - extern double log(/* double x */); - - printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP); - - if (argc < 2) { - printf("Usage: Uliscan filename\n"); - exit(-1); - } else { - printf("Measuring file %s\n", argv[1]); - } - - fptr = fopen(argv[1],"rb"); - - if (fptr == NULL) { - printf("Can't find %s\n", argv[1]); - exit(-1); - } - - for (i = 0; i < V; i++) { - table[i] = 0; - } - - for (i = 0; i < Q; i++) { - b = fgetc(fptr); - table[b] = i; - } - - printf("Init done\n"); - - printf("Expected value for L=8 is 7.1836656\n"); - - run = 1; - - while (run) { - sum = 0.0; - iproduct = 1; - - if (run) - for (i = Q; run && i < Q + K; i++) { - j = i; - b = fgetc(fptr); - - if (b < 0) - run = 0; - - if (run) { - if (table[b] > j) - j += K; - - sum += log((double)(j-table[b])); - - table[b] = i; - } - } - - if (!run) - printf("Premature end of file; read %d blocks.\n", i - Q); - - sum = (sum/((double)(i - Q))) / log(2.0); - printf("%4.4f ", sum); - - for (i = 0; i < (int)(sum*8.0 + 0.50); i++) - printf("-"); - - printf("\n"); - - /* refill initial table */ - if (0) { - for (i = 0; i < Q; i++) { - b = fgetc(fptr); - if (b < 0) { - run = 0; - } else { - table[b] = i; - } - } - } - } -}]]></pre> - </body> -</html> - - diff --git a/en_US.ISO_8859-1/articles/mh/Makefile b/en_US.ISO_8859-1/articles/mh/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO_8859-1/articles/mh/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/mh/article.sgml b/en_US.ISO_8859-1/articles/mh/article.sgml deleted file mode 100644 index 27ff6c8651..0000000000 --- a/en_US.ISO_8859-1/articles/mh/article.sgml +++ /dev/null @@ -1,782 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/mh/article.sgml,v 1.8 2000/07/26 18:24:49 jim Exp $ --> -<!-- FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"> -<article> - <articleinfo> - <title>An MH Primer</title> - - <authorgroup> - <author> - <firstname>Matt</firstname> - - <surname>Midboe</surname> - - <affiliation> - <address> - <email>matt@garply.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>v1.0, 16 January 1996</pubdate> - - <abstract> - <para>This document contains an introduction to using MH on - FreeBSD</para> - </abstract> - </articleinfo> - - <sect1 id="mhintro"> - <title>Introduction</title> - - <para>MH started back in 1977 at the RAND Corporation, where the - initial philosophies behind MH were developed. MH isn't so much - a monolithic email program but a philosophy about how best to - develop tools for reading email. The MH developers have done a - great job adhering to the <acronym>KISS</acronym> principle: Keep It - Simple Stupid. Rather than have one large program for reading, - sending and handling email they have written specialized - programs for each part of your email life. One might liken MH to - the specialization that one finds in insects and nature. Each - tool in MH does one thing, and does it very well.</para> - - <para>Beyond just the various tools that one uses to handle their - email MH has done an excellent job keeping the configuration of - each of these tools consistent and uniform. In fact, if you are - not quite sure how something is supposed to work or what the - arguments for some command are supposed to be then you can - generally guess and be right. Each MH command is consistent - about how it handles reading the configuration files and how it - takes arguments on the command line. One useful thing to - remember is that you can always add a <option>-help</option> to - the command to have it display the options for that - command.</para> - - <para>The first thing that you need to do is to make sure that you - have installed the MH package on your FreeBSD machine. If you - installed from CDROM you should be able to execute the following - to load mh: - - <informalexample> - <screen>&prompt.root; <userinput>pkg_add /cdrom/packages/mh-6.8.3.tgz</> - </screen> - </informalexample> - - You will notice that it created a <filename>/usr/local/lib/mh</filename> - directory for you as well as adding several binaries to the - <filename>/usr/local/bin</filename> directory. If you would prefer to - compile it yourself then you can anonymous ftp it from <ulink - URL="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink - URL="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para> - - <para>This primer is not a full comprehensive explanation of how - MH works. This is just intended to get you started on the road - to happier, faster mail reading. You should read the man pages - for the various commands. Also you might want to read the <ulink - URL="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also - you can read the <ulink - URL="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mh-faq/part1/faq.html">FAQ - for MH</ulink>. The best resource for MH is the O'Reilly and - Associates book written by Jerry Peek.</para> - </sect1> - - <sect1> - <title>Reading Mail</title> - - <para>This section covers how to use <command>inc</command>, - <command>show</command>, <command>scan</command>, <command>next</command>, - <command>prev</command>, <command>rmm</command>, <command>rmf</command>, and - <command>msgchk</command>. One of the best things about MH is the - consistent interface between programs. A few things to keep in - mind when using these commands is how to specify message lists. - In the case of <command>inc</command> this doesn't really make any - sense but with commands like <command>show</command> it is useful to - know. </para> - - <para>A message list can consist of something like <parameter>23 - 20 16</parameter> which will act on messages 23, 20 and 16. This is - fairly simple but you can do more useful things like - <parameter>23-30</parameter> which will act on all the messages between - 23 and 30. You can also specify something like - <parameter>cur:10</parameter> which will act on the current message and - the next 9 messages. The <parameter>cur</parameter>, <parameter>last</parameter>, - and <parameter>first</parameter> messages are special messages that refer - to the current, last or first message in the folder.</para> - - <sect2 id="inc"> - <title><command>inc</command>, <command>msgchk</command>—read in your - new email or check it</title> - - <para>If you just type in <userinput>inc</userinput> and hit - <keycap>return</keycap> you will be well on your way to getting - started with MH. The first time you run <command>inc</command> it - will setup your account to use all the MH defaults and ask you - about creating a Mail directory. If you have mail waiting to - be downloaded you will see something that looks like:</para> - - <informalexample> - <screen> 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J - 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - </screen> - </informalexample> - - <para>This is the same thing you will see from a - <command>scan</command> (see <xref linkend="scan">). If you just run - <command>inc</command> with no arguments it will look on your - computer for email that is supposed to be coming to - you.</para> - - <para>A lot of people like to use POP for grabbing their email. - MH can do POP to grab your email. You will need to give - <command>inc</command> a few command line arguments.</para> - - <informalexample> - <screen>&prompt.user; <userinput>inc -host mail.pop.org -user <replaceable>username</> -norpop</> - </screen> - </informalexample> - - <para>That tells <command>inc</command> to go to - <parameter>mail.pop.org</parameter> to download your email, and that - your username on their system is <replaceable>username</replaceable>. The - <option>-norpop</option> option tells <command>inc</command> to use - plain POP3 for downloading your email. MH has support for a - few different dialects of POP. More than likely you will never - ever need to use them though. While you can do more complex - things with inc such as audit files and scan format files this - will get you going.</para> - - <para>The <command>msgchk</command> command is used to get information - on whether or not you have new email. <command>msgchk</command> takes - the same <option>-host</option> and <option>-user</option> - options that <command>inc</command> takes.</para> - </sect2> - - <sect2 id="show"> - <title><command>show</command>, <command>next</command> and - <command>prev</command>—displaying and moving through - email</title> - - <para><command>show</command> is to show a letter in your current - folder. Like <command>inc</command>, <command>show</command> is a fairly - straightforward command. If you just type <userinput>show</userinput> - and hit <keycap>return</keycap> then it displays the current - message. You can also give specific message numbers to - show:</para> - - <informalexample> - <screen>&prompt.user; <userinput>show 32 45 56</> - </screen> - </informalexample> - - <para>This would display message numbers 32, 45 and 56 right - after each other. Unless you change the default behavior - <command>show</command> basically just does a <command>more</command> on the - email message.</para> - - <para><command>next</command> is used to move onto the next message and - <command>prev</command> will go to the previous message. Both - commands have an implied <command>show</command> command so that when - you go to the next message it automatically displays - it.</para> - </sect2> - - <sect2 id="scan"> - <title><command>scan</command>—shows you a scan of your - messages</title> - - <para><command>scan</command> will display a brief listing of the - messages in your current folder. This is an example of what - the <command>scan</command> command will give you.</para> - - <informalexample> - <screen> 30+ 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa - </screen> - </informalexample> - - <para>Like just about everything in MH this display is very - configurable. This is the typical default display. It gives - you the message number, the date on the email, the sender, the - subject line, and a sentence fragment from the very beginning - of the email if it can fit it. The <literal>+</literal> means that - message is the current message, so if you do a - <command>show</command> it will display that message.</para> - - <para>One useful option for scan is the - <option>-reverse</option> option. This will list your messages - with the highest message number first and lowest message - number last. Another useful option with <command>scan</command> is to - have it read from a file. If you want to scan your incoming - mailbox on FreeBSD without having to <command>inc</command> it you - can do <command>scan -file - /var/mail/<replaceable>username</replaceable></command>. This can be used - with any file that is in the <database>mbox</database> format.</para> - </sect2> - - <sect2 id="rmm"> - <title><command>rmm</command> and <command>rmf</command>—remove the - current message or folder</title> - - <para><command>rmm</command> is used to remove a mail message. The - default is typically to not actually remove the message but to - rename the file to one that is ignored by the MH commands. You - will need to through periodically and physically delete the - <quote>removed</quote> messages.</para> - - <para>The <command>rmf</command> command is used to remove folders. - This doesn't just rename the files but actually removes the - from the hard drive so you should be careful when you use this - command.</para> - </sect2> - - <sect2 id="samplereading"> - <title>A typical session of reading with MH</title> - - <para>The first thing that you will want to do is - <command>inc</command> your new mail. So at a shell prompt just type - in <command>inc</command> and hit <keycap>return</keycap>.</para> - - <informalexample> - <screen>&prompt.user; <userinput>inc</> -Incorporating new mail into inbox... - - 36+ 01/19 "Stephen L. Lange Request...<<Please remove me as contact for pind - 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -&prompt.user; - </screen> - </informalexample> - - <para>This shows you the new email that has been added to your - mailbox. So the next thing to do is <command>show</command> the email - and move around.</para> - - <informalexample> - <screen>&prompt.user; <userinput>show</> -Received: by sashimi.wwa.com (Smail3.1.29.1 #2) - id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST -Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) -From: "Stephen L. Lange" <stvlange@wwa.com> -To: matt@garply.com -Subject: Request... -Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII - - -Please remove me as contact for pindat.com - -&prompt.user; <userinput>rmm</> -&prompt.user; <userinput>next</> -Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 -.6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT -Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> -X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro -tocol -To: hsu@clinet.fi -Cc: hackers@FreeBSD.org -Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet - boards) -In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." - <199601182318.AA11772@Sysiphos> -X-Mailer: exmh version 1.5omega 10/6/94 -Date: Fri, 19 Jan 1996 17:56:40 +0000 -From: Matt Thomas <matt@lkg.dec.com> -Sender: owner-hackers@FreeBSD.org -Precedence: bulk - - -This is due to a typo in pcireg.h (to -which I am probably the guilty party). - </screen> - </informalexample> - - <para>The <command>rmm</command> removed the current message and the - <command>next</command> command moved me on to the next message. Now - if I wanted to look at ten most recent messages so I could - read one of them here is what I would do:</para> - - <informalexample> - <screen>&prompt.user; <userinput>scan last:10</> - 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has - 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 - 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue - 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki - 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< - 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 - 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan - 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne - 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 "Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -&prompt.user; - </screen> - </informalexample> - - <para>Then if I wanted to read message number 27 I would do a - <userinput>show 27</userinput> and it would be displayed. As you can - probably tell from this sample session MH is pretty easy to - use and looking through emails and displaying them is fairly - intuitive and easy.</para> - </sect2> - </sect1> - - <sect1> - <title>Folders and Mail Searching</title> - - <para>Anybody who gets lots of email definitely wants to be able - to prioritize, stamp, brief, de-brief, and number their emails - in a variety of different ways. MH can do this better than just - about anything. One thing that we haven't really talked about is - the concept of folders. You have undoubtedly come across the - folders concept using other email programs. MH has folders too. - MH can even do sub-folders of a folder. One thing you should - keep in mind with MH is that when you ran <command>inc</command> for - the first time and it asked you if it could create a - <filename>Mail</filename> directory it began storing everything in that - directory. If you look at that directory you will find a - directory named <filename>inbox</filename>. The <filename>inbox</filename> - directory houses all of your incoming mail that hasn't been - thrown anywhere else.</para> - - <para>Whenever you create a new folder a new directory is going to - be created underneath your MH <filename>Mail</filename> directory, and - messages in that folder are going to be stored in that - directory. When new email comes in that new email is thrown - into your <filename>inbox</filename> directory with a file name that is - equivalent to the message number. So even if you didn't have - any of the MH tools to read your email you could still use - standard UNIX commands to munge around in those directories and - just more your files. It's this simplicity that really gives you - a lot of power with what you can do with your email.</para> - - <para>Just as you can use message lists like <parameter>23 16 - 42</parameter> with most MH commands there is a folder option you can - specify with just about every MH command. If you do a - <command>scan +freebsd</command> it will scan your <filename>freebsd</filename> - folder, and your current folder will be changed to - <filename>freebsd</filename>. If you do a <command>show +freebsd 23 16 - 42</command>, <command>show</command> is going to switch to your - <filename>freebsd</filename> folder and display messages 23, 16 and 42. - So remember that <option>+<replaceable>folder</replaceable></option> syntax. You - will need to make sure you use it to make commands process - different folders. Remember you default folder for mail is - <filename>inbox</filename> so doing a <command>folder +inbox</command> should - always get you back to your mail. Of course, in MH's infinite - flexibility this can be changed but most places have probably - left it as <command>inbox</command>.</para> - - <sect2> - <title><command>pick</command>—search email that matches certain - criteria</title> - - <para><command>pick</command> is one of the more complex commands in - the MH system. So you might want to read the - <citerefentry><refentrytitle>pick</refentrytitle><manvolnum>1</manvolnum></citerefentry> man - page for a more thorough understanding. At its simplest level - you can do something like</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -search pci</> -15 -42 -55 -56 -57 - </screen> - </informalexample> - - <para>This will tell <command>pick</command> to look through every - single line in every message in your current folder and tell - you which message numbers it found the word <literal>pci</literal> - in. You can then <command>show</command> those messages and read them - if you wish or <command>rmm</command> them. You would have to specify - something like <command>show 15 42 55-57</command> to display them - though. A slightly more useful thing to do is this:</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -search pci -seq pick</> -5 hits -&prompt.user; <userinput>show pick</> - </screen> - </informalexample> - - <para>This will show you the same messages you just didn't have - to work as hard to do it. The <option>-seq</option> option is - really an abbreviation of <option>-sequence</option> and - <command>pick</command> is just a sequence which contains the message - numbers that matched. You can use sequences with just about - any MH command. So you could have done an <command>rmm pick</command> - and all those messages would be removed instead. You sequence - can be named anything. If you run pick again it will overwrite - the old sequence if you use the same name.</para> - - <para>Doing a <command>pick -search</command> can be a bit more - time consuming than just searching for message from someone, - or to someone. So <command>pick</command> allows you to use the - following predefined search criteria:</para> - - <variablelist> - <varlistentry> - <term><option>-to</option></term> - - <listitem> - <para>search based upon who the message is to</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-cc</option></term> - - <listitem> - <para>search based on who is in the cc list</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-from</option></term> - - <listitem> - <para>search for who sent the message</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-subject</option></term> - - <listitem> - <para>search for emails with this subject</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-date</option></term> - - <listitem> - <para>find emails with a matching dat</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--<replaceable>component</replaceable></option></term> - - <listitem> - <para>search for any other component in the header. (i.e. - <option>--reply-to</option> to find all emails with a certain - reply-to in the header)</para> - </listitem> - </varlistentry> - </variablelist> - - <para>This allows you to do things like - - <informalexample> - <screen>&prompt.user; <userinput>pick -to freebsd-hackers@FreeBSD.org -seq hackers</> - </screen> - </informalexample> - - to get a list of all the email send to the FreeBSD hackers - mailing list. <command>pick</command> also allows you to group these - criteria in different ways using the following options:</para> - - <itemizedlist> - <listitem> - <para>… <option>-and</option> …</para> - </listitem> - - <listitem> - <para>… <option>-or</option> &hellip</para> - </listitem> - - <listitem> - <para><option>-not</option> …</para> - </listitem> - - <listitem> - <para><option>-lbrace</option> … - <option>-rbrace</option></para> - </listitem> - </itemizedlist> - - <para>These commands allow you to do things like</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -to freebsd-hackers -and -cc freebsd-hackers</> - </screen> - </informalexample> - - <para>That will grab all the email in your inbox that was sent - to freebsd-hackers or cc'd to that list. The brace options - allow you to group search criteria together. This is sometimes - very necessary as in the following example</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -lbrace -to freebsd-hackers -and - -not -cc freebsd-questions -rbrace -and -subject pci</> - </screen> - </informalexample> - - <para>Basically this says <quote>pick (to freebsd-hackers and - not cc'd on freebsd-questions) and the subject is - pci</quote>. It should look through your folder and find - all messages sent to the freebsd-hackers list that aren't cc'd - to the freebsd-questions list that contain something on pci in - the subject line. Ordinarily you might have to worry about - something called operator precedence. Remember in math how you - evaluate from left to right and you do multiplication and - division first and addition and subtraction second? MH has the - same type of rules for <command>pick</command>. It's fairly complex - so you might want to study the man page. This document is just - to help you get acquainted with MH.</para> - </sect2> - - <sect2> - <title><command>folder</command>, <command>folders</command>, - <command>refile</command>—three useful programs for folder - maintenance</title> - - <para>There are three programs which are primarily just for - manipulating your folders. The <command>folder</command> program is - used to switch between folders, pack them, and list them. At - its simplest level you can do a <command>folder - +<replaceable>newfolder</replaceable></command> and you will be switched into - <replaceable>newfolder</replaceable>. From there on out all your MH - commands like <command>comp</command>, <command>repl</command>, - <command>scan</command>, and <command>show</command> will act on that - <command>newfolder</command> folder.</para> - - <para>Sometimes when you are reading and deleting messages you - will develop <quote>holes</quote> in your folders. If you do a - <command>scan</command> you might just see messages 34, 35, 36, 43, - 55, 56, 57, 80. If you do a <command>folder -pack</command> - this will renumber all your messages so that there are no - holes. It doesn't actually delete any messages though. So you - may need to periodically go through and physically delete - <command>rmm</command>'d messages.</para> - - <para>If you need statistics on your folders you can do a - <command>folders</command> or <command>folder -all</command> to list - all your folders, how many messages they have, what the - current message is in each one and so on. This line of stats - it displays for all your folders is the same one you get when - you change to a folder with <command>folder +foldername</command>. A - <command>folders</command> command looks like this:</para> - - <informalexample> - <screen> Folder # of messages ( range ); cur msg (other files) - announce has 1 message ( 1- 1). - drafts has no messages. - f-hackers has 43 messages ( 1- 43). - f-questions has 16 messages ( 1- 16). - inbox+ has 35 messages ( 1- 38); cur= 37. - lists has 8 messages ( 1- 8). - netfuture has 1 message ( 1- 1). - out has 31 messages ( 1- 31). - personal has 6 messages ( 1- 6). - todo has 58 messages ( 1- 58); cur= 1. - - TOTAL= 199 messages in 13 folders. - </screen> - </informalexample> - - <para>The <command>refile</command> command is what you use to move - messages between folders. When you do something like - <command>refile 23 +netfuture</command> message number 23 is moved - into the <filename>netfuture</filename> folder. You could also do - something like <command>refile 23 +netfuture/latest</command> which - would put message number 23 in a subfolder called - <filename>latest</filename> under the <filename>netfuture</filename> folder. - If you want to keep a message in the current folder and link - it you can do a <command>refile -link 23 +netfuture</command> - which would keep 23 in your current <filename>inbox</filename> but - also list in your <filename>netfuture</filename> folder. You are - probably beginning to realize some of the really powerful - things you can do with MH.</para> - </sect2> - </sect1> - - <sect1> - <title>Sending Mail</title> - - <para>Email is a two way street for most people so you want to be - able to send something back. The way MH handles sending mail can - be a bit difficult to follow at first, but it allows for - incredible flexibility. The first thing MH does is to copy a - components file into your outgoing email. A components file is - basically a skeleton email letter with stuff like the To: and - Subject: headers already in it. You are then sent into your - editor where you fill in the header information and then type - the body of your message below the dashed lines in the message. - Then to the <command>whatnow</command> program. When you are at the - <prompt>What now?</prompt> prompt you can tell it to - <command>send</command>, <command>list</command>, <command>edit</command>, - <command>edit</command>, <command>push</command>, and <command>quit</command>. Most - of these commands are self-explanatory. So the message sending - process involves copying a component file, editing your email, - and then telling the <command>whatnow</command> program what to do with - your email.</para> - - <sect2> - <title><command>comp</command>, <command>forw</command>, - <command>reply</command>—compose, forward or reply to a message - to someone</title> - - <para>The <command>comp</command> program has a few useful command line - options. The most important one to know right now is the - <option>-editor</option> option. When MH is installed the - default editor is usually a program called - <command>prompter</command> which comes with MH. It's not a very - exciting editor and basically just gets the job done. So when - you go to compose a message to someone you might want to use - <command>comp -editor /usr/bin/vi/</command> or <command>comp -editor - /usr/local/bin/pico/</command> instead. Once you have run - <emphasis>comp</emphasis> you are in your editor and you see - something that looks like this:</para> - - <informalexample> - <screen>To: -cc: -Subject: --------- - </screen> - </informalexample> - - <para>You need to put the person you are sending the mail to - after the <literal>To:</literal> line. It works the same way for the - other headers also, so you would need to put your subject - after the <literal>Subject:</literal> line. Then you would just put - the body of your message after the dashed lines. It may seem a - bit simplistic since a lot of email programs have special - requesters that ask you for this information but there really - isn't any point to that. Plus this really gives you excellent - flexibility.</para> - - <informalexample> - <screen>To:<userinput>freebsd-rave@FreeBSD.org</> -cc: -Subject:<userinput>And on the 8th day God created the FreeBSD core team</> --------- -<userinput>Wow this is an amazing operating system. Thanks!</> - </screen> - </informalexample> - - <para>You can now save this message and exit your editor. You - will see the <prompt>What now?</prompt> prompt and you can type in - <userinput>send</userinput> or <userinput>s</userinput> and hit - <keycap>return</keycap>. Then the FreeBSD core team will receive - their just rewards. As I mentioned earlier you can also use - other commands, for example <command>quit</command> if you don't want - to send the message.</para> - - <para>The <command>forw</command> command is stunningly similar. The - big difference being that the message you are forwarding is - automatically included in the outgoing message. When you run - <command>forw</command> it will forward your current message. You can - always tell it to forward something else by doing something - like <command>forw 23</command> and then message number 23 will be - put in your outgoing message instead of the current message. - Beyond those small differences <command>forw</command> functions - exactly the same as <command>comp</command>. You go through the exact - same message sending process.</para> - - <para>The <command>repl</command> command will reply to whatever your - current message is, unless you give it a different message to - reply to. <command>repl</command> will do its best to go ahead and - fill in some of the email headers already. So you will notice - that the <literal>To:</literal> header already has the address of the - recipient in there. Also the <literal>Subject:</literal> line will - already be filled in. You then go about the normal message - composition process and you are done. One useful command line - option to know here is the <option>-cc</option> option. You - can use <parameter>all</parameter>, <parameter>to</parameter>, <parameter>cc</parameter>, - <parameter>me</parameter> after the <option>-cc</option> option to have - <command>repl</command> automatically add the various addresses to - the cc list in the message. You have probably noticed that the - original message isn't included. This is because most MH - setups are configured to do this from the start.</para> - </sect2> - - <sect2> - <title><filename>components</filename>, and - <filename>replcomps</filename>—components files for - <command>comp</command> and <command>repl</command></title> - - <para>The <filename>components</filename> file is usually in - <filename>/usr/local/lib/mh</filename>. You can copy that file - into your MH Mail directory and edit to contain what you want - it to contain. It is a fairly basic file. You have various - email headers at the top, a dashed line and then nothing. The - <command>comp</command> command just copies this - <filename>components</filename> file and then edits it. You can add - any kind of valid RFC822 header you want. For instance you - could have something like this in your <filename>components</filename> - file:</para> - - <informalexample> - <screen>To: -Fcc: out -Subject: -X-Mailer: MH 6.8.3 -X-Home-Page: http://www.FreeBSD.org/ -------- - </screen> - </informalexample> - - <para>MH would then copy this components file and throw you into - your editor. The <filename>components</filename> file is fairly - simple. If you wanted to have a signature on those messages - you would just put your signature in that - <filename>components</filename> file.</para> - - <para>The <filename>replcomps</filename> file is a bit more complex. The - default <filename>replcomps</filename> looks like this:</para> - - <informalexample> - <screen>%(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ -%<(nonnull)%(void(width))%(putaddr To: )\n%>\ -%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ -%<(nonnull)%(void(width))%(putaddr cc: )\n%>\ -%<{fcc}Fcc: %{fcc}\n%>\ -%<{subject}Subject: Re: %{subject}\n%>\ -%<{date}In-reply-to: Your message of "\ -%<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} - %{message-id}%>\n%>\ --------- - </screen> - </informalexample> - - <para>It's in the same basic format as the - <filename>components</filename> file but it contains quite a few extra - formatting codes. The <literal>%(lit)</literal> command makes room - for the address. The <literal>%(formataddr</literal> is a function - that returns a proper email address. The next part is - <literal>%<</literal> which means if and the - <literal>{reply-to}</literal> means the reply-to field in the - original message. So that might be translated this way:</para> - - <informalexample> - <screen>%<<emphasis remap=bf>if</emphasis> {reply-to} <emphasis remap=bf>the original message has a reply-to</emphasis> -then give that to formataddr, %? <emphasis remap=bf>else</emphasis> {from} <emphasis remap=bf>take the -from address</emphasis>, %? <emphasis remap=bf>else</emphasis> {sender} <emphasis remap=bf>take the sender address</emphasis>, %? -<emphasis remap=bf>else</emphasis> {return-path} <emphasis remap=bf>take the return-path from the original -message</emphasis>, %> <emphasis remap=bf>endif</emphasis>. - </screen> - </informalexample> - - <para>As you can tell MH formatting can get rather involved. You - can probably decipher what most of the other functions and - variables mean. All of the information on writing these format - strings is in the MH-Format man page. The really nice thing is - that once you have built your customized - <filename>replcomps</filename> file you won't need to touch it again. - No other email program really gives you the power and - flexibility that MH gives you.</para> - </sect2> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/articles/multi-os/Makefile b/en_US.ISO_8859-1/articles/multi-os/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO_8859-1/articles/multi-os/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/multi-os/article.sgml b/en_US.ISO_8859-1/articles/multi-os/article.sgml deleted file mode 100644 index 63394e6f5f..0000000000 --- a/en_US.ISO_8859-1/articles/multi-os/article.sgml +++ /dev/null @@ -1,743 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/multi-os/article.sgml,v 1.13 2000/07/26 18:24:49 jim Exp $ --> -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"> -<article> - <articleinfo> - <title>Installing and Using FreeBSD With Other Operating Systems</title> - - <authorgroup> - <author> - <firstname>Jay</firstname> - - <surname>Richmond</surname> - - <affiliation> - <address> - <email>jayrich@sysc.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>6 August 1996</pubdate> - - <abstract> - <para>This document discusses how to make FreeBSD coexist nicely - with other popular operating systems such as Linux, MS-DOS, - OS/2, and Windows 95. Special thanks to: Annelise Anderson - <email>andrsn@stanford.edu</email>, Randall Hopper - <email>rhh@ct.picker.com</email>, and Jordan K. Hubbard - <email>jkh@time.cdrom.com</email></para> - </abstract> - </articleinfo> - - <sect1> - <title>Overview</title> - - <para>Most people can't fit these operating systems together - comfortably without having a larger hard disk, so special - information on large EIDE drives is included. Because there are - so many combinations of possible operating systems and hard disk - configurations, the <xref linkend="ch5"> section may be of the - most use to you. It contains descriptions of specific working - computer setups that use multiple operating systems.</para> - - <para>This document assumes that you have already made room on - your hard disk for an additional operating system. Any time you - repartition your hard drive, you run the risk of destroying the - data on the original partitions. However, if your hard drive is - completely occupied by DOS, you might find the FIPS utility - (included on the FreeBSD CD-ROM in the - <filename>\TOOLS</filename> directory or via <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools">ftp</ulink>) - useful. It lets you repartition your hard disk without - destroying the data already on it. There is also a commercial - program available called Partition Magic, which lets you size - and delete partitions without consequence.</para> - </sect1> - - <sect1 id="ch2"> - <title>Overview of Boot Managers</title> - - <para>These are just brief descriptions of some of the different - boot managers you may encounter. Depending on your computer - setup, you may find it useful to use more than one of them on - the same system.</para> - - <variablelist> - <varlistentry> - <term>Boot Easy</term> - - <listitem> - <para>This is the default boot manager used with FreeBSD. - It has the ability to boot most anything, including BSD, - OS/2 (HPFS), Windows 95 (FAT and FAT32), and Linux. - Partitions are selected with the function keys.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>OS/2 Boot Manager</term> - - <listitem> - <para>This will boot FAT, HPFS, FFS (FreeBSD), and EXT2 - (Linux). It will also boot FAT32 partitions. Partitions - are selected using arrow keys. The OS/2 Boot Manager is - the only one to use its own separate partition, unlike the - others which use the master boot record (MBR). Therefore, - it must be installed below the 1024th cylinder to avoid - booting problems. It can boot Linux using LILO when it is - part of the boot sector, not the MBR. Go to <ulink - URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux - HOWTOs</ulink> on the World Wide Web for more - information on booting Linux with OS/2's boot - manager.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>OS-BS</term> - - <listitem> - <para>This is an alternative to Boot Easy. It gives you more - control over the booting process, with the ability to set - the default partition to boot and the booting timeout. - The beta version of this programs allows you to boot by - selecting the OS with your arrow keys. It is included on - the FreeBSD CD in the <filename>\TOOLS</filename> - directory, and via <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools">ftp</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LILO, or LInux LOader</term> - - <listitem> - <para>This is a limited boot manager. It will boot FreeBSD, - though some customization work is required in the LILO - configuration file.</para> - </listitem> - </varlistentry> - </variablelist> - - <note id="fat32"> - <title>About FAT32</title> - - <para>FAT32 is the replacement to the FAT filesystem included in - Microsoft's OEM SR2 Beta release, which is expected to be - utilitized on computers pre-loaded with Windows 95 towards the - end of 1996. It converts the normal FAT file system and - allows you to use smaller cluster sizes for larger hard - drives. FAT32 also modifies the traditional FAT boot sector - and allocation table, making it incompatible with some boot - managers.</para> - </note> - </sect1> - - <sect1 id="ch3"> - <title>A Typical Installation</title> - - <para>Let's say I have two large EIDE hard drives, and I want to - install FreeBSD, Linux, and Windows 95 on them.</para> - - <para>Here's how I might do it using these hard disks:</para> - - <itemizedlist> - <listitem> - <para><filename>/dev/wd0</filename> (first physical hard disk)</para> - </listitem> - - <listitem> - <para><filename>/dev/wd1</filename> (second hard disk)</para> - </listitem> - </itemizedlist> - - <para>Both disks have 1416 cylinders.</para> - - <procedure> - <step> - <para>I boot from a MS-DOS or Windows 95 boot disk that - contains the <filename>FDISK.EXE</filename> utility and make a small - 50 meg primary partition (35-40 for Windows 95, plus a - little breathing room) on the first disk. Also create a - larger partition on the second hard disk for my Windows - applications and data.</para> - </step> - - <step> - <para>I reboot and install Windows 95 (easier said than done) - on the <filename>C:</filename> partition.</para> - </step> - - <step> - <para>The next thing I do is install Linux. I'm not sure - about all the distributions of Linux, but slackware includes - LILO (see <xref linkend="ch2">). When I am partitioning out - my hard disk with Linux <command>fdisk</command>, I would - put all of Linux on the first drive (maybe 300 megs for a - nice root partition and some swap space).</para> - </step> - - <step> - <para>After I install Linux, and are prompted about installing - LILO, make SURE that I install it on the boot sector of my - root Linux partition, not in the MBR (master boot - record).</para> - </step> - - <step> - <para>The remaining hard disk space can go to FreeBSD. I also - make sure that my FreeBSD root slice does not go beyond the - 1024th cylinder. (The 1024th cylinder is 528 megs into the - disk with our hypothetical 720MB disks). I will use the - rest of the hard drive (about 270 megs) for the - <filename>/usr</filename> and <filename>/</filename> slices if I wish. The - rest of the second hard disk (size depends on the amount of - my Windows application/data partition that I created in step - 1 can go to the <filename>/usr/src</filename> slice and swap - space.</para> - </step> - - <step> - <para>When viewed with the Windows 95 <command>fdisk</command> - utility, my hard drives should now look something like this: - - <screen> ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 1 - -Partition Status Type Volume_Label Mbytes System Usage -C: 1 A PRI DOS 50 FAT** 7% - 2 A Non-DOS (Linux) 300 43% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 2 - -Partition Status Type Volume_Label Mbytes System Usage -D: 1 A PRI DOS 420 FAT** 60% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - </screen> - ** May say FAT16 or FAT32 if you are using the OEM SR2 - update. See <xref linkend="ch2">).</para> - </step> - - <step> - <para>Install FreeBSD. I make sure to boot with my first hard - disk set at <quote>NORMAL</quote> in the BIOS. If it is not, - I'll have the enter my true disk geometry at boot time (to - get this, boot Windows 95 and consult Microsoft Diagnostics - (<filename>MSD.EXE</filename>), or check your BIOS) with the - parameter <literal>hd0=1416,16,63</literal> where - <replaceable>1416</replaceable> is the number of cylinders on my hard - disk, <replaceable>16</replaceable> is the number of heads per track, - and <replaceable>63</replaceable> is the number of sectors per track on - the drive.</para> - </step> - - <step> - <para>When partitioning out the hard disk, I make sure to - install Boot Easy on the first disk. I don't worry about - the second disk, nothing is booting off of it.</para> - </step> - - <step> - <para>When I reboot, Boot Easy should recognize my three - bootable partitions as DOS (Windows 95), Linux, and BSD - (FreeBSD).</para> - </step> - </procedure> - </sect1> - - <sect1 id="ch4"> - <title>Special Considerations</title> - - <para>Most operating systems are very picky about where and how - they are placed on the hard disk. Windows 95 and DOS need to be - on the first primary partitiin on the first hard disk. OS/2 is - the exception. It can be installed on the first or second disk - in a primary or extended partition. If you are not sure, keep - the beginning of the bootable partitions below the 1024th - cylinder.</para> - - <para>If you install Windows 95 on an existing BSD system, it will - <quote>destroy</quote> the MBR, and you will have to reinstall your - previous boot manager. Boot Easy can be reinstalled by using - the BOOTINST.EXE utility included in the \TOOLS directory on the - CD-ROM, and via <ulink - URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools">ftp</ulink>. - You can also re-start the installation process and go to the - partition editor. From there, mark the FreeBSD partition as - bootable, select Boot Manager, and then type W to (W)rite out - the information to the MBR. You can now reboot, and Boot Easy - should then recognize Windows 95 as DOS.</para> - - <para>Please keep in mind that OS/2 can read FAT and HPFS - partitions, but not FFS (FreeBSD) or EXT2 (Linux) partitions. - Likewise, Windows 95 can only read and write to FAT and FAT32 - (see <xref linkend="ch2">) partitions. FreeBSD can read most - file systems, but currently cannot read HPFS partitions. Linux - can read HPFS partitions, but can't write to them. Recent - versions of the Linux kernel (2.x) can read and write to Windows - 95 VFAT partitions (VFAT is what gives Windows 95 long file - names - it's pretty much the same as FAT). Linux can read and - write to most file systems. Got that? I hope so.</para> - </sect1> - - <sect1 id="ch5"> - <title>Examples</title> - - <para><emphasis>(section needs work, please send your example to - <email>jayrich@sysc.com</email>)</emphasis>.</para> - - <para>FreeBSD+Win95: If you installed FreeBSD after Windows 95, - you should see <literal>DOS</literal> on the Boot Easy menu. This is - Windows 95. If you installed Windows 95 after FreeBSD, read - <xref linkend="ch4"> above. As long as your hard disk does not - have 1024 cylinders you should not have a problem booting. If - one of your partitions goes beyond the 1024th cylinder however, - and you get messages like <errorname>invalid system disk</errorname> - under DOS (Windows 95) and FreeBSD will not boot, try looking - for a setting in your BIOS called <quote>> 1024 cylinder - support</quote> or <quote>NORMAL/LBA</quote> mode. DOS may need LBA - (Logical Block Addressing) in order to boot correctly. If the - idea of switching BIOS settings every time you boot up doesn't - appeal to you, you can boot FreeBSD through DOS via the - <filename>FBSDBOOT.EXE</filename> utility on the CD (It should find your - FreeBSD partition and boot it.)</para> - - <para>FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manger - can boot all of these operating systems, so that shouldn't be a - problem.</para> - - <para>FreeBSD+Linux: You can also use Boot Easy to boot both - operating systems.</para> - - <para>FreeBSD+Linux+Win95: (see <xref linkend="ch3">)</para> - </sect1> - - <sect1 id="sources"> - <title>Other Sources of Help</title> - - <para>There are many <ulink - URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux - HOW-TOs</ulink> that deal with multiple operating systems on - the same hard disk.</para> - - <para>The <ulink - URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+DOS+Win95+OS2.html">Linux+DOS+Win95+OS2 - mini-HOWTO</ulink> offers help on configuring the OS/2 boot - manager, and the <ulink - URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+FreeBSD.html">Linux+FreeBSD - mini-HOWTO</ulink> might be interesting as well. The <ulink - URL="http://www.in.net/~jkatz/win95/Linux-HOWTO.html">Linux-HOWTO</ulink> - is also helpful.</para> - - <para>The <ulink - URL="http://www.dorsai.org/~dcl/publications/NTLDR_Hacking">NT - Loader Hacking Guide</ulink> provides good information on - multibooting Windows NT, '95, and DOS with other operating - systems.</para> - - <para>And Hale Landis's "How It Works" document pack contains some - good info on all sorts of disk geometry and booting related - topics. You can find it at - <ulink - URL="ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip">ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip</ulink>.</para> - - <para>Finally, don't overlook FreeBSD's kernel documentation on - the booting procedure, available in the kernel source - distribution (it unpacks to <ulink - URL="file:/usr/src/sys/i386/boot/biosboot/README.386BSD">file:/usr/src/sys/i386/boot/biosboot/README.386BSD</ulink>.</para> - </sect1> - - <sect1> - <title>Technical Details</title> - - <para><emphasis>(Contributed by Randall Hopper, - <email>rhh@ct.picker.com</email>)</emphasis></para> - - <para>This section attempts to give you enough basic information - about your hard disks and the disk booting process so that you - can troubleshoot most problems you might encounter when getting - set up to boot several operating systems. It starts in pretty - basic terms, so you may want to skim down in this section until - it begins to look unfamiliar and then start reading.</para> - - <sect2> - <title>Disk Primer</title> - - <para>Three fundamental terms are used to describe the location - of data on your hard disk: Cylinders, Heads, and Sectors. - It's not particularly important to know what these terms - relate to except to know that, together, they identify where - data is physically on your disk.</para> - - <para>Your disk has a particular number of cylinders, number of - heads, and number of sectors per cylinder-head (a - cylinder-head also known nown as a track). Collectively this - information defines the "physical disk geometry" for your hard - disk. There are typically 512 bytes per sector, and 63 - sectors per track, with the number of cylinders and heads - varying widely from disk to disk. Thus you can figure the - number of bytes of data that'll fit on your own disk by - calculating:</para> - - <informalexample> - <para>(# of cylinders) × (# heads) × (63 - sectors/track) × (512 bytes/sect)</para> - </informalexample> - - <para>For example, on my 1.6 Gig Western Digital AC31600 EIDE hard - disk,that's:</para> - - <informalexample> - <para>(3148 cyl) × (16 heads) × (63 - sectors/track) × (512 bytes/sect)</para> - </informalexample> - - <para>which is 1,624,670,208 bytes, or around 1.6 Gig.</para> - - <para>You can find out the physical disk geometry (number of - cylinders, heads, and sectors/track counts) for your hard - disks using ATAID or other programs off the net. Your hard - disk probably came with this information as well. Be careful - though: if you're using BIOS LBA (see <xref - linkend="limits">), you can't use just any program to get - the physical geometry. This is because many programs (e.g. - <filename>MSD.EXE</filename> or FreeBSD fdisk) don't identify the - physical disk geometry; they instead report the - <firstterm>translated geometry</firstterm> (virtual numbers from using - LBA). Stay tuned for what that means.</para> - - <para>One other useful thing about these terms. Given 3 - numbers—a cylinder number, a head number, and a - sector-within-track number—you identify a specific - absolute sector (a 512 byte block of data) on your disk. - Cylinders and Heads are numbered up from 0, and Sectors are - numbered up from 1.</para> - - <para>For those that are interested in more technical details, - information on disk geometry, boot sectors, BIOSes, etc. can - be found all over the net. Query Lycos, Yahoo, etc. for - <literal>boot sector</literal> or <literal>master boot record</literal>. - Among the useful info you'll find are Hale Landis's - <citetitle>How It Works</citetitle> document pack. See the <xref - linkend="sources"> section for a few pointers to this - pack.</para> - - <para>Ok, enough terminology. We're talking about booting - here.</para> - </sect2> - - <sect2 id="booting"> - <title>The Booting Process</title> - - <para>On the first sector of your disk (Cyl 0, Head 0, Sector 1) - lives the Master Boot Record (MBR). It contains a map of your - disk. It identifies up to 4 <firstterm>partitions</firstterm>, each of - which is a contiguous chunk of that disk. FreeBSD calls - partitions <firstterm>slices</firstterm> to avoid confusion with it's - own partitions, but we won't do that here. Each partition can - contain its own operating system.</para> - - <para>Each partition entry in the MBR has a <firstterm>Partition - ID</firstterm>, a <firstterm>Start Cylinder/Head/Sector</firstterm>, and an - <firstterm>End Cylinder/Head/Sector</firstterm>. The Partition ID - tells what type of partition it is (what OS) and the Start/End - tells where it is. <xref linkend="tbl-pid"> lists a - smattering of some common Partition IDs.</para> - - <table id="tbl-pid"> - <title>Partition IDs</title> - - <tgroup cols="2"> - <thead> - <row> - <entry>ID (hex)</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>01</entry> - <entry>Primary DOS12 (12-bit FAT)</entry> - </row> - - <row> - <entry>04</entry> - <entry>Primary DOS16 (16-bit FAT)</entry> - </row> - - <row> - <entry>05</entry> - <entry>Extended DOS</entry> - </row> - - <row> - <entry>06</entry> - <entry>Primary big DOS (> 32MB)</entry> - </row> - - <row> - <entry>0A</entry> - <entry>OS/2</entry> - </row> - - <row> - <entry>83</entry> - <entry>Linux (EXT2FS)</entry> - </row> - - <row> - <entry>A5</entry> - <entry>FreeBSD, NetBSD, 386BSD (UFS)</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Note that not all partitions are bootable (e.g. Extended - DOS). Some are—some aren't. What makes a partition - bootable is the configuration of the <firstterm>Partition Boot - Sector</firstterm> that exists at the beginning of each - partition.</para> - - <para>When you configure your favorite boot manager, it looks up - the entries in the MBR partition tables of all your hard disks - and lets you name the entries in that list. Then when you - boot, the boot manager is invoked by special code in the - Master Boot Sector of the first probed hard disk on your - system. It looks at the MBR partition table entry - corresponding to the partition choice you made, uses the Start - Cylinder/Head/Sector information for that partition, loads up - the Partition Boot Sector for that partition, and gives it - control. That Boot Sector for the partition itself contains - enough information to start loading the operating system on - that partition.</para> - - <para>One thing we just brushed past that's important to know. - All of your hard disks have MBRs. However, the one that's - important is the one on the disk that's first probed by the - BIOS. If you have only IDE hard disks, its the first IDE disk - (e.g. primary disk on first controller). Similarly for SCSI - only systems. If you have both IDE and SCSI hard disks - though, the IDE disk is typically probed first by the BIOS, so - the first IDE disk is the first probed disk. The boot manager - you will install will be hooked into the MBR on this first - probed hard disk that we've just described.</para> - </sect2> - - <sect2 id="limits"> - <title>Booting Limitations and Warnings</title> - - <para>Now the interesting stuff that you need to watch out - for.</para> - - <sect3> - <title>The dreaded 1024 cylinder limit and how BIOS LBA helps</title> - - <para>The first part of the booting process is all done - through the BIOS, (if that's a new term to you, the BIOS is - a software chip on your system motherboard which provides - startup code for your computer). As such, this first part - of the process is subject to the limitations of the BIOS - interface.</para> - - <para>The BIOS interface used to read the hard disk during - this period (INT 13H, Subfunction 2) allocates 10 bits to - the Cylinder Number, 8 bits to the Head Number, and 6 bits - to the Sector Number. This restricts users of this - interface (i.e. boot managers hooked into your disk's MBR as - well as OS loaders hooked into the Boot Sectors) to the - following limits:</para> - - <itemizedlist> - <listitem> - <para>1024 cylinders, max</para> - </listitem> - - <listitem> - <para>256 heads, max</para> - </listitem> - - <listitem> - <para>64 sectors/track, max (actually 63, <literal>0</literal> - isn't available)</para> - </listitem> - </itemizedlist> - - <para>Now big hard disks have lots of cylinders but not a lot - of heads, so invariably with big hard disks the number of - cylinders is greater than 1024. Given this and the BIOS - interface as is, you can't boot off just anywhere on your - hard disk. The boot code (the boot manager and the OS - loader hooked into all bootable partitions' Boot Sectors) - has to reside below cylinder 1024. In fact, if your hard - disk is typical and has 16 heads, this equates to:</para> - - <informalexample> - <para>1024 cyl/disk × 16 heads/disk × 63 - sect/(cyl-head) × 512 bytes/sector</para> - </informalexample> - - <para>which is around the often-mentioned 528MB limit.</para> - - <para>This is where BIOS LBA (Logical Block Addressing) comes - in. BIOS LBA gives the user of the BIOS API calls access to - physical cylinders above 1024 though the BIOS interfaces by - redefining a cylinder. That is, it remaps your cylinders - and heads, making it appear through the BIOS as though the - disk has fewer cylinders and more heads than it actually - does. In other words, it takes advantage of the fact that - hard disks have relatively few heads and lots of cylinders - by shifting the balance between number of cylinders and - number of heads so that both numbers lie below the - above-mentioned limits (1024 cylinders, 256 heads).</para> - - <para>With BIOS LBA, the hard disk size limitation is - virtually removed (well, pushed up to 8 Gigabytes anyway). - If you have an LBA BIOS, you can put FreeBSD or any OS - anywhere you want and not hit the 1024 cylinder - limit.</para> - - <para>To use my 1.6 Gig Western Digital as an example again, - it's physical geometry is:</para> - - <informalexample> - <para>(3148 cyl, 16 heads, 63 sectors/track, 512 - bytes/sector)</para> - </informalexample> - - <para>However, my BIOS LBA remaps this to:</para> - - <informalexample> - <para>(787 cyl, 64 heads, 63 sectors/track, 512 - bytes/sector)</para> - </informalexample> - - <para>giving the same effective size disk, but with cylinder - and head counts within the BIOS API's range (Incidentally, I - have both Linux and FreeBSD existing on one of my hard disks - above the 1024th physical cylinder, and both operating - systems boot fine, thanks to BIOS LBA).</para> - </sect3> - - <sect3> - <title>Boot Managers and Disk Allocation</title> - - <para>Another gotcha to watch out when installing boot - managers is allocating space for your boot manager. It's - best to be aware of this issue up front to save yourself - from having to reinstall one or more of your OSs.</para> - - <para>If you followed the discussion in <xref - linkend="booting"> about the Master Boot Sector (where the - MBR is), Partition Boot Sectors, and the booting process, - you may have been wondering just exactly where on your hard - disk that nifty boot manager is going to live. Well, some - boot managers are small enough to fit entirely within the - Master Boot Sector (Cylinder 0, Head 0, Sector 0) along with - the partition table. Others need a bit more room and - actually extend a few sectors past the Master Boot Sector in - the Cylinder 0 Head 0 track, since that's typically - free…typically.</para> - - <para>That's the catch. Some operating systems (FreeBSD - included) let you start their partitions right after the - Master Boot Sector at Cylinder 0, Head 0, Sector 2 if you - want. In fact, if you give FreeBSD's sysinstall a disk with - an empty chunk up front or the whole disk empty, that's - where it'll start the FreeBSD partition by default (at least - it did when I fell into this trap). Then when you go to - install your boot manager, if it's one that occupies a few - extra sectors after the MBR, it'll overwrite the front of - the first partition's data. In the case of FreeBSD, this - overwrites the disk label, and renders your FreeBSD - partition unbootable.</para> - - <para>The easy way to avoid this problem (and leave yourself - the flexibility to try different boot managers later) is - just to always leave the first full track on your disk - unallocated when you partition your disk. That is, leave - the space from Cylinder 0, Head 0, Sector 2 through Cylinder - 0, Head 0, Sector 63 unallocated, and start your first - partition at Cylinder 0, Head 1, Sector 1. For what it's - worth, when you create a DOS partition at the front of your - disk, DOS leaves this space open by default (this is why - some boot managers assume it's free). So creating a DOS - partition up at the front of your disk avoids this problem - altogether. I like to do this myself, creating 1 Meg DOS - partition up front, because it also avoids my primary DOS - drive letters shifting later when I repartition.</para> - - <para>For reference, the following boot managers use the - Master Boot Sector to store their code and data:</para> - - <itemizedlist> - <listitem> - <para>OS-BS 1.35</para> - </listitem> - - <listitem> - <para>Boot Easy</para> - </listitem> - - <listitem> - <para>LILO</para> - </listitem> - </itemizedlist> - - <para>These boot managers use a few additional sectors after - the Master Boot Sector:</para> - - <itemizedlist> - <listitem> - <para>OS-BS 2.0 Beta 8 (sectors 2-5)</para> - </listitem> - - <listitem> - <para>OS/2's boot manager</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>What if your machine won't boot?</title> - - <para>At some point when installing boot managers, you might - leave the MBR in a state such that your machine won't boot. - This is unlikely, but possible when re-FDISKing underneath - an already-installed boot manager.</para> - - <para>If you have a bootable DOS partition on your disk, you - can boot off a DOS floppy, and run:</para> - - <informalexample> - <screen>A:\> <userinput>FDISK /MBR</> - </screen> - </informalexample> - - <para>to put the original, simple DOS boot code back into the - system. You can then boot DOS (and DOS only) off the hard - drive. Alternatively, just re-run your boot manager - installation program off a bootable floppy.</para> - </sect3> - </sect2> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/articles/new-users/Makefile b/en_US.ISO_8859-1/articles/new-users/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO_8859-1/articles/new-users/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/new-users/article.sgml b/en_US.ISO_8859-1/articles/new-users/article.sgml deleted file mode 100644 index 92a862ed06..0000000000 --- a/en_US.ISO_8859-1/articles/new-users/article.sgml +++ /dev/null @@ -1,1052 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/new-users/article.sgml,v 1.17 2001/04/09 00:33:41 dd Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"> -<article> - <articleinfo> - <title>For People New to Both FreeBSD and Unix</title> - - <authorgroup> - <author> - <firstname>Annelise</firstname> - - <surname>Anderson</surname> - - <affiliation> - <address><email>andrsn@andrsn.stanford.edu</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>August 15, 1997</pubdate> - - <abstract> - <para>Congratulations on installing FreeBSD! This introduction - is for people new to both FreeBSD <emphasis>and</emphasis> - Un*x—so it starts with basics. It assumes you're using - version 2.0.5 or later of FreeBSD as distributed by BSDi - or FreeBSD.org, your system (for now) has a single user - (you)—and you're probably pretty good with DOS/Windows - or OS/2.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Logging in and Getting Out</title> - - <para>Log in (when you see <prompt - >login:</prompt>) as a user you created during - installation or as <firstterm>root</firstterm>. (Your FreeBSD - installation will already have an account for root; root can go - anywhere and do anything, including deleting essential files, so - be careful!) The symbols &prompt.user; and &prompt.root; in the following stand for the - prompt (yours may be different), with &prompt.user; indicating an ordinary - user and &prompt.root; indicating root.</para> - - <para>To log out (and get a new <prompt - >login:</prompt> prompt) type</para> - - <informalexample> - <screen>&prompt.root; <userinput>exit</userinput> - </screen> - </informalexample> - - <para>as often as necessary. Yes, press <keysym>enter</keysym> - after commands, and remember that Unix is - case-sensitive—<command>exit</command>, not - <command>EXIT</command>.</para> - - <para>To shut down the machine type</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/shutdown -h now</userinput> - </screen> - </informalexample> - - <para>Or to reboot type</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/shutdown -r now</userinput> - </screen> - </informalexample> - - <para>or</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/reboot</userinput> - </screen> - </informalexample> - - <para>You can also reboot with - <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo>. - Give it a little time to do its work. This is equivalent to - <command>/sbin/reboot</command> in recent releases of FreeBSD - and is much, much better than hitting the reset button. You - don't want to have to reinstall this thing, do you?</para> - </sect1> - - <sect1> - <title>Adding A User with Root Privileges</title> - - <para>If you didn't create any users when you installed the system - and are thus logged in as root, you should probably create a - user now with</para> - - <informalexample> - <screen>&prompt.root; <userinput>adduser</userinput> - </screen> - </informalexample> - - <para>The first time you use adduser, it might ask for some - defaults to save. You might want to make the default shell csh - instead of sh, if it suggests sh as the default. Otherwise just - press enter to accept each default. These defaults are saved in - <filename>/etc/adduser.conf</filename>, an editable file.</para> - - <para>Suppose you create a user <emphasis>jack</emphasis> with - full name <emphasis>Jack Benimble</emphasis>. Give jack a - password if security (even kids around who might pound on the - keyboard) is an issue. When it asks you if you want to invite - jack into other groups, type <userinput>wheel</userinput></para> - - <informalexample> - <screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput> - </screen> - </informalexample> - - <para>This will make it possible to log in as - <emphasis>jack</emphasis> and use the <command>su</command> - command to become root. Then you won't get scolded any more for - logging in as root.</para> - - <para>You can quit <command>adduser</command> any time by typing - <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>, - and at the end you'll have a chance to approve your new user or - simply type <keycap>n</keycap> for no. You might want to create - a second new user (jill?) so that when you edit jack's login - files, you'll have a hot spare in case something goes - wrong.</para> - - <para>Once you've done this, use <command>exit</command> to get - back to a login prompt and log in as <emphasis>jack</emphasis>. - In general, it's a good idea to do as much work as possible as - an ordinary user who doesn't have the power—and - risk—of root.</para> - - <para>If you already created a user and you want the user to be - able to <command>su</command> to root, you can log in as root - and edit the file <filename>/etc/group</filename>, adding jack - to the first line (the group wheel). But first you need to - practice <command>vi</command>, the text editor--or use the - simpler text editor, <command>ee</command>, installed on recent - version of FreeBSD.</para> - - <para>To delete a user, use the <command>rmuser</command> - command.</para> - </sect1> - - <sect1> - <title>Looking Around</title> - - <para>Logged in as an ordinary user, look around and try out some - commands that will access the sources of help and information - within FreeBSD.</para> - - <para>Here are some commands and what they do:</para> - - <variablelist> - <varlistentry> - <term><command>id</command></term> - - <listitem> - <para>Tells you who you are!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>pwd</command></term> - - <listitem> - <para>Shows you where you are—the current working - directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls</command></term> - - <listitem> - <para>Lists the files in the current directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls <option>-F</option></command></term> - - <listitem> - <para>Lists the files in the current directory with a - <literal>*</literal> after executables, a - <literal>/</literal> after directories, and an - <literal>@</literal> after symbolic links.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls <option>-l</option></command></term> - - <listitem> - <para>Lists the files in long format—size, date, - permissions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls <option>-a</option></command></term> - - <listitem> - <para>Lists hidden <quote>dot</quote> files with the others. - If you're root, the <quote>dot</quote> files show up - without the <option>-a</option> switch.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>cd</command></term> - - <listitem> - <para>Changes directories. <command>cd - <parameter>..</parameter></command> backs up one level; - note the space after <command>cd</command>. <command>cd - <parameter>/usr/local</parameter></command> goes there. - <command>cd <parameter>~</parameter></command> goes to - the home directory of the person logged in—e.g., - <filename>/usr/home/jack</filename>. Try <command>cd - <parameter>/cdrom</parameter></command>, and then - <command>ls</command>, to find out if your CDROM is - mounted and working.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>view - <replaceable>filename</replaceable></command></term> - - <listitem> - <para>Lets you look at a file (named - <replaceable>filename</replaceable>) without changing it. - Try <command>view - <parameter>/etc/fstab</parameter></command>. - <command>:q</command> to quit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>cat - <replaceable>filename</replaceable></command></term> - - <listitem> - <para>Displays <replaceable>filename</replaceable> on - screen. If it's too long and you can see only the end of - it, press <keycap>ScrollLock</keycap> and use the - <keycap>up-arrow</keycap> to move backward; you can use - <keycap>ScrollLock</keycap> with man pages too. Press - <keycap>ScrollLock</keycap> again to quit scrolling. You - might want to try <command>cat</command> on some of the - dot files in your home directory—<command>cat - <parameter>.cshrc</parameter></command>, <command>cat - <parameter>.login</parameter></command>, <command>cat - <parameter>.profile</parameter></command>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>You'll notice aliases in <filename>.cshrc</filename> for - some of the <command>ls</command> commands (they're very - convenient). You can create other aliases by editing - <filename>.cshrc</filename>. You can make these aliases - available to all users on the system by putting them in the - system-wide csh configuration file, - <filename>/etc/csh.cshrc</filename>.</para> - </sect1> - - <sect1> - <title>Getting Help and Information</title> - - <para>Here are some useful sources of help. - <replaceable>Text</replaceable> stands for something of your - choice that you type in—usually a command or - filename.</para> - - <variablelist> - <varlistentry> - <term><command>apropos - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Everything containing string - <replaceable>text</replaceable> in the <database>whatis - database</database>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>man - <replaceable>text</replaceable></command></term> - - <listitem> - <para>The man page for <replaceable>text</replaceable>. The - major source of documentation for Un*x systems. - <command>man <parameter>ls</parameter></command> will tell - you all the ways to use the <command>ls</command> command. - Press <keycap>Enter</keycap> to move through text, - <keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> - to go back a page, - <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo> - to go forward, <keycap>q</keycap> or - <keycombo><keycap>Ctrl</keycap><keycap>c</keycap></keycombo> - to quit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>which - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Tells you where in the user's path the command - <replaceable>text</replaceable> is found.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>locate - <replaceable>text</replaceable></command></term> - - <listitem> - <para>All the paths where the string - <replaceable>text</replaceable> is found.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>whatis - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Tells you what the command - <replaceable>text</replaceable> does and its man page. - Typing <command>whatis *</command> will tell you about all - the binaries in the current directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>whereis - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Finds the file <replaceable>text</replaceable>, giving - its full path.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>You might want to try using <command>whatis</command> on - some common useful commands like <command>cat</command>, - <command>more</command>, <command>grep</command>, - <command>mv</command>, <command>find</command>, - <command>tar</command>, <command>chmod</command>, - <command>chown</command>, <command>date</command>, and - <command>script</command>. <command>more</command> lets you - read a page at a time as it does in DOS, e.g., <command>ls -l | - more</command> or <command>more - <replaceable>filename</replaceable></command>. The - <literal>*</literal> works as a wildcard—e.g., <command>ls - w*</command> will show you files beginning with - <literal>w</literal>.</para> - - <para>Are some of these not working very well? Both - <command>locate</command> and <command>whatis</command> depend - on a database that's rebuilt weekly. If your machine isn't - going to be left on over the weekend (and running FreeBSD), you - might want to run the commands for daily, weekly, and monthly - maintenance now and then. Run them as root and give each one - time to finish before you start the next one, for now.</para> - - <informalexample> - <screen>&prompt.root; <userinput>periodic daily</userinput> -<lineannotation>output omitted</lineannotation> -&prompt.root; <userinput>periodic weekly</userinput> -<lineannotation>output omitted</lineannotation> -&prompt.root; <userinput>periodic monthly</userinput> -<lineannotation>output omitted</lineannotation> - </screen> - </informalexample> - - <para>If you get tired of waiting, press - <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to - get another <firstterm>virtual console</firstterm>, and log in - again. After all, it's a multi-user, multi-tasking system. - Nevertheless these commands will probably flash messages on your - screen while they're running; you can type - <command>clear</command> at the prompt to clear the screen. - Once they've run, you might want to look at - <filename>/var/mail/root</filename> and - <filename>/var/log/messages</filename>.</para> - - <para>Running such commands is part of system - administration—and as a single user of a Unix system, - you're your own system administrator. Virtually everything you - need to be root to do is system administration. Such - responsibilities aren't covered very well even in those big fat - books on Unix, which seem to devote a lot of space to pulling - down menus in windows managers. You might want to get one of - the two leading books on systems administration, either Evi - Nemeth et.al.'s <citetitle>UNIX System Administration - Handbook</citetitle> (Prentice-Hall, 1995, ISBN - 0-13-15051-7)—the second edition with the red cover; or - Æleen Frisch's <citetitle>Essential System - Administration</citetitle> (O'Reilly & Associates, 1993, - ISBN 0-937175-80-3). I used Nemeth.</para> - </sect1> - - <sect1> - <title>Editing Text</title> - - <para>To configure your system, you need to edit text files. Most - of them will be in the <filename>/etc</filename> directory; and - you'll need to <command>su</command> to root to be able to - change them. You can use the easy <command>ee</command>, but in - the long run the text editor <command>vi</command> is worth - learning. There's an excellent tutorial on vi in - <filename>/usr/src/contrib/nvi/docs/tutorial</filename> if you - have that installed; otherwise you can get it by ftp to - <hostid>ftp.cdrom.com</hostid> in the directory - FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial.</para> - - <para>Before you edit a file, you should probably back it up. - Suppose you want to edit <filename>/etc/rc.conf</filename>. You - could just use <command>cd /etc</command> to get to the - <filename>/etc</filename> directory and do:</para> - - <informalexample> - <screen>&prompt.root; <userinput>cp rc.conf rc.conf.orig</userinput> - </screen> - </informalexample> - - <para>This would copy <filename>rc.conf</filename> to - <filename>rc.conf.orig</filename>, and you could later copy - <filename>rc.conf.orig</filename> to - <filename>rc.conf</filename> to recover the original. But even - better would be moving (renaming) and then copying back:</para> - - <informalexample> - <screen>&prompt.root; <userinput>mv rc.conf rc.conf.orig</userinput> -&prompt.root; <userinput>cp rc.conf.orig rc.conf</userinput> - </screen> - </informalexample> - - <para>because the <command>mv</command> command preserves the - original date and owner of the file. You can now edit - <filename>rc.conf</filename>. If you want the original back, - you'd then <userinput>mv rc.conf rc.conf.myedit</userinput> - (assuming you want to preserve your edited version) and - then</para> - - <informalexample> - <screen>&prompt.root; <userinput>mv rc.conf.orig rc.conf</userinput></screen> - </informalexample> - - <para>to put things back the way they were.</para> - - <para>To edit a file, type</para> - - <informalexample> - <screen>&prompt.root; <userinput>vi <replaceable>filename</replaceable></userinput> - </screen> - </informalexample> - - <para>Move through the text with the arrow keys. - <keycap>Esc</keycap> (the escape key) puts <command>vi</command> - in command mode. Here are some commands:</para> - - <variablelist> - <varlistentry> - <term><command>x</command></term> - - <listitem> - <para>delete letter the cursor is on</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>dd</command></term> - - <listitem> - <para>delete the entire line (even if it wraps on the - screen)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>i</command></term> - - <listitem> - <para>insert text at the cursor</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>a</command></term> - - <listitem> - <para>insert text after the cursor</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Once you type <command>i</command> or <command>a</command>, - you can enter text. <command>Esc</command> puts you back in - command mode where you can type</para> - - <variablelist> - <varlistentry> - <term><command>:w</command></term> - - <listitem> - <para>to write your changes to disk and continue - editing</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>:wq</command></term> - - <listitem> - <para>to write and quit</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>:q!</command></term> - - <listitem> - <para>to quit without saving changes</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>/<replaceable>text</replaceable></command></term> - - <listitem> - <para>to move the cursor to <replaceable>text</replaceable>; - <command>/<keycap>Enter</keycap></command> (the enter key) - to find the next instance of - <replaceable>text</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>G</command></term> - - <listitem> - <para>to go to the end of the file</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command><replaceable>n</replaceable>G</command></term> - - <listitem> - <para>to go to line <replaceable>n</replaceable> in the - file, where <replaceable>n</replaceable> is a - number</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo></term> - - <listitem> - <para>to redraw the screen</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> and - <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo></term> - - <listitem> - <para>go back and forward a screen, as they do with - <command>more</command> and <command>view</command>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Practice with <command>vi</command> in your home directory by - creating a new file with <command>vi <replaceable>filename</replaceable></command> - and adding and deleting text, saving the file, and calling it up - again. <command>vi</command> delivers some surprises because it's - really quite complex, and sometimes you'll inadvertently issue a - command that will do something you don't expect. (Some people - actually like <command>vi</command>—it's more powerful than DOS - EDIT—find out about the <command>:r</command> command.) Use - <keycap>Esc</keycap> one or more times to be sure you're in command - mode and proceed from there when it gives you trouble, save - often with <command>:w</command>, and use <command>:q!</command> to get out - and start over (from your last <command>:w</command>) when you need - to.</para> - - <para>Now you can <command>cd</command> to <filename>/etc</filename>, - <command>su</command> to root, use <command>vi</command> to edit the file - <filename>/etc/group</filename>, and add a user to wheel so the - user has root privileges. Just add a comma and the user's login - name to the end of the first line in the file, press - <keycap>Esc</keycap>, and use <command>:wq</command> to write the file to - disk and quit. Instantly effective. (You didn't put a space - after the comma, did you?)</para> - </sect1> - - <sect1> - <title>Printing Files from DOS</title> - - <para>At this point you probably don't have the printer working, - so here's a way to create a file from a man page, move it to a - floppy, and then print it from DOS. Suppose you want to read - carefully about changing permissions on files (pretty - important). You can use the command man chmod to read about it. - The command</para> - - <informalexample> - <screen>&prompt.user; <userinput>man chmod | col -b > chmod.txt</> - </screen> - </informalexample> - - <para>will remove formatting codes and send the man page to the - <filename>chmod.txt</filename> file instead of showing it on - your screen. Now put a dos-formatted diskette in your floppy - drive a, <command>su</command> to root, and type</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/mount -t msdos /dev/fd0 /mnt</> - </screen> - </informalexample> - - <para>to mount the floppy drive on - <filename>/mnt</filename>.</para> - - <para>Now (you no longer need to be root, and you can type - <command>exit</command> to get back to being user jack) you can go to - the directory where you created chmod.txt and copy the file to - the floppy with:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cp chmod.txt /mnt</> - </screen> - </informalexample> - - <para>and use <command>ls /mnt</command> to get a directory - listing of <filename>/mnt</filename>, which should show the file - <filename>chmod.txt</filename>.</para> - - <para>You might especially want to make a file from - <filename>/sbin/dmesg</filename> by typing</para> - - <informalexample> - <screen>&prompt.user; <userinput>/sbin/dmesg > dmesg.txt</> - </screen> - </informalexample> - - <para>and copying <filename>dmesg.txt</filename> to the floppy. - <command>/sbin/dmesg</command> is the boot log record, and it's - useful to understand it because it shows what FreeBSD found when - it booted up. If you ask questions on - <email>freebsd-questions@FreeBSD.org</email> or on a USENET - group—like <quote>FreeBSD isn't finding my tape drive, - what do I do?</quote>—people will want to know what - <command>dmesg</command> has to say.</para> - - <para>You can now dismount the floppy drive (as root) to get the - disk out with</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/umount /mnt</> - </screen> - </informalexample> - - <para>and reboot to go to DOS. Copy these files to a DOS - directory, call them up with DOS EDIT, Windows Notepad or - Wordpad, or a word processor, make a minor change so the file - has to be saved, and print as you normally would from DOS or - Windows. Hope it works! man pages come out best if printed - with the dos <command>print</command> command. (Copying files from - FreeBSD to a mounted dos partition is in some cases still a - little risky.)</para> - - <para>Getting the printer printing from FreeBSD involves creating - an appropriate entry in <filename>/etc/printcap</filename> and - creating a matching spool directory in - <filename>/var/spool/output</filename>. If your printer is on - <hardware>lpt0</hardware> (what dos calls <hardware>LPT1</hardware>), you may - only need to go to <filename>/var/spool/output</filename> and - (as root) create the directory <filename>lpd</filename> by typing: - <command> mkdir lpd</command>, if it doesn't already exist. - Then the printer should respond if it's turned on when the - system is booted, and lp or lpr should send a file to the - printer. Whether or not the file actually prints depends on - configuring it, which is covered in the <ulink - URL="../../handbook/handbook.html">FreeBSD handbook.</ulink></para> - </sect1> - - <sect1> - <title>Other Useful Commands</title> - - <variablelist> - <varlistentry> - <term><command>df</command></term> - - <listitem> - <para>shows file space and mounted systems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ps aux</command></term> - - <listitem> - <para>shows processes running. <command>ps ax</command> is a - narrower form.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>rm <replaceable>filename</replaceable></command></term> - - <listitem> - <para>remove <replaceable>filename</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>rm -R <replaceable>dir</replaceable></command></term> - - <listitem> - <para>removes a directory <replaceable>dir</replaceable> and all - subdirectories—careful!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls -R</command></term> - - <listitem> - <para>lists files in the current directory and all - subdirectories; I used a variant, <command>ls -AFR > - where.txt</command>, to get a list of all the files in - <filename>/</filename> and (separately) - <filename>/usr</filename> before I found better ways to - find files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>passwd</command></term> - - <listitem> - <para>to change user's password (or root's password)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>man hier</command></term> - - <listitem> - <para>man page on the Unix file system</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Use <command>find</command> to locate filename in - <filename>/usr</filename> or any of its subdirectories - with</para> - - <informalexample> - <screen>&prompt.user; <userinput>find /usr -name "<replaceable>filename</>"</> - </screen> - </informalexample> - - <para>You can use <literal>*</literal> as a wildcard in - <parameter>"<replaceable>filename</replaceable>"</parameter> (which should be in - quotes). If you tell find to search in <filename>/</filename> - instead of <filename>/usr</filename> it will look for the - file(s) on all mounted file systems, including the CDROM and the - dos partition.</para> - - <para>An excellent book that explains Unix commands and utilities - is Abrahams & Larson, <citetitle>Unix for the - Impatient</citetitle> (2nd ed., Addison-Wesley, 1996). - There's also a lot of Unix information on the Internet. Try the - <ulink URL="http://www.geek-girl.com/unix.html">Unix Reference - Desk</ulink>.</para> - </sect1> - - <sect1> - <title>Next Steps</title> - - <para>You should now have the tools you need to get around and - edit files, so you can get everything up and running. There is - a great deal of information in the FreeBSD handbook (which is - probably on your hard drive) and <ulink - URL="http://www.FreeBSD.org/">FreeBSD's web site</ulink>. A - wide variety of packages and ports are on the CDROM as well - as the web site. The handbook tells you more about how to use - them (get the package if it exists, with <command>pkg_add - /cdrom/packages/All/<replaceable>packagename</replaceable></command>, where - <replaceable>packagename</replaceable> is the filename of the - package). The cdrom has lists of the packages and ports with - brief descriptions in <filename>cdrom/packages/index</filename>, - <filename>cdrom/packages/index.txt</filename>, and - <filename>cdrom/ports/index</filename>, with fuller descriptions - in <filename>/cdrom/ports/*/*/pkg/DESCR</filename>, where the - <literal>*</literal>s represent subdirectories of kinds of - programs and program names respectively.</para> - - <para>If you find the handbook too sophisticated (what with - <command>lndir</command> and all) on installing ports from the cdrom, - here's what usually works:</para> - - <para>Find the port you want, say <command>kermit</command>. There will - be a directory for it on the cdrom. Copy the subdirectory to - <filename>/usr/local</filename> (a good place for software you - add that should be available to all users) with:</para> - - <informalexample> - <screen>&prompt.root; <userinput>cp -R /cdrom/ports/comm/kermit /usr/local</> - </screen> - </informalexample> - - <para>This should result in a - <filename>/usr/local/kermit</filename> subdirectory that has all - the files that the <command>kermit</command> subdirectory on the - CDROM has.</para> - - <para>Next, create the directory - <filename>/usr/ports/distfiles</filename> if it doesn't already - exist using <command>mkdir</command>. Now check check - <filename>/cdrom/ports/distfiles</filename> for a file with a - name that indicates it's the port you want. Copy that file to - <filename>/usr/ports/distfiles</filename>; in recent versions - you can skip this step, as FreeBSD will do it for you. In the - case of <command>kermit</command>, there is no distfile.</para> - - <para>Then <command>cd</command> to the subdirectory of - <filename>/usr/local/kermit</filename> that has the file - <filename>Makefile</filename>. Type</para> - - <informalexample> - <screen>&prompt.root; <userinput>make all install</> - </screen> - </informalexample> - - <para>During this process the port will ftp to get any compressed - files it needs that it didn't find on the cdrom or in - <filename>/usr/ports/distfiles</filename>. If you don't have - your network running yet and there was no file for the port in - <filename>/cdrom/ports/distfiles</filename>, you will have to - get the distfile using another machine and copy it to - <filename>/usr/ports/distfiles</filename> from a floppy or your - dos partition. Read <filename>Makefile</filename> (with <command>cat</command> - or <command>more</command> or <command>view</command>) to find out where to go - (the master distribution site) to get the file and what its name - is. Its name will be truncated when downloaded to DOS, and - after you get it into <filename>/usr/ports/distfiles</filename> - you'll have to rename it (with the <command>mv</command> command) to - its original name so it can be found. (Use binary file - transfers!) Then go back to - <filename>/usr/local/kermit</filename>, find the directory with - <filename>Makefile</filename>, and type <command>make all - install</command>.</para> - - <para>The other thing that happens when installing ports or - packages is that some other program is needed. If the - installation stops with a message <errorname>can't find - unzip</errorname> or whatever, you might need to install the - package or port for unzip before you continue.</para> - - <para>Once it's installed type <command>rehash</command> to make FreeBSD - reread the files in the path so it knows what's there. (If you - get a lot of <errorname>path not found</errorname> messages when you use - <command>whereis</command> or which, you might want to make additions - to the list of directories in the path statement in - <filename>.cshrc</filename> in your home directory. The path - statement in Unix does the same kind of work it does in DOS, - except the current directory is not (by default) in the path for - security reasons; if the command you want is in the directory - you're in, you need to type <filename>./</filename> before the - command to make it work; no space after the slash.)</para> - - <para>You might want to get the most recent version of Netscape - from their <ulink URL="ftp://ftp.netscape.com">ftp site</ulink>. - (Netscape requires the X Window System.) There's now a FreeBSD - version, so look around carefully. Just use <command>gunzip - <replaceable>filename</replaceable></command> and <command>tar xvf - <replaceable>filename</replaceable></command> on it, move the binary to - <filename>/usr/local/bin</filename> or some other place binaries - are kept, <command>rehash</command>, and then put the following lines - in <filename>.cshrc</filename> in each user's home directory or - (easier) in <filename>/etc/csh.cshrc</filename>, the - system-wide csh start-up file:</para> - - <informalexample> - <programlisting>setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB -setenv XNLSPATH /usr/X11R6/lib/X11/nls</programlisting> - </informalexample> - - <para>This assumes that the file <filename>XKeysymDB</filename> and the - directory <filename>nls</filename> are in - <filename>/usr/X11R6/lib/X11</filename>; if they're not, find - them and put them there.</para> - - <para>If you originally got Netscape as a port using the CDROM (or - ftp), don't replace <filename>/usr/local/bin/netscape</filename> - with the new netscape binary; this is just a shell script that - sets up the environment variables for you. Instead rename the - new binary to <filename>netscape.bin</filename> and replace the - old binary, which is - <filename>/usr/local/netscape/netscape</filename>.</para> - </sect1> - - <sect1> - <title>Your Working Environment</title> - - <para>Your shell is the most important part of your working - environment. In DOS, the usual shell is command.com. The shell - is what interprets the commands you type on the command line, - and thus communicates with the rest of the operating system. - You can also write shell scripts, which are like DOS batch - files: a series of commands to be run without your - intervention.</para> - - <para>Two shells come installed with FreeBSD: csh and sh. csh is - good for command-line work, but scripts should be written with - sh (or bash). You can find out what shell you have by typing - <command>echo $SHELL</command>.</para> - - <para>The csh shell is okay, but tcsh does everything csh does and - more. It It allows you to recall commands with the arrow keys - and edit them. It has tab-key completion of filenames (csh uses - the escape key), and it lets you switch to the directory you - were last in with <command>cd -</command>. It's also much - easier to alter your prompt with tcsh. It makes life a lot - easier.</para> - - <para>Here are the three steps for installing a new shell:</para> - - <procedure> - <step> - <para>Install the shell as a port or a package, just as you - would any other port or package. Use - <command>rehash</command> and <command>which tcsh</command> - (assuming you're installing tcsh) to make sure it got - installed.</para> - </step> - - <step> - <para>As root, edit <filename>/etc/shells</filename>, adding a - line in the file for the new shell, in this case - /usr/local/bin/tcsh, and save the file. (Some ports may do - this for you.)</para> - </step> - - <step> - <para>Use the <command>chsh</command> command to change your - shell to tcsh permanently, or type <command>tcsh</command> - at the prompt to change your shell without logging in - again.</para> - </step> - </procedure> - - <note> - <para>It can be dangerous to change root's shell to something - other than sh or csh on early versions of FreeBSD and many - other versions of Unix; you may not have a working shell when - the system puts you into single user mode. The solution is to - use <command>su -m</command> to become root, which will give - you the tcsh as root, because the shell is part of the - environment. You can make this permanent by adding it to your - <filename>.tcshrc</filename> file as an alias with - <programlisting>alias su su -m.</programlisting></para> - </note> - - <para>When tcsh starts up, it will read the - <filename>/etc/csh.cshrc</filename> and - <filename>/etc/csh.login</filename> files, as does csh. It will - also read the <filename>.login</filename> file in your home - directory and the <filename>.cshrc</filename> file as well, - unless you provide a <filename>.tcshrc</filename> file. This - you can do by simply copying <filename>.cshrc</filename> to - <filename>.tcshrc</filename>.</para> - - <para>Now that you've installed tcsh, you can adjust your prompt. - You can find the details in the manual page for tcsh, but here - is a line to put in your <filename>.tcshrc</filename> that will - tell you how many commands you have typed, what time it is, and - what directory you are in. It also produces a - <literal>></literal> if you're an ordinary user and a - <literal>#</literal> if you're root, but tsch will do that in - any case:</para> - - <para>set prompt = "%h %t %~ %# "</para> - - <para>This should go in the same place as the existing set prompt - line if there is one, or under "if($?prompt) then" if not. - Comment out the old line; you can always switch back to it if - you prefer it. Don't forget the spaces and quotes. You can get - the <filename>.tcshrc</filename> reread by typing - <command>source .tcshrc</command>.</para> - - <para>You can get a listing of other environmental variables that - have been set by typing <command>env</command> at the prompt. - The result will show you your default editor, pager, and - terminal type, among possibly many others. A useful command if - you log in from a remote location and can't run a program - because the terminal isn't capable is <command>setenv TERM - vt100</command>.</para> - </sect1> - - <sect1> - <title>Other</title> - - <para>As root, you can dismount the CDROM with - <command>/sbin/umount /cdrom</command>, take it out of the drive, - insert another one, and mount it with - <command>/sbin/mount_cd9660 /dev/cd0a /cdrom</command> assuming - <hardware>cd0a</hardware> is the device name for your CDROM drive. The - most recent versions of FreeBSD let you mount the cdrom with - just <command>/sbin/mount /cdrom</command>.</para> - - <para>Using the live file system—the second of FreeBSD's - CDROM disks—is useful if you've got limited space. What - is on the live file system varies from release to release. You - might try playing games from the cdrom. This involves using - <command>lndir</command>, which gets installed with the X Window - System, to tell the program(s) where to find the necessary - files, because they're in the <filename>/cdrom</filename> file - system instead of in <filename>/usr</filename> and its - subdirectories, which is where they're expected to be. Read - <command>man lndir</command>.</para> - </sect1> - - <sect1> - <title>Comments Welcome</title> - - <para>If you use this guide I'd be interested in knowing where it - was unclear and what was left out that you think should be - included, and if it was helpful. My thanks to Eugene W. Stark, - professor of computer science at SUNY-Stony Brook, and John - Fieber for helpful comments.</para> - - <para>Annelise Anderson, - <email>andrsn@andrsn.stanford.edu</email></para> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/articles/programming-tools/Makefile b/en_US.ISO_8859-1/articles/programming-tools/Makefile deleted file mode 100644 index 886e21cc9d..0000000000 --- a/en_US.ISO_8859-1/articles/programming-tools/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD$ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/programming-tools/article.sgml b/en_US.ISO_8859-1/articles/programming-tools/article.sgml deleted file mode 100644 index eabcea2da8..0000000000 --- a/en_US.ISO_8859-1/articles/programming-tools/article.sgml +++ /dev/null @@ -1,2256 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/programming-tools/article.sgml,v 1.14 2001/04/09 00:33:41 dd Exp $ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"> -<article> - <articleinfo> - <title>A User's Guide to FreeBSD Programming Tools</title> - - <authorgroup> - <author> - <firstname>James</firstname> - - <surname>Raynard</surname> - - <affiliation> - <address> - <email>jraynard@FreeBSD.org</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>August 17, 1997</pubdate> - - <copyright> - <year>1997</year> - <holder>James Raynard</holder> - </copyright> - - <abstract> - <para>This document is an introduction to using some of the - programming tools supplied with FreeBSD, although much of it - will be applicable to many other versions of Unix. It does - <emphasis>not</emphasis> attempt to describe coding in any - detail. Most of the document assumes little or no previous - programming knowledge, although it is hoped that most - programmers will find something of value in it</para> - </abstract> - </articleinfo> - - <sect1> - <title>Introduction<anchor id=foo></title> - - <para>FreeBSD offers an excellent development environment. - Compilers for C, C++, and Fortran and an assembler come with the - basic system, not to mention a Perl interpreter and classic Unix - tools such as <command>sed</command> and <command>awk</command>. If that is - not enough, there are many more compilers and interpreters in - the Ports collection. FreeBSD is very compatible with standards - such as <acronym>POSIX</acronym> and <acronym>ANSI</acronym> C, as well with - its own BSD heritage, so it is possible to write applications - that will compile and run with little or no modification on a - wide range of platforms.</para> - - <para>However, all this power can be rather overwhelming at first - if you've never written programs on a Unix platform before. - This document aims to help you get up and running, without - getting too deeply into more advanced topics. The intention is - that this document should give you enough of the basics to be - able to make some sense of the documentation.</para> - - <para>Most of the document requires little or no knowledge of - programming, although it does assume a basic competence with - using Unix and a willingness to learn!</para> - </sect1> - - <sect1> - <title>Introduction to Programming</title> - - <para>A program is a set of instructions that tell the computer to - do various things; sometimes the instruction it has to perform - depends on what happened when it performed a previous - instruction. This section gives an overview of the two main - ways in which you can give these instructions, or - <quote>commands</quote> as they are usually called. One way - uses an <firstterm>interpreter</firstterm>, the other a - <firstterm>compiler</firstterm>. As human languages are too difficult for - a computer to understand in an unambiguous way, commands are - usually written in one or other languages specially designed for - the purpose.</para> - - <sect2> - <title>Interpreters</title> - - <para>With an interpreter, the language comes as an environment, - where you type in commands at a prompt and the environment - executes them for you. For more complicated programs, you can - type the commands into a file and get the interpreter to load - the file and execute the commands in it. If anything goes - wrong, many interpreters will drop you into a debugger to help - you track down the problem.</para> - - <para>The advantage of this is that you can see the results of - your commands immediately, and mistakes can be corrected - readily. The biggest disadvantage comes when you want to - share your programs with someone. They must have the same - interpreter, or you must have some way of giving it to them, - and they need to understand how to use it. Also users may not - appreciate being thrown into a debugger if they press the - wrong key! From a performance point of view, interpreters can - use up a lot of memory, and generally do not generate code as - efficiently as compilers.</para> - - <para>In my opinion, interpreted languages are the best way to - start if you have not done any programming before. This kind - of environment is typically found with languages like Lisp, - Smalltalk, Perl and Basic. It could also be argued that the - Unix shell (<command>sh</command>, <command>csh</command>) is itself an - interpreter, and many people do in fact write shell - <quote>scripts</quote> to help with various - <quote>housekeeping</quote> tasks on their machine. Indeed, part - of the original Unix philosophy was to provide lots of small - utility programs that could be linked together in shell - scripts to perform useful tasks.</para> - </sect2> - - <sect2> - <title>Interpreters available with FreeBSD</title> - - <para>Here is a list of interpreters that are available as - <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/">FreeBSD - packages</ulink>, with a brief discussion of some of the - more popular interpreted languages.</para> - - <para>To get one of these packages, all you need to do is to - click on the hotlink for the package, then run</para> - - <screen>&prompt.root; <userinput>pkg_add <replaceable>package name</></userinput> - </screen> - - <para>as root. Obviously, you will need to have a fully - functional FreeBSD 2.1.0 or later system for the package to - work!</para> - - <variablelist> - <varlistentry> - <term><acronym>BASIC</acronym></term> - - <listitem> - <para>Short for Beginner's All-purpose Symbolic - Instruction Code. Developed in the 1950s for teaching - University students to program and provided with every - self-respecting personal computer in the 1980s, - <acronym>BASIC</acronym> has been the first programming - language for many programmers. It's also the foundation - for Visual Basic.</para> - - <para>The <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/bwbasic-2.10.tgz">Bywater - Basic Interpreter</ulink> and the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/pbasic-2.0.tgz">Phil - Cockroft's Basic Interpreter</ulink> (formerly Rabbit - Basic) are available as FreeBSD <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/">FreeBSD - packages</ulink></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Lisp</term> - - <listitem> - <para>A language that was developed in the late 1950s as - an alternative to the <quote>number-crunching</quote> - languages that were popular at the time. Instead of - being based on numbers, Lisp is based on lists; in fact - the name is short for <quote>List Processing</quote>. - Very popular in AI (Artificial Intelligence) - circles.</para> - - <para>Lisp is an extremely powerful and sophisticated - language, but can be rather large and unwieldy.</para> - - <para>FreeBSD has <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/gcl-2.0.tgz">GNU - Common Lisp</ulink> available as a package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Perl</term> - - <listitem> - <para>Very popular with system administrators for writing - scripts; also often used on World Wide Web servers for - writing <acronym>CGI</acronym> scripts.</para> - - <para>The latest version (version 5) comes with FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Scheme</term> - - <listitem> - <para>A dialect of Lisp that is rather more compact and - cleaner than Common Lisp. Popular in Universities as it - is simple enough to teach to undergraduates as a first - language, while it has a high enough level of - abstraction to be used in research work.</para> - - <para>FreeBSD has packages of the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/elk-3.0.tgz">Elk - Scheme Interpreter</ulink>, the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/mit-scheme-7.3.tgz">MIT - Scheme Interpreter</ulink> and the <ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/scm-4e1.tgz">SCM - Scheme Interpreter</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Icon</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/icon-9.0.tgz">The - Icon Programming Language</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Logo</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/ucblogo-3.3.tgz">Brian - Harvey's LOGO Interpreter</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Python</term> - - <listitem> - <para><ulink - URL="ftp://ftp.FreeBSD.org:pub/FreeBSD/packages/lang/python-1.2">The - Python Object-Oriented Programming - Language</ulink></para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Compilers</title> - - <para>Compilers are rather different. First of all, you write - your code in a file (or files) using an editor. You then run - the compiler and see if it accepts your program. If it did - not compile, grit your teeth and go back to the editor; if it - did compile and gave you a program, you can run it either at a - shell command prompt or in a debugger to see if it works - properly. - - <footnote> - <para>If you run it in the shell, you may get a core - dump.</para> - </footnote></para> - - <para>Obviously, this is not quite as direct as using an - interpreter. However it allows you to do a lot of things - which are very difficult or even impossible with an - interpreter, such as writing code which interacts closely with - the operating system—or even writing your own operating - system! It's also useful if you need to write very efficient - code, as the compiler can take its time and optimise the code, - which would not be acceptable in an interpreter. And - distributing a program written for a compiler is usually more - straightforward than one written for an interpreter—you - can just give them a copy of the executable, assuming they - have the same operating system as you.</para> - - <para>Compiled languages include Pascal, C and C++. C and C++ - are rather unforgiving languages, and best suited to more - experienced programmers; Pascal, on the other hand, was - designed as an educational language, and is quite a good - language to start with. Unfortunately, FreeBSD doesn't have - any Pascal support, except for a Pascal-to-C converter in the - ports.</para> - - <para>As the edit-compile-run-debug cycle is rather tedious when - using separate programs, many commercial compiler makers have - produced Integrated Development Environments - (<acronym>IDE</acronym>s for short). FreeBSD does not have an - <acronym>IDE</acronym> as such; however it is possible to use Emacs - for this purpose. This is discussed in <xref - linkend="emacs">.</para> - </sect2> - </sect1> - - <sect1> - <title>Compiling with <command>cc</command></title> - - <para>This section deals only with the GNU compiler for C and C++, - since that comes with the base FreeBSD system. It can be - invoked by either <command>cc</command> or <command>gcc</command>. The - details of producing a program with an interpreter vary - considerably between interpreters, and are usually well covered - in the documentation and on-line help for the - interpreter.</para> - - <para>Once you've written your masterpiece, the next step is to - convert it into something that will (hopefully!) run on FreeBSD. - This usually involves several steps, each of which is done by a - separate program.</para> - - <procedure> - <step> - <para>Pre-process your source code to remove comments and do - other tricks like expanding macros in C.</para> - </step> - - <step> - <para>Check the syntax of your code to see if you have obeyed - the rules of the language. If you have not, it will - complain!</para> - </step> - - <step> - <para>Convert the source code into assembly - language—this is very close to machine code, but still - understandable by humans. Allegedly. - - <footnote> - <para>To be strictly accurate, <command>cc</command> converts the - source code into its own, machine-independent - <firstterm>p-code</firstterm> instead of assembly language at - this stage.</para> - </footnote></para> - </step> - - <step> - <para>Convert the assembly language into machine - code—yep, we are talking bits and bytes, ones and - zeros here.</para> - </step> - - <step> - <para>Check that you have used things like functions and - global variables in a consistent way. For example, if you - have called a non-existent function, it will - complain.</para> - </step> - - <step> - <para>If you are trying to produce an executable from several - source code files, work out how to fit them all - together.</para> - </step> - - <step> - <para>Work out how to produce something that the system's - run-time loader will be able to load into memory and - run.</para> - </step> - - <step> - <para>Finally, write the executable on the file system.</para> - </step> - </procedure> - - <para>The word <firstterm>compiling</firstterm> is often used to refer to - just steps 1 to 4—the others are referred to as - <firstterm>linking</firstterm>. Sometimes step 1 is referred to as - <firstterm>pre-processing</firstterm> and steps 3-4 as - <firstterm>assembling</firstterm>.</para> - - <para>Fortunately, almost all this detail is hidden from you, as - <command>cc</command> is a front end that manages calling all these - programs with the right arguments for you; simply typing</para> - - <screen>&prompt.user; <userinput>cc foobar.c</> - </screen> - - <para>will cause <filename>foobar.c</filename> to be compiled by all the - steps above. If you have more than one file to compile, just do - something like</para> - - <screen>&prompt.user; <userinput>cc foo.c bar.c</> - </screen> - - <para>Note that the syntax checking is just that—checking - the syntax. It will not check for any logical mistakes you may - have made, like putting the program into an infinite loop, or - using a bubble sort when you meant to use a binary - sort. - - <footnote> - <para>In case you didn't know, a binary sort is an efficient - way of sorting things into order and a bubble sort - isn't.</para> - </footnote></para> - - <para>There are lots and lots of options for <command>cc</command>, which - are all in the man page. Here are a few of the most important - ones, with examples of how to use them.</para> - - <variablelist> - <varlistentry> - <term><option>-o <replaceable>filename</replaceable></option></term> - - <listitem> - <para>The output name of the file. If you do not use this - option, <command>cc</command> will produce an executable called - <filename>a.out</filename>. - - <footnote> - <para>The reasons for this are buried in the mists of - history.</para> - </footnote></para> - - <informalexample> - <screen>&prompt.user; <userinput>cc foobar.c</> <lineannotation>executable is <filename>a.out</></> -&prompt.user; <userinput>cc -o foobar foobar.c</> <lineannotation>executable is <filename>foobar</></> - </screen> - </informalexample> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - - <listitem> - <para>Just compile the file, do not link it. Useful for toy - programs where you just want to check the syntax, or if - you are using a <filename>Makefile</filename>.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -c foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an <firstterm>object file</firstterm> (not an - executable) called <filename>foobar.o</filename>. This - can be linked together with other object files into an - executable.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-g</option></term> - - <listitem> - <para>Create a debug version of the executable. This makes - the compiler put information into the executable about - which line of which source file corresponds to which - function call. A debugger can use this information to show - the source code as you step through the program, which is - <emphasis>very</emphasis> useful; the disadvantage is that - all this extra information makes the program much bigger. - Normally, you compile with <option>-g</option> while you - are developing a program and then compile a <quote>release - version</quote> without <option>-g</option> when you're - satisfied it works properly.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -g foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce a debug version of the - program. - - <footnote> - <para>Note, we didn't use the <option>-o</option> flag - to specify the executable name, so we will get an - executable called <filename>a.out</filename>. - Producing a debug version called - <filename>foobar</filename> is left as an exercise for - the reader!</para> - </footnote></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-O</option></term> - - <listitem> - <para>Create an optimised version of the executable. The - compiler performs various clever tricks to try and produce - an executable that runs faster than normal. You can add a - number after the <option>-O</option> to specify a higher - level of optimisation, but this often exposes bugs in the - compiler's optimiser. For instance, the version of - <command>cc</command> that comes with the 2.1.0 release of - FreeBSD is known to produce bad code with the - <option>-O2</option> option in some circumstances.</para> - - <para>Optimisation is usually only turned on when compiling - a release version.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an optimised version of - <filename>foobar</filename>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The following three flags will force <command>cc</command> - to check that your code complies to the relevant international - standard, often referred to as the <acronym>ANSI</acronym> - standard, though strictly speaking it is an - <acronym>ISO</acronym> standard.</para> - - <variablelist> - <varlistentry> - <term><option>-Wall</option></term> - - <listitem> - <para>Enable all the warnings which the authors of - <command>cc</command> believe are worthwhile. Despite the - name, it will not enable all the warnings - <command>cc</command> is capable of.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-ansi</option></term> - - <listitem> - <para>Turn off most, but not all, of the - non-<acronym>ANSI</acronym> C features provided by - <command>cc</command>. Despite the name, it does not - guarantee strictly that your code will comply to the - standard.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-pedantic</option></term> - - <listitem> - <para>Turn off <emphasis>all</emphasis> - <command>cc</command>'s non-<acronym>ANSI</acronym> C - features.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Without these flags, <command>cc</command> will allow you to - use some of its non-standard extensions to the standard. Some - of these are very useful, but will not work with other - compilers—in fact, one of the main aims of the standard is - to allow people to write code that will work with any compiler - on any system. This is known as <firstterm>portable - code</firstterm>.</para> - - <para>Generally, you should try to make your code as portable as - possible, as otherwise you may have to completely re-write the - program later to get it to work somewhere else—and who - knows what you may be using in a few years time?</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -Wall -ansi -pedantic -o foobar foobar.c</userinput> - </screen> - </informalexample> - - <para>This will produce an executable <filename>foobar</filename> - after checking <filename>foobar.c</filename> for standard - compliance.</para> - - <variablelist> - <varlistentry> - <term><option>-l<replaceable>library</replaceable></option></term> - - <listitem> - <para>Specify a function library to be used during when - linking.</para> - - <para>The most common example of this is when compiling a - program that uses some of the mathematical functions in C. - Unlike most other platforms, these are in a separate - library from the standard C one and you have to tell the - compiler to add it.</para> - - <para>The rule is that if the library is called - <filename>lib<replaceable>something</replaceable>.a</filename>, - you give <command>cc</command> the argument - <option>-l<replaceable>something</replaceable></option>. - For example, the math library is - <filename>libm.a</filename>, so you give - <command>cc</command> the argument <option>-lm</option>. - A common <quote>gotcha</quote> with the math library is - that it has to be the last library on the command - line.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput> - </screen> - </informalexample> - - <para>This will link the math library functions into - <filename>foobar</filename>.</para> - - <para>If you are compiling C++ code, you need to add - <option>-lg++</option>, or <option>-lstdc++</option> if - you are using FreeBSD 2.2 or later, to the command line - argument to link the C++ library functions. - Alternatively, you can run <command>c++</command> instead - of <command>cc</command>, which does this for you. - <command>c++</command> can also be invoked as - <command>g++</command> on FreeBSD.</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.cc -lg++</userinput> <lineannotation>For FreeBSD 2.1.6 and earlier</> -&prompt.user; <userinput>cc -o foobar foobar.cc -lstdc++</userinput> <lineannotation>For FreeBSD 2.2 and later</> -&prompt.user; <userinput>c++ -o foobar foobar.cc</userinput> - </screen> - </informalexample> - - <para>Each of these will both produce an executable - <filename>foobar</filename> from the C++ source file - <filename>foobar.cc</filename>. Note that, on Unix - systems, C++ source files traditionally end in - <filename>.C</filename>, <filename>.cxx</filename> or - <filename>.cc</filename>, rather than the - MS-DOS style - <filename>.cpp</filename> (which was already used for - something else). <command>gcc</command> used to rely on - this to work out what kind of compiler to use on the - source file; however, this restriction no longer applies, - so you may now call your C++ files - <filename>.cpp</filename> with impunity!</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2> - <title>Common <command>cc</command> Queries and Problems</title> - - <qandaset> - <qandaentry> - <question> - <para>I am trying to write a program which uses the - <function>sin()</function> function and I get an error - like this. What does it mean?</para> - - <informalexample> - <screen>/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment - </screen> - </informalexample> - </question> - - <answer> - <para>When using mathematical functions like - <function>sin()</function>, you have to tell - <command>cc</command> to link in the math library, like - so:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput> - </screen> - </informalexample> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>All right, I wrote this simple program to practice - using <option>-lm</option>. All it does is raise 2.1 to - the power of 6.</para> - - <informalexample> - <programlisting>#include <stdio.h> - -int main() { - float f; - - f = pow(2.1, 6); - printf("2.1 ^ 6 = %f\n", f); - return 0; -} - </programlisting> - </informalexample> - - <para>and I compiled it as:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc temp.c -lm</userinput> - </screen> - </informalexample> - - <para>like you said I should, but I get this when I run - it:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./a.out</userinput> -2.1 ^ 6 = 1023.000000 - </screen> - </informalexample> - - <para>This is <emphasis>not</emphasis> the right answer! - What is going on?</para> - </question> - - <answer> - <para>When the compiler sees you call a function, it - checks if it has already seen a prototype for it. If it - has not, it assumes the function returns an - <type>int</type>, which is definitely not what you want - here.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>So how do I fix this?</para> - </question> - - <answer> - <para>The prototypes for the mathematical functions are in - <filename>math.h</filename>. If you include this file, - the compiler will be able to find the prototype and it - will stop doing strange things to your - calculation!</para> - - <informalexample> - <programlisting>#include <math.h> -#include <stdio.h> - -int main() { -... - </programlisting> - </informalexample> - - <para>After recompiling it as you did before, run - it:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./a.out</userinput> -2.1 ^ 6 = 85.766121 - </screen> - </informalexample> - - <para>If you are using any of the mathematical functions, - <emphasis>always</emphasis> include - <filename>math.h</filename> and remember to link in the - math library.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I compiled a file called - <filename>foobar.c</filename> and I cannot find an - executable called <filename>foobar</filename>. Where's - it gone?</para> - </question> - - <answer> - <para>Remember, <command>cc</command> will call the - executable <filename>a.out</filename> unless you tell it - differently. Use the - <option>-o <replaceable>filename</replaceable></option> - option:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cc -o foobar foobar.c</userinput> - </screen> - </informalexample> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>OK, I have an executable called - <filename>foobar</filename>, I can see it when I run - <command>ls</command>, but when I type in - <command>foobar</command> at the command prompt it tells - me there is no such file. Why can it not find - it?</para> - </question> - - <answer> - <para>Unlike MS-DOS, Unix does not - look in the current directory when it is trying to find - out which executable you want it to run, unless you tell - it to. Either type <command>./foobar</command>, which - means <quote>run the file called - <filename>foobar</filename> in the current - directory</quote>, or change your <envar - >PATH</envar> environment - variable so that it looks something like</para> - - <informalexample> - <screen>bin:/usr/bin:/usr/local/bin:. - </screen> - </informalexample> - - <para>The dot at the end means <quote>look in the current - directory if it is not in any of the - others</quote>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I called my executable <filename>test</filename>, - but nothing happens when I run it. What is going - on?</para> - </question> - - <answer> - <para>Most Unix systems have a program called - <command>test</command> in <filename>/usr/bin</filename> - and the shell is picking that one up before it gets to - checking the current directory. Either type:</para> - - <informalexample> - <screen>&prompt.user; <userinput>./test</userinput> - </screen> - </informalexample> - - <para>or choose a better name for your program!</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I compiled my program and it seemed to run all right - at first, then there was an error and it said something - about <errorname>core dumped</errorname>. What does that - mean?</para> - </question> - - <answer> - <para>The name <firstterm>core dump</firstterm> dates back - to the very early days of Unix, when the machines used - core memory for storing data. Basically, if the program - failed under certain conditions, the system would write - the contents of core memory to disk in a file called - <filename>core</filename>, which the programmer could - then pore over to find out what went wrong.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Fascinating stuff, but what I am supposed to do - now?</para> - </question> - - <answer> - <para>Use <command>gdb</command> to analyse the core (see - <xref linkend="debugging">).</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>When my program dumped core, it said something about - a <errorname>segmentation fault</errorname>. What's - that?</para> - </question> - - <answer> - <para>This basically means that your program tried to - perform some sort of illegal operation on memory; Unix - is designed to protect the operating system and other - programs from rogue programs.</para> - - <para>Common causes for this are:</para> - - <itemizedlist> - <listitem> - <para>Trying to write to a <symbol>NULL</symbol> - pointer, eg</para> - - <programlisting>char *foo = NULL; -strcpy(foo, "bang!"); - </programlisting> - </listitem> - - <listitem> - <para>Using a pointer that hasn't been initialised, - eg</para> - - <programlisting>char *foo; -strcpy(foo, "bang!"); - </programlisting> - - <para>The pointer will have some random value that, - with luck, will point into an area of memory that - isn't available to your program and the kernel will - kill your program before it can do any damage. If - you're unlucky, it'll point somewhere inside your - own program and corrupt one of your data structures, - causing the program to fail mysteriously.</para> - </listitem> - - <listitem> - <para>Trying to access past the end of an array, - eg</para> - - <programlisting>int bar[20]; -bar[27] = 6; - </programlisting> - </listitem> - - <listitem> - <para>Trying to store something in read-only memory, - eg</para> - - <programlisting>char *foo = "My string"; -strcpy(foo, "bang!"); - </programlisting> - - <para>Unix compilers often put string literals like - <literal>"My string"</literal> into read-only areas - of memory.</para> - </listitem> - - <listitem> - <para>Doing naughty things with - <function>malloc()</function> and - <function>free()</function>, eg</para> - - <programlisting>char bar[80]; -free(bar); - </programlisting> - - <para>or</para> - - <programlisting>char *foo = malloc(27); -free(foo); -free(foo); - </programlisting> - </listitem> - </itemizedlist> - - <para>Making one of these mistakes will not always lead to - an error, but they are always bad practice. Some - systems and compilers are more tolerant than others, - which is why programs that ran well on one system can - crash when you try them on an another.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Sometimes when I get a core dump it says - <errorname>bus error</errorname>. It says in my Unix - book that this means a hardware problem, but the - computer still seems to be working. Is this - true?</para> - </question> - - <answer> - <para>No, fortunately not (unless of course you really do - have a hardware problem…). This is usually - another way of saying that you accessed memory in a way - you shouldn't have.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>This dumping core business sounds as though it could - be quite useful, if I can make it happen when I want to. - Can I do this, or do I have to wait until there's an - error?</para> - </question> - - <answer> - <para>Yes, just go to another console or xterm, do</para> - - <screen>&prompt.user; <userinput>ps</userinput> - </screen> - - <para>to find out the process ID of your program, and - do</para> - - <screen>&prompt.user; <userinput>kill -ABRT <replaceable>pid</replaceable></userinput> - </screen> - - <para>where - <parameter><replaceable>pid</replaceable></parameter> is - the process ID you looked up.</para> - - <para>This is useful if your program has got stuck in an - infinite loop, for instance. If your program happens to - trap <symbol>SIGABRT</symbol>, there are several other - signals which have a similar effect.</para> - </answer> - </qandaentry> - </qandaset> - </sect2> - </sect1> - - <sect1> - <title>Make</title> - - <sect2> - <title>What is <command>make</command>?</title> - - <para>When you're working on a simple program with only one or - two source files, typing in</para> - - <screen>&prompt.user; <userinput>cc file1.c file2.c</userinput> - </screen> - - <para>is not too bad, but it quickly becomes very tedious when - there are several files—and it can take a while to - compile, too.</para> - - <para>One way to get around this is to use object files and only - recompile the source file if the source code has changed. So - we could have something like:</para> - - <screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> … <userinput>file37.c</userinput> &hellip - </screen> - - <para>if we'd changed <filename>file37.c</filename>, but not any - of the others, since the last time we compiled. This may - speed up the compilation quite a bit, but doesn't solve the - typing problem.</para> - - <para>Or we could write a shell script to solve the typing - problem, but it would have to re-compile everything, making it - very inefficient on a large project.</para> - - <para>What happens if we have hundreds of source files lying - about? What if we're working in a team with other people who - forget to tell us when they've changed one of their source - files that we use?</para> - - <para>Perhaps we could put the two solutions together and write - something like a shell script that would contain some kind of - magic rule saying when a source file needs compiling. Now all - we need now is a program that can understand these rules, as - it's a bit too complicated for the shell.</para> - - <para>This program is called <command>make</command>. It reads - in a file, called a <firstterm>makefile</firstterm>, that - tells it how different files depend on each other, and works - out which files need to be re-compiled and which ones don't. - For example, a rule could say something like <quote>if - <filename>fromboz.o</filename> is older than - <filename>fromboz.c</filename>, that means someone must have - changed <filename>fromboz.c</filename>, so it needs to be - re-compiled.</quote> The makefile also has rules telling - make <emphasis>how</emphasis> to re-compile the source file, - making it a much more powerful tool.</para> - - <para>Makefiles are typically kept in the same directory as the - source they apply to, and can be called - <filename>makefile</filename>, <filename>Makefile</filename> - or <filename>MAKEFILE</filename>. Most programmers use the - name <filename>Makefile</filename>, as this puts it near the - top of a directory listing, where it can easily be - seen. - - <footnote> - <para>They don't use the <filename>MAKEFILE</filename> form - as block capitals are often used for documentation files - like <filename>README</filename>.</para> - </footnote></para> - </sect2> - - <sect2> - <title>Example of using <command>make</command></title> - - <para>Here's a very simple make file:</para> - - <programlisting>foo: foo.c - cc -o foo foo.c</programlisting> - - <para>It consists of two lines, a dependency line and a creation - line.</para> - - <para>The dependency line here consists of the name of the - program (known as the <firstterm>target</firstterm>), followed - by a colon, then whitespace, then the name of the source file. - When <command>make</command> reads this line, it looks to see - if <filename>foo</filename> exists; if it exists, it compares - the time <filename>foo</filename> was last modified to the - time <filename>foo.c</filename> was last modified. If - <filename>foo</filename> does not exist, or is older than - <filename>foo.c</filename>, it then looks at the creation line - to find out what to do. In other words, this is the rule for - working out when <filename>foo.c</filename> needs to be - re-compiled.</para> - - <para>The creation line starts with a <token>tab</token> (press - the <keycap>tab</keycap> key) and then the command you would - type to create <filename>foo</filename> if you were doing it - at a command prompt. If <filename>foo</filename> is out of - date, or does not exist, <command>make</command> then executes - this command to create it. In other words, this is the rule - which tells make how to re-compile - <filename>foo.c</filename>.</para> - - <para>So, when you type <userinput>make</userinput>, it will - make sure that <filename>foo</filename> is up to date with - respect to your latest changes to <filename>foo.c</filename>. - This principle can be extended to - <filename>Makefile</filename>s with hundreds of - targets—in fact, on FreeBSD, it is possible to compile - the entire operating system just by typing <userinput>make - world</userinput> in the appropriate directory!</para> - - <para>Another useful property of makefiles is that the targets - don't have to be programs. For instance, we could have a make - file that looks like this:</para> - - <programlisting>foo: foo.c - cc -o foo foo.c - -install: - cp foo /home/me</programlisting> - - <para>We can tell make which target we want to make by - typing:</para> - - <screen>&prompt.user; <userinput>make <replaceable>target</replaceable></userinput> - </screen> - - <para><command>make</command> will then only look at that target - and ignore any others. For example, if we type - <userinput>make foo</userinput> with the makefile above, make - will ignore the <action>install</action> target.</para> - - <para>If we just type <userinput>make</userinput> on its own, - make will always look at the first target and then stop - without looking at any others. So if we typed - <userinput>make</userinput> here, it will just go to the - <action>foo</action> target, re-compile - <filename>foo</filename> if necessary, and then stop without - going on to the <action>install</action> target.</para> - - <para>Notice that the <action>install</action> target doesn't - actually depend on anything! This means that the command on - the following line is always executed when we try to make that - target by typing <userinput>make install</userinput>. In this - case, it will copy <filename>foo</filename> into the user's - home directory. This is often used by application makefiles, - so that the application can be installed in the correct - directory when it has been correctly compiled.</para> - - <para>This is a slightly confusing subject to try and explain. - If you don't quite understand how <command>make</command> - works, the best thing to do is to write a simple program like - <quote>hello world</quote> and a make file like the one above - and experiment. Then progress to using more than one source - file, or having the source file include a header file. The - <command>touch</command> command is very useful here—it - changes the date on a file without you having to edit - it.</para> - </sect2> - - <sect2> - <title>FreeBSD Makefiles</title> - - <para>Makefiles can be rather complicated to write. Fortunately, - BSD-based systems like FreeBSD come with some very powerful - ones as part of the system. One very good example of this is - the FreeBSD ports system. Here's the essential part of a - typical ports <filename>Makefile</filename>:</para> - - <programlisting>MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ -DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz - -.include <bsd.port.mk></programlisting> - - <para>Now, if we go to the directory for this port and type - <userinput>make</userinput>, the following happens:</para> - - <procedure> - <step> - <para>A check is made to see if the source code for this - port is already on the system.</para> - </step> - - <step> - <para>If it isn't, an FTP connection to the URL in - <symbol>MASTER_SITES</symbol> is set up to download the - source.</para> - </step> - - <step> - <para>The checksum for the source is calculated and compared - it with one for a known, good, copy of the source. This - is to make sure that the source was not corrupted while in - transit.</para> - </step> - - <step> - <para>Any changes required to make the source work on - FreeBSD are applied—this is known as - <firstterm>patching</firstterm>.</para> - </step> - - <step> - <para>Any special configuration needed for the source is - done. (Many Unix program distributions try to work out - which version of Unix they are being compiled on and which - optional Unix features are present—this is where - they are given the information in the FreeBSD ports - scenario).</para> - </step> - - <step> - <para>The source code for the program is compiled. In - effect, we change to the directory where the source was - unpacked and do <command>make</command>—the - program's own make file has the necessary information to - build the program.</para> - </step> - - <step> - <para>We now have a compiled version of the program. If we - wish, we can test it now; when we feel confident about the - program, we can type <userinput>make install</userinput>. - This will cause the program and any supporting files it - needs to be copied into the correct location; an entry is - also made into a <database>package database</database>, so - that the port can easily be uninstalled later if we change - our mind about it.</para> - </step> - </procedure> - - <para>Now I think you'll agree that's rather impressive for a - four line script!</para> - - <para>The secret lies in the last line, which tells - <command>make</command> to look in the system makefile called - <filename>bsd.port.mk</filename>. It's easy to overlook this - line, but this is where all the clever stuff comes - from—someone has written a makefile that tells - <command>make</command> to do all the things above (plus a - couple of other things I didn't mention, including handling - any errors that may occur) and anyone can get access to that - just by putting a single line in their own make file!</para> - - <para>If you want to have a look at these system makefiles, - they're in <filename>/usr/share/mk</filename>, but it's - probably best to wait until you've had a bit of practice with - makefiles, as they are very complicated (and if you do look at - them, make sure you have a flask of strong coffee - handy!)</para> - </sect2> - - <sect2> - <title>More advanced uses of <command>make</command></title> - - <para><command>Make</command> is a very powerful tool, and can - do much more than the simple example above shows. - Unfortunately, there are several different versions of - <command>make</command>, and they all differ considerably. - The best way to learn what they can do is probably to read the - documentation—hopefully this introduction will have - given you a base from which you can do this.</para> - - <para>The version of make that comes with FreeBSD is the - <application>Berkeley make</application>; there is a tutorial - for it in <filename>/usr/share/doc/psd/12.make</filename>. To - view it, do</para> - - <screen>&prompt.user; <userinput>zmore paper.ascii.gz</userinput> - </screen> - - <para>in that directory.</para> - - <para>Many applications in the ports use <application>GNU - make</application>, which has a very good set of - <quote>info</quote> pages. If you have installed any of these - ports, <application>GNU make</application> will automatically - have been installed as <command>gmake</command>. It's also - available as a port and package in its own right.</para> - - <para>To view the info pages for <application>GNU - make</application>, you will have to edit the - <filename>dir</filename> file in the - <filename>/usr/local/info</filename> directory to add an entry - for it. This involves adding a line like</para> - - <programlisting> * Make: (make). The GNU Make utility.</programlisting> - - <para>to the file. Once you have done this, you can type - <userinput>info</userinput> and then select - <guimenuitem>make</guimenuitem> from the menu (or in - <application>Emacs</application>, do <userinput>C-h - i</userinput>).</para> - </sect2> - </sect1> - - <sect1 id="debugging"> - <title>Debugging</title> - - <sect2> - <title>The Debugger</title> - - <para>The debugger that comes with FreeBSD is called - <command>gdb</command> (<application>GNU - debugger</application>). You start it up by typing</para> - - <screen>&prompt.user; <userinput>gdb <replaceable>progname</replaceable></userinput> - </screen> - - <para>although most people prefer to run it inside - <application>Emacs</application>. You can do this by:</para> - - <screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput> - </screen> - - <para>Using a debugger allows you to run the program under more - controlled circumstances. Typically, you can step through the - program a line at a time, inspect the value of variables, - change them, tell the debugger to run up to a certain point - and then stop, and so on. You can even attach to a program - that's already running, or load a core file to investigate why - the program crashed. It's even possible to debug the kernel, - though that's a little trickier than the user applications - we'll be discussing in this section.</para> - - <para><command>gdb</command> has quite good on-line help, as - well as a set of info pages, so this section will concentrate - on a few of the basic commands.</para> - - <para>Finally, if you find its text-based command-prompt style - off-putting, there's a graphical front-end for it <ulink - URL="../../ports/devel.html">xxgdb</ulink> in the ports - collection.</para> - - <para>This section is intended to be an introduction to using - <command>gdb</command> and does not cover specialised topics - such as debugging the kernel.</para> - </sect2> - - <sect2> - <title>Running a program in the debugger</title> - - <para>You'll need to have compiled the program with the - <option>-g</option> option to get the most out of using - <command>gdb</command>. It will work without, but you'll only - see the name of the function you're in, instead of the source - code. If you see a line like:</para> - - <screen>… (no debugging symbols found) … - </screen> - - <para>when <command>gdb</command> starts up, you'll know that - the program wasn't compiled with the <option>-g</option> - option.</para> - - <para>At the <command>gdb</command> prompt, type - <userinput>break main</userinput>. This will tell the - debugger to skip over the preliminary set-up code in the - program and start at the beginning of your code. Now type - <userinput>run</userinput> to start the program—it will - start at the beginning of the set-up code and then get stopped - by the debugger when it calls <function>main()</function>. - (If you've ever wondered where <function>main()</function> - gets called from, now you know!).</para> - - <para>You can now step through the program, a line at a time, by - pressing <command>n</command>. If you get to a function call, - you can step into it by pressing <command>s</command>. Once - you're in a function call, you can return from stepping into a - function call by pressing <command>f</command>. You can also - use <command>up</command> and <command>down</command> to take - a quick look at the caller.</para> - - <para>Here's a simple example of how to spot a mistake in a - program with <command>gdb</command>. This is our program - (with a deliberate mistake):</para> - - <programlisting>#include <stdio.h> - -int bazz(int anint); - -main() { - int i; - - printf("This is my program\n"); - bazz(i); - return 0; -} - -int bazz(int anint) { - printf("You gave me %d\n", anint); - return anint; -}</programlisting> - - <para>This program sets <symbol>i</symbol> to be - <literal>5</literal> and passes it to a function - <function>bazz()</function> which prints out the number we - gave it.</para> - - <para>When we compile and run the program we get</para> - - <screen>&prompt.user; <userinput>cc -g -o temp temp.c</userinput> -&prompt.user; <userinput>./temp</userinput> -This is my program -anint = 4231 - </screen> - - <para>That wasn't what we expected! Time to see what's going - on!</para> - - <screen>&prompt.user; <userinput>gdb temp</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>break main</> <lineannotation>Skip the set-up code</> -Breakpoint 1 at 0x160f: file temp.c, line 9. <lineannotation><command>gdb</command> puts breakpoint at <function>main()</></> -(gdb) <userinput>run</> <lineannotation>Run as far as <function>main()</></> -Starting program: /home/james/tmp/temp <lineannotation>Program starts running</> - -Breakpoint 1, main () at temp.c:9 <lineannotation><command>gdb</command> stops at <function>main()</></> -(gdb) <userinput>n</> <lineannotation>Go to next line</> -This is my program <lineannotation>Program prints out</> -(gdb) <userinput>s</> <lineannotation>step into <function>bazz()</></> -bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) - </screen> - - <para>Hang on a minute! How did <symbol>anint</symbol> get to be - <literal>4231</literal>? Didn't we set it to be - <literal>5</literal> in <function>main()</function>? Let's - move up to <function>main()</function> and have a look.</para> - - <screen>(gdb) <userinput>up</> <lineannotation>Move up call stack</> -#1 0x1625 in main () at temp.c:11 <lineannotation><command>gdb</command> displays stack frame</> -(gdb) <userinput>p i</> <lineannotation>Show us the value of <symbol>i</></> -$1 = 4231 <lineannotation><command>gdb</command> displays <literal>4231</></> - </screen> - - <para>Oh dear! Looking at the code, we forgot to initialise - <symbol>i</symbol>. We meant to put</para> - - <programlisting><lineannotation>…</> -main() { - int i; - - i = 5; - printf("This is my program\n"); -<lineannotation>&hellip</></programlisting> - - <para>but we left the <literal>i=5;</literal> line out. As we - didn't initialise <symbol>i</symbol>, it had whatever number - happened to be in that area of memory when the program ran, - which in this case happened to be - <literal>4231</literal>.</para> - - <note> - <para><command>gdb</command> displays the stack frame every - time we go into or out of a function, even if we're using - <command>up</command> and <command>down</command> to move - around the call stack. This shows the name of the function - and the values of its arguments, which helps us keep track - of where we are and what's going on. (The stack is a - storage area where the program stores information about the - arguments passed to functions and where to go when it - returns from a function call).</para> - </note> - </sect2> - - <sect2> - <title>Examining a core file</title> - - <para>A core file is basically a file which contains the - complete state of the process when it crashed. In <quote>the - good old days</quote>, programmers had to print out hex - listings of core files and sweat over machine code manuals, - but now life is a bit easier. Incidentally, under FreeBSD and - other 4.4BSD systems, a core file is called - <filename><replaceable>progname</replaceable>.core</filename> instead of just - <filename>core</filename>, to make it clearer which program a - core file belongs to.</para> - - <para>To examine a core file, start up <command>gdb</command> in - the usual way. Instead of typing <command>break</command> or - <command>run</command>, type</para> - - <screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput> - </screen> - - <para>If you're not in the same directory as the core file, - you'll have to do <userinput>dir - /path/to/core/file</userinput> first.</para> - - <para>You should see something like this:</para> - - <screen>&prompt.user; <userinput>gdb a.out</userinput> -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. -(gdb) <userinput>core a.out.core</userinput> -Core was generated by `a.out'. -Program terminated with signal 11, Segmentation fault. -Cannot access memory at address 0x7020796d. -#0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb) - </screen> - - <para>In this case, the program was called - <filename>a.out</filename>, so the core file is called - <filename>a.out.core</filename>. We can see that the program - crashed due to trying to access an area in memory that was not - available to it in a function called - <function>bazz</function>.</para> - - <para>Sometimes it's useful to be able to see how a function was - called, as the problem could have occurred a long way up the - call stack in a complex program. The <command>bt</command> - command causes <command>gdb</command> to print out a - back-trace of the call stack:</para> - - <screen>(gdb) <userinput>bt</userinput> -#0 0x164a in bazz (anint=0x5) at temp.c:17 -#1 0xefbfd888 in end () -#2 0x162c in main () at temp.c:11 -(gdb) - </screen> - - <para>The <function>end()</function> function is called when a - program crashes; in this case, the <function>bazz()</function> - function was called from <function>main()</function>.</para> - </sect2> - - <sect2> - <title>Attaching to a running program</title> - - <para>One of the neatest features about <command>gdb</command> - is that it can attach to a program that's already running. Of - course, that assumes you have sufficient permissions to do so. - A common problem is when you are stepping through a program - that forks, and you want to trace the child, but the debugger - will only let you trace the parent.</para> - - <para>What you do is start up another <command>gdb</command>, - use <command>ps</command> to find the process ID for the - child, and do</para> - - <screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput> - </screen> - - <para>in <command>gdb</command>, and then debug as usual.</para> - - <para><quote>That's all very well,</quote> you're probably - thinking, <quote>but by the time I've done that, the child - process will be over the hill and far away</quote>. Fear - not, gentle reader, here's how to do it (courtesy of the - <command>gdb</command> info pages):</para> - - <screen><lineannotation>&hellip</lineannotation> -if ((pid = fork()) < 0) /* _Always_ check this */ - error(); -else if (pid == 0) { /* child */ - int PauseMode = 1; - - while (PauseMode) - sleep(10); /* Wait until someone attaches to us */ - <lineannotation>&hellip</lineannotation> -} else { /* parent */ - <lineannotation>&hellip</lineannotation> - </screen> - - <para>Now all you have to do is attach to the child, set - <symbol>PauseMode</symbol> to <literal>0</literal>, and wait - for the <function>sleep()</function> call to return!</para> - </sect2> - </sect1> - - <sect1 id="emacs"> - <title>Using Emacs as a Development Environment</title> - - <sect2> - <title>Emacs</title> - - <para>Unfortunately, Unix systems don't come with the kind of - everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package - integrated development environments that other systems - have. - - <footnote> - <para>At least, not unless you pay out very large sums of - money.</para> - </footnote> - - However, it is possible to set up your own environment. It - may not be as pretty, and it may not be quite as integrated, - but you can set it up the way you want it. And it's free. - And you have the source to it.</para> - - <para>The key to it all is Emacs. Now there are some people who - loathe it, but many who love it. If you're one of the former, - I'm afraid this section will hold little of interest to you. - Also, you'll need a fair amount of memory to run it—I'd - recommend 8MB in text mode and 16MB in X as the bare minimum - to get reasonable performance.</para> - - <para>Emacs is basically a highly customisable - editor—indeed, it has been customised to the point where - it's more like an operating system than an editor! Many - developers and sysadmins do in fact spend practically all - their time working inside Emacs, leaving it only to log - out.</para> - - <para>It's impossible even to summarise everything Emacs can do - here, but here are some of the features of interest to - developers:</para> - - <itemizedlist> - <listitem> - <para>Very powerful editor, allowing search-and-replace on - both strings and regular expressions (patterns), jumping - to start/end of block expression, etc, etc.</para> - </listitem> - - <listitem> - <para>Pull-down menus and online help.</para> - </listitem> - - <listitem> - <para>Language-dependent syntax highlighting and - indentation.</para> - </listitem> - - <listitem> - <para>Completely customisable.</para> - </listitem> - - <listitem> - <para>You can compile and debug programs within - Emacs.</para> - </listitem> - - <listitem> - <para>On a compilation error, you can jump to the offending - line of source code.</para> - </listitem> - - <listitem> - <para>Friendly-ish front-end to the <command>info</command> - program used for reading GNU hypertext documentation, - including the documentation on Emacs itself.</para> - </listitem> - - <listitem> - <para>Friendly front-end to <command>gdb</command>, allowing - you to look at the source code as you step through your - program.</para> - </listitem> - - <listitem> - <para>You can read Usenet news and mail while your program - is compiling.</para> - </listitem> - </itemizedlist> - - <para>And doubtless many more that I've overlooked.</para> - - <para>Emacs can be installed on FreeBSD using <ulink - URL="../../ports/editors.html">the Emacs - port</ulink>.</para> - - <para>Once it's installed, start it up and do <userinput>C-h - t</userinput> to read an Emacs tutorial—that means - hold down the <keycap>control</keycap> key, press - <keycap>h</keycap>, let go of the <keycap>control</keycap> - key, and then press <keycap>t</keycap>. (Alternatively, you - can you use the mouse to select <guimenuitem>Emacs - Tutorial</guimenuitem> from the <guimenu>Help</guimenu> - menu).</para> - - <para>Although Emacs does have menus, it's well worth learning - the key bindings, as it's much quicker when you're editing - something to press a couple of keys than to try and find the - mouse and then click on the right place. And, when you're - talking to seasoned Emacs users, you'll find they often - casually throw around expressions like <quote><literal>M-x - replace-s RET foo RET bar RET</literal></quote> so it's - useful to know what they mean. And in any case, Emacs has far - too many useful functions for them to all fit on the menu - bars.</para> - - <para>Fortunately, it's quite easy to pick up the key-bindings, - as they're displayed next to the menu item. My advice is to - use the menu item for, say, opening a file until you - understand how it works and feel confident with it, then try - doing C-x C-f. When you're happy with that, move on to - another menu command.</para> - - <para>If you can't remember what a particular combination of - keys does, select <guimenuitem>Describe Key</guimenuitem> from - the <guimenu>Help</guimenu> menu and type it in—Emacs - will tell you what it does. You can also use the - <guimenuitem>Command Apropos</guimenuitem> menu item to find - out all the commands which contain a particular word in them, - with the key binding next to it.</para> - - <para>By the way, the expression above means hold down the - <keysym>Meta</keysym> key, press <keysym>x</keysym>, release - the <keysym>Meta</keysym> key, type - <userinput>replace-s</userinput> (short for - <literal>replace-string</literal>—another feature of - Emacs is that you can abbreviate commands), press the - <keysym>return</keysym> key, type <userinput>foo</userinput> - (the string you want replaced), press the - <keysym>return</keysym> key, type bar (the string you want to - replace <literal>foo</literal> with) and press - <keysym>return</keysym> again. Emacs will then do the - search-and-replace operation you've just requested.</para> - - <para>If you're wondering what on earth the - <keysym>Meta</keysym> key is, it's a special key that many - Unix workstations have. Unfortunately, PC's don't have one, - so it's usually the <keycap>alt</keycap> key (or if you're - unlucky, the <keysym>escape</keysym> key).</para> - - <para>Oh, and to get out of Emacs, do <command>C-x C-c</command> - (that means hold down the <keysym>control</keysym> key, press - <keysym>x</keysym>, press <keysym>c</keysym> and release the - <keysym>control</keysym> key). If you have any unsaved files - open, Emacs will ask you if you want to save them. (Ignore - the bit in the documentation where it says - <command>C-z</command> is the usual way to leave - Emacs—that leaves Emacs hanging around in the - background, and is only really useful if you're on a system - which doesn't have virtual terminals).</para> - </sect2> - - <sect2> - <title>Configuring Emacs</title> - - <para>Emacs does many wonderful things; some of them are built - in, some of them need to be configured.</para> - - <para>Instead of using a proprietary macro language for - configuration, Emacs uses a version of Lisp specially adapted - for editors, known as Emacs Lisp. This can be quite useful if - you want to go on and learn something like Common Lisp, as - it's considerably smaller than Common Lisp (although still - quite big!).</para> - - <para>The best way to learn Emacs Lisp is to download the <ulink - URL="ftp://prep.ai.mit.edu:pub/gnu/elisp-manual-19-2.4.tar.gz">Emacs - Tutorial</ulink></para> - - <para>However, there's no need to actually know any Lisp to get - started with configuring Emacs, as I've included a sample - <filename>.emacs</filename> file, which should be enough to - get you started. Just copy it into your home directory and - restart Emacs if it's already running; it will read the - commands from the file and (hopefully) give you a useful basic - setup.</para> - </sect2> - - <sect2> - <title>A sample <filename>.emacs</filename> file</title> - - <para>Unfortunately, there's far too much here to explain it in - detail; however there are one or two points worth - mentioning.</para> - - <itemizedlist> - <listitem> - <para>Everything beginning with a <literal>;</literal> is a comment - and is ignored by Emacs.</para> - </listitem> - - <listitem> - <para>In the first line, the - <literal>-*- Emacs-Lisp -*-</literal> is so that - we can edit the <filename>.emacs</filename> file itself - within Emacs and get all the fancy features for editing - Emacs Lisp. Emacs usually tries to guess this based on - the filename, and may not get it right for - <filename>.emacs</filename>.</para> - </listitem> - - <listitem> - <para>The <keysym>tab</keysym> key is bound to an - indentation function in some modes, so when you press the - tab key, it will indent the current line of code. If you - want to put a <token>tab</token> character in whatever - you're writing, hold the <keysym>control</keysym> key down - while you're pressing the <keysym>tab</keysym> key.</para> - </listitem> - - <listitem> - <para>This file supports syntax highlighting for C, C++, - Perl, Lisp and Scheme, by guessing the language from the - filename.</para> - </listitem> - - <listitem> - <para>Emacs already has a pre-defined function called - <function>next-error</function>. In a compilation output - window, this allows you to move from one compilation error - to the next by doing <command>M-n</command>; we define a - complementary function, - <function>previous-error</function>, that allows you to go - to a previous error by doing <command>M-p</command>. The - nicest feature of all is that <command>C-c C-c</command> - will open up the source file in which the error occurred - and jump to the appropriate line.</para> - </listitem> - - <listitem> - <para>We enable Emacs's ability to act as a server, so that - if you're doing something outside Emacs and you want to - edit a file, you can just type in</para> - - <screen>&prompt.user; <userinput>emacsclient <replaceable>filename</replaceable></userinput> - </screen> - - <para>and then you can edit the file in your - Emacs! - - <footnote> - <para>Many Emacs users set their <envar - >EDITOR</envar> environment to - <literal>emacsclient</literal> so this happens every - time they need to edit a file.</para> - </footnote></para> - </listitem> - </itemizedlist> - - <example> - <title>A sample <filename>.emacs</filename> file</title> - - <programlisting>;; -*-Emacs-Lisp-*- - -;; This file is designed to be re-evaled; use the variable first-time -;; to avoid any problems with this. -(defvar first-time t - "Flag signifying this is the first time that .emacs has been evaled") - -;; Meta -(global-set-key "\M- " 'set-mark-command) -(global-set-key "\M-\C-h" 'backward-kill-word) -(global-set-key "\M-\C-r" 'query-replace) -(global-set-key "\M-r" 'replace-string) -(global-set-key "\M-g" 'goto-line) -(global-set-key "\M-h" 'help-command) - -;; Function keys -(global-set-key [f1] 'manual-entry) -(global-set-key [f2] 'info) -(global-set-key [f3] 'repeat-complex-command) -(global-set-key [f4] 'advertised-undo) -(global-set-key [f5] 'eval-current-buffer) -(global-set-key [f6] 'buffer-menu) -(global-set-key [f7] 'other-window) -(global-set-key [f8] 'find-file) -(global-set-key [f9] 'save-buffer) -(global-set-key [f10] 'next-error) -(global-set-key [f11] 'compile) -(global-set-key [f12] 'grep) -(global-set-key [C-f1] 'compile) -(global-set-key [C-f2] 'grep) -(global-set-key [C-f3] 'next-error) -(global-set-key [C-f4] 'previous-error) -(global-set-key [C-f5] 'display-faces) -(global-set-key [C-f8] 'dired) -(global-set-key [C-f10] 'kill-compilation) - -;; Keypad bindings -(global-set-key [up] "\C-p") -(global-set-key [down] "\C-n") -(global-set-key [left] "\C-b") -(global-set-key [right] "\C-f") -(global-set-key [home] "\C-a") -(global-set-key [end] "\C-e") -(global-set-key [prior] "\M-v") -(global-set-key [next] "\C-v") -(global-set-key [C-up] "\M-\C-b") -(global-set-key [C-down] "\M-\C-f") -(global-set-key [C-left] "\M-b") -(global-set-key [C-right] "\M-f") -(global-set-key [C-home] "\M-<") -(global-set-key [C-end] "\M->") -(global-set-key [C-prior] "\M-<") -(global-set-key [C-next] "\M->") - -;; Mouse -(global-set-key [mouse-3] 'imenu) - -;; Misc -(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. -(setq backup-by-copying-when-mismatch t) - -;; Treat 'y' or <CR> as yes, 'n' as no. -(fset 'yes-or-no-p 'y-or-n-p) - (define-key query-replace-map [return] 'act) - (define-key query-replace-map [?\C-m] 'act) - -;; Load packages -(require 'desktop) -(require 'tar-mode) - -;; Pretty diff mode -(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) -(autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") - -(if first-time - (setq auto-mode-alist - (append '(("\\.cpp$" . c++-mode) - ("\\.hpp$" . c++-mode) - ("\\.lsp$" . lisp-mode) - ("\\.scm$" . scheme-mode) - ("\\.pl$" . perl-mode) - ) auto-mode-alist))) - -;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode") - -(defvar font-lock-mode-keyword-alist - '((c++-c-mode . c-font-lock-keywords) - (perl-mode . perl-font-lock-keywords)) - "Associations between modes and keywords") - -(defun font-lock-auto-mode-select () - "Automatically select font-lock-mode if the current major mode is -in font-lock-auto-mode-list" - (if (memq major-mode font-lock-auto-mode-list) - (progn - (font-lock-mode t)) - ) - ) - -(global-set-key [M-f1] 'font-lock-fontify-buffer) - -;; New dabbrev stuff -;(require 'new-dabbrev) -(setq dabbrev-always-check-other-buffers t) -(setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") -(add-hook 'emacs-lisp-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'c-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) nil) - (set (make-local-variable 'dabbrev-case-replace) nil))) -(add-hook 'text-mode-hook - '(lambda () - (set (make-local-variable 'dabbrev-case-fold-search) t) - (set (make-local-variable 'dabbrev-case-replace) t))) - -;; C++ and C mode... -(defun my-c++-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c++-mode-map "\C-ce" 'c-comment-edit) - (setq c++-auto-hungry-initial-state 'none) - (setq c++-delete-function 'backward-delete-char) - (setq c++-tab-always-indent t) - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c++-empty-arglist-indent 4)) - -(defun my-c-mode-hook () - (setq tab-width 4) - (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key c-mode-map "\C-ce" 'c-comment-edit) - (setq c-auto-hungry-initial-state 'none) - (setq c-delete-function 'backward-delete-char) - (setq c-tab-always-indent t) -;; BSD-ish indentation style - (setq c-indent-level 4) - (setq c-continued-statement-offset 4) - (setq c-brace-offset -4) - (setq c-argdecl-indent 0) - (setq c-label-offset -4)) - -;; Perl mode -(defun my-perl-mode-hook () - (setq tab-width 4) - (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) - (setq perl-indent-level 4) - (setq perl-continued-statement-offset 4)) - -;; Scheme mode... -(defun my-scheme-mode-hook () - (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) - -;; Emacs-Lisp mode... -(defun my-lisp-mode-hook () - (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) - (define-key lisp-mode-map "\C-i" 'lisp-indent-line) - (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) - -;; Add all of the hooks... -(add-hook 'c++-mode-hook 'my-c++-mode-hook) -(add-hook 'c-mode-hook 'my-c-mode-hook) -(add-hook 'scheme-mode-hook 'my-scheme-mode-hook) -(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'lisp-mode-hook 'my-lisp-mode-hook) -(add-hook 'perl-mode-hook 'my-perl-mode-hook) - -;; Complement to next-error -(defun previous-error (n) - "Visit previous compilation error message and corresponding source code." - (interactive "p") - (next-error (- n))) - -;; Misc... -(transient-mark-mode 1) -(setq mark-even-if-inactive t) -(setq visible-bell nil) -(setq next-line-add-newlines nil) -(setq compile-command "make") -(setq suggest-key-bindings nil) -(put 'eval-expression 'disabled nil) -(put 'narrow-to-region 'disabled nil) -(put 'set-goal-column 'disabled nil) - -;; Elisp archive searching -(autoload 'format-lisp-code-directory "lispdir" nil t) -(autoload 'lisp-dir-apropos "lispdir" nil t) -(autoload 'lisp-dir-retrieve "lispdir" nil t) -(autoload 'lisp-dir-verify "lispdir" nil t) - -;; Font lock mode -(defun my-make-face (face colour &optional bold) - "Create a face from a colour and optionally make it bold" - (make-face face) - (copy-face 'default face) - (set-face-foreground face colour) - (if bold (make-face-bold face)) - ) - -(if (eq window-system 'x) - (progn - (my-make-face 'blue "blue") - (my-make-face 'red "red") - (my-make-face 'green "dark green") - (setq font-lock-comment-face 'blue) - (setq font-lock-string-face 'bold) - (setq font-lock-type-face 'bold) - (setq font-lock-keyword-face 'bold) - (setq font-lock-function-name-face 'red) - (setq font-lock-doc-string-face 'green) - (add-hook 'find-file-hooks 'font-lock-auto-mode-select) - - (setq baud-rate 1000000) - (global-set-key "\C-cmm" 'menu-bar-mode) - (global-set-key "\C-cms" 'scroll-bar-mode) - (global-set-key [backspace] 'backward-delete-char) - ; (global-set-key [delete] 'delete-char) - (standard-display-european t) - (load-library "iso-transl"))) - -;; X11 or PC using direct screen writes -(if window-system - (progn - ;; (global-set-key [M-f1] 'hilit-repaint-command) - ;; (global-set-key [M-f2] [?\C-u M-f1]) - (setq hilit-mode-enable-list - '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode - scheme-mode) - hilit-auto-highlight nil - hilit-auto-rehighlight 'visible - hilit-inhibit-hooks nil - hilit-inhibit-rebinding t) - (require 'hilit19) - (require 'paren)) - (setq baud-rate 2400) ; For slow serial connections - ) - -;; TTY type terminal -(if (and (not window-system) - (not (equal system-type 'ms-dos))) - (progn - (if first-time - (progn - (keyboard-translate ?\C-h ?\C-?) - (keyboard-translate ?\C-? ?\C-h))))) - -;; Under UNIX -(if (not (equal system-type 'ms-dos)) - (progn - (if first-time - (server-start)))) - -;; Add any face changes here -(add-hook 'term-setup-hook 'my-term-setup-hook) -(defun my-term-setup-hook () - (if (eq window-system 'pc) - (progn -;; (set-face-background 'default "red") - ))) - -;; Restore the "desktop" - do this as late as possible -(if first-time - (progn - (desktop-load-default) - (desktop-read))) - -;; Indicate that this file has been read at least once -(setq first-time nil) - -;; No need to debug anything now -(setq debug-on-error nil) - -;; All done -(message "All done, %s%s" (user-login-name) ".") - </programlisting> - </example> - </sect2> - - <sect2> - <title>Extending the Range of Languages Emacs Understands</title> - - <para>Now, this is all very well if you only want to program in - the languages already catered for in the - <filename>.emacs</filename> file (C, C++, Perl, Lisp and - Scheme), but what happens if a new language called - <quote>whizbang</quote> comes out, full of exciting - features?</para> - - <para>The first thing to do is find out if whizbang comes with - any files that tell Emacs about the language. These usually - end in <filename>.el</filename>, short for <quote>Emacs - Lisp</quote>. For example, if whizbang is a FreeBSD port, we - can locate these files by doing</para> - - <screen>&prompt.user; <userinput>find /usr/ports/lang/whizbang -name "*.el" -print</userinput> - </screen> - - <para>and install them by copying them into the Emacs site Lisp - directory. On FreeBSD 2.1.0-RELEASE, this is - <filename>/usr/local/share/emacs/site-lisp</filename>.</para> - - <para>So for example, if the output from the find command - was</para> - - <screen>/usr/ports/lang/whizbang/work/misc/whizbang.el - </screen> - - <para>we would do</para> - - <screen>&prompt.root; <userinput>cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp</userinput> - </screen> - - <para>Next, we need to decide what extension whizbang source - files have. Let's say for the sake of argument that they all - end in <filename>.wiz</filename>. We need to add an entry to - our <filename>.emacs</filename> file to make sure Emacs will - be able to use the information in - <filename>whizbang.el</filename>.</para> - - <para>Find the <symbol>auto-mode-alist entry</symbol> in - <filename>.emacs</filename> and add a line for whizbang, such - as:</para> - - <programlisting><lineannotation>…</> -("\\.lsp$" . lisp-mode) -("\\.wiz$" . whizbang-mode) -("\\.scm$" . scheme-mode) -<lineannotation>…</></programlisting> - - <para>This means that Emacs will automatically go into - <function>whizbang-mode</function> when you edit a file ending - in <filename>.wiz</filename>.</para> - - <para>Just below this, you'll find the - <symbol>font-lock-auto-mode-list</symbol> entry. Add - <function>whizbang-mode</function> to it like so:</para> - - <programlisting>;; Auto font lock mode -(defvar font-lock-auto-mode-list - (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) - "List of modes to always start in font-lock-mode")</programlisting> - - <para>This means that Emacs will always enable - <function>font-lock-mode</function> (ie syntax highlighting) - when editing a <filename>.wiz</filename> file.</para> - - <para>And that's all that's needed. If there's anything else - you want done automatically when you open up a - <filename>.wiz</filename> file, you can add a - <function>whizbang-mode hook</function> (see - <function>my-scheme-mode-hook</function> for a simple example - that adds <function>auto-indent</function>).</para> - </sect2> - </sect1> - - <sect1> - <title>Further Reading</title> - - <itemizedlist> - <listitem> - <para>Brian Harvey and Matthew Wright - <emphasis>Simply Scheme</emphasis> - MIT 1994.<!-- <br> --> - ISBN 0-262-08226-8</para> - </listitem> - - <listitem> - <para>Randall Schwartz - <emphasis>Learning Perl</emphasis> - O'Reilly 1993<!-- <br> --> - ISBN 1-56592-042-2</para> - </listitem> - - <listitem> - <para>Patrick Henry Winston and Berthold Klaus Paul Horn - <emphasis>Lisp (3rd Edition)</emphasis> - Addison-Wesley 1989<!-- <br> --> - ISBN 0-201-08319-1</para> - </listitem> - - <listitem> - <para>Brian W. Kernighan and Rob Pike - <emphasis>The Unix Programming Environment</emphasis> - Prentice-Hall 1984<!-- <br> --> - ISBN 0-13-937681-X</para> - </listitem> - - <listitem> - <para>Brian W. Kernighan and Dennis M. Ritchie - <emphasis>The C Programming Language (2nd Edition)</emphasis> - Prentice-Hall 1988<!-- <br> --> - ISBN 0-13-110362-8</para> - </listitem> - - <listitem> - <para>Bjarne Stroustrup - <emphasis>The C++ Programming Language</emphasis> - Addison-Wesley 1991<!-- <br> --> - ISBN 0-201-53992-6</para> - </listitem> - - <listitem> - <para>W. Richard Stevens - <emphasis>Advanced Programming in the Unix Environment</emphasis> - Addison-Wesley 1992<!-- <br> --> - ISBN 0-201-56317-7</para> - </listitem> - - <listitem> - <para>W. Richard Stevens - <emphasis>Unix Network Programming</emphasis> - Prentice-Hall 1990<!-- <br> --> - ISBN 0-13-949876-1</para> - </listitem> - </itemizedlist> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/articles/vm-design/Makefile b/en_US.ISO_8859-1/articles/vm-design/Makefile deleted file mode 100644 index 6758b4073a..0000000000 --- a/en_US.ISO_8859-1/articles/vm-design/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# $FreeBSD: doc/en_US.ISO_8859-1/articles/mh/Makefile,v 1.8 1999/09/06 06:52:37 peter Exp $ - -DOC?= article - -FORMATS?= html - -IMAGES= fig1.eps fig2.eps fig3.eps fig4.eps - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/vm-design/article.sgml b/en_US.ISO_8859-1/articles/vm-design/article.sgml deleted file mode 100644 index 54bafaf6dd..0000000000 --- a/en_US.ISO_8859-1/articles/vm-design/article.sgml +++ /dev/null @@ -1,838 +0,0 @@ -<!-- $FreeBSD: doc/en_US.ISO_8859-1/articles/vm-design/article.sgml,v 1.3 2001/01/24 11:50:30 ben Exp $ --> -<!-- FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <articleinfo> - <title>Design elements of the FreeBSD VM system</title> - - <authorgroup> - <author> - <firstname>Matthew</firstname> - - <surname>Dillon</surname> - - <affiliation> - <address> - <email>dillon@apollo.backplane.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <abstract> - <para>The title is really just a fancy way of saying that I am going to - attempt to describe the whole VM enchilada, hopefully in a way that - everyone can follow. For the last year I have concentrated on a number - of major kernel subsystems within FreeBSD, with the VM and Swap - subsystems being the most interesting and NFS being ‘a necessary - chore’. I rewrote only small portions of the code. In the VM - arena the only major rewrite I have done is to the swap subsystem. - Most of my work was cleanup and maintenance, with only moderate code - rewriting and no major algorithmic adjustments within the VM - subsystem. The bulk of the VM subsystem's theoretical base remains - unchanged and a lot of the credit for the modernization effort in the - last few years belongs to John Dyson and David Greenman. Not being a - historian like Kirk I will not attempt to tag all the various features - with peoples names, since I will invariably get it wrong.</para> - </abstract> - - <legalnotice> - <para>This article was originally published in the January 2000 issue of - <ulink url="http://www.daemonnews.org/">DaemonNews</ulink>. This - version of the article may include updates from Matt and other authors - to reflect changes in FreeBSD's VM implementation.</para> - </legalnotice> - </articleinfo> - - <sect1> - <title>Introduction</title> - - <para>Before moving along to the actual design let's spend a little time - on the necessity of maintaining and modernizing any long-living - codebase. In the programming world, algorithms tend to be more - important than code and it is precisely due to BSD's academic roots that - a great deal of attention was paid to algorithm design from the - beginning. More attention paid to the design generally leads to a clean - and flexible codebase that can be fairly easily modified, extended, or - replaced over time. While BSD is considered an ‘old’ - operating system by some people, those of us who work on it tend to view - it more as a ‘mature’ codebase which has various components - modified, extended, or replaced with modern code. It has evolved, and - FreeBSD is at the bleeding edge no matter how old some of the code might - be. This is an important distinction to make and one that is - unfortunately lost to many people. The biggest error a programmer can - make is to not learn from history, and this is precisely the error that - many other modern operating systems have made. NT is the best example - of this, and the consequences have been dire. Linux also makes this - mistake to some degree—enough that we BSD folk can make small - jokes about it every once in a while, anyway. Linux's problem is simply - one of a lack of experience and history to compare ideas against, a - problem that is easily and rapidly being addressed by the Linux - community in the same way it has been addressed in the BSD - community—by continuous code development. The NT folk, on the - other hand, repeatedly make the same mistakes solved by UNIX decades ago - and then spend years fixing them. Over and over again. They have a - severe case of ‘not designed here’ and ‘we are always - right because our marketing department says so’. I have little - tolerance for anyone who cannot learn from history.</para> - - <para>Much of the apparent complexity of the FreeBSD design, especially in - the VM/Swap subsystem, is a direct result of having to solve serious - performance issues that occur under various conditions. These issues - are not due to bad algorithmic design but instead rise from - environmental factors. In any direct comparison between platforms, - these issues become most apparent when system resources begin to get - stressed. As I describe FreeBSD's VM/Swap subsystem the reader should - always keep two points in mind. First, the most important aspect of - performance design is what is known as “Optimizing the Critical - Path”. It is often the case that performance optimizations add a - little bloat to the code in order to make the critical path perform - better. Second, a solid, generalized design outperforms a - heavily-optimized design over the long run. While a generalized design - may end up being slower than an heavily-optimized design when they are - first implemented, the generalized design tends to be easier to adapt to - changing conditions and the heavily-optimized design winds up having to - be thrown away. Any codebase that will survive and be maintainable for - years must therefore be designed properly from the beginning even if it - costs some performance. Twenty years ago people were still arguing that - programming in assembly was better than programming in a high-level - language because it produced code that was ten times as fast. Today, - the fallibility of that argument is obvious—as are the parallels - to algorithmic design and code generalization.</para> - </sect1> - - <sect1> - <title>VM Objects</title> - - <para>The best way to begin describing the FreeBSD VM system is to look at - it from the perspective of a user-level process. Each user process sees - a single, private, contiguous VM address space containing several types - of memory objects. These objects have various characteristics. Program - code and program data are effectively a single memory-mapped file (the - binary file being run), but program code is read-only while program data - is copy-on-write. Program BSS is just memory allocated and filled with - zeros on demand, called demand zero page fill. Arbitrary files can be - memory-mapped into the address space as well, which is how the shared - library mechanism works. Such mappings can require modifications to - remain private to the process making them. The fork system call adds an - entirely new dimension to the VM management problem on top of the - complexity already given.</para> - - <para>A program binary data page (which is a basic copy-on-write page) - illustrates the complexity. A program binary contains a preinitialized - data section which is initially mapped directly from the program file. - When a program is loaded into a process's VM space, this area is - initially memory-mapped and backed by the program binary itself, - allowing the VM system to free/reuse the page and later load it back in - from the binary. The moment a process modifies this data, however, the - VM system must make a private copy of the page for that process. Since - the private copy has been modified, the VM system may no longer free it, - because there is no longer any way to restore it later on.</para> - - <para>You will notice immediately that what was originally a simple file - mapping has become much more complex. Data may be modified on a - page-by-page basis whereas the file mapping encompasses many pages at - once. The complexity further increases when a process forks. When a - process forks, the result is two processes—each with their own - private address spaces, including any modifications made by the original - process prior to the call to <function>fork()</function>. It would be - silly for the VM system to make a complete copy of the data at the time - of the <function>fork()</function> because it is quite possible that at - least one of the two processes will only need to read from that page - from then on, allowing the original page to continue to be used. What - was a private page is made copy-on-write again, since each process - (parent and child) expects their own personal post-fork modifications to - remain private to themselves and not effect the other.</para> - - <para>FreeBSD manages all of this with a layered VM Object model. The - original binary program file winds up being the lowest VM Object layer. - A copy-on-write layer is pushed on top of that to hold those pages which - had to be copied from the original file. If the program modifies a data - page belonging to the original file the VM system takes a fault and - makes a copy of the page in the higher layer. When a process forks, - additional VM Object layers are pushed on. This might make a little - more sense with a fairly basic example. A <function>fork()</function> - is a common operation for any *BSD system, so this example will consider - a program that starts up, and forks. When the process starts, the VM - system creates an object layer, let's call this A:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig1" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ -| A | -+---------------+</literallayout> - </textobject> - - <textobject> - <phrase>A picture</phrase> - </textobject> - </mediaobject> - - <para>A represents the file—pages may be paged in and out of the - file's physical media as necessary. Paging in from the disk is - reasonable for a program, but we really don't want to page back out and - overwrite the executable. The VM system therefore creates a second - layer, B, that will be physically backed by swap space:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig2" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ -| B | -+---------------+ -| A | -+---------------+</literallayout> - </textobject> - </mediaobject> - - <para>On the first write to a page after this, a new page is created in B, - and its contents are initialized from A. All pages in B can be paged in - or out to a swap device. When the program forks, the VM system creates - two new object layers—C1 for the parent, and C2 for the - child—that rest on top of B:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig3" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+-------+-------+ -| C1 | C2 | -+-------+-------+ -| B | -+---------------+ -| A | -+---------------+</literallayout> - </textobject> - </mediaobject> - - <para>In this case, let's say a page in B is modified by the original - parent process. The process will take a copy-on-write fault and - duplicate the page in C1, leaving the original page in B untouched. - Now, let's say the same page in B is modified by the child process. The - process will take a copy-on-write fault and duplicate the page in C2. - The original page in B is now completely hidden since both C1 and C2 - have a copy and B could theoretically be destroyed if it does not - represent a 'real' file). However, this sort of optimization is not - trivial to make because it is so fine-grained. FreeBSD does not make - this optimization. Now, suppose (as is often the case) that the child - process does an <function>exec()</function>. Its current address space - is usually replaced by a new address space representing a new file. In - this case, the C2 layer is destroyed:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig4" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+-------+ -| C1 | -+-------+-------+ -| B | -+---------------+ -| A | -+---------------+</literallayout> - </textobject> - </mediaobject> - - <para>In this case, the number of children of B drops to one, and all - accesses to B now go through C1. This means that B and C1 can be - collapsed together. Any pages in B that also exist in C1 are deleted - from B during the collapse. Thus, even though the optimization in the - previous step could not be made, we can recover the dead pages when - either of the processes exit or <function>exec()</function>.</para> - - <para>This model creates a number of potential problems. The first is that - you can wind up with a relatively deep stack of layered VM Objects which - can cost scanning time and memory when you take a fault. Deep - layering can occur when processes fork and then fork again (either - parent or child). The second problem is that you can wind up with dead, - inaccessible pages deep in the stack of VM Objects. In our last example - if both the parent and child processes modify the same page, they both - get their own private copies of the page and the original page in B is - no longer accessible by anyone. That page in B can be freed.</para> - - <para>FreeBSD solves the deep layering problem with a special optimization - called the “All Shadowed Case”. This case occurs if either - C1 or C2 take sufficient COW faults to completely shadow all pages in B. - Lets say that C1 achieves this. C1 can now bypass B entirely, so rather - then have C1->B->A and C2->B->A we now have C1->A and C2->B->A. But - look what also happened—now B has only one reference (C2), so we - can collapse B and C2 together. The end result is that B is deleted - entirely and we have C1->A and C2->A. It is often the case that B will - contain a large number of pages and neither C1 nor C2 will be able to - completely overshadow it. If we fork again and create a set of D - layers, however, it is much more likely that one of the D layers will - eventually be able to completely overshadow the much smaller dataset - reprsented by C1 or C2. The same optimization will work at any point in - the graph and the grand result of this is that even on a heavily forked - machine VM Object stacks tend to not get much deeper then 4. This is - true of both the parent and the children and true whether the parent is - doing the forking or whether the children cascade forks.</para> - - <para>The dead page problem still exists in the case where C1 or C2 do not - completely overshadow B. Due to our other optimizations this case does - not represent much of a problem and we simply allow the pages to be - dead. If the system runs low on memory it will swap them out, eating a - little swap, but that's it.</para> - - <para>The advantage to the VM Object model is that - <function>fork()</function> is extremely fast, since no real data - copying need take place. The disadvantage is that you can build a - relatively complex VM Object layering that slows page fault handling - down a little, and you spend memory managing the VM Object structures. - The optimizations FreeBSD makes proves to reduce the problems enough - that they can be ignored, leaving no real disadvantage.</para> - </sect1> - - <sect1> - <title>SWAP Layers</title> - - <para>Private data pages are initially either copy-on-write or zero-fill - pages. When a change, and therefore a copy, is made, the original - backing object (usually a file) can no longer be used to save a copy of - the page when the VM system needs to reuse it for other purposes. This - is where SWAP comes in. SWAP is allocated to create backing store for - memory that does not otherwise have it. FreeBSD allocates the swap - management structure for a VM Object only when it is actually needed. - However, the swap management structure has had problems - historically.</para> - - <para>Under FreeBSD 3.x the swap management structure preallocates an - array that encompasses the entire object requiring swap backing - store—even if only a few pages of that object are swap-backed. - This creates a kernel memory fragmentation problem when large objects - are mapped, or processes with large runsizes (RSS) fork. Also, in order - to keep track of swap space, a ‘list of holes’ is kept in - kernel memory, and this tends to get severely fragmented as well. Since - the 'list of holes' is a linear list, the swap allocation and freeing - performance is a non-optimal O(n)-per-page. It also requires kernel - memory allocations to take place during the swap freeing process, and - that creates low memory deadlock problems. The problem is further - exacerbated by holes created due to the interleaving algorithm. Also, - the swap block map can become fragmented fairly easily resulting in - non-contiguous allocations. Kernel memory must also be allocated on the - fly for additional swap management structures when a swapout occurs. It - is evident that there was plenty of room for improvement.</para> - - <para>For FreeBSD 4.x, I completely rewrote the swap subsystem. With this - rewrite, swap management structures are allocated through a hash table - rather than a linear array giving them a fixed allocation size and much - finer granularity. Rather then using a linearly linked list to keep - track of swap space reservations, it now uses a bitmap of swap blocks - arranged in a radix tree structure with free-space hinting in the radix - node structures. This effectively makes swap allocation and freeing an - O(1) operation. The entire radix tree bitmap is also preallocated in - order to avoid having to allocate kernel memory during critical low - memory swapping operations. After all, the system tends to swap when it - is low on memory so we should avoid allocating kernel memory at such - times in order to avoid potential deadlocks. Finally, to reduce - fragmentation the radix tree is capable of allocating large contiguous - chunks at once, skipping over smaller fragmented chunks. I did not take - the final step of having an 'allocating hint pointer' that would trundle - through a portion of swap as allocations were made in order to further - guarantee contiguous allocations or at least locality of reference, but - I ensured that such an addition could be made.</para> - </sect1> - - <sect1> - <title>When to free a page</title> - - <para>Since the VM system uses all available memory for disk caching, - there are usually very few truly-free pages. The VM system depends on - being able to properly choose pages which are not in use to reuse for - new allocations. Selecting the optimal pages to free is possibly the - single-most important function any VM system can perform because if it - makes a poor selection, the VM system may be forced to unnecessarily - retrieve pages from disk, seriously degrading system performance.</para> - - <para>How much overhead are we willing to suffer in the critical path to - avoid freeing the wrong page? Each wrong choice we make will cost us - hundreds of thousands of CPU cycles and a noticeable stall of the - affected processes, so we are willing to endure a significant amount of - overhead in order to be sure that the right page is chosen. This is why - FreeBSD tends to outperform other systems when memory resources become - stressed.</para> - - <para>The free page determination algorithm is built upon a history of the - use of memory pages. To acquire this history, the system takes advantage - of a page-used bit feature that most hardware page tables have.</para> - - <para>In any case, the page-used bit is cleared and at some later point - the VM system comes across the page again and sees that the page-used - bit has been set. This indicates that the page is still being actively - used. If the bit is still clear it is an indication that the page is not - being actively used. By testing this bit periodically, a use history (in - the form of a counter) for the physical page is developed. When the VM - system later needs to free up some pages, checking this history becomes - the cornerstone of determining the best candidate page to reuse.</para> - - <sidebar> - <title>What if the hardware has no page-used bit?</title> - - <para>For those platforms that do not have this feature, the system - actually emulates a page-used bit. It unmaps or protects a page, - forcing a page fault if the page is accessed again. When the page - fault is taken, the system simply marks the page as having been used - and unprotects the page so that it may be used. While taking such page - faults just to determine if a page is being used appears to be an - expensive proposition, it is much less expensive than reusing the page - for some other purpose only to find that a process needs it back and - then have to go to disk.</para> - </sidebar> - - <para>FreeBSD makes use of several page queues to further refine the - selection of pages to reuse as well as to determine when dirty pages - must be flushed to their backing store. Since page tables are dynamic - entities under FreeBSD, it costs virtually nothing to unmap a page from - the address space of any processes using it. When a page candidate has - been chosen based on the page-use counter, this is precisely what is - done. The system must make a distinction between clean pages which can - theoretically be freed up at any time, and dirty pages which must first - be written to their backing store before being reusable. When a page - candidate has been found it is moved to the inactive queue if it is - dirty, or the cache queue if it is clean. A separate algorithm based on - the dirty-to-clean page ratio determines when dirty pages in the - inactive queue must be flushed to disk. Once this is accomplished, the - flushed pages are moved from the inactive queue to the cache queue. At - this point, pages in the cache queue can still be reactivated by a VM - fault at relatively low cost. However, pages in the cache queue are - considered to be ‘immediately freeable’ and will be reused - in an LRU (least-recently used) fashion when the system needs to - allocate new memory.</para> - - <para>It is important to note that the FreeBSD VM system attempts to - separate clean and dirty pages for the express reason of avoiding - unnecessary flushes of dirty pages (which eats I/O bandwidth), nor does - it move pages between the various page queues gratuitously when the - memory subsystem is not being stressed. This is why you will see some - systems with very low cache queue counts and high active queue counts - when doing a <command>systat -vm</command> command. As the VM system - becomes more stressed, it makes a greater effort to maintain the various - page queues at the levels determined to be the most effective. An urban - myth has circulated for years that Linux did a better job avoiding - swapouts than FreeBSD, but this in fact is not true. What was actually - occurring was that FreeBSD was proactively paging out unused pages in - order to make room for more disk cache while Linux was keeping unused - pages in core and leaving less memory available for cache and process - pages. I don't know whether this is still true today.</para> - </sect1> - - <sect1> - <title>Pre-Faulting and Zeroing Optimizations</title> - - <para>Taking a VM fault is not expensive if the underlying page is already - in core and can simply be mapped into the process, but it can become - expensive if you take a whole lot of them on a regular basis. A good - example of this is running a program such as &man.ls.1; or &man.ps.1; - over and over again. If the program binary is mapped into memory but - not mapped into the page table, then all the pages that will be accessed - by the program will have to be faulted in every time the program is run. - This is unnecessary when the pages in question are already in the VM - Cache, so FreeBSD will attempt to pre-populate a process's page tables - with those pages that are already in the VM Cache. One thing that - FreeBSD does not yet do is pre-copy-on-write certain pages on exec. For - example, if you run the &man.ls.1; program while running <command>vmstat - 1</command> you will notice that it always takes a certain number of - page faults, even when you run it over and over again. These are - zero-fill faults, not program code faults (which were pre-faulted in - already). Pre-copying pages on exec or fork is an area that could use - more study.</para> - - <para>A large percentage of page faults that occur are zero-fill faults. - You can usually see this by observing the <command>vmstat -s</command> - output. These occur when a process accesses pages in its BSS area. The - BSS area is expected to be initially zero but the VM system does not - bother to allocate any memory at all until the process actually accesses - it. When a fault occurs the VM system must not only allocate a new page, - it must zero it as well. To optimize the zeroing operation the VM system - has the ability to pre-zero pages and mark them as such, and to request - pre-zeroed pages when zero-fill faults occur. The pre-zeroing occurs - whenever the CPU is idle but the number of pages the system pre-zeros is - limited in order to avoid blowing away the memory caches. This is an - excellent example of adding complexity to the VM system in order to - optimize the critical path.</para> - </sect1> - - <sect1> - <title>Page Table Optimizations</title> - - <para>The page table optimizations make up the most contentious part of - the FreeBSD VM design and they have shown some strain with the advent of - serious use of <function>mmap()</function>. I think this is actually a - feature of most BSDs though I am not sure when it was first introduced. - There are two major optimizations. The first is that hardware page - tables do not contain persistent state but instead can be thrown away at - any time with only a minor amount of management overhead. The second is - that every active page table entry in the system has a governing - <literal>pv_entry</literal> structure which is tied into the - <literal>vm_page</literal> structure. FreeBSD can simply iterate - through those mappings that are known to exist while Linux must check - all page tables that <emphasis>might</emphasis> contain a specific - mapping to see if it does, which can achieve O(n^2) overhead in certain - situations. It is because of this that FreeBSD tends to make better - choices on which pages to reuse or swap when memory is stressed, giving - it better performance under load. However, FreeBSD requires kernel - tuning to accommodate large-shared-address-space situations such as - those that can occur in a news system because it may run out of - <literal>pv_entry</literal> structures.</para> - - <para>Both Linux and FreeBSD need work in this area. FreeBSD is trying to - maximize the advantage of a potentially sparse active-mapping model (not - all processes need to map all pages of a shared library, for example), - whereas Linux is trying to simplify its algorithms. FreeBSD generally - has the performance advantage here at the cost of wasting a little extra - memory, but FreeBSD breaks down in the case where a large file is - massively shared across hundreds of processes. Linux, on the other hand, - breaks down in the case where many processes are sparsely-mapping the - same shared library and also runs non-optimally when trying to determine - whether a page can be reused or not.</para> - </sect1> - - <sect1> - <title>Page Coloring</title> - - <para>We'll end with the page coloring optimizations. Page coloring is a - performance optimization designed to ensure that accesses to contiguous - pages in virtual memory make the best use of the processor cache. In - ancient times (i.e. 10+ years ago) processor caches tended to map - virtual memory rather than physical memory. This led to a huge number of - problems including having to clear the cache on every context switch in - some cases, and problems with data aliasing in the cache. Modern - processor caches map physical memory precisely to solve those problems. - This means that two side-by-side pages in a processes address space may - not correspond to two side-by-side pages in the cache. In fact, if you - aren't careful side-by-side pages in virtual memory could wind up using - the same page in the processor cache—leading to cacheable data - being thrown away prematurely and reducing CPU performance. This is true - even with multi-way set-associative caches (though the effect is - mitigated somewhat).</para> - - <para>FreeBSD's memory allocation code implements page coloring - optimizations, which means that the memory allocation code will attempt - to locate free pages that are contiguous from the point of view of the - cache. For example, if page 16 of physical memory is assigned to page 0 - of a process's virtual memory and the cache can hold 4 pages, the page - coloring code will not assign page 20 of physical memory to page 1 of a - process's virtual memory. It would, instead, assign page 21 of physical - memory. The page coloring code attempts to avoid assigning page 20 - because this maps over the same cache memory as page 16 and would result - in non-optimal caching. This code adds a significant amount of - complexity to the VM memory allocation subsystem as you can well - imagine, but the result is well worth the effort. Page Coloring makes VM - memory as deterministic as physical memory in regards to cache - performance.</para> - </sect1> - - <sect1> - <title>Conclusion</title> - - <para>Virtual memory in modern operating systems must address a number of - different issues efficiently and for many different usage patterns. The - modular and algorithmic approach that BSD has historically taken allows - us to study and understand the current implementation as well as - relatively cleanly replace large sections of the code. There have been a - number of improvements to the FreeBSD VM system in the last several - years, and work is ongoing.</para> - </sect1> - - <sect1> - <title>Bonus QA session by Allen Briggs - <email>briggs@ninthwonder.com</email></title> - - <qandaset> - <qandaentry> - <question> - <para>What is “the interleaving algorithm” that you - refer to in your listing of the ills of the FreeBSD 3.x swap - arrangments?</para> - </question> - - <answer> - <para>FreeBSD uses a fixed swap interleave which defaults to 4. This - means that FreeBSD reserves space for four swap areas even if you - only have one, two, or three. Since swap is interleaved the linear - address space representing the ‘four swap areas’ will be - fragmented if you don't actually have four swap areas. For - example, if you have two swap areas A and B FreeBSD's address - space representation for that swap area will be interleaved in - blocks of 16 pages:</para> - - <literallayout>A B C D A B C D A B C D A B C D</literallayout> - - <para>FreeBSD 3.x uses a ‘sequential list of free - regions’ approach to accounting for the free swap areas. - The idea is that large blocks of free linear space can be - represented with a single list node - (<filename>kern/subr_rlist.c</filename>). But due to the - fragmentation the sequential list winds up being insanely - fragmented. In the above example, completely unused swap will - have A and B shown as ‘free’ and C and D shown as - ‘all allocated’. Each A-B sequence requires a list - node to account for because C and D are holes, so the list node - cannot be combined with the next A-B sequence.</para> - - <para>Why do we interleave our swap space instead of just tack swap - areas onto the end and do something fancier? Because it's a whole - lot easier to allocate linear swaths of an address space and have - the result automatically be interleaved across multiple disks than - it is to try to put that sophistication elsewhere.</para> - - <para>The fragmentation causes other problems. Being a linear list - under 3.x, and having such a huge amount of inherent - fragmentation, allocating and freeing swap winds up being an O(N) - algorithm instead of an O(1) algorithm. Combined with other - factors (heavy swapping) and you start getting into O(N^2) and - O(N^3) levels of overhead, which is bad. The 3.x system may also - need to allocate KVM during a swap operation to create a new list - node which can lead to a deadlock if the system is trying to - pageout pages in a low-memory situation.</para> - - <para>Under 4.x we do not use a sequential list. Instead we use a - radix tree and bitmaps of swap blocks rather than ranged list - nodes. We take the hit of preallocating all the bitmaps required - for the entire swap area up front but it winds up wasting less - memory due to the use of a bitmap (one bit per block) instead of a - linked list of nodes. The use of a radix tree instead of a - sequential list gives us nearly O(1) performance no matter how - fragmented the tree becomes.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I don't get the following:</para> - - <blockquote> - <para>It is important to note that the FreeBSD VM system attempts - to separate clean and dirty pages for the express reason of - avoiding unnecessary flushes of dirty pages (which eats I/O - bandwidth), nor does it move pages between the various page - queues gratitously when the memory subsystem is not being - stressed. This is why you will see some systems with very low - cache queue counts and high active queue counts when doing a - <command>systat -vm</command> command.</para> - </blockquote> - - <para>How is the separation of clean and dirty (inactive) pages - related to the situation where you see low cache queue counts and - high active queue counts in <command>systat -vm</command>? Do the - systat stats roll the active and dirty pages together for the - active queue count?</para> - </question> - - <answer> - <para>Yes, that is confusing. The relationship is - “goal” verses “reality”. Our goal is to - separate the pages but the reality is that if we are not in a - memory crunch, we don't really have to.</para> - - <para>What this means is that FreeBSD will not try very hard to - separate out dirty pages (inactive queue) from clean pages (cache - queue) when the system is not being stressed, nor will it try to - deactivate pages (active queue -> inactive queue) when the system - is not being stressed, even if they aren't being used.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> In the &man.ls.1; / <command>vmstat 1</command> example, - wouldn't some of the page faults be data page faults (COW from - executable file to private page)? I.e., I would expect the page - faults to be some zero-fill and some program data. Or are you - implying that FreeBSD does do pre-COW for the program data?</para> - </question> - - <answer> - <para>A COW fault can be either zero-fill or program-data. The - mechanism is the same either way because the backing program-data - is almost certainly already in the cache. I am indeed lumping the - two together. FreeBSD does not pre-COW program data or zero-fill, - but it <emphasis>does</emphasis> pre-map pages that exist in its - cache.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>In your section on page table optimizations, can you give a - little more detail about <literal>pv_entry</literal> and - <literal>vm_page</literal> (or should vm_page be - <literal>vm_pmap</literal>—as in 4.4, cf. pp. 180-181 of - McKusick, Bostic, Karel, Quarterman)? Specifically, what kind of - operation/reaction would require scanning the mappings?</para> - - <para>How does Linux do in the case where FreeBSD breaks down - (sharing a large file mapping over many processes)?</para> - </question> - - <answer> - <para>A <literal>vm_page</literal> represents an (object,index#) - tuple. A <literal>pv_entry</literal> represents a hardware page - table entry (pte). If you have five processes sharing the same - physical page, and three of those processes's page tables actually - map the page, that page will be represented by a single - <literal>vm_page</literal> structure and three - <literal>pv_entry</literal> structures.</para> - - <para><literal>pv_entry</literal> structures only represent pages - mapped by the MMU (one <literal>pv_entry</literal> represnts one - pte). This means that when we need to remove all hardware - references to a <literal>vm_page</literal> (in order to reuse the - page for something else, page it out, clear it, dirty it, and so - forth) we can simply scan the linked list of - <literal>pv_entry</literal>'s associated with that - <literal>vm_page</literal> to remove or modify the pte's from - their page tables.</para> - - <para>Under Linux there is no such linked list. In order to remove - all the hardware page table mappings for a - <literal>vm_page</literal> linux must index into every VM object - that <emphasis>might</emphasis> have mapped the page. For - example, if you have 50 processes all mapping the same shared - library and want to get rid of page X in that library, you need to - index into the page table for each of those 50 processes even if - only 10 of them have actually mapped the page. So Linux is - trading off the simplicity of its design against performance. - Many VM algorithms which are O(1) or (small N) under FreeBSD wind - up being O(N), O(N^2), or worse under Linux. Since the pte's - representing a particular page in an object tend to be at the same - offset in all the page tables they are mapped in, reducing the - number of accesses into the page tables at the same pte offset - will often avoid blowing away the L1 cache line for that offset, - which can lead to better performance.</para> - - <para>FreeBSD has added complexity (the <literal>pv_entry</literal> - scheme) in order to increase performance (to limit page table - accesses to <emphasis>only</emphasis> those pte's that need to be - modified).</para> - - <para>But FreeBSD has a scaling problem that Linux does not in that - there are a limited number of <literal>pv_entry</literal> - structures and this causes problems when you have massive sharing - of data. In this case you may run out of - <literal>pv_entry</literal> structures even though there is plenty - of free memory available. This can be fixed easily enough by - bumping up the number of <literal>pv_entry</literal> structures in - the kernel config, but we really need to find a better way to do - it.</para> - - <para>In regards to the memory overhead of a page table verses the - <literal>pv_entry</literal> scheme: Linux uses - ‘permanent’ page tables that are not throw away, but - does not need a <literal>pv_entry</literal> for each potentially - mapped pte. FreeBSD uses ‘throw away’ page tables but - adds in a <literal>pv_entry</literal> structure for each - actually-mapped pte. I think memory utilization winds up being - about the same, giving FreeBSD an algorithmic advantage with its - ability to throw away page tables at will with very low - overhead.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Finally, in the page coloring section, it might help to have a - little more description of what you mean here. I didn't quite - follow it.</para> - </question> - - <answer> - <para>Do you know how an L1 hardware memory cache works? I'll - explain: Consider a machine with 16MB of main memory but only 128K - of L1 cache. Generally the way this cache works is that each 128K - block of main memory uses the <emphasis>same</emphasis> 128K of - cache. If you access offset 0 in main memory and then offset - offset 128K in main memory you can wind up throwing away the - cached data you read from offset 0!</para> - - <para>Now, I am simplifying things greatly. What I just described - is what is called a ‘direct mapped’ hardware memory - cache. Most modern caches are what are called - 2-way-set-associative or 4-way-set-associative caches. The - set-associatively allows you to access up to N different memory - regions that overlap the same cache memory without destroying the - previously cached data. But only N.</para> - - <para>So if I have a 4-way set associative cache I can access offset - 0, offset 128K, 256K and offset 384K and still be able to access - offset 0 again and have it come from the L1 cache. If I then - access offset 512K, however, one of the four previously cached - data objects will be thrown away by the cache.</para> - - <para>It is extremely important… - <emphasis>extremely</emphasis> important for most of a processor's - memory accesses to be able to come from the L1 cache, because the - L1 cache operates at the processor frequency. The moment you have - an L1 cahe miss and have to go to the L2 cache or to main memory, - the processor will stall and potentially sit twidling its fingers - for <emphasis>hundreds</emphasis> of instructions worth of time - waiting for a read from main memory to complete. Main memory (the - dynamic ram you stuff into a computer) is - <emphasis>slow</emphasis>, when compared to the speed of a modern - processor core.</para> - - <para>Ok, so now onto page coloring: All modern memory caches are - what are known as <emphasis>physical</emphasis> caches. They - cache physical memory addresses, not virtual memory addresses. - This allows the cache to be left alone across a process context - switch, which is very important.</para> - - <para>But in the UNIX world you are dealing with virtual address - spaces, not physical address spaces. Any program you write will - see the virtual address space given to it. The actual - <emphasis>physical</emphasis> pages underlying that virtual - address space are not necessarily physically contiguous! In fact, - you might have two pages that are side by side in a processes - address space which wind up being at offset 0 and offset 128K in - <emphasis>physical</emphasis> memory.</para> - - <para>A program normally assumes that two side-by-side pages will be - optimally cached. That is, that you can access data objects in - both pages without having them blow away each other's cache entry. - But this is only true if the physical pages underlying the virtual - address space are contiguous (insofar as the cache is - concerned).</para> - - <para>This is what Page coloring does. Instead of assigning - <emphasis>random</emphasis> physical pages to virtual addresses, - which may result in non-optimal cache performance , Page coloring - assigns <emphasis>reasonably-contiguous</emphasis> physical pages - to virtual addresses. Thus programs can be written under the - assumption that the characteristics of the underlying hardware - cache are the same for their virtual address space as they would - be if the program had been run directly in a physical address - space.</para> - - <para>Note that I say ‘reasonably’ contiguous rather - than simply ‘contiguous’. From the point of view of a - 128K direct mapped cache, the physical address 0 is the same as - the physical address 128K. So two side-by-side pages in your - virtual address space may wind up being offset 128K and offset - 132K in physical memory, but could also easily be offset 128K and - offset 4K in physical memory and still retain the same cache - performance characteristics. So page-coloring does - <emphasis>not</emphasis> have to assign truly contiguous pages of - physical memory to contiguous pages of virtual memory, it just - needs to make sure it assigns contiguous pages from the point of - view of cache performance and operation.</para> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/articles/vm-design/fig1.eps b/en_US.ISO_8859-1/articles/vm-design/fig1.eps deleted file mode 100644 index 49d2c05a56..0000000000 --- a/en_US.ISO_8859-1/articles/vm-design/fig1.eps +++ /dev/null @@ -1,104 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: fig1.eps -%%Creator: fig2dev Version 3.2.3 Patchlevel -%%CreationDate: Sun Oct 8 19:54:25 2000 -%%For: nik@canyon.nothing-going-on.org (Nik Clayton) -%%BoundingBox: 0 0 119 65 -%%Magnification: 1.0000 -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {0 setgray} bind def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save -newpath 0 65 moveto 0 0 lineto 119 0 lineto 119 65 lineto closepath clip newpath --143.0 298.0 translate -1 -1 scale - -/cp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/sa {save} bind def -/rs {restore} bind def -/l {lineto} bind def -/m {moveto} bind def -/rm {rmoveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/sh {show} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/sd {setdash} bind def -/ff {findfont} bind def -/sf {setfont} bind def -/scf {scalefont} bind def -/sw {stringwidth} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def - -$F2psBegin -%%Page: 1 1 -10 setmiterlimit - 0.06000 0.06000 sc -% Polyline -7.500 slw -n 2400 4200 m 4050 4200 l 4050 4950 l 2400 4950 l - cp gs col0 s gr -% Polyline -n 4050 4200 m - 4350 3900 l gs col0 s gr -% Polyline -n 2400 4200 m 2700 3900 l 4350 3900 l 4350 4650 l - 4050 4950 l gs col0 s gr -/Helvetica-Bold ff 180.00 scf sf -3225 4650 m -gs 1 -1 sc (A) dup sw pop 2 div neg 0 rm col0 sh gr -$F2psEnd -rs diff --git a/en_US.ISO_8859-1/articles/vm-design/fig2.eps b/en_US.ISO_8859-1/articles/vm-design/fig2.eps deleted file mode 100644 index fcb8bd41ad..0000000000 --- a/en_US.ISO_8859-1/articles/vm-design/fig2.eps +++ /dev/null @@ -1,115 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: fig2.eps -%%Creator: fig2dev Version 3.2.3 Patchlevel -%%CreationDate: Sun Oct 8 19:55:31 2000 -%%For: nik@canyon.nothing-going-on.org (Nik Clayton) -%%BoundingBox: 0 0 120 110 -%%Magnification: 1.0000 -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {0 setgray} bind def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save -newpath 0 110 moveto 0 0 lineto 120 0 lineto 120 110 lineto closepath clip newpath --174.0 370.0 translate -1 -1 scale - -/cp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/sa {save} bind def -/rs {restore} bind def -/l {lineto} bind def -/m {moveto} bind def -/rm {rmoveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/sh {show} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/sd {setdash} bind def -/ff {findfont} bind def -/sf {setfont} bind def -/scf {scalefont} bind def -/sw {stringwidth} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def - -$F2psBegin -%%Page: 1 1 -10 setmiterlimit - 0.06000 0.06000 sc -/Helvetica-Bold ff 180.00 scf sf -3750 5100 m -gs 1 -1 sc (B) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -7.500 slw -n 4871 5100 m 4879 5100 l gs col0 s gr -% Polyline -n 2925 5400 m 4575 5400 l 4575 6150 l 2925 6150 l - cp gs col0 s gr -% Polyline -n 4575 4650 m - 4875 4350 l gs col0 s gr -% Polyline -n 2925 4650 m 4575 4650 l 4575 5400 l 2925 5400 l - cp gs col0 s gr -% Polyline -n 2925 4650 m 3225 4350 l 4875 4350 l 4875 5100 l - 4575 5400 l gs col0 s gr -/Helvetica-Bold ff 180.00 scf sf -3750 5850 m -gs 1 -1 sc (A) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -n 4875 5100 m 4875 5850 l - 4575 6150 l gs col0 s gr -$F2psEnd -rs diff --git a/en_US.ISO_8859-1/articles/vm-design/fig3.eps b/en_US.ISO_8859-1/articles/vm-design/fig3.eps deleted file mode 100644 index 0e3138b2ed..0000000000 --- a/en_US.ISO_8859-1/articles/vm-design/fig3.eps +++ /dev/null @@ -1,133 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: fig3.eps -%%Creator: fig2dev Version 3.2.3 Patchlevel -%%CreationDate: Sun Oct 8 19:53:51 2000 -%%For: nik@canyon.nothing-going-on.org (Nik Clayton) -%%BoundingBox: 0 0 120 155 -%%Magnification: 1.0000 -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {0 setgray} bind def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save -newpath 0 155 moveto 0 0 lineto 120 0 lineto 120 155 lineto closepath clip newpath --174.0 370.0 translate -1 -1 scale - -/cp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/sa {save} bind def -/rs {restore} bind def -/l {lineto} bind def -/m {moveto} bind def -/rm {rmoveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/sh {show} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/sd {setdash} bind def -/ff {findfont} bind def -/sf {setfont} bind def -/scf {scalefont} bind def -/sw {stringwidth} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def - -$F2psBegin -%%Page: 1 1 -10 setmiterlimit - 0.06000 0.06000 sc -/Helvetica-Bold ff 180.00 scf sf -4125 4350 m -gs 1 -1 sc (C2) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -7.500 slw -n 4871 5100 m 4879 5100 l gs col0 s gr -% Polyline -n 2925 5400 m 4575 5400 l 4575 6150 l 2925 6150 l - cp gs col0 s gr -% Polyline -n 4575 4650 m - 4875 4350 l gs col0 s gr -% Polyline -n 2925 4650 m 4575 4650 l 4575 5400 l 2925 5400 l - cp gs col0 s gr -% Polyline -n 4875 3600 m 4875 5100 l - 4575 5400 l gs col0 s gr -% Polyline -n 2925 4650 m 2925 3900 l 3225 3600 l - 4875 3600 l gs col0 s gr -% Polyline -n 2925 3900 m 4425 3900 l 4575 3900 l - 4875 3600 l gs col0 s gr -% Polyline -n 4575 4650 m - 4575 3900 l gs col0 s gr -% Polyline -n 3750 4650 m 3750 3900 l - 4050 3600 l gs col0 s gr -/Helvetica-Bold ff 180.00 scf sf -3750 5850 m -gs 1 -1 sc (A) dup sw pop 2 div neg 0 rm col0 sh gr -/Helvetica-Bold ff 180.00 scf sf -3750 5100 m -gs 1 -1 sc (B) dup sw pop 2 div neg 0 rm col0 sh gr -/Helvetica-Bold ff 180.00 scf sf -3375 4350 m -gs 1 -1 sc (C1) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -n 4875 5100 m 4875 5850 l - 4575 6150 l gs col0 s gr -$F2psEnd -rs diff --git a/en_US.ISO_8859-1/articles/vm-design/fig4.eps b/en_US.ISO_8859-1/articles/vm-design/fig4.eps deleted file mode 100644 index 24fc1b5add..0000000000 --- a/en_US.ISO_8859-1/articles/vm-design/fig4.eps +++ /dev/null @@ -1,133 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: fig4.eps -%%Creator: fig2dev Version 3.2.3 Patchlevel -%%CreationDate: Sun Oct 8 19:55:53 2000 -%%For: nik@canyon.nothing-going-on.org (Nik Clayton) -%%BoundingBox: 0 0 120 155 -%%Magnification: 1.0000 -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {0 setgray} bind def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save -newpath 0 155 moveto 0 0 lineto 120 0 lineto 120 155 lineto closepath clip newpath --174.0 370.0 translate -1 -1 scale - -/cp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/sa {save} bind def -/rs {restore} bind def -/l {lineto} bind def -/m {moveto} bind def -/rm {rmoveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/sh {show} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/sd {setdash} bind def -/ff {findfont} bind def -/sf {setfont} bind def -/scf {scalefont} bind def -/sw {stringwidth} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def - -$F2psBegin -%%Page: 1 1 -10 setmiterlimit - 0.06000 0.06000 sc -/Helvetica-Bold ff 180.00 scf sf -3375 4350 m -gs 1 -1 sc (C1) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -7.500 slw -n 4871 5100 m 4879 5100 l gs col0 s gr -% Polyline -n 2925 5400 m 4575 5400 l 4575 6150 l 2925 6150 l - cp gs col0 s gr -% Polyline -n 4575 4650 m - 4875 4350 l gs col0 s gr -% Polyline -n 2925 4650 m 4575 4650 l 4575 5400 l 2925 5400 l - cp gs col0 s gr -% Polyline -n 4875 4350 m 4875 5100 l - 4575 5400 l gs col0 s gr -% Polyline -n 2925 4650 m 2925 3900 l 3225 3600 l - 4050 3600 l gs col0 s gr -% Polyline -n 3750 4650 m 3750 3900 l - 4050 3600 l gs col0 s gr -% Polyline -n 2925 3900 m - 3750 3900 l gs col0 s gr -% Polyline -n 3750 4650 m 4050 4350 l - 4875 4350 l gs col0 s gr -% Polyline -n 4050 4350 m - 4050 3600 l gs col0 s gr -/Helvetica-Bold ff 180.00 scf sf -3750 5850 m -gs 1 -1 sc (A) dup sw pop 2 div neg 0 rm col0 sh gr -/Helvetica-Bold ff 180.00 scf sf -3750 5100 m -gs 1 -1 sc (B) dup sw pop 2 div neg 0 rm col0 sh gr -% Polyline -n 4875 5100 m 4875 5850 l - 4575 6150 l gs col0 s gr -$F2psEnd -rs diff --git a/en_US.ISO_8859-1/articles/zip-drive/Makefile b/en_US.ISO_8859-1/articles/zip-drive/Makefile deleted file mode 100644 index 60f4a450ea..0000000000 --- a/en_US.ISO_8859-1/articles/zip-drive/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -# $FreeBSD: doc/en_US.ISO_8859-1/articles/programming-tools/Makefile,v 1.8 1999/09/06 06:52:38 peter Exp $ - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/zip-drive/article.sgml b/en_US.ISO_8859-1/articles/zip-drive/article.sgml deleted file mode 100644 index 4e1aeeacaa..0000000000 --- a/en_US.ISO_8859-1/articles/zip-drive/article.sgml +++ /dev/null @@ -1,267 +0,0 @@ -<!-- $FreeBSD --> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; -]> - -<article> - <articleinfo> - <title>ZIP Drives</title> - - <authorgroup> - <author> - <firstname>Jason</firstname> - <surname>Bacon</surname> - - <affiliation> - <address><email>acadix@execpc.com</email></address> - </affiliation> - </author> - </authorgroup> - </articleinfo> - - <sect1> - <title>ZIP Drive Basics</title> - - <para>ZIP disks are high capacity, removable, magnetic disks, which can be - read or written by ZIP drives from iomega corporation. ZIP disks are - similar to floppy disks, except that they are much faster, and have a - much greater capacity. While floppy disks typically hold 1.44 - megabytes, ZIP disks are available in two sizes, namely 100 megabytes - and 250 megabytes. ZIP drives should not be confused with the - super-floppy, a 120 megabyte floppy drive which also handles traditional - 1.44 megabyte floppies.</para> - - <para>IOMEGA also sells a higher capacity, higher performance drive - called the JAZZ drive. JAZZ drives come in 1 gigabyte and - 2 gigabyte sizes.</para> - - <para>ZIP drives are available as internal or external units, using one - of three interfaces:</para> - - <orderedlist> - <listitem> - <para>The SCSI (Small Computer Standard Interface) interface is the - fastest, most sophisticated, most expandable, and most expensive - interface. The SCSI interface is used by all types of computers - from PC's to RISC workstations to minicomputers, to connect all - types of peripherals such as disk drives, tape drives, scanners, and - so on. SCSI ZIP drives may be internal or external, assuming your - host adapter has an external connector.</para> - - <note> - <para>If you are using an external SCSI device, it is important - never to connect or disconnect it from the SCSI bus while the - computer is running. Doing so may cause file-system damage on the - disks that remain connected.</para> - </note> - - <para>If you want maximum performance and easy setup, the SCSI - interface is the best choice. This will probably require adding a - SCSI host adapter, since most PC's (except for high-performance - servers) don't have built-in SCSI support. Each SCSI host adapter - can support either 7 or 15 SCSI devices, depending on the - model.</para> - - <para>Each SCSI device has it's own controller, and these - controllers are fairly intelligent and well standardized, (the - second `S' in SCSI is for Standard) so from the operating system's - point of view, all SCSI disk drives look about the same, as do all - SCSI tape drives, etc. To support SCSI devices, the operating - system need only have a driver for the particular host adapter, and - a generic driver for each type of device, i.e. a SCSI disk driver, - SCSI tape driver, and so on. There are some SCSI devices that can - be better utilized with specialized drivers (e.g. DAT tape drives), - but they tend to work OK with the generic driver, too. It's just - that the generic drivers may not support some of the special - features.</para> - - <para>Using a SCSI zip drive is simply a matter of determining which - device file in the <filename>/dev</filename> directory represents - the ZIP drive. This can be determined by looking at the boot - messages while FreeBSD is booting (or in - <filename>/var/log/messages</filename> after booting), where you'll - see a line something like this:</para> - - <programlisting>da1: <IOMEGA ZIP 100 D.13> Removable Direct Access SCSI-2 Device</programlisting> - - <para>This means that the ZIP drive is represented by the file - <filename>/dev/da1</filename>.</para> - </listitem> - - <listitem> - <para>The IDE (Integrated Drive Electronics) interface is a low-cost - disk drive interface used by many desktop PC's. Most IDE devices - are strictly internal.</para> - - <para>Performance of IDE ZIP drives is comparable to SCSI ZIP drives. - (The IDE interface is not as fast as SCSI, but ZIP drives - performance is limited mainly by the mechanics of the drive, not by - the bus interface.)</para> - - <para>The drawback of the IDE interface is the limitations it imposes. - Most IDE adapters can only support 2 devices, and IDE interfaces are - not typically designed for the long term. For example, the original - IDE interface would not support hard disks with more than 1024 - cylinders, which forced a lot of people to upgrade their hardware - prematurely. If you have plans to expand your PC by adding another - disk, a tape drive, or scanner, you may want to invest in a SCSI - host adapter and a SCSI ZIP drive to avoid problems in the - future.</para> - - <para>IDE devices in FreeBSD are prefixed with a <literal>w</literal>. - For example, an IDE hard disk might be - <filename>/dev/wd0</filename>, an IDE (ATAPI) cdrom might be - <filename>/dev/wcd1</filename>, and so on.</para> - </listitem> - - <listitem> - <para>The parallel port interface is popular for portable external - devices such as external ZIP drives and scanners, because virtually - every computer has a standard parallel port (usually used for - printers). This makes things easy for people to transfer data - between multiple computers by toting around their ZIP drive.</para> - - <para>Performance will generally be slower than a SCSI or IDE ZIP - drive, since it is limited by the speed of the parallel port. - Parallel port speed varies considerably between various computers, - and can often be configured in the system BIOS. Some machines - will also require BIOS configuration to operate the parallel - port in bidirectional mode. (Parallel ports were originally - designed only for output to printers)</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>Parallel ZIP: The <devicename>vpo</devicename> Driver</title> - - <para>To use a parallel-port ZIP drive under FreeBSD, the - <devicename>vpo</devicename> driver must be configured into the kernel. - Parallel port ZIP drives also have a built-in SCSI controller. The vpo - driver allows the FreeBSD kernel to communicate with the ZIP drive's - SCSI controller through the parallel port.</para> - - <para>Since the vpo driver is not a standard part of the kernel (as of - FreeBSD 3.2), you will need to rebuild the kernel to enable this device. - The process of building a kernel is outlined in detail in another - section. The following steps outline the process in brief for the - purpose of enabling the vpo driver:</para> - - <orderedlist> - <listitem> - <para>Run <command>/stand/sysinstall</command>, and install the kernel - source code on your system.</para> - - <screen>&prompt.root; <userinput>cd /sys/i386/conf</userinput> -&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen> - - <para>Edit <filename>MYKERNEL</filename>, change the - <literal>ident</literal> line to <literal>MYKERNEL</literal>, and - uncomment the line describing the vpo driver.</para> - - <para>If you have a second parallel port, you may need to copy the - section for <literal>ppc0</literal> to create a - <literal>ppc1</literal> device. The second parallel port usually - uses IRQ 5 and address 378. Only the IRQ is required in the config - file.</para> - - <para>If you're root hard disk is a SCSI disk, you might run into a - problem with probing order, which will cause the system to attempt - to use the ZIP drive as the root device. This will cause a boot - failure, unless you happen to have a FreeBSD root file-system on - your ZIP disk! In this case, you will need to <quote>wire - down</quote> the root disk, i.e. force the kernel to bind a - specific device to <filename>/dev/da0</filename>, the root SCSI - disk. It will then assign the ZIP disk to the next available SCSI - disk, e.g. <literal>/dev/da1</literal>. To wire down your SCSI hard - drive as <literal>da0</literal>, change the line - - <programlisting>device da0</programlisting> - - to - - <programlisting>disk da0 at scbus0 target 0 unit 0</programlisting></para> - - <para>You may need to change the target above to match the SCSI ID of - your disk drive. You should also wire down the scbus0 entry to your - controller. For example, if you have an Adaptec 15xx controller, - you would change - - <programlisting>controller scbus0</programlisting> - - to - - <programlisting>controller scbus0 at aha0</programlisting></para> - - <para>Lastly, as long as you're editing the kernel config, you - can take the opportunity to remove all the unnecessary drivers. This - should be done with a great deal of caution, and only if you feel - confident about making kernel modifications. Removing unnecessary - drivers will reduce the kernel size, leaving more memory available - for your applications. To determine which drivers are not needed, - go to the end of the file <filename>/var/log/messages</filename>, and look for lines - reading "not found". Then, comment out these devices in your config - file. You can also change other options to reduce the size and - increase the speed of your kernel. Read the section on rebuilding - your kernel for more complete information.</para> - </listitem> - - <listitem> - <para>Now it's time to compile the kernel:</para> - - <screen>&prompt.root; <userinput>/usr/sbin/config MYKERNEL</userinput> -&prompt.root; <userinput>cd ../../compile/MYKERNEL</userinput> -&prompt.root; <userinput>make clean depend && make all install</userinput></screen> - </listitem> - </orderedlist> - - <para>After the kernel is rebuilt, you'll need to reboot. Make sure the - ZIP drive is connected to the parallel port before the boot begins. You - should see the ZIP drive show up in the boot messages as device vpo0 or - vpo1, depending on which parallel port the drive is attached to. It - should also show which device file the ZIP drive has been bound to. This - will be <filename>/dev/da0</filename> if you have no other SCSI disks in - the system, or <filename>/dev/da1</filename> if you have a SCSI hard - disk wired down as the root device.</para> - </sect1> - - <sect1> - <title>Mounting ZIP disks</title> - - <para>To access the ZIP disk, you simply mount it like any other disk - device. The file-system is represented as slice 4 on the device, so for - SCSI or parallel ZIP disks, you would use:</para> - - <screen>&prompt.root; <userinput>mount_msdos /dev/da1s4 /mnt</userinput></screen> - - <para>For IDE ZIP drives, use:</para> - - <screen>&prompt.root; <userinput>mount_msdos /dev/wd1s4 /mnt</userinput></screen> - - <para>It will also be helpful to update <filename>/etc/fstab</filename> to - make mounting easier. Add a line like the following, edited to suit your - system: - - <programlisting>/dev/da1s4 /zip msdos rw,noauto 0 0</programlisting> - - and create the directory <filename>/zip</filename>.</para> - - <para>Then, you can mount simply by typing - - <screen>&prompt.root; <userinput>mount /zip</userinput></screen> - - and unmount by typing - - <screen>&prompt.root; <userinput>umount /zip</userinput></screen></para> - - <para>For more information on the format of - <filename>/etc/fstab</filename>, see &man.fstab.5;.</para> - - <para>You can also create a FreeBSD file-system on the ZIP disk - using &man.newfs.8;. However, the disk will only be usable on a FreeBSD - system, or perhaps a few other Unix clones that recognize FreeBSD - file-systems. (Definitely not DOS or Windows.)</para> - </sect1> -</article> diff --git a/en_US.ISO_8859-1/books/Makefile b/en_US.ISO_8859-1/books/Makefile deleted file mode 100644 index de2ed2f597..0000000000 --- a/en_US.ISO_8859-1/books/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -# $FreeBSD: doc/en_US.ISO_8859-1/books/Makefile,v 1.9 2001/04/09 20:41:33 nik Exp $ - -SUBDIR = corp-net-guide -SUBDIR+= design-44bsd -SUBDIR+= developers-handbook -SUBDIR+= faq -SUBDIR+= fdp-primer -SUBDIR+= handbook -SUBDIR+= porters-handbook -SUBDIR+= ppp-primer - -ROOT_SYMLINKS= faq handbook - -DOC_PREFIX?= ${.CURDIR}/../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/books/Makefile.inc b/en_US.ISO_8859-1/books/Makefile.inc deleted file mode 100644 index b9219d69af..0000000000 --- a/en_US.ISO_8859-1/books/Makefile.inc +++ /dev/null @@ -1,5 +0,0 @@ -# -# $FreeBSD$ -# - -DESTDIR?= ${DOCDIR}/en_US.ISO_8859-1/books/${.CURDIR:T} diff --git a/en_US.ISO_8859-1/books/corp-net-guide/08-01.eps b/en_US.ISO_8859-1/books/corp-net-guide/08-01.eps deleted file mode 100644 index a23990fc07..0000000000 --- a/en_US.ISO_8859-1/books/corp-net-guide/08-01.eps +++ /dev/null @@ -1,8104 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%Creator: Adobe Illustrator(R) 8.0 -%%AI8_CreatorVersion: 8.0.1 -%%For: (Mark Bergeron) (PD&PS) -%%Title: (08-01 3594) -%%CreationDate: (11/21/00) (9:07 AM) -%%BoundingBox: 150 275 421 404 -%%HiResBoundingBox: 150.9429 275.7031 420.7891 403.7451 -%%DocumentProcessColors: Black -%%DocumentFonts: Formata-Bold -%%+ Helvetica -%%DocumentNeededFonts: Formata-Bold -%%+ Helvetica -%%DocumentSuppliedResources: procset Adobe_level2_AI5 1.2 0 -%%+ procset Adobe_typography_AI5 1.0 1 -%%+ procset Adobe_ColorImage_AI6 1.3 0 -%%+ procset Adobe_Illustrator_AI5 1.3 0 -%%+ procset Adobe_cshow 2.0 8 -%%+ procset Adobe_shading_AI8 1.0 0 -%AI5_FileFormat 4.0 -%AI3_ColorUsage: Black&White -%AI3_IncludePlacedImages -%AI7_ImageSettings: 1 -%%CMYKProcessColor: 0 0 0 0.15 (15%) -%%+ 0 0 0 0.3 (30%) -%%+ 0 0 0 0.5 (50%) -%%+ 0 0 0 0.75 (75%) -%%+ 1 1 1 1 ([Registration]) -%%AI6_ColorSeparationSet: 1 1 (AI6 Default Color Separation Set) -%%+ Options: 1 16 0 1 0 1 1 1 0 1 1 1 1 18 0 0 0 0 0 0 0 0 -1 -1 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 1 2 3 4 -%%+ PPD: 1 21 0 0 60 45 2 2 1 0 0 1 0 0 0 0 0 0 0 0 0 0 () -%AI3_TemplateBox: 306.5 395.5 306.5 395.5 -%AI3_TileBox: 12 14 600 782 -%AI3_DocumentPreview: Macintosh_ColorPic -%AI5_ArtSize: 612 792 -%AI5_RulerUnits: 3 -%AI5_ArtFlags: 1 0 0 1 0 0 1 0 0 -%AI5_TargetResolution: 800 -%AI5_NumLayers: 1 -%AI8_OpenToView: 147 503 2.3424 1137 777 18 0 1 7 40 0 0 -%AI5_OpenViewLayers: 7 -%%PageOrigin:12 14 -%%AI3_PaperRect:-12 782 600 -10 -%%AI3_Margin:12 -14 -12 10 -%AI7_GridSettings: 12 3 12 3 1 0 0.29 1 1 0.65 1 1 -%%EndComments -%%BeginProlog -%%BeginResource: procset Adobe_level2_AI5 1.2 0 -%%Title: (Adobe Illustrator (R) Version 5.0 Level 2 Emulation) -%%Version: 1.2 0 -%%CreationDate: (04/10/93) () -%%Copyright: ((C) 1987-1996 Adobe Systems Incorporated All Rights Reserved) -userdict /Adobe_level2_AI5 26 dict dup begin - put - /packedarray where not - { - userdict begin - /packedarray - { - array astore readonly - } bind def - /setpacking /pop load def - /currentpacking false def - end - 0 - } if - pop - userdict /defaultpacking currentpacking put true setpacking - /initialize - { - Adobe_level2_AI5 begin - } bind def - /terminate - { - currentdict Adobe_level2_AI5 eq - { - end - } if - } bind def - mark - /setcustomcolor where not - { - /findcmykcustomcolor - { - (AI8_CMYK_CustomColor) - 6 packedarray - } bind def - /findrgbcustomcolor - { - (AI8_RGB_CustomColor) - 5 packedarray - } bind def - /setcustomcolor - { - exch - aload pop dup - (AI8_CMYK_CustomColor) eq - { - pop pop - 4 - { - 4 index mul - 4 1 roll - } repeat - 5 -1 roll pop - setcmykcolor - } - { - dup (AI8_RGB_CustomColor) eq - { - pop pop - 3 - { - 1 exch sub - 3 index mul - 1 exch sub - 3 1 roll - } repeat - 4 -1 roll pop - setrgbcolor - } - { - pop - 4 - { - 4 index mul 4 1 roll - } repeat - 5 -1 roll pop - setcmykcolor - } ifelse - } ifelse - } - def - } if - /setAIseparationgray - { - false setoverprint - 0 setgray - /setseparationgray where{ - pop setseparationgray - }{ - /setcolorspace where{ - pop - [/Separation (All) /DeviceCMYK {dup dup dup}] setcolorspace - 1 exch sub setcolor - }{ - setgray - }ifelse - }ifelse - } def - - /gt38? mark {version cvr cvx exec} stopped {cleartomark true} {38 gt exch pop} ifelse def - userdict /deviceDPI 72 0 matrix defaultmatrix dtransform dup mul exch dup mul add sqrt put - userdict /level2? - systemdict /languagelevel known dup - { - pop systemdict /languagelevel get 2 ge - } if - put -/level2ScreenFreq -{ - begin - 60 - HalftoneType 1 eq - { - pop Frequency - } if - HalftoneType 2 eq - { - pop GrayFrequency - } if - HalftoneType 5 eq - { - pop Default level2ScreenFreq - } if - end -} bind def -userdict /currentScreenFreq - level2? {currenthalftone level2ScreenFreq} {currentscreen pop pop} ifelse put -level2? not - { - /setcmykcolor where not - { - /setcmykcolor - { - exch .11 mul add exch .59 mul add exch .3 mul add - 1 exch sub setgray - } def - } if - /currentcmykcolor where not - { - /currentcmykcolor - { - 0 0 0 1 currentgray sub - } def - } if - /setoverprint where not - { - /setoverprint /pop load def - } if - /selectfont where not - { - /selectfont - { - exch findfont exch - dup type /arraytype eq - { - makefont - } - { - scalefont - } ifelse - setfont - } bind def - } if - /cshow where not - { - /cshow - { - [ - 0 0 5 -1 roll aload pop - ] cvx bind forall - } bind def - } if - } if - cleartomark - /anyColor? - { - add add add 0 ne - } bind def - /testColor - { - gsave - setcmykcolor currentcmykcolor - grestore - } bind def - /testCMYKColorThrough - { - testColor anyColor? - } bind def - userdict /composite? - 1 0 0 0 testCMYKColorThrough - 0 1 0 0 testCMYKColorThrough - 0 0 1 0 testCMYKColorThrough - 0 0 0 1 testCMYKColorThrough - and and and - put - composite? not - { - userdict begin - gsave - /cyan? 1 0 0 0 testCMYKColorThrough def - /magenta? 0 1 0 0 testCMYKColorThrough def - /yellow? 0 0 1 0 testCMYKColorThrough def - /black? 0 0 0 1 testCMYKColorThrough def - grestore - /isCMYKSep? cyan? magenta? yellow? black? or or or def - /customColor? isCMYKSep? not def - end - } if - end defaultpacking setpacking -%%EndResource -%%BeginResource: procset Adobe_typography_AI5 1.0 1 -%%Title: (Typography Operators) -%%Version: 1.0 1 -%%CreationDate:(6/10/1996) () -%%Copyright: ((C) 1987-1996 Adobe Systems Incorporated All Rights Reserved) -currentpacking true setpacking -userdict /Adobe_typography_AI5 68 dict dup begin -put -/initialize -{ - begin - begin - Adobe_typography_AI5 begin - Adobe_typography_AI5 - { - dup xcheck - { - bind - } if - pop pop - } forall - end - end - end - Adobe_typography_AI5 begin -} def -/terminate -{ - currentdict Adobe_typography_AI5 eq - { - end - } if -} def -/modifyEncoding -{ - /_tempEncode exch ddef - /_pntr 0 ddef - { - counttomark -1 roll - dup type dup /marktype eq - { - pop pop exit - } - { - /nametype eq - { - _tempEncode /_pntr dup load dup 3 1 roll 1 add ddef 3 -1 roll - put - } - { - /_pntr exch ddef - } ifelse - } ifelse - } loop - _tempEncode -} def -/havefont -{ - systemdict /languagelevel known - { - /Font resourcestatus dup - { exch pop exch pop } - if - } - { - systemdict /FontDirectory get 1 index known - { pop true } - { - systemdict /fileposition known - { - dup length 6 add exch - Ss 6 250 getinterval - cvs pop - Ss exch 0 exch getinterval - status - { pop pop pop pop true } - { false } - ifelse - } - { - pop false - } - ifelse - } - ifelse - } - ifelse -} def -/TE -{ - StandardEncoding 256 array copy modifyEncoding - /_nativeEncoding exch def -} def -/subststring { - exch 2 index exch search - { - exch pop - exch dup () eq - { - pop exch concatstring - } - { - 3 -1 roll - exch concatstring - concatstring - } ifelse - exch pop true - } - { - pop pop false - } ifelse -} def -/concatstring { - 1 index length 1 index length - 1 index add - string - dup 0 5 index putinterval - dup 2 index 4 index putinterval - 4 1 roll pop pop pop -} def -% -/TZ -{ - dup type /arraytype eq - { - /_wv exch def - } - { - /_wv 0 def - } ifelse - /_useNativeEncoding exch def - 2 index havefont - { - 3 index - 255 string - cvs - - dup - (_Symbol_) - eq - { - pop - 2 index - findfont - - } - { - 1 index 0 eq - { - dup length 1 sub - 1 exch - getinterval - - cvn - findfont - } - { - pop 2 index findfont - } ifelse - } ifelse - } - { - dup 1 eq - { - 2 index 64 string cvs - dup (-90pv-RKSJ-) (-83pv-RKSJ-) subststring - { - exch pop dup havefont - { - findfont false - } - { - pop true - } ifelse - } - { - pop dup - (-90ms-RKSJ-) (-Ext-RKSJ-) subststring - { - exch pop dup havefont - { - findfont false - } - { - pop true - } ifelse - } - { - pop pop true - } ifelse - } ifelse - { - 1 index 1 eq - { - /Ryumin-Light-Ext-RKSJ-V havefont - {/Ryumin-Light-Ext-RKSJ-V} - {/Courier} - ifelse - } - { - /Ryumin-Light-83pv-RKSJ-H havefont - {/Ryumin-Light-83pv-RKSJ-H} - {/Courier} - ifelse - } ifelse - findfont - [1 0 0.5 1 0 0] makefont - } if - } - { - /Courier findfont - } ifelse - } ifelse - _wv type /arraytype eq - { - _wv makeblendedfont - } if - dup length 10 add dict - begin - mark exch - { - 1 index /FID ne - { - def - } if - cleartomark mark - } forall - pop - /FontScript exch def - /FontDirection exch def - /FontRequest exch def - /FontName exch def - counttomark 0 eq - { - 1 _useNativeEncoding eq - { - /Encoding _nativeEncoding def - } if - cleartomark - } - { - /Encoding load 256 array copy - modifyEncoding /Encoding exch def - } ifelse - FontName currentdict - end - definefont pop -} def -/tr -{ - _ax _ay 3 2 roll -} def -/trj -{ - _cx _cy _sp _ax _ay 6 5 roll -} def -/a0 -{ - /Tx - { - dup - currentpoint 3 2 roll - tr _psf - newpath moveto - tr _ctm _pss - } ddef - /Tj - { - dup - currentpoint 3 2 roll - trj _pjsf - newpath moveto - trj _ctm _pjss - } ddef -} def -/a1 -{ -W B -} def -/e0 -{ - /Tx - { - tr _psf - } ddef - /Tj - { - trj _pjsf - } ddef -} def -/e1 -{ -W F -} def -/i0 -{ - /Tx - { - tr sp - } ddef - /Tj - { - trj jsp - } ddef -} def -/i1 -{ - W N -} def -/o0 -{ - /Tx - { - tr sw rmoveto - } ddef - /Tj - { - trj swj rmoveto - } ddef -} def -/r0 -{ - /Tx - { - tr _ctm _pss - } ddef - /Tj - { - trj _ctm _pjss - } ddef -} def -/r1 -{ -W S -} def -/To -{ - pop _ctm currentmatrix pop -} def -/TO -{ - iTe _ctm setmatrix newpath -} def -/Tp -{ - pop _tm astore pop _ctm setmatrix - _tDict begin - /W - { - } def - /h - { - } def -} def -/TP -{ - end - iTm 0 0 moveto -} def -/Tr -{ - _render 3 le - { - currentpoint newpath moveto - } if - dup 8 eq - { - pop 0 - } - { - dup 9 eq - { - pop 1 - } if - } ifelse - dup /_render exch ddef - _renderStart exch get load exec -} def -/iTm -{ - _ctm setmatrix _tm concat - _shift aload pop _lineorientation 1 eq { exch } if translate - _scale aload pop _lineorientation 1 eq _yokoorientation 1 eq or { exch } if scale -} def -/Tm -{ - _tm astore pop iTm 0 0 moveto -} def -/Td -{ - _mtx translate _tm _tm concatmatrix pop iTm 0 0 moveto -} def -/iTe -{ - _render -1 eq - { - } - { - _renderEnd _render get dup null ne - { - load exec - } - { - pop - } ifelse - } ifelse - /_render -1 ddef -} def -/Ta -{ - pop -} def -/Tf -{ - 1 index type /nametype eq - { - dup 0.75 mul 1 index 0.25 mul neg - } if - /_fontDescent exch ddef - /_fontAscent exch ddef - /_fontSize exch ddef - /_fontRotateAdjust _fontAscent _fontDescent add 2 div neg ddef - /_fontHeight _fontSize ddef - findfont _fontSize scalefont setfont -} def -/Tl -{ - pop neg 0 exch - _leading astore pop -} def -/Tt -{ - pop -} def -/TW -{ - 3 npop -} def -/Tw -{ - /_cx exch ddef -} def -/TC -{ - 3 npop -} def -/Tc -{ - /_ax exch ddef -} def -/Ts -{ - 0 exch - _shift astore pop - currentpoint - iTm - moveto -} def -/Ti -{ - 3 npop -} def -/Tz -{ - count 1 eq { 100 } if - 100 div exch 100 div exch - _scale astore pop - iTm -} def -/TA -{ - pop -} def -/Tq -{ - pop -} def -/Tg -{ - pop -} def -/TG -{ - pop -} def -/Tv -{ - /_lineorientation exch ddef -} def -/TV -{ - /_charorientation exch ddef -} def -/Ty -{ - dup /_yokoorientation exch ddef 1 sub neg Tv -} def -/TY -{ - pop -} def -/T~ -{ - Tx -} def -/Th -{ - pop pop pop pop pop -} def -/TX -{ - pop -} def -/Tk -{ - _fontSize mul 1000 div - _lineorientation 0 eq { neg 0 } { 0 exch } ifelse - rmoveto - pop -} def -/TK -{ - 2 npop -} def -/T* -{ - _leading aload pop - _lineorientation 0 ne { exch } if - Td -} def -/T*- -{ - _leading aload pop - _lineorientation 0 ne { exch } if - exch neg exch neg - Td -} def -/T- -{ - _ax neg 0 rmoveto - _lineorientation 1 eq _charorientation 0 eq and { 1 TV _hyphen Tx 0 TV } { _hyphen Tx } ifelse -} def -/T+ -{ -} def -/TR -{ - _ctm currentmatrix pop - _tm astore pop - iTm 0 0 moveto -} def -/TS -{ - currentfont 3 1 roll - /_Symbol_ findfont _fontSize scalefont setfont - - 0 eq - { - Tx - } - { - Tj - } ifelse - setfont -} def -/Xb -{ - pop pop -} def -/Tb /Xb load def -/Xe -{ - pop pop pop pop -} def -/Te /Xe load def -/XB -{ -} def -/TB /XB load def -currentdict readonly pop -end -setpacking -% -/X^ -{ - currentfont 5 1 roll - dup havefont - { - findfont _fontSize scalefont setfont - } - { - pop - exch - } ifelse - 2 index 0 eq - { - Tx - } - { - Tj - } ifelse - pop pop - setfont -} def -/T^ /X^ load def -%%EndResource -%%BeginProcSet: Adobe_ColorImage_AI6 1.3 0 -userdict /Adobe_ColorImage_AI6 known not -{ - userdict /Adobe_ColorImage_AI6 53 dict put -} if -userdict /Adobe_ColorImage_AI6 get begin -/initialize { - Adobe_ColorImage_AI6 begin - Adobe_ColorImage_AI6 { - dup type /arraytype eq { - dup xcheck { - bind - } if - } if - pop pop - } forall -} def -/terminate { end } def -currentdict /Adobe_ColorImage_AI6_Vars known not { - /Adobe_ColorImage_AI6_Vars 41 dict def -} if -Adobe_ColorImage_AI6_Vars begin - /plateindex -1 def - /_newproc null def - /_proc1 null def - /_proc2 null def - /sourcearray 4 array def - /_ptispace null def - /_ptiname null def - /_pti0 0 def - /_pti1 0 def - /_ptiproc null def - /_ptiscale 0 def - /_pticomps 0 def - /_ptibuf 0 string def - /_gtigray 0 def - /_cticmyk null def - /_rtirgb null def - /XIEnable true def - /XIType 0 def - /XIEncoding 0 def - /XICompression 0 def - /XIChannelCount 0 def - /XIBitsPerPixel 0 def - /XIImageHeight 0 def - /XIImageWidth 0 def - /XIImageMatrix null def - /XIRowBytes 0 def - /XIFile null def - /XIBuffer1 null def - /XIBuffer2 null def - /XIBuffer3 null def - /XIDataProc null def - /XIColorSpace /DeviceGray def - /XIColorValues 0 def - /XIPlateList false def -end -/ci6colorimage /colorimage where {/colorimage get}{null} ifelse def -/ci6image systemdict /image get def -/ci6curtransfer systemdict /currenttransfer get def -/ci6curoverprint /currentoverprint where {/currentoverprint get}{{_of}} ifelse def -/ci6foureq { - 4 index ne { - pop pop pop false - }{ - 4 index ne { - pop pop false - }{ - 4 index ne { - pop false - }{ - 4 index eq - } ifelse - } ifelse - } ifelse -} def -/ci6testplate { - Adobe_ColorImage_AI6_Vars begin - /plateindex -1 def - /setcmykcolor where { - pop - gsave - 1 0 0 0 setcmykcolor systemdict /currentgray get exec 1 exch sub - 0 1 0 0 setcmykcolor systemdict /currentgray get exec 1 exch sub - 0 0 1 0 setcmykcolor systemdict /currentgray get exec 1 exch sub - 0 0 0 1 setcmykcolor systemdict /currentgray get exec 1 exch sub - grestore - 1 0 0 0 ci6foureq { - /plateindex 0 def - }{ - 0 1 0 0 ci6foureq { - /plateindex 1 def - }{ - 0 0 1 0 ci6foureq { - /plateindex 2 def - }{ - 0 0 0 1 ci6foureq { - /plateindex 3 def - }{ - 0 0 0 0 ci6foureq { - /plateindex 5 def - } if - } ifelse - } ifelse - } ifelse - } ifelse - pop pop pop pop - } if - plateindex - end -} def -/ci6concatprocs { - /packedarray where { - pop dup type /packedarraytype eq 2 index type - /packedarraytype eq or - }{ - false - } ifelse - { - /_proc2 exch cvlit def - /_proc1 exch cvlit def - _proc1 aload pop - _proc2 aload pop - _proc1 length - _proc2 length add - packedarray cvx - }{ - /_proc2 exch cvlit def - /_proc1 exch cvlit def - /_newproc _proc1 length _proc2 length add array def - _newproc 0 _proc1 putinterval - _newproc _proc1 length _proc2 putinterval - _newproc cvx - } ifelse -} def -/ci6istint { - type /arraytype eq -} def -/ci6isspot { - dup type /arraytype eq { - dup length 1 sub get /Separation eq - }{ - pop false - } ifelse -} def -/ci6spotname { - dup ci6isspot {dup length 2 sub get}{pop ()} ifelse -} def -/ci6altspace { - aload pop pop pop ci6colormake -} def -/ci6numcomps { - dup /DeviceGray eq { - pop 1 - }{ - dup /DeviceRGB eq { - pop 3 - }{ - /DeviceCMYK eq { - 4 - }{ - 1 - } ifelse - } ifelse - } ifelse -} def -/ci6marksplate { - dup /DeviceGray eq { - pop plateindex 3 eq - }{ - dup /DeviceRGB eq { - pop plateindex 5 ne - }{ - dup /DeviceCMYK eq { - pop plateindex 5 ne - }{ - dup ci6isspot { - /findcmykcustomcolor where { - pop - dup length 2 sub get - 0.1 0.1 0.1 0.1 5 -1 roll - findcmykcustomcolor 1 setcustomcolor - systemdict /currentgray get exec - 1 ne - }{ - pop plateindex 5 ne - } ifelse - }{ - pop plateindex 5 ne - } ifelse - } ifelse - } ifelse - } ifelse -} def -/ci6colormake { - dup ci6numcomps - exch 1 index 2 add 1 roll - dup 1 eq {pop}{array astore} ifelse - exch -} def -/ci6colorexpand { - dup ci6spotname exch - dup ci6istint { - ci6altspace - exch 4 1 roll - }{ - 1 3 1 roll - } ifelse -} def -/ci6colortint { - dup /DeviceGray eq { - 3 1 roll 1 exch sub mul 1 exch sub exch - }{ - dup /DeviceRGB eq { - 3 1 roll {1 exch sub 1 index mul 1 exch sub exch} forall pop 3 array astore exch - }{ - dup /DeviceCMYK eq { - 3 1 roll {1 index mul exch} forall pop 4 array astore exch - }{ - 3 1 roll mul exch - } ifelse - } ifelse - } ifelse -} def -/ci6colortocmyk { - dup /DeviceGray eq { - pop 1 exch sub 0 0 0 4 -1 roll 4 array astore - }{ - dup /DeviceRGB eq { - pop aload pop _rgbtocmyk 4 array astore - }{ - dup /DeviceCMYK eq { - pop - }{ - ci6altspace ci6colortint ci6colortocmyk - } ifelse - } ifelse - } ifelse -} def -/ci6makeimagedict { - 7 dict begin - /ImageType 1 def - /Decode exch def - /DataSource exch def - /ImageMatrix exch def - /BitsPerComponent exch def - /Height exch def - /Width exch def - currentdict end -} def -/ci6stringinvert { - 0 1 2 index length 1 sub { - dup 2 index exch get 255 exch sub 2 index 3 1 roll put - } for -} def -/ci6stringknockout { - 0 1 2 index length 1 sub { - 255 2 index 3 1 roll put - } for -} def -/ci6stringapply { - 0 1 4 index length 1 sub { - dup - 4 index exch get - 3 index 3 1 roll - 3 index exec - } for - pop exch pop -} def -/ci6walkrgbstring { - 0 3 index - dup length 1 sub 0 3 3 -1 roll { - 3 getinterval {} forall - 5 index exec - 3 index - } for - - 5 {pop} repeat -} def -/ci6walkcmykstring -{ - 0 3 index - dup length 1 sub 0 4 3 -1 roll { - 4 getinterval {} forall - - 6 index exec - - 3 index - - } for - - 5 { pop } repeat - -} def -/ci6putrgbtograystr -{ - .11 mul exch - - .59 mul add exch - - .3 mul add - - cvi 3 copy put - - pop 1 add -} def -/ci6putcmyktograystr -{ - exch .11 mul add - - exch .59 mul add - - exch .3 mul add - - dup 255 gt { pop 255 } if - - 255 exch sub cvi 3 copy put - - pop 1 add -} def -/ci6rgbtograyproc { - Adobe_ColorImage_AI6_Vars begin - sourcearray 0 get exec - XIBuffer3 - dup 3 1 roll - - /ci6putrgbtograystr load exch - ci6walkrgbstring - end -} def -/ci6cmyktograyproc { - Adobe_ColorImage_AI6_Vars begin - sourcearray 0 get exec - XIBuffer3 - dup 3 1 roll - - /ci6putcmyktograystr load exch - ci6walkcmykstring - end -} def -/ci6separatecmykproc { - Adobe_ColorImage_AI6_Vars begin - sourcearray 0 get exec - - XIBuffer3 - - 0 2 index - - plateindex 4 2 index length 1 sub { - get 255 exch sub - - 3 copy put pop 1 add - - 2 index - } for - pop pop exch pop - end -} def - -/ci6compositeimage { - dup 1 eq { - pop pop image - }{ - /ci6colorimage load null ne { - ci6colorimage - }{ - 3 1 roll pop - sourcearray 0 3 -1 roll put - 3 eq {/ci6rgbtograyproc}{/ci6cmyktograyproc} ifelse load - image - } ifelse - } ifelse -} def -/ci6knockoutimage { - gsave - 0 ci6curtransfer exec 1 ci6curtransfer exec - eq { - 0 ci6curtransfer exec 0.5 lt - }{ - 0 ci6curtransfer exec 1 ci6curtransfer exec gt - } ifelse - {{pop 0}}{{pop 1}} ifelse - systemdict /settransfer get exec - ci6compositeimage - grestore -} def -/ci6drawimage { - ci6testplate -1 eq { - pop ci6compositeimage - }{ - dup type /arraytype eq { - dup length plateindex gt {plateindex get}{pop false} ifelse - }{ - { - true - }{ - dup 1 eq {plateindex 3 eq}{plateindex 3 le} ifelse - } ifelse - } ifelse - { - dup 1 eq { - pop pop ci6image - }{ - dup 3 eq { - ci6compositeimage - }{ - pop pop - sourcearray 0 3 -1 roll put - /ci6separatecmykproc load - ci6image - } ifelse - } ifelse - }{ - ci6curoverprint { - 7 {pop} repeat - }{ - ci6knockoutimage - } ifelse - } ifelse - } ifelse -} def -/ci6proctintimage { - /_ptispace exch store /_ptiname exch store /_pti1 exch store /_pti0 exch store /_ptiproc exch store - /_pticomps _ptispace ci6numcomps store - /_ptiscale _pti1 _pti0 sub store - level2? { - _ptiname length 0 gt version cvr 2012 ge and { - [/Separation _ptiname _ptispace {_ptiproc}] setcolorspace - [_pti0 _pti1] ci6makeimagedict ci6image - }{ - [/Indexed _ptispace 255 {255 div _ptiscale mul _pti0 add _ptiproc}] setcolorspace - [0 255] ci6makeimagedict ci6image - } ifelse - }{ - _pticomps 1 eq { - { - dup - { - 255 div _ptiscale mul _pti0 add _ptiproc 255 mul cvi put - } ci6stringapply - } ci6concatprocs ci6image - }{ - { - dup length _pticomps mul dup _ptibuf length ne {/_ptibuf exch string store}{pop} ifelse - _ptibuf { - exch _pticomps mul exch 255 div _ptiscale mul _pti0 add _ptiproc - _pticomps 2 add -2 roll - _pticomps 1 sub -1 0 { - 1 index add 2 index exch - 5 -1 roll - 255 mul cvi put - } for - pop pop - } ci6stringapply - } ci6concatprocs false _pticomps - /ci6colorimage load null eq {7 {pop} repeat}{ci6colorimage} ifelse - } ifelse - } ifelse -} def -/ci6graytintimage { - /_gtigray 5 -1 roll store - {1 _gtigray sub mul 1 exch sub} 4 1 roll - /DeviceGray ci6proctintimage -} def -/ci6cmyktintimage { - /_cticmyk 5 -1 roll store - {_cticmyk {1 index mul exch} forall pop} 4 1 roll - /DeviceCMYK ci6proctintimage -} def -/ci6rgbtintimage { - /_rtirgb 5 -1 roll store - {_rtirgb {1 exch sub 1 index mul 1 exch sub exch} forall pop} 4 1 roll - /DeviceRGB ci6proctintimage -} def -/ci6tintimage { - ci6testplate -1 eq { - ci6colorexpand - 3 -1 roll 5 -1 roll {0}{0 exch} ifelse 4 2 roll - dup /DeviceGray eq { - pop ci6graytintimage - }{ - dup /DeviceRGB eq { - pop ci6rgbtintimage - }{ - pop ci6cmyktintimage - } ifelse - } ifelse - }{ - dup ci6marksplate { - plateindex 5 lt { - ci6colortocmyk plateindex get - dup 0 eq ci6curoverprint and { - 7 {pop} repeat - }{ - 1 exch sub - exch {1 0}{0 1} ifelse () ci6graytintimage - } ifelse - }{ - pop exch {0}{0 exch} ifelse 0 3 1 roll () ci6graytintimage - } ifelse - }{ - ci6curoverprint { - 8 {pop} repeat - }{ - pop pop pop - {pop 1} 0 1 () /DeviceGray ci6proctintimage - } ifelse - } ifelse - } ifelse -} def -/XINullImage { -} def -/XIImageMask { - XIImageWidth XIImageHeight false - [XIImageWidth 0 0 XIImageHeight neg 0 0] - /XIDataProc load - imagemask -} def -/XIImageTint { - XIImageWidth XIImageHeight XIBitsPerPixel - [XIImageWidth 0 0 XIImageHeight neg 0 0] - /XIDataProc load - XIType 3 eq XIColorValues XIColorSpace ci6tintimage -} def -/XIImage { - XIImageWidth XIImageHeight XIBitsPerPixel - [XIImageWidth 0 0 XIImageHeight neg 0 0] - /XIDataProc load - false XIChannelCount XIPlateList ci6drawimage -} def -/XG { - pop pop -} def -/XF { - 13 {pop} repeat -} def -/Xh { - Adobe_ColorImage_AI6_Vars begin - gsave - /XIType exch def - /XIImageHeight exch def - /XIImageWidth exch def - /XIImageMatrix exch def - 0 0 moveto - XIImageMatrix concat - XIImageWidth XIImageHeight scale - - /_lp /null ddef - _fc - /_lp /imagemask ddef - end -} def -/XH { - Adobe_ColorImage_AI6_Vars begin - grestore - end -} def -/XIEnable { - Adobe_ColorImage_AI6_Vars /XIEnable 3 -1 roll put -} def -/XC { - Adobe_ColorImage_AI6_Vars begin - ci6colormake - /XIColorSpace exch def - /XIColorValues exch def - end -} def -/XIPlates { - Adobe_ColorImage_AI6_Vars begin - /XIPlateList exch def - end -} def -/XI -{ - Adobe_ColorImage_AI6_Vars begin - gsave - /XIType exch def - cvi dup - 256 idiv /XICompression exch store - 256 mod /XIEncoding exch store - pop pop - /XIChannelCount exch def - /XIBitsPerPixel exch def - /XIImageHeight exch def - /XIImageWidth exch def - pop pop pop pop - /XIImageMatrix exch def - XIBitsPerPixel 1 eq { - XIImageWidth 8 div ceiling cvi - }{ - XIImageWidth XIChannelCount mul - } ifelse - /XIRowBytes exch def - XIEnable { - /XIBuffer3 XIImageWidth string def - XICompression 0 eq { - /XIBuffer1 XIRowBytes string def - XIEncoding 0 eq { - {currentfile XIBuffer1 readhexstring pop} - }{ - {currentfile XIBuffer1 readstring pop} - } ifelse - }{ - /XIBuffer1 256 string def - /XIBuffer2 XIRowBytes string def - {currentfile XIBuffer1 readline pop (%) anchorsearch {pop} if} - /ASCII85Decode filter /DCTDecode filter - /XIFile exch def - {XIFile XIBuffer2 readstring pop} - } ifelse - /XIDataProc exch def - - XIType 1 ne { - 0 setgray - } if - XIType 1 eq { - XIImageMask - }{ - XIType 2 eq XIType 3 eq or { - XIImageTint - }{ - XIImage - } ifelse - } ifelse - }{ - XINullImage - } ifelse - /XIPlateList false def - grestore - end -} def -end -%%EndProcSet -%%BeginResource: procset Adobe_Illustrator_AI5 1.3 0 -%%Title: (Adobe Illustrator (R) Version 8.0 Full Prolog) -%%Version: 1.3 0 -%%CreationDate: (3/7/1994) () -%%Copyright: ((C) 1987-1998 Adobe Systems Incorporated All Rights Reserved) -currentpacking true setpacking -userdict /Adobe_Illustrator_AI5_vars 112 dict dup begin -put -/_?cmyk false def -/_eo false def -/_lp /none def -/_pf -{ -} def -/_ps -{ -} def -/_psf -{ -} def -/_pss -{ -} def -/_pjsf -{ -} def -/_pjss -{ -} def -/_pola 0 def -/_doClip 0 def -/cf currentflat def -/_lineorientation 0 def -/_charorientation 0 def -/_yokoorientation 0 def -/_tm matrix def -/_renderStart -[ -/e0 /r0 /a0 /o0 /e1 /r1 /a1 /i0 -] def -/_renderEnd -[ -null null null null /i1 /i1 /i1 /i1 -] def -/_render -1 def -/_shift [0 0] def -/_ax 0 def -/_ay 0 def -/_cx 0 def -/_cy 0 def -/_leading -[ -0 0 -] def -/_ctm matrix def -/_mtx matrix def -/_sp 16#020 def -/_hyphen (-) def -/_fontSize 0 def -/_fontAscent 0 def -/_fontDescent 0 def -/_fontHeight 0 def -/_fontRotateAdjust 0 def -/Ss 256 string def -Ss 0 (fonts/) putinterval -/_cnt 0 def -/_scale [1 1] def -/_nativeEncoding 0 def -/_useNativeEncoding 0 def -/_tempEncode 0 def -/_pntr 0 def -/_tDict 2 dict def -/_hfname 100 string def -/_hffound false def -/Tx -{ -} def -/Tj -{ -} def -/CRender -{ -} def -/_AI3_savepage -{ -} def -/_gf null def -/_cf 4 array def -/_rgbf 3 array def -/_if null def -/_of false def -/_fc -{ -} def -/_gs null def -/_cs 4 array def -/_rgbs 3 array def -/_is null def -/_os false def -/_sc -{ -} def -/_pd 1 dict def -/_ed 15 dict def -/_pm matrix def -/_fm null def -/_fd null def -/_fdd null def -/_sm null def -/_sd null def -/_sdd null def -/_i null def -/_lobyte 0 def -/_hibyte 0 def -/_cproc null def -/_cscript 0 def -/_hvax 0 def -/_hvay 0 def -/_hvwb 0 def -/_hvcx 0 def -/_hvcy 0 def -/_bitfont null def -/_bitlobyte 0 def -/_bithibyte 0 def -/_bitkey null def -/_bitdata null def -/_bitindex 0 def -/discardSave null def -/buffer 256 string def -/beginString null def -/endString null def -/endStringLength null def -/layerCnt 1 def -/layerCount 1 def -/perCent (%) 0 get def -/perCentSeen? false def -/newBuff null def -/newBuffButFirst null def -/newBuffLast null def -/clipForward? false def -end -userdict /Adobe_Illustrator_AI5 known not { - userdict /Adobe_Illustrator_AI5 100 dict put -} if -userdict /Adobe_Illustrator_AI5 get begin -/initialize -{ - Adobe_Illustrator_AI5 dup begin - Adobe_Illustrator_AI5_vars begin - /_aicmykps where {pop /_?cmyk _aicmykps def}if - discardDict - { - bind pop pop - } forall - dup /nc get begin - { - dup xcheck 1 index type /operatortype ne and - { - bind - } if - pop pop - } forall - end - newpath -} def -/terminate -{ - end - end -} def -/_ -null def -/ddef -{ - Adobe_Illustrator_AI5_vars 3 1 roll put -} def -/xput -{ - dup load dup length exch maxlength eq - { - dup dup load dup - length 2 mul dict copy def - } if - load begin - def - end -} def -/npop -{ - { - pop - } repeat -} def -/hswj -{ - dup stringwidth 3 2 roll - { - _hvwb eq { exch _hvcx add exch _hvcy add } if - exch _hvax add exch _hvay add - } cforall -} def -/vswj -{ - 0 0 3 -1 roll - { - dup 255 le - _charorientation 1 eq - and - { - dup cstring stringwidth 5 2 roll - _hvwb eq { exch _hvcy sub exch _hvcx sub } if - exch _hvay sub exch _hvax sub - 4 -1 roll sub exch - 3 -1 roll sub exch - } - { - _hvwb eq { exch _hvcy sub exch _hvcx sub } if - exch _hvay sub exch _hvax sub - _fontHeight sub - } ifelse - } cforall -} def -/swj -{ - 6 1 roll - /_hvay exch ddef - /_hvax exch ddef - /_hvwb exch ddef - /_hvcy exch ddef - /_hvcx exch ddef - _lineorientation 0 eq { hswj } { vswj } ifelse -} def -/sw -{ - 0 0 0 6 3 roll swj -} def -/vjss -{ - 4 1 roll - { - dup cstring - dup length 1 eq - _charorientation 1 eq - and - { - -90 rotate - currentpoint - _fontRotateAdjust add - moveto - gsave - false charpath currentpoint - 5 index setmatrix stroke - grestore - _fontRotateAdjust sub - moveto - _sp eq - { - 5 index 5 index rmoveto - } if - 2 copy rmoveto - 90 rotate - } - { - currentpoint - _fontHeight sub - 5 index sub - 3 index _sp eq - { - 9 index sub - } if - - currentpoint - exch 4 index stringwidth pop 2 div sub - exch _fontAscent sub - moveto - - gsave - 2 index false charpath - 6 index setmatrix stroke - grestore - - moveto pop pop - } ifelse - } cforall - 6 npop -} def -/hjss -{ - 4 1 roll - { - dup cstring - gsave - false charpath currentpoint - 5 index setmatrix stroke - grestore - moveto - _sp eq - { - 5 index 5 index rmoveto - } if - 2 copy rmoveto - } cforall - 6 npop -} def -/jss -{ - _lineorientation 0 eq { hjss } { vjss } ifelse -} def -/ss -{ - 0 0 0 7 3 roll jss -} def -/vjsp -{ - 4 1 roll - { - dup cstring - dup length 1 eq - _charorientation 1 eq - and - { - -90 rotate - currentpoint - _fontRotateAdjust add - moveto - false charpath - currentpoint - _fontRotateAdjust sub - moveto - _sp eq - { - 5 index 5 index rmoveto - } if - 2 copy rmoveto - 90 rotate - } - { - currentpoint - _fontHeight sub - 5 index sub - 3 index _sp eq - { - 9 index sub - } if - - currentpoint - exch 4 index stringwidth pop 2 div sub - exch _fontAscent sub - moveto - - 2 index false charpath - - moveto pop pop - } ifelse - } cforall - 6 npop -} def -/hjsp -{ - 4 1 roll - { - dup cstring - false charpath - _sp eq - { - 5 index 5 index rmoveto - } if - 2 copy rmoveto - } cforall - 6 npop -} def -/jsp -{ - matrix currentmatrix - _lineorientation 0 eq {hjsp} {vjsp} ifelse -} def -/sp -{ - matrix currentmatrix - 0 0 0 7 3 roll - _lineorientation 0 eq {hjsp} {vjsp} ifelse -} def -/pl -{ - transform - 0.25 sub round 0.25 add exch - 0.25 sub round 0.25 add exch - itransform -} def -/setstrokeadjust where -{ - pop true setstrokeadjust - /c - { - curveto - } def - /C - /c load def - /v - { - currentpoint 6 2 roll curveto - } def - /V - /v load def - /y - { - 2 copy curveto - } def - /Y - /y load def - /l - { - lineto - } def - /L - /l load def - /m - { - moveto - } def -} -{ - /c - { - pl curveto - } def - /C - /c load def - /v - { - currentpoint 6 2 roll pl curveto - } def - /V - /v load def - /y - { - pl 2 copy curveto - } def - /Y - /y load def - /l - { - pl lineto - } def - /L - /l load def - /m - { - pl moveto - } def -} ifelse -/d -{ - setdash -} def -/cf -{ -} def -/i -{ - dup 0 eq - { - pop cf - } if - setflat -} def -/j -{ - setlinejoin -} def -/J -{ - setlinecap -} def -/M -{ - setmiterlimit -} def -/w -{ - setlinewidth -} def -/XR -{ - 0 ne - /_eo exch ddef -} def -/H -{ -} def -/h -{ - closepath -} def -/N -{ - _pola 0 eq - { - _doClip 1 eq - { - _eo {eoclip} {clip} ifelse /_doClip 0 ddef - } if - newpath - } - { - /CRender - { - N - } ddef - } ifelse -} def -/n -{ - N -} def -/F -{ - _pola 0 eq - { - _doClip 1 eq - { - gsave _pf grestore _eo {eoclip} {clip} ifelse newpath /_lp /none ddef _fc - /_doClip 0 ddef - } - { - _pf - } ifelse - } - { - /CRender - { - F - } ddef - } ifelse -} def -/f -{ - closepath - F -} def -/S -{ - _pola 0 eq - { - _doClip 1 eq - { - gsave _ps grestore _eo {eoclip} {clip} ifelse newpath /_lp /none ddef _sc - /_doClip 0 ddef - } - { - _ps - } ifelse - } - { - /CRender - { - S - } ddef - } ifelse -} def -/s -{ - closepath - S -} def -/B -{ - _pola 0 eq - { - _doClip 1 eq - gsave F grestore - { - gsave S grestore _eo {eoclip} {clip} ifelse newpath /_lp /none ddef _sc - /_doClip 0 ddef - } - { - S - } ifelse - } - { - /CRender - { - B - } ddef - } ifelse -} def -/b -{ - closepath - B -} def -/W -{ - /_doClip 1 ddef -} def -/* -{ - count 0 ne - { - dup type /stringtype eq - { - pop - } if - } if - newpath -} def -/u -{ -} def -/U -{ -} def -/q -{ - _pola 0 eq - { - gsave - } if -} def -/Q -{ - _pola 0 eq - { - grestore - } if -} def -/*u -{ - _pola 1 add /_pola exch ddef -} def -/*U -{ - _pola 1 sub /_pola exch ddef - _pola 0 eq - { - CRender - } if -} def -/D -{ - pop -} def -/*w -{ -} def -/*W -{ -} def -/` -{ - /_i save ddef - clipForward? - { - nulldevice - } if - 6 1 roll 4 npop - concat pop - userdict begin - /showpage - { - } def - 0 setgray - 0 setlinecap - 1 setlinewidth - 0 setlinejoin - 10 setmiterlimit - [] 0 setdash - /setstrokeadjust where {pop false setstrokeadjust} if - newpath - 0 setgray - false setoverprint -} def -/~ -{ - end - _i restore -} def -/_rgbtocmyk -{ - 3 - { - 1 exch sub 3 1 roll - } repeat - 3 copy 1 4 1 roll - 3 - { - 3 index 2 copy gt - { - exch - } if - pop 4 1 roll - } repeat - pop pop pop - 4 1 roll - 3 - { - 3 index sub - 3 1 roll - } repeat - 4 -1 roll -} def -/setrgbfill -{ - _rgbf astore pop - /_fc - { - _lp /fill ne - { - _of setoverprint - _rgbf aload pop setrgbcolor - /_lp /fill ddef - } if - } ddef - /_pf - { - _fc - _eo {eofill} {fill} ifelse - } ddef - /_psf - { - _fc - hvashow - } ddef - /_pjsf - { - _fc - hvawidthshow - } ddef - /_lp /none ddef -} def -/setrgbstroke -{ - _rgbs astore pop - /_sc - { - _lp /stroke ne - { - _os setoverprint - _rgbs aload pop setrgbcolor - /_lp /stroke ddef - } if - } ddef - /_ps - { - _sc - stroke - } ddef - /_pss - { - _sc - ss - } ddef - /_pjss - { - _sc - jss - } ddef - /_lp /none ddef -} def -/O -{ - 0 ne - /_of exch ddef - /_lp /none ddef -} def -/R -{ - 0 ne - /_os exch ddef - /_lp /none ddef -} def -/g -{ - /_gf exch ddef - /_fc - { - _lp /fill ne - { - _of setoverprint - _gf setgray - /_lp /fill ddef - } if - } ddef - /_pf - { - _fc - _eo {eofill} {fill} ifelse - } ddef - /_psf - { - _fc - hvashow - } ddef - /_pjsf - { - _fc - hvawidthshow - } ddef - /_lp /none ddef -} def -/G -{ - /_gs exch ddef - /_sc - { - _lp /stroke ne - { - _os setoverprint - _gs setgray - /_lp /stroke ddef - } if - } ddef - /_ps - { - _sc - stroke - } ddef - /_pss - { - _sc - ss - } ddef - /_pjss - { - _sc - jss - } ddef - /_lp /none ddef -} def -/k -{ - _cf astore pop - /_fc - { - _lp /fill ne - { - _of setoverprint - _cf aload pop setcmykcolor - /_lp /fill ddef - } if - } ddef - /_pf - { - _fc - _eo {eofill} {fill} ifelse - } ddef - /_psf - { - _fc - hvashow - } ddef - /_pjsf - { - _fc - hvawidthshow - } ddef - /_lp /none ddef -} def -/K -{ - _cs astore pop - /_sc - { - _lp /stroke ne - { - _os setoverprint - _cs aload pop setcmykcolor - /_lp /stroke ddef - } if - } ddef - /_ps - { - _sc - stroke - } ddef - /_pss - { - _sc - ss - } ddef - /_pjss - { - _sc - jss - } ddef - /_lp /none ddef -} def -/Xa -{ - _?cmyk { - 3 npop k - }{ - setrgbfill 4 npop - } ifelse -} def -/XA -{ - _?cmyk { - 3 npop K - }{ - setrgbstroke 4 npop - } ifelse -} def -/Xs -{ - /_gf exch ddef - 5 npop - /_fc - { - _lp /fill ne - { - _of setoverprint - _gf setAIseparationgray - /_lp /fill ddef - } if - } ddef - /_pf - { - _fc - _eo {eofill} {fill} ifelse - } ddef - /_psf - { - _fc - hvashow - } ddef - /_pjsf - { - _fc - hvawidthshow - } ddef - /_lp /none ddef -} def -/XS -{ - /_gs exch ddef - 5 npop - /_sc - { - _lp /stroke ne - { - _os setoverprint - _gs setAIseparationgray - /_lp /stroke ddef - } if - } ddef - /_ps - { - _sc - stroke - } ddef - /_pss - { - _sc - ss - } ddef - /_pjss - { - _sc - jss - } ddef - /_lp /none ddef -} def -/Xx -{ - exch - /_gf exch ddef - 0 eq { - findcmykcustomcolor - }{ - _?cmyk {true}{/findrgbcustomcolor where{pop false}{true}ifelse}ifelse - { - 4 1 roll 3 npop - findcmykcustomcolor - }{ - 8 -4 roll 4 npop - findrgbcustomcolor - } ifelse - } ifelse - /_if exch ddef - /_fc - { - _lp /fill ne - { - _of setoverprint - _if _gf 1 exch sub setcustomcolor - /_lp /fill ddef - } if - } ddef - /_pf - { - _fc - _eo {eofill} {fill} ifelse - } ddef - /_psf - { - _fc - hvashow - } ddef - /_pjsf - { - _fc - hvawidthshow - } ddef - /_lp /none ddef -} def -/XX -{ - exch - /_gs exch ddef - 0 eq { - findcmykcustomcolor - }{ - _?cmyk {true}{/findrgbcustomcolor where{pop false}{true}ifelse}ifelse - { - 4 1 roll 3 npop - findcmykcustomcolor - }{ - 8 -4 roll 4 npop - findrgbcustomcolor - } ifelse - } ifelse - /_is exch ddef - /_sc - { - _lp /stroke ne - { - _os setoverprint - _is _gs 1 exch sub setcustomcolor - /_lp /stroke ddef - } if - } ddef - /_ps - { - _sc - stroke - } ddef - /_pss - { - _sc - ss - } ddef - /_pjss - { - _sc - jss - } ddef - /_lp /none ddef -} def -/x -{ - /_gf exch ddef - findcmykcustomcolor - /_if exch ddef - /_fc - { - _lp /fill ne - { - _of setoverprint - _if _gf 1 exch sub setcustomcolor - /_lp /fill ddef - } if - } ddef - /_pf - { - _fc - _eo {eofill} {fill} ifelse - } ddef - /_psf - { - _fc - hvashow - } ddef - /_pjsf - { - _fc - hvawidthshow - } ddef - /_lp /none ddef -} def -/X -{ - /_gs exch ddef - findcmykcustomcolor - /_is exch ddef - /_sc - { - _lp /stroke ne - { - _os setoverprint - _is _gs 1 exch sub setcustomcolor - /_lp /stroke ddef - } if - } ddef - /_ps - { - _sc - stroke - } ddef - /_pss - { - _sc - ss - } ddef - /_pjss - { - _sc - jss - } ddef - /_lp /none ddef -} def -/XK -{ - 3 -1 roll pop - 0 eq - { - 1 exch sub - 3 {dup 3 1 roll mul 5 1 roll} repeat - mul 4 1 roll - K - } - { - 1 exch sub 4 1 roll - 3 {1 exch sub 3 index mul 1 exch sub 3 1 roll} repeat - 4 -1 roll pop - XA - } ifelse -} def -/Xk -{ - 3 -1 roll pop - 0 eq - { - 1 exch sub - 3 {dup 3 1 roll mul 5 1 roll} repeat - mul 4 1 roll - k - } - { - 1 exch sub 4 1 roll - 3 {1 exch sub 3 index mul 1 exch sub 3 1 roll} repeat - 4 -1 roll pop - Xa - } ifelse -} def -/A -{ - pop -} def -/annotatepage -{ -userdict /annotatepage 2 copy known {get exec} {pop pop} ifelse -} def -/XT { - pop pop -} def -/Xt { - pop -} def -/discard -{ - save /discardSave exch store - discardDict begin - /endString exch store - gt38? - { - 2 add - } if - load - stopped - pop - end - discardSave restore -} bind def -userdict /discardDict 7 dict dup begin -put -/pre38Initialize -{ - /endStringLength endString length store - /newBuff buffer 0 endStringLength getinterval store - /newBuffButFirst newBuff 1 endStringLength 1 sub getinterval store - /newBuffLast newBuff endStringLength 1 sub 1 getinterval store -} def -/shiftBuffer -{ - newBuff 0 newBuffButFirst putinterval - newBuffLast 0 - currentfile read not - { - stop - } if - put -} def -0 -{ - pre38Initialize - mark - currentfile newBuff readstring exch pop - { - { - newBuff endString eq - { - cleartomark stop - } if - shiftBuffer - } loop - } - { - stop - } ifelse -} def -1 -{ - pre38Initialize - /beginString exch store - mark - currentfile newBuff readstring exch pop - { - { - newBuff beginString eq - { - /layerCount dup load 1 add store - } - { - newBuff endString eq - { - /layerCount dup load 1 sub store - layerCount 0 eq - { - cleartomark stop - } if - } if - } ifelse - shiftBuffer - } loop - } if -} def -2 -{ - mark - { - currentfile buffer {readline} stopped { - % assume error was due to overfilling the buffer - }{ - not - { - stop - } if - endString eq { - cleartomark stop - } if - }ifelse - } loop -} def -3 -{ - /beginString exch store - /layerCnt 1 store - mark - { - currentfile buffer {readline} stopped { - % assume error was due to overfilling the buffer - }{ - not - { - stop - } if - dup beginString eq - { - pop /layerCnt dup load 1 add store - } - { - endString eq - { - layerCnt 1 eq - { - cleartomark stop - } - { - /layerCnt dup load 1 sub store - } ifelse - } if - } ifelse - }ifelse - } loop -} def -end -userdict /clipRenderOff 15 dict dup begin -put -{ - /n /N /s /S /f /F /b /B -} -{ - { - _doClip 1 eq - { - /_doClip 0 ddef _eo {eoclip} {clip} ifelse - } if - newpath - } def -} forall -/Tr /pop load def -/Bb {} def -/BB /pop load def -/Bg {12 npop} def -/Bm {6 npop} def -/Bc /Bm load def -/Bh {4 npop} def -end -/Lb -{ - 6 npop - 7 2 roll - 5 npop - 0 eq - { - 0 eq - { - (%AI5_BeginLayer) 1 (%AI5_EndLayer--) discard - } - { - - /clipForward? true def - - /Tx /pop load def - /Tj /pop load def - - currentdict end clipRenderOff begin begin - } ifelse - } - { - 0 eq - { - save /discardSave exch store - } if - } ifelse -} bind def -/LB -{ - discardSave dup null ne - { - restore - } - { - pop - clipForward? - { - currentdict - end - end - begin - - /clipForward? false ddef - } if - } ifelse -} bind def -/Pb -{ - pop pop - 0 (%AI5_EndPalette) discard -} bind def -/Np -{ - 0 (%AI5_End_NonPrinting--) discard -} bind def -/Ln /pop load def -/Ap -/pop load def -/Ar -{ - 72 exch div - 0 dtransform dup mul exch dup mul add sqrt - dup 1 lt - { - pop 1 - } if - setflat -} def -/Mb -{ - q -} def -/Md -{ -} def -/MB -{ - Q -} def -/nc 4 dict def -nc begin -/setgray -{ - pop -} bind def -/setcmykcolor -{ - 4 npop -} bind def -/setrgbcolor -{ - 3 npop -} bind def -/setcustomcolor -{ - 2 npop -} bind def -currentdict readonly pop -end -/XP -{ - 4 npop -} bind def -/XD -{ - pop -} bind def -end -setpacking -%%EndResource -%%BeginResource: procset Adobe_cshow 2.0 8 -%%Title: (Writing System Operators) -%%Version: 2.0 8 -%%CreationDate: (1/23/89) () -%%Copyright: ((C) 1992-1996 Adobe Systems Incorporated All Rights Reserved) -currentpacking true setpacking -userdict /Adobe_cshow 14 dict dup begin put -/initialize -{ - Adobe_cshow begin - Adobe_cshow - { - dup xcheck - { - bind - } if - pop pop - } forall - end - Adobe_cshow begin -} def -/terminate -{ -currentdict Adobe_cshow eq - { - end - } if -} def -/cforall -{ - /_lobyte 0 ddef - /_hibyte 0 ddef - /_cproc exch ddef - /_cscript currentfont /FontScript known { currentfont /FontScript get } { -1 } ifelse ddef - { - /_lobyte exch ddef - _hibyte 0 eq - _cscript 1 eq - _lobyte 129 ge _lobyte 159 le and - _lobyte 224 ge _lobyte 252 le and or and - _cscript 2 eq - _lobyte 161 ge _lobyte 254 le and and - _cscript 3 eq - _lobyte 161 ge _lobyte 254 le and and - _cscript 25 eq - _lobyte 161 ge _lobyte 254 le and and - _cscript -1 eq - or or or or and - { - /_hibyte _lobyte ddef - } - { - _hibyte 256 mul _lobyte add - _cproc - /_hibyte 0 ddef - } ifelse - } forall -} def -/cstring -{ - dup 256 lt - { - (s) dup 0 4 3 roll put - } - { - dup 256 idiv exch 256 mod - (hl) dup dup 0 6 5 roll put 1 4 3 roll put - } ifelse -} def -/clength -{ - 0 exch - { 256 lt { 1 } { 2 } ifelse add } cforall -} def -/hawidthshow -{ - { - dup cstring - show - _hvax _hvay rmoveto - _hvwb eq { _hvcx _hvcy rmoveto } if - } cforall -} def -/vawidthshow -{ - { - dup 255 le - _charorientation 1 eq - and - { - -90 rotate - 0 _fontRotateAdjust rmoveto - cstring - _hvcx _hvcy _hvwb _hvax _hvay 6 -1 roll awidthshow - 0 _fontRotateAdjust neg rmoveto - 90 rotate - } - { - currentpoint - _fontHeight sub - exch _hvay sub exch _hvax sub - 2 index _hvwb eq { exch _hvcy sub exch _hvcx sub } if - 3 2 roll - cstring - dup stringwidth pop 2 div neg _fontAscent neg rmoveto - show - moveto - } ifelse - } cforall -} def -/hvawidthshow -{ - 6 1 roll - /_hvay exch ddef - /_hvax exch ddef - /_hvwb exch ddef - /_hvcy exch ddef - /_hvcx exch ddef - _lineorientation 0 eq { hawidthshow } { vawidthshow } ifelse -} def -/hvwidthshow -{ - 0 0 3 -1 roll hvawidthshow -} def -/hvashow -{ - 0 0 0 6 -3 roll hvawidthshow -} def -/hvshow -{ - 0 0 0 0 0 6 -1 roll hvawidthshow -} def -currentdict readonly pop end -setpacking -%%EndResource -%%BeginResource: procset Adobe_shading_AI8 1.0 0 -%%Title: (Adobe Illustrator 8 Shading Procset) -%%Version: 1.0 0 -%%CreationDate: (12/17/97) () -%%Copyright: ((C) 1987-1997 Adobe Systems Incorporated All Rights Reserved) -userdict /defaultpacking currentpacking put true setpacking -userdict /Adobe_shading_AI8 10 dict dup begin put -/initialize { - Adobe_shading_AI8 begin - Adobe_shading_AI8 bdprocs - Mesh /initialize get exec -} def -/terminate { - currentdict Adobe_shading_AI8 eq { - end - } if -} def -/bdprocs { - { - dup xcheck 1 index type /arraytype eq and { - bind - } if - pop pop - } forall -} def -/X! {pop} def -/X# {pop pop} def -/Mesh 40 dict def -Mesh begin -/initialize { - Mesh bdprocs - Mesh begin - /emulate? /AI8MeshEmulation where { - pop AI8MeshEmulation - }{ - systemdict /shfill known not - } ifelse def - end -} def -/bd { - shadingdict begin -} def -/paint { - emulate? { - end - }{ - /_lp /none ddef _fc /_lp /none ddef - - /AIColorSpace AIColorSpace tocolorspace store - /ColorSpace AIColorSpace topsspace store - - version_ge_3010.106 not systemdict /setsmoothness known and { - 0.0001 setsmoothness - } if |