aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn Fieber <jfieber@FreeBSD.org>1995-05-18 03:05:22 +0000
committerJohn Fieber <jfieber@FreeBSD.org>1995-05-18 03:05:22 +0000
commit9d509395d0ea885e44d900e417f8d94aa77c65c8 (patch)
tree724704265f9be22876d90fb65d2a61443226dc00
parent9b0719e7fd81a0fc545dd567234722a47c924f37 (diff)
downloaddoc-9d509395d0ea885e44d900e417f8d94aa77c65c8.tar.gz
doc-9d509395d0ea885e44d900e417f8d94aa77c65c8.zip
handbook.sgml
Rearranged a few sections, add memoryuse section. current.sgml, ports.sgml, porting.sgml Added a <label>s for cross reference targes. submitters.sgml Lots of editing, added cross references to other sections of the handbook. Added a sample BSD-style copyright statement. eresources.sgml Updated the mailing list section, thanks to Peter Dufault. authors.sgml Added Peter Dufault, David Greenman and Joerg Wunsch. memoryuse.sgml A new section about how/where in PC memory the FreeBSD kernel gets loaded and run.
Notes
Notes: svn path=/head/; revision=13
-rw-r--r--handbook/authors.sgml5
-rw-r--r--handbook/current.sgml6
-rw-r--r--handbook/eresources.sgml391
-rw-r--r--handbook/handbook.sgml12
-rw-r--r--handbook/memoryuse.sgml55
-rw-r--r--handbook/porting.sgml4
-rw-r--r--handbook/ports.sgml4
-rw-r--r--handbook/submitters.sgml262
8 files changed, 518 insertions, 221 deletions
diff --git a/handbook/authors.sgml b/handbook/authors.sgml
index c092cbc090..5380e7f1d0 100644
--- a/handbook/authors.sgml
+++ b/handbook/authors.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: authors.sgml,v 1.2 1995-05-11 22:31:19 jfieber Exp $ -->
+<!-- $Id: authors.sgml,v 1.3 1995-05-18 03:05:00 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!--
@@ -7,12 +7,15 @@ entities when referencing people.
-->
<!ENTITY a.asami "Satoshi Asami <tt>&lt;asami@FreeBSD.org&gt;</tt>">
+<!ENTITY a.davidg "David Greenman <tt>&lt;davidg@Root.COM&gt;</tt>">
+<!ENTITY a.dufalt "Peter Dufault <tt>&lt;dufault@hda.com&gt;</tt>">
<!ENTITY a.gclarkii "Gary Clark II <tt>&lt;gclarkii@FreeBSD.org&gt;</tt>">
<!ENTITY a.gena "Gennady B. Sorokopud <tt>&lt;gena@NetVision.net.il&gt;</tt>">
<!ENTITY a.ghelmer "Guy Helmer <tt>&lt;ghelmer@alpha.dsu.edu&gt;</tt>">
<!ENTITY a.gpalmer "Gary Palmer <tt>&lt;gpalmer@FreeBSD.org&gt;</tt>">
<!ENTITY a.jfieber "John Fieber <tt>&lt;jfieber@FreeBSD.org&gt;</tt>">
<!ENTITY a.jkh "Jordan Hubbard <tt>&lt;jkh@FreeBSD.org&gt;</tt>">
+<!ENTITY a.joerg "Joerg Wunsch <tt>&lt;joerg_wunsch@uriah.heep.sax.de&gt;</tt>">
<!ENTITY a.john "John Lind <tt>&lt;john@starfire.MN.ORG&gt;</tt>">
<!ENTITY a.mark "Mark Murray <tt>&lt;mark@grondar.za&gt;</tt>">
<!ENTITY a.martin "Martin Renters <tt>&lt;martin@innovus.com&gt;</tt>">
diff --git a/handbook/current.sgml b/handbook/current.sgml
index bfb0751121..276a96d0f4 100644
--- a/handbook/current.sgml
+++ b/handbook/current.sgml
@@ -1,8 +1,8 @@
-<!-- $Id: current.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
+<!-- $Id: current.sgml,v 1.2 1995-05-18 03:05:03 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
-<chapt><heading>Staying current with FreeBSD</heading>
+<chapt><heading>Staying current with FreeBSD<label id="current:"></heading>
<p><em>Contributed by &a.jkh;.</em>
@@ -10,7 +10,7 @@
THE FREEBSD CURRENT POLICY
-Last updated: $Date: 1995-04-28 16:19:59 $
+Last updated: $Date: 1995-05-18 03:05:03 $
This document attempts to explain the rationale behind FreeBSD-current,
what you should expect should you decide to run it, and states some
diff --git a/handbook/eresources.sgml b/handbook/eresources.sgml
index c8da616aae..09cfe7fd92 100644
--- a/handbook/eresources.sgml
+++ b/handbook/eresources.sgml
@@ -1,118 +1,297 @@
-<!-- $Id: eresources.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
+<!-- $Id: eresources.sgml,v 1.2 1995-05-18 03:05:06 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt>
<heading>Additional resources on the Internet</heading>
<sect>
- <heading>Mailing lists</heading>
-
- <p>The FreeBSD Project runs a number of Internet mailing
- lists dedicated to the discussion of FreeBSD and
- related topics. Users with access to Internet mail are
- encouraged to subscribe to the lists that interest them
- and ask questions. The procedure is quite simple, just
- send a mail message to:
- <tscreen>
- <tt>majordomo@freebsd.org</tt>
- </tscreen>
- with a message body of:
- <tscreen>
- <tt><bf>subscribe <it>listname</it></bf></tt>
- </tscreen>
- where <em>listname</em> is one of the lists described
- below. You can subscribe to multiple lists with a
- single message by having several <em>subscribe</em>
- lines. For more detailed information, send a message
- to:
- <tscreen>
- <tt>majordomo@freebsd.org</tt>
- </tscreen>
- with a message body of
- <tscreen>
- <tt><bf>help</bf></tt>
- </tscreen>
-
- <sect1>
- <heading>General discussion lists</heading>
- <p><descrip>
- <tag>freebsd-announce</tag> Important announcements
- about FreeBSD are posted here.
-
- <tag>freebsd-questions</tag> General discussion of
- problems people experience in setting up and using
- FreeBSD.
-
- <tag>freebsd-hackers</tag> Technical discussions
- about the design and implementation of FreeBSD.
-
- <tag>freebsd-bugs</tag> Bug reports and discussions
- of reported bugs are posted here, although the
- discussions are usually moved over to the
- <em>freebsd-hackers</em> mailing list if the become involved.
- </descrip>
-
- <sect1>
- <heading>CVS lists</heading>
+ <heading>Mailing lists<label id="eresources:mailing-lists"></heading>
+
+<p><em>Contributed by &a.dufalt;.<newline>
+ 5 May 1995.</em>
+
+Though many of the FreeBSD development members read USENET, we cannot
+always guarantee that we'll get to your questions in a timely fashion
+(or at all) if you post them only to one of the comp.os.386bsd.*
+groups. By addressing your questions to the appropriate mailing list
+you will reach both us and a concentrated FreeBSD audience, invariably
+assuring a better (or at least faster) response.
+
+There are list charters at the bottom of this document. Please read
+the list charter before joining a list. We must strive to
+keep the signal to noise ratio of the lists high, especially in
+the technical lists.
+
+<sect1><heading>List summary</heading>
+
+<p><bf>General lists:</bf> The following are general lists that
+anyone is free to join:
+<verb>
+List Purpose
+----------------------------------------------------------------------
+freebsd-announce Important events / milestones
+freebsd-bugs Bug reports
+freebsd-chat Non technical items related to the community
+freebsd-policy Policy issues and suggestions
+freebsd-questions User questions
+freebsd-current Discussions about the use of FreeBSD-current
+</verb>
+
+<bf>Technical lists:</bf> The following are the technical lists. You should
+read the charter carefully before joining them, and you should keep
+your e-mail within the scope of the guidelines.
+<verb>
+List Purpose
+----------------------------------------------------------------------
+freebsd-doc Documentation project
+freebsd-fs Filesystems
+freebsd-hackers General Technical discussions
+freebsd-hardware General discussion of FreeBSD hardware
+freebsd-platforms Porting to Non-Intel platforms
+freebsd-ports Discussion of "ports"
+freebsd-security Security issues
+freebsd-scsi SCSI subsystem
+</verb>
+
+<bf>Limited lists:</bf> The following are limited lists that you will need
+approval to join. Even though access to these lists is controled,
+anyone is free to send suggestions and comments to them. It is a
+good idea establish a presence in the technical lists before asking
+to join one of these limited lists.
+<verb>
+List Purpose
+----------------------------------------------------------------------
+freebsd-admin Administrative issues
+freebsd-arch Architecture and design discussions
+freebsd-core FreeBSD core team
+freebsd-install Installation development
+</verb>
+
+<bf>CVS lists:</bf> The following lists are for people seeing the log messages
+for source changes in specific areas:
+<verb>
+List name Source area Area Description (source for)
+----------------------------------------------------------------------
+cvs-CVSROOT /usr/src/[A-Z]* Top level /usr/src file changes
+cvs-all /usr/src All changes to the tree (superset)
+cvs-bin /usr/src/bin System binaries
+cvs-etc /usr/src/etc System files
+cvs-games /usr/src/games Games
+cvs-gnu /usr/src/gnu GPL'd utilities
+cvs-include /usr/src/include Include files
+cvs-kerberosIV /usr/src/kerberosIV Kerberos encryption code
+cvs-lib /usr/src/lib System libraries
+cvs-libexec /usr/src/libexec System binaries
+cvs-ports /usr/ports Ported software
+cvs-sbin /usr/src/sbin System binaries
+cvs-share /usr/src/share System shared files
+cvs-sys /usr/src/sys Kernel
+cvs-usrbin /usr/src/usr.bin Use binaries
+cvs-usrsbin /usr/src/usr.sbin System binaries
+</verb>
+
+<sect1><heading>How to subscribe</heading>
+
+<p>All mailing lists live on `FreeBSD.ORG', so to post to a list you
+simply mail to `&lt;listname&gt;@FreeBSD.ORG'. It will then be redistributed
+to mailing list members throughout the world.
+
+To subscribe to a list, send mail to:
+<tscreen><verb>
+majordomo@FreeBSD.ORG
+</verb></tscreen>
+And include the keyword
+<tscreen><verb>
+subscribe <listname> [<optional address>]
+</verb></tscreen>
+In the body of your message. For example, to subscribe yourself to
+freebsd-announce, you'd do:
+<tscreen><verb>
+% mail majordomo@FreeBSD.ORG
+subscribe freebsd-announce
+^D
+</verb></tscreen>
+If you want to subscribe yourself under a different name, or submit a
+subscription request for a local mailing list (note: this is more efficient
+if you have several interested parties at one site, and highly appreciated by
+us!), you would do something like:
+<tscreen><verb>
+% mail majordomo@FreeBSD.ORG
+subscribe freebsd-announce local-announce@somesite.com
+^D
+</verb></tscreen>
+Finally, it is also possible to unsubscribe yourself from a list, get a
+list of other list members or see the list of mailing lists again by
+sending other types of control messages to majordomo. For a complete
+list of available commands, do this:
+<tscreen><verb>
+% mail majordomo@FreeBSD.ORG
+help
+^D
+</verb></tscreen>
+Finally, we again request that you keep the technical mailing lists on
+a technical track. If you're only interested in the "high points",
+then it's suggested that you join freebsd-announce, which will contain
+only infrequent traffic.
+
+<sect1><heading>List charters</heading>
+
+<p>
+<descrip>
+<tag/FREEBSD-ADMIN/ <em>Administrative issues</em><newline>
+<!-- XXX -->
+
+<tag/FREEBSD-ANNOUNCE/ <em>Important events / milestones</em><newline>
+This is the mailing list for people interested only in occasional
+announcements of significant freebsd events. This includes
+announcements about snapshots and other releases. It contains
+announcements of new FreeBSD capabilities. It may contain calls
+for volunteers etc. This is a low volume list.
+
+<tag/FREEBSD-ARCH/ <em>Architecture and design discussions</em><newline>
+This is the mailing list for people discussing FreeBSD architectural
+issues. It is a closed list, and not for general subscription.
+
+<tag/FREEBSD-BUGS/ <em>Bug reports</em><newline>
+This is the mailing list for reporting bugs in FreeBSD
+Whenever possible, bugs should be
+submitted using "send-pr".
+
+<tag/FREEBSD-CHAT/ <em>Non technical items related to the
+ community</em><newline>
+This list contains the overflow from the other lists about
+non-technical, social information. It includes discussion about
+whether Jordan looks like a tune ferret or not, whether or not to
+type in capitals, who is drinking too much coffee, where the best
+beer is brewed, who is brewing beer in their basement, and so on.
+Occasional announcements of important events (such as upcoming
+parties, weddings, births, new jobs, etc) can be made to the
+technical lists, but the follow ups should be directed to this
+-chat list.
+
+<tag/FREEBSD-CORE/ <em>FreeBSD core team</em><newline>
+This is an internal mailing list for use by the core members.
+
+<tag/FREEBSD-CURRENT/ <em>Discussions about the use of
+ FreeBSD-current</em><newline>
+This is the mailing list for users of freebsd-current. It includes
+warnings about new features coming out in -current that will affect the
+users, and instructions on steps that must be taken to remain -current.
+Anyone running "current" must subscribe to this list.
+
+<tag/FREEBSD-DOC/ <em>Documentation project</em><newline>
+This mailing list belongs to the FreeBSD Doc Project and is for
+the discussion of documentation related issues and projects.
+
+<tag/FREEBSD-FS/ <em>Filesystems</em><newline>
+Discussions concerning FreeBSD filesystems.
+
+<tag/FREEBSD-HACKERS/ <em>Technical discussions</em><newline>
+This is a forum for technical discussions related to FreeBSD. This
+is the primary technical mailing list. It
+is for individuals actively working on FreeBSD, to bring up problems
+or discuss alternative solutions. Individuals interested in
+following the technical discussion are also welcome.
+
+<tag/FREEBSD-HARDWARE/ <em>General discussion of FreeBSD
+ hardware</em><newline>
+General discussion about the types of hardware that FreeBSD runs on,
+various problems and suggestions concerning what to buy or avoid.
+
+<tag/FREEBSD-INSTALL/ <em>Installation discussion</em><newline>
+This is the mailing list for people discussing FreeBSD installation
+development for the 2.0 release.
+
+<tag/FREEBSD-PLATFORMS/ <em>Porting to Non-Intel
+ platforms</em><newline>
+Cross-platform freebsd issues, general discussion and proposals for
+non-Intel FreeBSD ports.
+
+<tag/FREEBSD-POLICY/ <em>Policy issues and
+ suggestions</em><newline>
+This is a forum for policy discussions related to FreeBSD. This
+includes where FreeBSD is going, how to set up a consortium, whether
+or not and how to make FreeBSD pay for itself, how to attract more
+users, and so on. When a topic relates directly to FreeBSD but has
+little or no technical content then it should be sent to this list.
+
+<tag/FREEBSD-PORTS/ <em>Discussion of "ports"</em><newline>
+Discussions concerning FreeBSD's "ports collection" (/usr/ports), proposed
+ports, modifications to ports collection infrastructure and general
+coordination efforts.
+
+<tag/FREEBSD-QUESTIONS/ <em>User questions</em><newline>
+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.
+
+<tag/FREEBSD-SCSI/ <em>SCSI subsystem</em><newline>
+This is the mailing list for people working on the scsi subsystem
+for FreeBSD.
+
+<tag/FREEBSD-SECURITY/ <em>Security issues</em><newline>
+FreeBSD computer security issues (DES, Kerberos, known security holes and
+fixes, etc).
+</descrip>
<sect>
- <heading>Usenet newsgroups</heading>
-
- <p>While no newsgroups dedicated to FreeBSD exist, there
- are many in which FreeBSD is discussed or are otherwise
- relevant to FreeBSD users.
-
- <sect1>
- <heading>BSD specific newsgroups</heading>
-
- <p><itemize>
- <item> comp.unix.bsd.freebsd.announce
- <item> comp.unix.bsd.freebsd.misc
- </itemize>
-
- <sect1>
- <heading>Other Unix newsgroups of interest</heading>
-
- <p><itemize>
- <item> comp.unix
- <item> comp.unix.questions
- <item> comp.unix.admin
- <item> comp.unix.programmer
- <item> comp.unix.shell
- <item> comp.unix.user-friendly
- <item> comp.security.unix
- <item> comp.sources.unix
- <item> comp.unix.advocacy
- <item> comp.unix.misc
- <item> comp.os.386bsd.announce
- <item> comp.os.386bsd.apps
- <item> comp.os.386bsd.bugs
- <item> comp.os.386bsd.development
- <item> comp.os.386bsd.misc
- <item> comp.os.386bsd.questions
- <item> comp.bugs.4bsd
- <item> comp.bugs.4bsd.ucb-fixes
- <item> comp.unix.bsd
- </itemize>
-
- <sect1>
- <heading>X-Window system</heading>
-
- <p><itemize>
- <item> comp.windows.x.i386unix
- <item> comp.windows.x
- <item> comp.windows.x.apps
- <item> comp.windows.x.announce
- <item> comp.windows.x.intrinsics
- <item> comp.windows.x.motif
- <item> comp.windows.x.pex
- <item> comp.emulators.ms-windows.wine
- </itemize>
+ <heading>Usenet newsgroups</heading>
+
+ <p>While no newsgroups dedicated to FreeBSD exist, there
+ are many in which FreeBSD is discussed or are otherwise
+ relevant to FreeBSD users.
+
+ <sect1>
+ <heading>BSD specific newsgroups</heading>
+
+ <p><itemize>
+ <item> comp.unix.bsd.freebsd.announce
+ <item> comp.unix.bsd.freebsd.misc
+ </itemize>
+
+ <sect1>
+ <heading>Other Unix newsgroups of interest</heading>
+
+ <p><itemize>
+ <item> comp.unix
+ <item> comp.unix.questions
+ <item> comp.unix.admin
+ <item> comp.unix.programmer
+ <item> comp.unix.shell
+ <item> comp.unix.user-friendly
+ <item> comp.security.unix
+ <item> comp.sources.unix
+ <item> comp.unix.advocacy
+ <item> comp.unix.misc
+ <item> comp.os.386bsd.announce
+ <item> comp.os.386bsd.apps
+ <item> comp.os.386bsd.bugs
+ <item> comp.os.386bsd.development
+ <item> comp.os.386bsd.misc
+ <item> comp.os.386bsd.questions
+ <item> comp.bugs.4bsd
+ <item> comp.bugs.4bsd.ucb-fixes
+ <item> comp.unix.bsd
+ </itemize>
+
+ <sect1>
+ <heading>X-Window system</heading>
+
+ <p><itemize>
+ <item> comp.windows.x.i386unix
+ <item> comp.windows.x
+ <item> comp.windows.x.apps
+ <item> comp.windows.x.announce
+ <item> comp.windows.x.intrinsics
+ <item> comp.windows.x.motif
+ <item> comp.windows.x.pex
+ <item> comp.emulators.ms-windows.wine
+ </itemize>
<sect>
- <heading>Word Wide Web servers</heading>
+ <heading>Word Wide Web servers</heading>
- <p><itemize>
- <item> <url url="http://www.freebsd.org/"></item>
- </itemize>
+ <p><itemize>
+ <item> <url url="http://www.freebsd.org/"></item>
+ </itemize>
</sect>
diff --git a/handbook/handbook.sgml b/handbook/handbook.sgml
index 1083960ad7..6255de5531 100644
--- a/handbook/handbook.sgml
+++ b/handbook/handbook.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: handbook.sgml,v 1.6 1995-05-11 22:31:23 jfieber Exp $ -->
+<!-- $Id: handbook.sgml,v 1.7 1995-05-18 03:05:08 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
@@ -16,6 +16,7 @@
<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY history SYSTEM "history.sgml">
<!ENTITY kerberos SYSTEM "kerberos.sgml">
+<!ENTITY memoryuse SYSTEM "memoryuse.sgml">
<!ENTITY nfs SYSTEM "nfs.sgml">
<!ENTITY nutshell SYSTEM "nutshell.sgml">
<!ENTITY porting SYSTEM "porting.sgml">
@@ -54,7 +55,7 @@ OUTLINE:
<author>
<name>The FreeBSD Documentation Project</name>
</author>
- <date>May 11, 1995</date>
+ <date>May 17, 1995</date>
<abstract>Welcome to FreeBSD! This handbook covers the
installation and day to day use of FreeBSD.
@@ -183,13 +184,16 @@ OUTLINE:
<!-- ************************************************************ -->
<part><heading>Advanced topics</heading>
- &booting;
&current;
&ctm;
&sup;
<chapt><heading>Kernel debugging</heading>
- &troubleshooting;
&submitters;
+ &booting;
+ &memoryuse;
+ &troubleshooting;
+
+<!-- ************************************************************ -->
<part><heading>Additional resources</heading>
&bibliography;
diff --git a/handbook/memoryuse.sgml b/handbook/memoryuse.sgml
new file mode 100644
index 0000000000..aa984fccea
--- /dev/null
+++ b/handbook/memoryuse.sgml
@@ -0,0 +1,55 @@
+<!-- $Id: memoryuse.sgml,v 1.1 1995-05-18 03:05:11 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<chapt><heading>PC memory utilization</heading>
+
+<p><em>Contributed by &a.joerg;.<newline>
+ 16 Apr 1995.</em>
+
+<bf>Question:</bf> <em>By the way, I have seen no description
+of how FreeBSD uses PC memory, ie
+what 0-640K gets used for, does the kernel load there or higher,
+is the kernel relocated, etc. Is there a paper on this?</em>
+
+The boot sector will be loaded at 0:0x7c00, and relocates itself
+immediately to 0x7c0:0. (This is nothing magic, just an adjustment
+for the %cs selector, done by an ljmp.)
+
+It then loads the first 15 sectors at 0x10000 (segment BOOTSEG in the
+biosboot Makefile), and sets up the stack to work below 0x1fff0.
+After this, it jumps to the entry of boot2 within that code. I.e., it
+jumps over itself and the (dummy) partition table, and it's going to
+adjust the %cs selector---we are still in 16-bit mode there.
+
+boot2 asks for the boot file, and examines the a.out header. It masks
+the file entry point (usually 0xf0100000) by 0x00ffffff, and loads the
+file there. Hence the usual load point is 1 MB (0x00100000). During
+load, the boot code toggles back and forth between real and protected
+mode, to use the BIOS in real mode.
+
+The boot code itself uses segment selectors 0x18 and 0x20 for %cs and
+%ds/%es in protected mode, and 0x28 to jump back into real mode. The
+kernel is finally started with %cs 0x08 and %ds/%es/%ss 0x10, which
+refer to dummy descriptors covering the whole address space.
+
+The kernel will be started at its load point. Since it's been linked
+for another (high) address, it will have to execute PIC until the page
+table and page directory stuff is setup properly, at which point
+paging will be enabled and the kernel will finally run at the address
+for which it was linked.
+
+The kernel still skips over the first 0x500 bytes of code, in the
+assumption this were valuable BIOS data space (back from old days
+where it has been loaded low).
+
+<em>Contributed by &a.davidg;.<newline>
+ 16 Apr 1995.</em>
+
+The physical pages immediately following the kernel BSS contain
+proc0's page directory, page tables, and upages. Some time later
+when the VM system is initialized, the physical memory between
+0x1000-0x9ffff and the physical memory after the kernel
+(text+data+bss+proc0 stuff+other misc) is made available in the
+form of general VM pages and added to the global free page list.
+
+
diff --git a/handbook/porting.sgml b/handbook/porting.sgml
index a633ac990b..9dbce8d02c 100644
--- a/handbook/porting.sgml
+++ b/handbook/porting.sgml
@@ -1,7 +1,7 @@
-<!-- $Id: porting.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
+<!-- $Id: porting.sgml,v 1.2 1995-05-18 03:05:15 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
-<sect><heading>Porting applications</heading>
+<sect><heading>Porting applications<label id="porting:"></heading>
<p><em>Contributed by &a.jkh;.</em>
diff --git a/handbook/ports.sgml b/handbook/ports.sgml
index 702c232225..0cb957954a 100644
--- a/handbook/ports.sgml
+++ b/handbook/ports.sgml
@@ -1,7 +1,7 @@
-<!-- $Id: ports.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
+<!-- $Id: ports.sgml,v 1.2 1995-05-18 03:05:19 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
-<sect><heading>The Ports collection</heading>
+<sect><heading>The Ports collection<label id="ports:"></heading>
<p><em>Contributed by &a.gpalmer; and &a.jkh;.</em>
diff --git a/handbook/submitters.sgml b/handbook/submitters.sgml
index 6607e5593c..3389f8a917 100644
--- a/handbook/submitters.sgml
+++ b/handbook/submitters.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: submitters.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
+<!-- $Id: submitters.sgml,v 1.2 1995-05-18 03:05:22 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Contributing to FreeBSD</heading>
@@ -11,22 +11,22 @@ customizations or fixes to the system which they'd like to incorporate
back into the mainstream sources, thus saving the work of having to
re-integrate the changes for each subsequent FreeBSD release. Submitting
something to the FreeBSD project is also an excellent way of getting your
-code seriously *tested*! Many people have developed an original concept
+code seriously <em>tested</em>! Many people have developed an original concept
far beyond what they might have envisioned at the start just due to the
flood of feedback and ideas generated by the many thousands of users of
FreeBSD. Contributions are also what FreeBSD lives and grows from,
and so your contributions are very important to the continued survival
-of this communal effort of ours - we're very glad to see you reading this
-documentation! :-)
+of this communal effort of ours---we're very glad to see you reading this
+documentation!
Submissions to FreeBSD can generally be classified into four catagories:
<enum>
-<item> Ideas, general suggestions, bug reports.
-<item> Addition, deletion, renaming or patching of existing sources.
-<item> Significant contribution of a large body of independant work.
-<item> Porting of freely available software.
+<item>Ideas, general suggestions, bug reports.
+<item>Addition, deletion, renaming or patching of existing sources.
+<item>Significant contribution of a large body of independant work.
+<item>Porting of freely available software.
</enum>
-A submission in *any* of these catagories is highly welcomed as they
+A submission in <em>any</em> of these catagories is highly welcomed as they
are each, in their own way, quite significant to the project.
@@ -34,26 +34,30 @@ are each, in their own way, quite significant to the project.
<p>An idea, suggestion or fix can be communicated in one of the following ways:
<itemize>
- <item> An idea or suggestion of general technical interest should be
- mailed to &lt;hackers@freebsd.org&gt;. Likewise, people with an interest
- in such things (and a tolerance for a HIGH volume of mail!) may
- subscribe by sendimg mail to &lt;majordomo@freebsd.org&gt;. See also the
- file /usr/share/FAQ/mailing-list.FAQ.
-
- <item> An actual bug report should be filed by using the send-pr(1)
- command (``man send-pr'' for information). This will prompt
+ <item>An idea or suggestion of general technical interest should be
+ mailed to <tt>&lt;hackers@freebsd.org&gt;</tt>.
+ Likewise, people with an interest
+ in such things (and a tolerance for a <em>high</em>
+ volume of mail!) may
+ subscribe to the hackers mailing list by sendimg mail to
+ <tt>&lt;majordomo@freebsd.org&gt;</tt>.
+ See <ref id="eresources:mailing-lists"
+ name="mailing lists">
+ for more information about this and other mailing lists.
+
+ <item>An actual bug report should be filed by using the
+ <tt>send-pr(1)</tt> program. This will prompt
you for various fields to fill in. Simply go to the fields
- surrounded by &lt;&gt;'s and fill in your own information in place of
+ surrounded by <tt>&lt;&gt;</tt>'s and fill in your own
+ information in place of
what's suggested there. You should receive confirmation of your
- bug report and a tracking number (which you should also reference in
- any subsequent correspondence).
-
+ bug report and a tracking number. Keep this tracking number and use
+ it in any subsequent correspondence.
If you do not receive confirmation in a timely fashion (3 days to
a week, depending on your email connection) or are, for some
- reason, unable to use the send-pr command, then you may also
- file a bug report (or follow-up to one) by sending mail to:
-
- &lt;bugs@freebsd.org&gt;
+ reason, unable to use the <tt>send-pr(1)</tt> command,
+ then you may also file a bug report by sending mail to
+ <tt>&lt;bugs@freebsd.org&gt;</tt>.
</itemize>
<sect><heading>Changes to the existing code</heading>
@@ -61,90 +65,104 @@ are each, in their own way, quite significant to the project.
<p>An addition or change to the existing source code is a somewhat trickier
affair and depends a lot on how far out of date you are with the current
state of the core FreeBSD development. There is a special on-going release
- of FreeBSD known as "FreeBSD-current" and made available in a variety of
- ways (see /usr/share/FAQ/current-policy.FAQ and /usr/share/FAQ/ctm.FAQ) for
- the convenience of developers who wish to actively work on the system.
+ of FreeBSD known as ``FreeBSD-current'' and made available in a variety of
+ ways for the convenience of developers who wish to actively work on the
+ system. See <ref id="current:" name="Staying current with
+ FreeBSD"> for more information about getting and using FreeBSD-current.
Working from older sources unfortunately means that your changes may
sometimes be too obsolete to use, or too divergent to allow for easy
re-integration. This can be minimized somewhat by subscribing to the
- &lt;announce@freebsd.org&gt; mailing list (among others) where periodic
+ <tt>&lt;announce@freebsd.org&gt;</tt> mailing list, among
+ others, where periodic
announcements concerning the current state of the system are made.
If you see a change being proposed for which you have a better solution,
- then please, by all means come forward with your contribution and we
+ by all means come forward with your contribution and we
will do our very best to evaluate it fairly and perhaps integrate it if
- it is indeed a better (or easier :) solution.
+ it is indeed a better solution.
Assuming that you can manage to secure fairly up-to-date sources to base
your changes on, the next step is to produce a set of diffs to send to the
FreeBSD maintainers for evaluation and possible adoption. This is done
- with the diff(1) command, with the FreeBSD maintainers preferring to receive
- diffs in `context diff' form. See the man page for diff for more details
- on producing both context and recursive context diffs
- (diff -c &lt;oldfile&gt &lt;newfile&gt; or diff -c -r &lt;olddir&gt; &lt;newdir&gt;).
-
- Once you have a set of diffs that are capable of taking a copy of the
- original code and bringing it to a state identical to the "new" sources
- (you may test this with the patch(1) command - see patch man page), you
- should bundle them up in an email message and send it, along with a brief
- description of what the diffs are for, to &lt;hackers@freebsd.org&gt;. Someone
- will very likely get back in touch with you in 24 hours or less, assuming
- of course that your diffs are interesting! :-)
-
- If your changes don't express themselves well as diffs alone (e.g. you've
- perhaps added, deleted or renamed files as well) then you may be better off
- bundling any new files, diffs and instructions for deleting/renaming any
- others into a tar file and running the `uuencode' program on it before
- sending the output of that to &lt;hackers@freebsd.org&gt;. See the man pages
- on tar and uuencode for more info on bundling files through the mail this
- way.
-
- If your change is of a potentially sensitive nature, e.g. you're unsure
- of copyright issues governing its further distribution, or you're simply
- not ready to release it without a tighter review first, then you should
- send it to &lt;core@freebsd.org&gt; rather than &lt;hackers@freebsd.org&gt;. The core
- mailing list reaches a much smaller group of people who do much of the
- day-to-day work on FreeBSD. Note that this group is also VERY BUSY and so
- you should really only mail to them in cases where mailing to hackers
- truly is impractical.
+ with the <tt>diff(1)</tt> command, with the FreeBSD
+ maintainers preferring to receive
+ diffs in `context diff' form. For example:
+<tscreen><verb>
+diff -c &lt;oldfile&gt &lt;newfile&gt;
+</verb></tscreen>
+or
+<tscreen><verb>
+diff -c -r &lt;olddir&gt &lt;newdir&gt;
+</verb></tscreen>
+ See the man page for <tt>diff(1)</tt> for more details
+ on producing both context and recursive context diffs.
+
+ Once you have a set of diffs that are capable of taking a copy
+ of the original code and bringing it to a state identical to
+ the ``new'' sources (you may test this with the
+ <tt>patch(1)</tt> command), you should bundle them up in an
+ email message and send it, along with a brief description of
+ what the diffs are for, to
+ <tt>&lt;hackers@freebsd.org&gt;</tt>. Someone will very
+ likely get back in touch with you in 24 hours or less,
+ assuming of course that your diffs are interesting!
+
+ If your changes don't express themselves well as diffs alone
+ (e.g. you've perhaps added, deleted or renamed files as well)
+ then you may be better off bundling any new files, diffs and
+ instructions for deleting/renaming any others into a
+ <tt>tar</tt> file and running the <tt>uuencode(1)</tt> program
+ on it before sending the output of that to
+ <tt>&lt;hackers@freebsd.org&gt;</tt>. See the man pages on
+ <tt>tar(1)</tt> and <tt>uuencode(1)</tt> for more info on
+ bundling files through the mail this way.
+
+ If your change is of a potentially sensitive nature, for
+ example you're unsure of copyright issues governing its
+ further distribution, or you're simply not ready to release it
+ without a tighter review first, then you should send it to
+ <tt>&lt;core@freebsd.org&gt;</tt> rather than
+ <tt>&lt;hackers@freebsd.org&gt;</tt>. The core mailing list
+ reaches a much smaller group of people who do much of the
+ day-to-day work on FreeBSD. Note that this group is also
+ <em>very busy</em> and so you should only mail to them
+ in cases where mailing to hackers truly is impractical.
<sect><heading>Contributions of new code</heading>
-<p>In the case of a significant contribution of a large body work, or the
- addition of an important new feature to FreeBSD, it becomes almost always
- necessary to either send changes as uuencoded tar files (see above)
- or upload them to our ftp site:
-
- <url url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming">
+<p>In the case of a significant contribution of a large body
+ work, or the addition of an important new feature to FreeBSD,
+ it becomes almost always necessary to either send changes as
+ uuencoded tar files or upload them to our ftp site <url
+ url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming"> where
+ users may log in anonymously and upload their work or download
+ the work-in-progress files left by others.
- Users may log in anonymously and upload their work or download the
- work-in-progress files left by others.
-
- When working with large amounts of code, the touchy subject of copyrights
- also invariably comes up. The view of the FreeBSD project towards
- acceptable copyrights (for code included in FreeBSD) are:
+ When working with large amounts of code, the touchy subject of
+ copyrights also invariably comes up. Acceptable copyrights
+ for code included in FreeBSD are:
<enum>
- <item> Contributions under the BSD copyright (see the file
- /usr/share/examples/etc/bsd-style-copyright for a template)
- is greatly preferred due to its "no strings attached"
+ <item>Contributions under the BSD copyright
+ are greatly preferred due to its ``no strings attached''
nature and general attractiveness to commercial enterprises
who might then be inclined to invest something of their own
into FreeBSD.
- <item> Contributions under the GNU Public License, or "GPL". This is
- not quite as popular a solution for us, due to (all religious
- issues aside) the amount of extra effort demanded of anyone
+ <item>Contributions under the GNU Public License, or ``GPL''. This is
+ not quite as popular a solution for us, due to
+ the amount of extra effort demanded of anyone
using the code for commercial purposes. However, given the
sheer quantity of GPL'd code we currently require (compiler,
assembler, text formatter, etc), it would be silly to pretend
that we couldn't deal with the GPL at all and so we have become
more willing to accept code with either the BSD or the GPL
copyright. Code under the GPL also goes into a different part
- of the tree, that being /sys/gnu or /usr/src/gnu.
+ of the tree, that being <tt>/sys/gnu</tt> or
+ <tt>/usr/src/gnu</tt>.
- <item> Contributions coming under any other type of copyright must be
+ <item>Contributions coming under any other type of copyright must be
carefully reviewed before their inclusion into FreeBSD will even
be considered. Contributions for which particularly restrictive
commercial copyrights apply are generally rejected, though the
@@ -152,30 +170,68 @@ are each, in their own way, quite significant to the project.
their own channels.
</enum>
+ To place such a copyright on your work, place the following
+ text at the very beginning of every source code file you wish
+ to protect, replacing the text between the `<tt>%%</tt>' with
+ the appropriate information.
+<tscreen><verb>
+Copyright (c) %%proper_years_here%%
+ %%your_name_here%%, %%your_state%% %%your_zip%%. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer as
+ the first lines of this file unmodified.
+2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+3. All advertising materials mentioning features or use of this software
+ must display the following acknowledgment:
+ This product includes software developed by %%your_name_here%%.
+4. The name of the author may not be used to endorse or promote products
+ derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+ $Id: submitters.sgml,v 1.2 1995-05-18 03:05:22 jfieber Exp $
+</verb></tscreen>
+For your convenience, a copy of this text can be found in
+<tt>/usr/share/examples/etc/bsd-style-copyright</tt>.
+
+
<sect><heading>Porting of software</heading>
-<p>The porting of freely available software, while perhaps not as gratifying
- as developing your own package from scratch, is still a vital part of
- FreeBSD's growth and of great usefulness to those who wouldn't otherwise
- know where to turn for it. All ported software is organized into a
- hierarchy know as ``the ports collection''. This collection enables
- a new user to get a complete overview of what's available in a short time,
- and with a logical (we hope) framework. The ports collection also saves
- considerable space by not actually containing the the majority of the
- sources being ported. This can be confusing to the new user and the file
- /usr/share/FAQ/ports.FAQ goes some way towards explaing how it all works.
-
- If you have the ports collection on your machine, the file
- /usr/ports/GUIDELINES also helps to explain the process of creating
- and contributing a port of your own. For more information on the ports
- collection (that wasn't available in the FAQ), you may also send mail to
- &lt;ports@freebsd.org&gt;.
-
-
-Whichever way you decide to contribute, we hope you'll find it an enjoyable
-process and also realize how valuable your contributions are to the project!
-FreeBSD is one of those great projects where the more we all put in, the
-more we all get back out of it again, and with enough steady contributions
-it begins to aquire a momentum of its own. It is through such momentum
+<p>The porting of freely available software, while perhaps not as
+gratifying as developing your own package from scratch, is still
+a vital part of FreeBSD's growth and of great usefulness to those
+who wouldn't otherwise know where to turn for it. All ported
+software is organized into a hierarchy know as ``the ports
+collection''. This collection enables a new user to get a
+complete overview of what's available in a short time, and with a
+logical framework. The ports collection also saves
+considerable space by not actually containing the the majority of
+the sources being ported. See <ref id="ports:" name="The ports
+collection"> for more information on using the ports collection
+and <ref id="porting:" name="Porting applications"> for
+guidelines on creating new ports. You may also send mail to
+<tt>&lt;ports@freebsd.org&gt;</tt>.
+
+Whichever way you decide to contribute, we hope you'll find it an
+enjoyable process and also realize how valuable your
+contributions are to the project! FreeBSD is one of those great
+projects where the more we all put in, the more we all get back
+out of it again, and with enough steady contributions it begins
+to aquire a momentum of its own. It is through such momentum
that mountains are moved!